IMS PSB and PCB: Program Specification Block Complete Guide

The PSB (Program Specification Block) and PCB (Program Communication Block) are the bridge between a DL/I program and an IMS database. Before a COBOL program can issue a single DL/I call, it must have a PSB that defines its access rights, and at runtime it communicates with IMS through the PCB masks mapped to its working storage.

What is a PSB?

A PSB defines a program's relationship to IMS databases. It specifies:

• Which databases the program can access (one PCB per database)
• What sensitivity the program has (which segment types it can see)
• What processing options the program has (read-only, update, insert/delete)

PSBs are stored in PSBLIB and assembled from PCB macros using the PSBGEN utility.

What is a PCB?

A PCB is a single entry within a PSB representing one database view. A program's PSB may have multiple PCBs — one per database accessed, or even multiple PCBs for the same database (giving different views or processing options).

At runtime, IMS maintains a set of PCB masks in memory for each executing program. After every DL/I call, IMS updates the relevant PCB mask with the status code, segment name, and hierarchical path of the last segment processed. The COBOL program reads the PCB mask to determine whether the call succeeded.

PCB Macro Syntax

PCB   TYPE=DB,DBDNAME=CUSTDB,KEYLEN=25,PROCOPT=LS
      SENSEG NAME=CUSTOMER,PARENT=0
      SENSEG NAME=ACCOUNT,PARENT=CUSTOMER
      SENSEG NAME=TRANSACT,PARENT=ACCOUNT

Key parameters:

TYPE=DB — this PCB accesses a full-function database (use TYPE=TP for a transaction manager PCB or TYPE=GSAM for sequential datasets).

DBDNAME=CUSTDB — the name of the DBD this PCB accesses.

KEYLEN= — the total length of the concatenated key fields from root to the deepest segment this PCB accesses. For CUSTOMER(10) + ACCOUNT(15) = 25 bytes minimum.

PROCOPT= — the processing options:

SENSEG — Segment Sensitivity

The SENSEG macro controls which segment types within a database a program can see and access. Segments not listed in SENSEG are invisible to the program.

SENSEG NAME=CUSTOMER,PARENT=0
SENSEG NAME=ACCOUNT,PARENT=CUSTOMER

If TRANSACT is omitted from the SENSEG list, the program cannot access transaction segments — they are physically skipped during navigation as if they do not exist.

Sensitive segments only (PCBTYPE=SNGL): You can further restrict sensitivity to specific fields within a segment using SENFLD macros, limiting what data a program can read or update within a segment.

PSBGEN — Generating the PSB

A complete PSB for the customer database:

         PCB   TYPE=DB,DBDNAME=CUSTDB,KEYLEN=25,PROCOPT=LS
               SENSEG NAME=CUSTOMER,PARENT=0
               SENSEG NAME=ACCOUNT,PARENT=CUSTOMER
               SENSEG NAME=TRANSACT,PARENT=ACCOUNT
               SENSEG NAME=ADDRESS,PARENT=CUSTOMER
         PSBGEN LANG=COBOL,PSBNAME=CUSTPGM
         END

Run with the PSBGEN JCL utility:

//PSBGEN EXEC PSBGEN
//SYSIN  DD DSN=YOUR.SOURCE.LIBRARY(CUSTPGM),DISP=SHR
//PSBLIB DD DSN=IMS.PSBLIB,DISP=SHR

PCB Mask in COBOL

The COBOL program must define a PCB mask in the LINKAGE SECTION that exactly matches the PCB structure IMS provides:

LINKAGE SECTION.
01 CUSTOMER-PCB.
   05 PCB-DBD-NAME     PIC X(8).
   05 PCB-SEG-LEVEL    PIC XX.
   05 PCB-STATUS-CODE  PIC XX.
   05 PCB-PROC-OPT     PIC X(4).
   05 FILLER           PIC S9(5) COMP.
   05 PCB-SEG-NAME     PIC X(8).
   05 PCB-KEY-FEEDBACK PIC X(25).

The critical fields:

• PCB-STATUS-CODE: Blank = success, GE = segment not found, GB = end of database, others indicate errors
• PCB-SEG-NAME: The name of the last segment successfully processed
• PCB-KEY-FEEDBACK: The concatenated key of the last segment processed (useful for position tracking)

Entry Linkage in COBOL

The COBOL program must declare the PCB masks in the PROCEDURE DIVISION USING clause:

PROCEDURE DIVISION USING CUSTOMER-PCB.

For programs with multiple PCBs:

PROCEDURE DIVISION USING CUSTOMER-PCB
                         ACCTREF-PCB
                         IOPCB.

The order of PCBs in the PROCEDURE DIVISION USING must match the order of PCBs in the PSB.

Frequently Asked Questions

Q: What is the IOPCB and when is it required? The IOPCB (Input/Output PCB) is required for IMS TM programs that read from and write to the message queue. It is always the first PCB in the PSB for message processing programs. Batch programs accessing only databases do not need an IOPCB.

Q: Can two programs share the same PSB? Yes — multiple program executions can use the same PSB name. The PSB defines an access template; IMS creates a separate set of PCB masks in memory for each running program instance. Sharing a PSB is common for multiple versions of the same program running in different MPP regions.

Q: What happens if a program tries to access a segment not listed in SENSEG? IMS treats unlisted segments as if they do not exist. A GN call that would normally return such a segment will skip it and return the next sensitive segment, or return a GE status code if no more sensitive segments exist. The program never knows the skipped segments are there — they are completely invisible.

Part of the IMS Mastery Course — Module 8 of 22.