IMS DB PCB Mask

What is a PCB?

A PCB defines how an application program interacts with the database. It specifies which database the program can access, the segments it can interact with, and the operations it can perform.

Example: Imagine a company database with segments for Company, Project, and Employee. A PCB would define the program's view of this database, specifying access to the Project and Employee segments and the operations allowed, such as reading or updating employee records.

What is a PCB Mask?

A PCB Mask is a copybook or a data structure in the application program that matches the layout of the Program Communication Block (PCB) used internally by IMS to interact with the database.

Purpose of PCB Mask

It acts as an interface between your program and IMS.
When you make a DL/I call, IMS updates the fields inside the PCB mask with important status and position information.
It helps your COBOL program interpret IMS responses, such as whether the data was found, or if there was an error.

Declaring a PCB Mask in COBOL

The PCB Mask is typically declared in the Linkage Section of a COBOL program. Here's a sample structure:

01 PCB-MASK.
   05 DBD-NAME         PIC X(8).
   05 SEG-LEVEL        PIC XX.
   05 STATUS-CODE      PIC XX.
   05 PROC-OPTIONS     PIC X(4).
   05 RESERVED-DLI     PIC S9(5).
   05 SEG-NAME         PIC X(8).
   05 LENGTH-FB-KEY    PIC S9(5).
   05 NUM-OF-SENS-SEGS PIC S9(5).
   05 KEY-FB-AREA      PIC X(n).

Each field corresponds to specific information provided by IMS.

Understanding each field -

PCB-MASK (PCB Group Name): PCB name is the group variable for the PCB mask. PCB name is used to refer to the PCB mask in the program. PCB-MASK refers to the PCB name in the above structure.
DBD-NAME (Database Name): An 8-character field indicating the name of the database being accessed.
SEG-LEVEL (Segment Level): A 2-character field specifies the hierarchical level of the segment retrieved. When the segment is retrieved successfully, the level number is stored in the segment level.
STATUS-CODE: A 2-character field where IMS places the result of the DL/I call. A blank indicates success; otherwise, it contains an error code. If the DL/I operation is successful, the Status code would be spaces. If the DL/I operation is unsuccessful, the status code would be non-spaces and pre-defined characters.
PROC-OPTIONS (Processing Options): A 4-character field specifying the operations permitted (e.g., read, insert, delete).
RESERVED-DLI: A 5-digit signed numeric field reserved for IMS internal use. IMS uses it for internal linkage purposes of the application program.
SEG-NAME (Segment Name): An 8-character field containing the name of the segment processed in the last call.
LENGTH-FB-KEY (Length of Feedback Key): A 5-digit signed numeric field indicating the length of the key feedback area. It is used to report the length of the concatenated key of the lowest-level segment processed during the previous call.
NUM-OF-SENS-SEGS (Number of Sensitive Segments): A 5-digit signed numeric field showing how many segment types the program is sensitive to.
KEY-FB-AREA (Key Feedback Area): A variable-length field holding the concatenated key of the segment retrieved. It is used to contain the longest possible concatenated key that can be used from application program for the database view.

How the PCB Mask Works in a Program -

When your COBOL program makes a DL/I call, it uses the PCB Mask to:

Identify which database to access.
Determine the result of the operation via the STATUS-CODE.
Access information about the segment retrieved, such as its name and hierarchical level.
Obtain the concatenated key for positioning within the database.

Example Usage

Here's how a DL/I call might look in a COBOL program:

CALL 'CBLTDLI' USING
   FUNCTION-CODE
   PCB-MASK
   IO-AREA
   SSA.

FUNCTION-CODE: Specifies the DL/I function (e.g., 'GU' for Get Unique).
PCB-MASK: The PCB Mask structure defined earlier.
IO-AREA: The area where the segment data will be placed.
SSA: Segment Search Argument, used to specify the segment to retrieve.