Using the RPC Communication Area

This document explains how clients use the RPC communication area and covers the following topics:

The RPC communication area is not relevant for servers.


Purpose of the RPC Communication Area

The RPC communication area is mainly used to specify parameters that are needed to communicate with the broker and are not specific to client interface objects. In this way it defines a context for RPC clients. Its purpose, among others, is

The RPC communication area is also the API to the generic RPC services, for example:

From a COBOL point of view, the RPC communication area is the copybook ERXCOMM. It is generated in the folder include for RPC client generation, see Generating COBOL Source Files from Software AG IDL Files.

The layout of the RPC communication area is described in section The RPC Communication Area (Reference).

Using the RPC Communication Area with a Standard Call Interface

The COBOL Wrapper allows the RPC communication to be used in the following ways:

Option External Clause

This kind of RPC communication area usage applies to the scenarios CICS | Batch | IMS | Micro Focus.

With the RPC communication area option External Clause under RPC Communication Area, the RPC communication area is passed using the COBOL External clause to the client interface objects. Note that this is an extension to COBOL 85 standards, which might not be supported by every compiler.

The RPC communication area is allocated (declared) in the COBOL client application. The client interface objects are statically linked (it is not possible to call them dynamically) to the COBOL client application. It is important that the RPC communication area is initialized correctly with the data format defined in the copybook ERXCOMM, otherwise results will be unpredictable. Do not move SPACES to ERX-COMMUNICATION-AREA! The easiest approach is to use a COBOL INITIALIZE statement.

Examples

For examples on how the option External Clause is used correctly, see Step 1: Declare and Initialize the RPC Communication Area and Step 5: Issue the RPC Request in Writing Standard Call Interface Clients.

Option Linkage Section

This kind of RPC communication area usage applies to the scenarios CICS | Batch | IMS | Micro Focus.

With the RPC communication area option Linkage Section under RPC Communication Area, the client interface objects are generated are generated to receive the RPC communication area with an additional parameter from the COBOL client program.

The RPC communication area is allocated (declared) in the COBOL client application in the working storage section. The client interface objects can be statically linked or called dynamically. For IBM compilers, refer to documentation on the DYNAM compiler option; for other compilers, to your compiler documentation. It is important that the RPC communication area is initialized correctly with the data format defined in the copybook ERXCOMM, otherwise results will be unpredictable. Do not move SPACES to ERX-COMMUNICATION-AREA! The easiest approach is to use a COBOL INITIALIZE statement. See example below.

Example

The example given below will pass the RPC communication area via the COBOL Linkage section to the client interface objects. It differs in two steps from the example in Writing Standard Call Interface Clients (which uses option External Clause):

Step 1 has no EXTERNAL attribute.

 01 ERX-COMMUNICATION-AREA.
     COPY ERXCOMM.
* Initialize RPC communication area
     INITIALIZE ERX-COMMUNICATION-AREA.
     MOVE "2000" TO COMM-VERSION.

Step 5 will include the RPC communication area as an extra parameter.

     CALL "CALC" USING  OPERATOR
                        OPERAND1
                        OPERAND2
                        FUNCTION-RESULT
                        ERX-COMMUNICATION-AREA
       ON EXCEPTION
*      Perform error-handling
       NOT ON EXCEPTION
          IF RETURN-CODE = ZERO
*            Perform success-handling
          ELSE
*            Perform error-handling
          END-IF
     END-CALL.

With this example the client interface objects are generated, for example for target platform "z/OS", client interface type "Batch with standard linkage calling convention" and RPC communication area "Linkage Section". See Generating COBOL Source Files from Software AG IDL Files.

Option Copybook

This kind of RPC communication area usage is available in z/OS operating system and Micro Focus environments. Refer to the scenarios CICS | Batch | IMS | Micro Focus.

With the RPC communication area option Copybook under RPC Communication Area, the client interface objects are generated with an RPC communication area in their working storage section.

The RPC communication area is not visible in the client application - it is local to the client interface objects. The client interface objects can be statically linked or called dynamically. For IBM compilers, refer to documentation on the DYNAM compiler option and for other compilers to your compiler documentation.

Example

With option copybook, two steps are different from the example in Writing Standard Call Interface Clients (which uses option External Clause):

  • Step 1: Declare and Initialize the RPC Communication Area

    This step is obsolete in the client application and is omitted there. Default values for the RPC communication area are retrieved from Designer preferences or IDL-specific properties. If required, those default values can be overwritten in the COBINIT Copybook.

  • Step 6: Examine the Error Code

    Because the RPC communication area is not used for data exchange between the client application and the client interface objects (see Purpose of the RPC Communication Area), the COMM-RETURN-CODE field in the RPC communication area cannot be checked directly upon return from RPC calls. Therefore, the COBOL mechanism RETURN-CODE special register is used to provide errors from client interface objects to the client application. For IBM compilers, errors can be adapted in the copybook COBEXIT (see folder include).

    After the RPC reply has been received, you can check if the call was successful using the RETURN-CODE special register:

 IF RETURN-CODE IS = ZERO
*    Perform success-handling
 ELSE
*    Perform error-handling
 END-IF.

Using the RPC Communication Area with EXEC CICS LINK

This kind of RPC communication area usage applies to the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE).

The RPC communication area is allocated (declared) in the COBOL client application and passed in the DFHCOMMAREA to the client interface objects. It is important that the RPC communication area is initialized correctly with the data format defined in the copybook ERXCOMM, otherwise results will be unpredictable. Do not move SPACES to ERX-COMMUNICATION-AREA! The easiest approach is to use a COBOL INITIALIZE statement. See examples below:

Example 1

Two steps are different from the example in Writing a COBOL RPC Client Application. See Writing Standard Call Interface Clients. Assume CALC is your generated IDL interface copybook:

Copybook CALC

  3 OPERATOR                   PIC X.
  3 OPERAND1                   PIC S9(8) COMP.
  3 OPERAND2                   PIC S9(8) COMP.
  3 RESULT                     PIC S9(8) COMP.

Step 1 contains the IDL interface copybook as well as the RPC communication area within one area:

RPC Client Program

01 CALC-AREA.
  COPY CALC
  03 ERX-COMMUNICATION-AREA.
     COPY ERXCOMM.
* Initialize RPC communication area
     INITIALIZE ERX-COMMUNICATION-AREA.
     MOVE "2000" TO COMM-VERSION.

Step 5 uses EXEC CICS LINK interface:

 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
    END-IF
 ELSE
*    Perform error-handling
 END-IF.

With this example, the client interface objects are generated e.g. for target platform "z/OS", client interface type "CICS with DFHCOMMAREA Calling Convention", and RPC communication area "Linkage Section". See Generating COBOL Source Files from Software AG IDL Files.

Example 2

Assume your IDL File contains an unbounded array that is mapped to OCCURS DEPENDING ON (see Mapping Fixed and Unbounded Arrays). Your generated IDL interface copybook looks similar to:

Copybook MYIDL

    3 IDL-FIELD1                 PIC X(8).
    3 IDL-FIELD2                 PIC X(32).
    3 . . .
    3 ODO-OBJECT                 PIC 9(8) BINARY.
    3 ODO-SUBJECT OCCURS 1 TO 24 DEPENDING ON ODO-OBJECT.
      4 ODO-FIELD1               PIC X(5).
      4 ODO-FIELD1               PIC X(1).
      4 . . .

RPC Client Program

In your RPC client program, embed the IDL interface copybook MYIDL as shown below. Use a subprogram for proper initialization of the RPC communication area. It is important to set the ODO object to the required value for upper-bound before you call the initialization subprogram:

  01 IDL-AREA.
    COPY MYIDL.
    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. 

* 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 RPC-COMMUNICATION-AREA.
      MOVE '2000'       TO COMM-VERSION.
      MOVE '<brokerid>' TO COMM-ETB-BROKER-ID.
      MOVE 'RPC'        TO COMM-ETB-SERVER-CLASS.
      MOVE '<server>'   TO COMM-ETB-SERVER-NAME.
      MOVE 'CALLNAT'    TO COMM-ETB-SERVICE-NAME.
      MOVE '<userid>'   TO COMM-USERID.
      MOVE . . .
      EXIT PROGRAM.
  END PROGRAM INIT-RPC.