Specifying the DL/I interface block (DIB)

Each time your program executes a DL/I command, DL/I returns a status code and other information to your program through the DL/I interface block (DIB), which is a subset of IMS PCB. Your program should check the status code to make sure the command executed successfully.

Each program's working storage contains its own DIB. The contents of the DIB reflect the status of the last DL/I command executed in that program. If the information in your program's DIB is required by another program used by your transaction, you must pass the information to that program.

To access fields in the DIB, use labels that are automatically generated in your program by the translator.

Restriction: These labels are reserved; you must not redefine them.

In your COBOL, PL/I, assembler language, and C programs, some variable names are mandatory.

For a COBOL program:
DIBVER    PICTURE X(2)
DIBSTAT    PICTURE X(2)
DIBSEGM    PICTURE X(8)
DIBFIL01     PICTURE X
DIBFIL02     PICTURE X
DIBSEGLV    PICTURE X(2)
DIBKFBL    PICTURE S9(4) COMPUTATIONAL
DIBDBDNM    PICTURE X(8)
DIBDBORG    PICTURE X(8) 
DIBFIL03 PIC X(6)
For a PL/I program: 
DIBVER    CHAR(2)
DIBSTAT    CHAR(2)
DIBSEGM    CHAR(8)
DIBFIL01 CHAR(1)
DIBFIL02 CHAR(1)
DIBSEGLV    CHAR(2)
DIBKFBL    FIXED BINARY (15,0)
DIBDBDNM    CHAR(8)
DIBDBORG    CHAR(8)
DIBFIL03 CHAR(6)
For an assembler language program: 
DIBVER    CL2
DIBSTAT    CL2
DIBSEGM    CL8
DIBFIL01   CL1
DIBFIL02   CL1
DIBSEGLV   CL2
DIBKFBL    H
DIBDBDNM   CL8
DIBDBORG   CL8
DIBFILR3   CL6
For a C program: 
unsigned char     dibver    {2}  ;
unsigned char     dibstat   {2}  ;
unsigned char     dibsegm   {8}  ;
unsigned char     dibfic01  ;
unsigned char     dibfic02  ;
unsigned char     dibseglv  {2}  ;
signed short int  dibkfbl   ;
unsigned char     dibdbdnm  {8}  ;
unsigned char     dibdborg  {8}  ;
unsigned char     dibfic03  {6}  ;

The following notes explain the contents of each variable name. The name in parenthesis is the label used to access the contents.

  1. Translator Version (DIBVER)

    This is the version of the DIB format your program is using. (DIBVER is used for documentation and problem determination.)

  2. Status Codes (DIBSTAT)

    DL/I places a 2-character status code in this field after executing each DL/I command. This code describes the results of the command.

    After processing a DL/I command, DL/I returns control to your program at the next sequential instruction following the command. The first thing your program should do after each command is to test the status code field and take appropriate action. If the command was completely successful, this field contains blanks.

    The status codes that can be returned to this field (they are the only status codes returned to your program) are:
    bb
    (Blanks) The command was completely successful.
    BA
    For GU, GN, GNP, DLET, REPL, and ISRT commands. Data was unavailable.
    BC
    For DLET, REPL, and ISRT commands. A deadlock was detected.
    FH
    For GU, GN, GNP, DLET, REPL, ISRT, POS, CHKP, and SYMCHKP commands. The DEDB was inaccessible.
    FW
    For GU, GN, GNP, DLET, REPL, ISRT, and POS commands. More buffer space is required than normally allowed.
    GA
    For unqualified GN and GNP commands. DL/I returned a segment, but the segment is at a higher level in the hierarchy than the last segment that was returned.
    GB
    For GN commands. DL/I reached the end of the database trying to satisfy your GN command and did not return a segment to your program's I/O area.
    GD
    For ISRT commands. The program issued an ISRT command that did not have SEGMENT options for all levels above that of the segment being inserted.
    GE
    For GU, GN, GNP, ISRT, and STAT commands. DL/I was unable to find the segment you requested, or one or more of the parents of the segment you are trying to insert.
    GG
    For Get commands. DL/I returns a GG status code to a program with a processing option of GOT or GON when the segment that the program is trying to retrieve contains an invalid pointer.
    GK
    For unqualified GN and GNP commands. DL/I returned a segment that satisfies an unqualified GN or GNP request, but the segment is of a different segment type (but at the same level) than the last segment returned.
    II
    For ISRT commands. The segment you are trying to insert already exists in the database. This code can also be returned if you have not established a path for the segment before trying to insert it. The segment you are trying to insert might match a segment with the same key in another hierarchy or database record.
    LB
    For load programs only after issuing a LOAD command. The segment you are trying to load already exists in the database. DL/I returns this status code only for segments with key fields.
    NI
    For ISRT and REPL commands. The segment you are trying to insert or replace requires a duplicate entry to be inserted in a secondary index that does not allow duplicate entries. This status code is returned for batch programs that write log records to direct access storage. If a CICS® program that does not log to disk encounters this condition, the program (transaction) is abnormally terminated.
    TG
    For TERM commands. The program tried to terminate a PSB when one was not scheduled.

    The listed status codes (DIBSTAT) indicate exceptional conditions, and are the only status codes returned to your program. All other status codes indicate error conditions and cause your transaction or batch program to abnormally terminate. If you want to pass control to an error routine from your CICS program, you can use the CICS HANDLE ABEND command; the last 2 bytes of the abend code are the IMS status code that caused the abnormal termination. For more information on the HANDLE ABEND command, see the application programming reference manual for your version of CICS. Batch BMP programs abend with abend 1041.

  3. Segment Name (DIBSEGM)

    This is the name of the lowest-level segment successfully accessed. When a retrieval is successful, this field contains the name of the retrieved segment. If the retrieval is unsuccessful, this field contains the last segment, along the path to the requested segment, that satisfies the command.

    After issuing an XRST command, this field is either set to blanks (indicating a successful normal start), or a checkpoint ID (indicating the checkpoint ID from which the program was restarted).

    You should test this field after issuing any of the following commands:

    • GN
    • GNP
    • GU
    • ISRT
    • LOAD
    • RETRIEVE
    • XRST
  4. Segment Level Number (DIBSEGLV)

    This is the hierarchic level of the lowest-level segment retrieved. When IMS DB retrieves the segment you have requested, IMS DB places, in character format, the level number of that segment in this field. If you are issuing a path command, IMS DB places the number of the lowest-level segment retrieved. If IMS DB is unable to find the segment you have requested, it gives the level number of the last segment it encountered that satisfied your command. This is the lowest segment on the last path that IMS DB encountered while searching for the segment you requested.

    You should test this field after issuing any of the listed commands:

    • GN
    • GNP
    • GU
    • ISRT
    • LOAD
    • RETRIEVE
  5. Key Feedback Length (DIBKFBL)

    This is a halfword field that contains the length of the concatenated key when you use the KEYFEEDBACK option with get commands. If your key feedback area is not long enough to contain the concatenated key, the key is truncated, and this area indicates the actual length of the full concatenated key.

  6. Database Description Name (DIBDBDNM)

    This is the fullword field that contains the name of the DBD. The DBD is the DL/I control block that contains all information used to describe a database. The DIBDBDNM field is returned only on a QUERY command.

  7. Database Organization (DIBDBORG)

    This is the fullword field that names the type of database organization (HDAM, HIDAM, HISAM, HSAM, GSAM, SHSAM, INDEX, or DEDB) padded to the right with blanks. The DIBDBORG field is returned only on a QUERY command.