IMS DL/I Call Format

Because DL/I is used to communicate and process the message queues, you need to know the format of the DL/I DC call to the message queues. Below code shows this format.

PL/I:

CALL PLITDLI (W_PARM_CNT,     Parameter Count
              C_FUNC_CODE,    Function Code
              L_PCB_PTR,      I/O PCB (L_IO_PCB_PTR)
              W_MESSAGE_IO,   Message (screen) I/O Area
              W_FMT_DEST);    Format MOD Name (optional)

COBOL:

CALL 'CBLTDLI' USING W-PARM-CNT,    Parameter Count (optional)
                     C-FUNC-CODE,   Function Code
                     L-PCB-MASK,    I/O PCB (L-IO-PCB)
                     W-MESSAGE-IO,  Message (screen) I/O Area
                     W-FMT-DEST.    Format MOD Name (optional)

DL/I Message Call Format

The fact we are calling DL/I to process our request to the message queue means the call must follow the same format as if we were processing a database. Each call parameter is described below.

PARM_CNT

This parameter is the parameter count. It is a binary full word (for PL/I and half word for COBOL) that has a value equal to the number of parameters passed to the DL/I call, not including the parm count itself. This is a required parameter for PL/I, optional for COBOL. Although it is an optional parameter for COBOL, we will use it in all the text examples. The PL/1 DCL is FIXED BIN(31). For COBOL it is PIC S9(9) COMP.

FUNC_CODE

This parameter is the function code. It must be a character string four bytes in length, and specify the type of function DL/I should perform to the message queue: retrieve, insert, purge, and so on. Below table of common DL/I DC function codes and their descriptions.

PCB_PTR

This parameter is either the I/O PCB or alternate PCB pointer name. This name must be the same name used in the main PROCEDURE statement of a PL/I program, or the same name used in the LINKAGE SECTION and ENTRY statement of a COBOL program. This is a required parameter in all DL/I calls.

MESSAGE_IO

This parameter specifies the starting address of the input area for input messages, or the starting address for output messages. For input messages, the allocated area must be large enough to hold the entire message, or storage overlay may occur.

FMT_DEST

This is an optional parameter. It is a character string eight bytes in length containing one of the following: if FUNC CODE is ISRT, this must be a MOD name; if FUNC CODE is CHNG, this could be either the LTERM name of an alternate device such as a printer or another terminal, or it could be a Transaction Name.

I/O PCB Mask

Whenever a call is made to DL/I, information about the call is provided to your application program through the PCB pointer used in the call. (It is assumed that you are experienced with using DL/I to process IMS databases, and therefore with the database PCB I/O area or PCB mask.) Specify the I/O PCB pointer in your DL/I call the same way you specify the database PCB pointer. As with databases, DL/I will provide you with an address to a PCB I/O area. The content of the PCB I/O area for the I/O PCB is different from that of a data base PCB. Below code shows how the I/O PCB mask should be coded in your application program.

PL/I:

  DCL L_IO_PCB_PTR  POINTER:
  DCL 01 L_IO_PCB_MASK   BASED(L_IO_PCB_PTR),
  05 L_IO_LTERM-NAME      CHAR(8),
  05 L_IO_IMS_RSVD        CHAR(2),
  05 L_IO_STATUS_CODE     CHAR(2),
  05 L_IO_CURR_DATE       FIXED DEC(7,0),
  05 L_IO_CURR_TIME       FIXED DEC(7,1),
  05 L_IO_MSG_NUMBER      FIXED BIN(31),
  05 L_IO_MOD_NAME        CHAR(8),
  05 L_IO_USER-ID         CHAR(8);

COBOL:

  LINKAGE SECTION
  01   L -10-PCB.
    05  L-IO-LTERM-NAME         PIC   X(8).
    05  L-IO-IMS-RSVD           PIC   X(2).
    05  L-IO-STATUS-CODE        PIC   X(2).
    05  L-IO-CURR-DATE          PIC   S9(7)   COMP-3.
    05  L-IO-CURR-TIME          PIC   S9(6)V9 COMP-3.
    05  L-IO-MSG-NUMBER         PIC   S9(9)   COMP.
    05  L-IO-MOD-NAME           PIC   X(8).
    05  L-IO-USER-ID            PIC   X(8).

I/O PCB Mask

The following is a detailed description of each element in the mask:

LTERM NAME

This field contains the LTERM name of the device that sent the message. It is a string of characters eight bytes in length.

IMS RSVD

These two bytes are reserved for IMS/VS.

STATUS CODE

This field will contain the status code of the call. It is a string of characters two bytes in length.

CURR DATE

This field contains the current data that the entire message was sent. It is in Julian data format, YYDDD, and is a four-byte, right-justified, packed-decimal field.

CURR TIME

This field contains the current time the entire message was sent. It is a four byte, right-justified, packed decimal field in the HHMMSST format.

MSG NUMBER

This field is binary, four bytes in length, and contains the sequence number assigned by IMS. Sequence numbers are assigned by LTERM and are continuous, based on the current IMS start up.

MOD NAME

This field contains the Message Output Descriptor name, if MFS was used to format the message. If MFS was not used, the field is blank. It is a character string of eight bytes.

USER ID

This field is a character string of eight-bytes that contains a unique user identification, and is used in conjunction with IMS sign-on security facilities.

If you have any doubts or queries related to this chapter, get them clarified from our Mainframe experts on IBMMainframer Community!