COBOL and PLI Programming Considerations | An Introduction to IMS: Your Complete Guide to IBMs Information Management System

COBOL and PL/I Programming Considerations

This section discusses programming considerations that are unique to the COBOL and PL/I programming languages.

The basic programming considerations for Java are discussed in Chapter 18, "Application Programming in Java," on page 311.

COBOL Programming Considerations

A few considerations apply when you are coding DL/I programs in COBOL. In the text that follows Figure 15-12, the numbers between parentheses map to the line numbers in Figure 15-12. Specific parameter values and formats are described throughout the rest of this chapter.

Figure 15-12. Example of a COBOL Batch Program

 ID  DIVISION.                                                               000001                                                                          000002 ENVIRONMENT DIVISION.                                                    000003                                                                          000004 DATA DIVISION.                                                           000005 WORKING-STORAGE SECTION.                                                 000006 77          GU-FUNC            PIC XXXX    VALUE    'GU'.             000007 77          GN-FUNC            PIC XXXX    VALUE    'GN'.             000008 77          ERROPT             PIC XXXX    VALUE    '1 '.             000009 77          DERRID             PIC X(8)    VALUE    'DERROR01'.          000010 01          IOAREA             PIC X(256)  VALUE SPACES.                 000011 01          SSA001-GU-SE1PART.                                           000012              02 SSA001-BEGIN     PIC X(19) VALUE 'SE1PART (FE1PGPNR ='.  000013              02 SSA001-FE1PGPNR  PIC X(8).                               000014              02 SSA001-END       PIC X     VALUE ')'.                    000015                                                                          000016 LINKAGE SECTION.                                                         000017 01         D1PC.                                                         000018              02   D1PCDBN   PIC X(8).                                    000019              02   D1PCLEVL  PIC 99.                                      000020              02   D1PCSTAT  PIC XX.                                      000021              02   D1PCPROC  PIC XXXX.                                    000022              02   D1PCRESV  PIC S9(5) COMP.                              000023              02   D1PCSEGN  PIC X(8).                                    000024              02   D1PCKFBL  PIC S9(5) COMP.                              000025              02   D1PCNSSG  PIC S9(5) COMP.                              000026              02   D1PCKFBA  PIC X(20).                                   000027                                                                          000028 PROCEDURE DIVISION.                                                      000029   ENTRY 'DLITCBL' USING D1PC.                                            000030   :                                                                      000031   :                                                                      000032   CALL 'CBLTDLI' USING GU-FUNC, D1PC, IOAREA,                            000033        SSA001-GU-SE1PART.                                                000034   :                                                                      000035   CALL 'CBLTDLI' USING GN-FUNC, D1PC, IOAREA.                            000036   IF D1PCSTAT NOT = '',                                               000037      CALL 'ERRRTN' USING D1PC, DERRID, IOAREA, ERROPT.                   000038      MOVE +4 TO RETURN-CODE.                                             000039   :                                                                      000040   CALL DFSOAST USING D1PC.                                               000041   :                                                                      000043   :                                                                      000044   GOBACK.                                                                000045

In Figure 15-12:

The DL/I function codes (line 7), IOAREA (line 11), and segment search arguments (line 12) should be defined in the working-storage section of the data division. Typically, either the IOAREA is redefined to provide addressability to the fields of each segment, or separate IOAREAs are defined for each segment.
The PCBS should be defined in the linkage section of the data division (line 18). When multiple database structures and thus multiple PCBs exist in a program, one PCB must be defined in the linkage section for each PCB in the PSB. However, these PCBs need not be in any specific order.
Code an ENTRY statement (line 30) at the entry to your program. A parameter of the USING clause should exist for each database structure (PCB) that is used in your program. The order of PCBs in this clause must be the same as the order that is specified in PSB for your program.
Each DL/I CALL statement should be coded like the statement on line 33. The parameters of the DL/I CALL statement differ in number for different functions and are explained elsewhere in this chapter.
The status code in the PCB should be checked after each call (line 37). The status-code error routine (line 38) is described in "Status Code Processing" on page 228.
At the end of processing, control must be returned to DL/I through a GOBACK statement (line 44). Optionally, you can set the COBOL RETURN-CODE (line 39). If DL/I detects no errors, and thus does not set the return code, the COBOL RETURN-CODE value is passed on to the next job step.

PL/I Programming Considerations

A few considerations apply when you are coding DL/I programs in PL/I. In the text that follows Figure 15-13, the numbers between parentheses map to the line numbers in Figure 15-13. Specific parameter values and formats are described throughout this rest of this chapter.

Figure 15-13. Example of a PL/I Batch Program

 /*------------------------------------------------------------------*/ 000001 /*                  SAMPLE PL/I PROGRAM                             */ 000002 /*------------------------------------------------------------------*/ 000003 PE2PROD:                                                               000004 PROCEDURE (DC_PTR,DB_PTR) OPTIONS (MAIN);                              000005 /*        DECLARE POINTERS AND PCBS.                                */ 000006  DECLARE                                                               000007    PLITDLI ENTRY,                              /* DL/I WILL BE CALLD*/ 000008    DFSOAST ENTRY OPTIONS (ASSEMBLER INTER),    /* STATISTICS PRINT  */ 000009    DFSOAER ENTRY OPTIONS (ASSEMBLER INTER),    /* STATUS CODE PRINT */ 000010    DC_PTR POINTER,                             /* CHPAT IN PSB      */ 000011    DB_PTR POINTER,                             /* ORDER DB PCB      */ 000012   01 CLPC BASED (DC_PTR),                      /* NOT USED IN       */ 000013      02 DUMMY CHAR (32),                       /* BATCH DL/I        */ 000014   01 DLPC BASED (DB_PTR),                      /* PHASE 2 ORDER DB  */ 000015      02 DLPCDBDN CHAR (8),                     /* DBD NAME          */ 000016      02 DLPCLEVL CHAR (2),                     /* SEGMENT LEVEL     */ 000017      02 DLPCSTAT CHAR (2),                     /* STATUS CODE       */ 000018      02 DLPCPROC CHAR (4),                     /* PROCESSING OPTN   */ 000019      02 OLPCRESV FIXED BINARY(31),             /* RESERVED          */ 000020      02 DLPCSEGN CHAR (8),                     /* SEGMENT NAME      */ 000021      02 DLPCKFBL FIXED BINARY(31),             /* KEY FEEDBACK LNG  */ 000022      02 DLPCNSSG FIXED BINARY(31),             /* N0. OF SENSEGS    */ 000023      02 DLPCKFBA CHAR (14);                    /* KEY FEEDBACK      */ 000024 /*  DECLARE FUNCTION CODES, I/0 AREA, CALL ARG LIST LENGTHS         */ 000025   DECLARE                                                              000026     IO_AREA CHAR (256),                        /* I/0 AREA          */ 000027     GU_FUNC STATIC CHAR (4) INIT ('GU'),       /* CALL FUNCTION     */ 000028     FOUR STATIC FIXED BINARY (31) INIT ( 4 ),  /* ARG LIST LENGTH   */ 000029     ERROPT1 CHAR (4) INIT ('0') STATIC,        /* OPTN FOR DFSOAER  */ 000030     ERROPT2 CHAR (4) INIT ('2') STATIC,        /* FINAL OPTN:DFSOAER*/ 000040     DERRID CHAR (8) INIT ('DERFORO1') STATIC;  /* ID FOR DFSOAER    */ 000041 /* DECLARE SEGMENT SEARCH AFGUMENT (SSA) - ORDER SEGMENT.           */ 000042   DECLARE                                                              000043    01 SSA007_GU_SE2ORDER,                                              000044       02 SSA007_BEGIN CHAR (19) INIT ('SE2ORDER(FE2OGPEF ='),          000045       02 SSA007_FE2OGPEF CHAR (6),                                     000046       02 SSA007_END CHAR (1) INIT ('1');                               000047 /* PROCESSING PORTION OF THE PROGRAM                                */ 000048  SSA007_FE2OGPEF = 'XXXXXX';                   /* SET SSA VALUE     */ 000049  CALL PLITDLI (FOUR,GU_FUNC,DB_PTR,IO_AREA,    /* THIS CALL WILL    */ 000050              SSA007_GU_SE2ORDER);              /* RETURN 'GE' STAT  */ 000060  IF DLPCSTAT ^= ' ' THEN DO;                   /* CALL ERROR PRINT  */ 000061     CALL DFSOAER (DLPC,DERRID,IO_AREA,ERROPT1);                        000062     CALL DFSOAER (DLPC,DERRID,IO_AREA,ERROPT2);/* FINAL CALL TO ERR */ 000063  END;                                                                  000064 /* RETURN TO CALLER.                                                */ 000065   END PE2PROD;                                                         000066

When DL/I invokes your PL/I program, it passes the addresses, in the form of pointers, to each PCB that is required for execution. These pointers are passed in the same sequence as specified in the PSB. To use the PCBs, you must code parameters in your PROCEDURE statement, and declare them to have the attribute POINTER.

In Figure 15-13, DC_PTR and DB_PTR are specified in the PROCEDURE statement (line 5) and declared as POINTER variables (lines 11 and 12). Use these pointer variables to declare the PCBs as BASED structures (lines 13 and 15), and in calling DL/I (line 50).

The format of the PL/I CALL statement to invoke DL/I (line 50) is:

 CALL PLITDLI (parmcount, function, pcb-ptr, io-area,ssal,...,ssan):

parmcount

The number of arguments in this call that follow this argument. The value of parmcount must have the attributes FIXED BINARY (31). See line 29.

function

The DL/I function code. The function code must be a fixed-length character string of length four.

pcb-ptr

A pointer variable that contains the address of the PCB. The pcb-ptr is normally the name of one of the parameters passed to your program at invocation.

io-area

The storage in your program into which and from which DL/I stores or fetches data. The io-area can be a major structure, a connected array, a fixed-length character string (CHAR (n)), a pointer to any of these, or a pointer to a minor structure. The io-area cannot be the name of a minor structure of a character string with the attribute VARYING.

ssa1...

One or more optional segment search arguments. Each SSA must be in one of the same PL/I forms allowed for io-areas. See line 44 in Figure 15-13 on page 264.

Upon completion of your program, you should return control to DL/I by either using a RETURN statement or by executing the main procedure END statement.