Writing EXEC CICS LINK Clients

This document describes in five steps how to write your first COBOL RPC client program for an EXEC CICS LINK interface. You can also write an RPC client for CICS with a standard call interface, see Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE).

The example given here does not use function calls as described under Using Broker Logon and Logoff. It demonstrates an implicit broker logon (because no broker logon/logoff calls are implemented), where it is required to switch on the AUTOLOGON feature in the broker attribute file.

Step 1: Declare IDL Structures and RPC Communication Area

For every program definition of the IDL file, the COBOL Wrapper generates an IDL interface copybook with the description of the customer's interface data as a COBOL structure. For ease of use you can include these structures together with the RPC communication area copybook ERXCOMM into your RPC client program. The RPC communication area is your interface (API) to RPC communication and the Generation and Usage of Generic RPC Service Module COBSRVI.

Definition is physically in a specific order (see code snippet below):

  • A parent label on COBOL level 01 (here label CALC-AREA) is followed by the IDL interface copybook (here copybook CALC).

  • Then comes a COBOL label with the RPC communication area below (here label RPC-COMMUNICATION-AREA together with copybook ERXCOMM).

Label names could be different in your application, but the physical sequence of labels and copybooks are important. See following code snippets:

See following code snippets:

* Declare customer data to generated client interface objects
 01 CALC-AREA.
   COPY CALC
* Declare RPC communication area
   03 ERX-COMMUNICATION-AREA.
      COPY ERXCOMM.

However, as an alternative, you can use your own customer data structures. In this case the COBOL data types and structures must match the interfaces of the generated client interface objects, otherwise unpredictable results may occur. 

* Declare customer data to generated client interface objects
 01 CALC-AREA.
   03 OPERATOR                   PIC X.
   03 OPERAND1                   PIC S9(8) COMP.
   03 OPERAND2                   PIC S9(8) COMP.
   03 RESULT                     PIC S9(8) COMP.
* Declare RPC communication area
   03 ERX-COMMUNICATION-AREA.
      COPY ERXCOMM.

Step 2: Initialize the RPC Communication Area

  . . .

* Call subprogram to initialize the RPC Communication Area (see Note 1)
  CALL "INIT-RPC" USING ERX-COMMUNICATION-AREA. 
* Set version (see Note 2)
  MOVE "2000" to COMM-VERSION.
  . . .

* Subprogram to initialize the RPC communication area
  IDENTIFICATION DIVISION.
  PROGRAM-ID. INIT-RPC.
  DATA DIVISION.
  LINKAGE SECTION.
   01 RPC-COMMUNICATION-AREA.
      COPY ERXCOMM.
  PROCEDURE DIVISION USING RPC-COMMUNICATION-AREA.
  MAIN SECTION.
* Initialize the RPC Communication Area (see Note 3)
      INITIALIZE RPC-COMMUNICATION-AREA.
      EXIT PROGRAM.
  END PROGRAM INIT-RPC.

Notes:

  1. If your generated IDL interface copybook contains a COBOL table with an OCCURS DEPENDING ON clause, originating from an IDL unbounded array, it is important to set the ODO object to the required value for upper-bound before you call the initialization subprogram. (Refer to Fixed and Unbounded Arrays in the IDL Editor documentation.) See the following code snippet: 
    . . . 
01 IDL-AREA.
   03 IDL-FIELD1                 PIC X(8).
   03 IDL-FIELD2                 PIC X(32).
   03 . . .
   03 ODO-OBJECT                 PIC 9(8) BINARY.
   03 ODO-SUBJECT OCCURS 1 TO 24 DEPENDING ON ODO-OBJECT.
      04 ODO-FIELD1              PIC X(5).
      04 ODO-FIELD1              PIC X(1).
      04 . . .
    03 ERX-COMMUNICATION-AREA.
       COPY ERXCOMM.
. . . 
* Set the ODO object to required value for input
      MOVE <upper-bound> TO ODO-OBJECT.
      MOVE . . .
* Initialize RPC communication area
      CALL "INIT-RPC" USING ERX-COMMUNICATION-AREA. 
. . .
  2. Because only copybook ERXCOMM is used, COMM-VERSION is set to "2000".
  3. The RPC communication area copybook ERXCOMM must be correctly initialized with the data formats. Do not move SPACES to it! Use, for example, a COBOL INITIALIZE statement.

Step 3: Required Settings in the RPC Communication Area

The following settings to the RPC communication area are required as a minimum to use the COBOL Wrapper. These settings have to be applied in your RPC client program. It is not possible to generate any defaults into the client interface objects. 

* assign the broker to talk with ...
 MOVE "localhost:1971" to COMM-ETB-BROKER-ID.
* assign the server to talk with ...
 MOVE "RPC"            to COMM-ETB-SERVER-CLASS.
 MOVE "SRV1"           to COMM-ETB-SERVER-NAME.
 MOVE "CALLNAT"        to COMM-ETB-SERVICE-NAME.
* assign the user id to the broker ...
 MOVE "ERXUSER"        to COMM-USERID.

Step 4: Optional Settings in the RPC Communication Area

Here you specify optional settings to the RPC communication area used by the COBOL Wrapper, for example: 

 MOVE "EXAMPLE"        to COMM-LIBRARY.
 MOVE "00000300"       to COMM-ETB-WAIT.
 MOVE "PASSWORD"       to COMM-PASSWORD.  (Note 1)

Notes:

  1. For Implicit Logon, if required in your environment, the client password can be given here. It is provided then through the client interface object. If you have to issue an Explicit Logon, see Using Broker Logon and Logoff.

Step 5: Issue the RPC Request and Check for Success

See following code snippets:

 MOVE LENGTH OF CALC-AREA TO COMLEN.
 EXEC CICS LINK PROGRAM("CALC") COMMAREA(CALC-AREA)
           LENGTH(COMLEN) RESP(WORKRESP)
 END-EXEC.
 IF WORKRESP = DFHRESP(NORMAL)
    IF (COMM-RETURN-CODE = 0) THEN
*       Perform success-handling
    ELSE
*       Perform error-handling (See Note 1)
    END-IF
 ELSE
*    Perform error-handling
 END-IF.

Notes:

  1. The field COMM-RETURN-CODE in the RPC communication area contains the error provided by the COBOL Wrapper. For the error messages returned, see Error Messages and Codes.