Programming a CICS-DPL-COBOL application & setting up the region.

DPL (Distributed Program Link) enables a Local CICS program to issue a EXEC CICS LINK to a program in the remote CICS region which return control to the calling program. DPL provides the below advantages for a CICS application.

1. It allows a non OS390/zOS application to use DL/I, SQL, BDAM and VSAM files owned by a zOS/os390 system.
2. Allows CICS programmer to use LU 6.2 link Protocol without knowing the protocol.

Restrictions of DPL.

You cannot use the below CICS services on the remote application.

1. You cannot issue any terminal control commands. e.g. SEND, RECEIVE.
2. No BMS commands.
3. No security commands like SIGNON or SIGNOFF.

If you are receiving any abends on the remote application and it didn’t handle the abend by itself then, abend code will returned to the Main program.

Defining and installing CICS entries.

Assume that you have a Mainframe connectivity like below.

Here I have 2 TSO sessions, 8 CICS regions, 2 IMS, 1 CICSPlex/SM and few Session manager setups and Misce sessions.

I am using the CICSA and CICSB regions, I.e my Main program is in CICSA and it then calling the program on CICSB using a COMMAREA, second program will write the message passed in commarea into a VSAM file, set a message onto COMMAREA and returns into CICSA region.

Before you are getting started with your program, make sure that MRO/ISC is configured in your Mainframe, you can contact you system Admin or follow my instructions below.

1. Go to your CICS region batch job in spool.
2. Open the JESYSMSG and Check for ISC and IRCSTRT init parms are setup to YES.
3. IF the above initparms are not setup to YES then you need to ask your sysadmin to set this up before you continue with DPL program.

Usually SYSADMIN do the below steps to setup ISC or IRCSTRT.

1. Bring down CICS region using master console or Perform SHUTDOWN using CEMT.
2. Find SIP parameter for the region.
3. Go to SYSIN PDS of the Installed CICS TS.
4. Find the DFH$SIP<SIP PARM> member and add the ISC and IRCSTRT parms.
5. Restart CICS region.

You can also issue a CEMT I IRC to check whether IRC is setup for the region.

Steps to create CICS table entries for a DPL program.

1. Define and Install the main program on LOCAL CICS region as usual.
2. Define and install Mirror Entries of remote CICS transaction and program on LOCAL CIS region. Set the remote Attributes (Remote System as the 4 digit remote CICS region ID, and program name) You can see the remote system ID on SYSID field once you issue a CEMT/CEDA command (See below screenshots).
3. Go to Remote CICS region and define and Install only remote Program and Transaction.
4. Compile CICS programs and move Load module to the respective libraries of local and Remote CICS regions.
5. Perform New copy for the Local program on Local CICS region and Remote program on remote region.
6. Invoke the Local CICS program using the defined Transaction on Local CICS region.

DPL Sample program

Main program.

IDENTIFICATION DIVISION. PROGRAM-ID. CDPL01A. AUTHOR.     SHIBU.T. * DATA DIVISION. WORKING-STORAGE SECTION. 77  WS-MSG-1                    PIC X(100). 77  WS-MSG-LEN                  PIC S9(4) COMP. * 01  WS-COMMAREA.      02  WS-RECID                PIC X(10).      02  WS-MSG                  PIC X(40).      02  WS-PROG-ID              PIC X(08). LINKAGE SECTION. 01  DFHCOMMAREA.      02  LS-COMMAREA.          03  LS-RECID            PIC X(10).          03  LS-MSG              PIC X(40).          03  LS-PROG-ID          PIC X(08). PROCEDURE DIVISION. A0001-MAIN-PARA.      MOVE SPACES                 TO WS-COMMAREA WS-MSG-1.      IF EIBCALEN = 0 THEN         PERFORM A00150-INITIALIZE      ELSE         PERFORM A00200-LINK      END-IF. * A00150-INITIALIZE.      MOVE 'PROGRAM ON CICSAOR1 REGION'                                  TO WS-MSG.      MOVE '1000000123'           TO WS-RECID.      MOVE 'CDPL01A'              TO WS-PROG-ID.      MOVE 'WS-MSG BEFORE DPL: '  TO WS-MSG-1(1:20).      MOVE WS-MSG                 TO WS-MSG-1(21:26).      MOVE '* PROGRAM-ID: '       TO WS-MSG-1(47:14).      MOVE WS-PROG-ID             TO WS-MSG-1(61:08).      EXEC CICS SEND TEXT          FROM(WS-MSG-1)          ERASE      END-EXEC.      EXEC CICS RETURN          TRANSID('AA05')          COMMAREA(WS-COMMAREA)      END-EXEC. * A00200-LINK.      MOVE LS-COMMAREA            TO WS-COMMAREA.      EXEC CICS LINK          PROGRAM('CDPL01B')          COMMAREA(WS-COMMAREA)      END-EXEC.      MOVE SPACES                 TO WS-MSG-1.      MOVE 'WS-MSG AFTER  DPL: '  TO WS-MSG-1(1:20).      MOVE WS-MSG                 TO WS-MSG-1(21:26).      MOVE '* PROGRAM-ID: '       TO WS-MSG-1(47:14).      MOVE WS-PROG-ID             TO WS-MSG-1(61:08).      EXEC CICS SEND TEXT          FROM(WS-MSG-1)          ERASE      END-EXEC.      EXEC CICS RETURN      END-EXEC.

Sub Program on Remote region.

IDENTIFICATION DIVISION. PROGRAM-ID. CDPL01B. AUTHOR.     SHIBU.T. * DATA DIVISION. WORKING-STORAGE SECTION. 77  WS-MSG-1                    PIC X(100). 77  WS-MSG-LEN                  PIC S9(4) COMP. 01  WS-FILE-DT.      02  WS-DAT.          03  WS-KEY              PIC X(10).          03  WS-DAT1             PIC X(40) VALUE SPACES.          03                      PIC X(60) VALUE SPACES. * 01  WS-COMMAREA.      02  WS-RECID                PIC X(10) VALUE SPACES.      02  WS-MSG                  PIC X(40).      02  WS-PROG-ID              PIC X(08). LINKAGE SECTION. 01  DFHCOMMAREA.      02  LS-COMMAREA.          03  LS-RECID            PIC X(10).          03  LS-MSG              PIC X(40).          03  LS-PROG-ID          PIC X(08). PROCEDURE DIVISION USING DFHCOMMAREA. A0001-MAIN-PARA. *    MOVE SPACES                 TO WS-COMMAREA WS-MSG-1.      MOVE LS-RECID               TO WS-KEY.      MOVE LS-MSG                 TO WS-DAT1.      EXEC CICS WRITE           DATASET('VFILE1')           FROM(WS-DAT)           LENGTH(LENGTH OF WS-DAT)           RIDFLD(WS-KEY)      END-EXEC.      MOVE 'PROGRAM ON CICSAORB REGION'                                  TO WS-MSG.      MOVE 'CDPL01B'              TO WS-PROG-ID.      MOVE WS-COMMAREA            TO LS-COMMAREA.      EXEC CICS RETURN      END-EXEC.

Compile aCICS programs and Move load modules to respective LOAD LIBS of CICS regions.

Please refer to http://mainframegeek.wordpress.com/2011/10/11/prepare-compile-define-install-execute-a-cics-cobol-program/ for more info on how to prepare compile a COBOL-CICS program, how to find LOAD LIB od CICS region and move the Load module.

Defining and Installing Resources to CICS.

On CICS REGION CICSA

Step 1 Create and Install Program entries for the Main program on CICSA, defining is similar to a normal CICS program.

Step 2 Install the program.

Step 3 Define Transaction Entry for Main program on CICSA, you need to mention main program name (CDPL01A) while defining Transaction entry.

Step 4  Install the transaction.

Step 5 Define Mirror Program.

Step 6 Define and Install Mirror Transaction.

on remote region

Step 7 Define, Install Program and Transaction entries .

Step 9 Execute Program.

Issue AA05 on CICSA to execute program, do a cedf if you want to see what is exactly happening in the program. This is a pseudo-conversation program, it displays commarea content before links to the remote app. Press enter to issue LINK.

Control came back from Remote app, you can see the commarea contents which set up by remote app.

You can also open the file to ensure that Remote app is getitng COMMAREA conts correctly ( Remote app will write the commarea contents to VSAM file). Look for th last line, that is the message passed on commarea.