Sample programs using the Spool API

The Spool API provides functions that allow an application program to write data to the IMS Spool using the same techniques for sending data to native IMS printers.

The Spool API provides functions such as error checking for invalid OUTDES parameters. Error checking makes application programs more complex. To simplify these application programs, develop a common routine to manage error information, then make the diagnostic information from the Spool API available for problem determination.

The sample programs in these topic shows how DL/I calls can be coded to send data to the IMS Spool. Only the parts of the application program necessary to understand the DL/I call formats are included. The examples are in assembler language.

Application PCB structure

The application PCBs are as follows:

I/O PCB
ALTPCB1
ALTPCB2
ALTPCB3
ALTPCB4

GU call to I/O PCB

IMS application programs begin with initialization and a call to the I/O PCB to obtain the input message. The following code example shows how to issue a GU call to the I/O PCB.

After completing the GU call to the I/O PCB, the application program prepares output data for the IMS Spool.

Issuing a GU call to the I/O PCB

***********************************************************************
*       ISSUE GU ON IOPCB                                             *
***********************************************************************
         L     9,IOPCB             I/O PCB ADDRESS
         LA    9,0(9)
         MVC   FUNC,=CL4'GU'       GU FUNCTION
         CALL  ASMTDLI,(FUNC,(9),IOA1),VL
         BAL   10,STATUS           CHECK STATUS
*        ADDITIONAL PROGRAM LOGIC HERE
FUNC     DC    CL4' '
IOA1     DC    AL2(IOA1LEN),AL2(0)
TRAN     DS    CL8                 TRANSACTION CODE AREA
DATA     DS    CL5                 DATA STARTS HERE
         DC    20F'0'
IOA1LEN  EQU   *-IOA1

CHNG call to alternate PCB

In the same way that other programs specify the destination of the output using the CHNG call, this program specifies the IMS Spool as the output destination. For a native IMS printer, the DEST NAME parameter identifies the output LTERM name. When a CHNG call is issued that contains the IAFP= keyword, the DEST NAME parameter is used only if integrity option '2' is specified. If option '2' is not specified, the DEST NAME parameter can be used by the application program to identify something else, such as the routine producing the change call. The destination for the print data set is established using a combination of initialization parameters or OUTDES parameters.

The following code example shows how to issue a CHNG call to the alternate modifiable PCB.

After the CHNG call is issued, the application program creates the print data set by issuing ISRT calls.

Issuing a CHNG call to the alternate modifiable PCB

***********************************************************************
*       ISSUE CHNG ON ALTPCB4                                         *
***********************************************************************
         L     9,ALTPCB4           ALT MODIFIABLE PCB
         LA    9,0(9)              CLEAR HIGH BYTE/BIT
         MVC   FUNC,=CL4'CHNG'     CHNG FUNCTION
         CALL  ASMTDLI,(FUNC,(9),DEST2,OPT1,FBA1),VL
         BAL   10,STATUS           CHECK STATUS OF CALL
*        ADDITIONAL PROGRAM LOGIC HERE
FUNC     DC    CL4' '
DEST2    DC    CL8'IAFP1'          LTERM NAME
*
         DC    C'OPT1'             OPTIONS LIST AREA
OPT1     DC    AL2(OPT1LEN),AL2(0)
         DC    C'IAFP='
OCC      DC    C'M'                DEFAULT TO MACHINE CHAR
OOPT     DC    C'1'                DEFAULT TO HOLD
OMSG     DC    C'M'                DEFAULT TO ISSUE MSG
         DC    C','
         DC    C'PRTO='
PRTO1    EQU   *
         DC    AL2(PRTO1LEN)
         DC    C'COPIES(2),CLASS(T),DEST(RMT003)'
PRTO1LEN EQU   *-PRTO1
         DC    C' '
OPT1LEN  EQU   *-OPT1
*
FBA1     DC    AL2(FBA1LEN),AL2(0)
         DC    CL40' '
FBA1LEN  EQU   *-FBA1

ISRT call to alternate PCB

Once the IMS Spool is specified as the destination of the PCB, ISRT calls can be issued against the alternate PCB.

The following code example shows how to issue the ISRT call to the alternate modifiable PCB.

The print data streams can be stored in databases or generated by the application, depending on the requirements of the application program and the type of data set being created.

Issuing an ISRT call to the alternate modifiable PCB

***********************************************************************
*       ISSUE ISRT TO ALTPCB4                                         *
***********************************************************************
         L     9,ALTPCB4           ALT MODIFIABLE PCB
         LA    9,0(9)              CLEAR HIGH BYTE/BIT
         MVC   FUNC,=CL4'ISRT'     ISRT FUNCTION
         CALL  ASMTDLI,(FUNC,(9),IOA2),VL
         BAL   10,STATUS           CHECK STATUS OF CALL
*        ADDITIONAL PROGRAM LOGIC HERE
FUNC     DC    CL4' '
IOA2     DC    AL2(IOA2LEN),AL2(0)
IOA21    DC    AL2(MSG2LEN),AL2(0)
         DC    C' '                CONTROL CHARACTER
         DC    C'MESSAGE TO SEND TO IMS SPOOL'
MSG2LEN  EQU   *-IOA21
IOA2LEN  EQU   *-IOA2

Program termination

After the calls are issued, the program sends a message back to originating terminal, issues a GU call to the I/O PCB, or terminates normally.