Writing Standard Call Interface Clients

This document describes in five steps how to write your first COBOL RPC client program. It uses the standard call interface: CICS | Batch | IMS.

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 and Initialize the RPC Communication Area

The RPC Communication Area is your interface (API) to RPC communication and the generic RPC service module COBSRVI.

How to declare the communication area in your RPC client program depends on the generation option External Clause, Linkage Section or Copybook (see RPC Communication Area under Generation Settings - Properties) and whether only copybook ERXCOMM is used, or both copybooks ERXCOMM and ERXVSTR are used.

The optional ERXVSTR copybook is an extension to the ERXCOMM copybook. It enables an RPC client to specify long data strings (e.g. passwords). For usage see ERXVSTR Copybook under Using the Generated Copybooks.

See the following code snippets:

Only Copybook ERXCOMM is Used

  • For External Clause Option 
    * Declare RPC communication area 
  01 ERX-COMMUNICATION-AREA EXTERNAL.
     COPY ERXCOMM.

* Initialize RPC communication area (see Note 1)
  INITIALIZE ERX-COMMUNICATION-AREA.

* Set version (see Note 2)
  MOVE "2000" to COMM-VERSION.
  • For Linkage Section option 
    * Declare RPC communication area
  01 ERX-COMMUNICATION-AREA.
     COPY ERXCOMM.

* Initialize RPC communication area (see Note 1)
  INITIALIZE ERX-COMMUNICATION-AREA.

* Set version (see Note 2)
  MOVE "2000" to COMM-VERSION.

Both Copybooks ERXCOMM and ERXVSTR are Used

  • For External Clause option 
    * Declare RPC communication area 
  01 ERX-COMMUNICATION-AREA EXTERNAL.
     COPY ERXCOMM.
  01 ERX-COMMUNICATION-VSTR EXTERNAL.
     COPY ERXVSTR. 

* Initialize RPC communication area (see Note 1)
  INITIALIZE ERX-COMMUNICATION-AREA.
  INITIALIZE ERX-COMMUNICATION-VSTR.

* Set version (see Note 2)
  MOVE "4000" to COMM-VERSION.
  • For Linkage Section option 
    * Declare RPC communication area
  01 ERX-COMMUNICATION-AREA.
     COPY ERXCOMM.
  01 ERX-COMMUNICATION-VSTR.
     COPY ERXVSTR. 

* Initialize RPC communication area (see Note 1)
  INITIALIZE ERX-COMMUNICATION-AREA.
  INITIALIZE ERX-COMMUNICATION-VSTR.

* Set version (see Note 2)
  MOVE "4000" to COMM-VERSION.

  • For Copybook option
    This step is obsolete in the client application and is omitted. 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.

Notes:

  1. The RPC communication area copybook ERXCOMM and - if used - its extension copybook ERXVSTR must be correctly initialized with the data formats. Do not move SPACES to them! Use, for example, a COBOL INITIALIZE statement.
  2. If the copybook ERXCOMM only is used, COMM-VERSION is set to "2000". If both copybooks are used (ERXCOMM and its extension ERXVSTR), COMM-VERSION is set to "4000".

Step 2: Declare the IDL Data Structures for Client Interface Objects

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 into your RPC client program as shown below. 

* Declare customer data to generated RPC Stubs
   01 CALC-AREA.
      COPY CALC.

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 RPC Stubs
 01 CALC-AREA.
    10 PARAMETER.
       15 OPERATOR                   PIC X.
       15 OPERAND1                   PIC S9(9) BINARY.
       15 OPERAND2                   PIC S9(9) BINARY.
       15 RESULT                     PIC S9(9) BINARY.

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

How to issue the request in your RPC client program depends on the generation option External Clause, Linkage Section or Copybook (see RPC Communication Area) and usage of the copybooks ERXCOMM and ERXVSTR. See following code snippets:

  • External Clause option 
       CALL "CALC" USING  OPERATOR OPERAND1 OPERAND2 RESULT
       ON EXCEPTION
*         Perform error-handling
       NOT ON EXCEPTION
          IF COMM-RETURN-CODE = ZERO
*            Perform success-handling
          ELSE
*            Perform error-handling (See Note 1)
          END-IF
   END-CALL.
  • Linkage Section option; copybook ERXCOMM is used only 
       CALL "CALC" USING  OPERATOR OPERAND1 OPERAND2 RESULT 
                     ERX-COMMUNICATION-AREA
       ON EXCEPTION
*         Perform error-handling
       NOT ON EXCEPTION
          IF COMM-RETURN-CODE = ZERO
*            Perform success-handling
          ELSE
*            Perform error-handling (See Note 1)
          END-IF
   END-CALL.
  • Linkage Section option; both copybooks ERXCOMM and ERXVSTR are used 
       CALL "CALC" USING  OPERATOR OPERAND1 OPERAND2 RESULT 
                      ERX-COMMUNICATION-AREA
                      ERX-COMMUNICATION-VSTR
       ON EXCEPTION
*      Perform error-handling
       NOT ON EXCEPTION
          IF COMM-RETURN-CODE = ZERO
*            Perform success-handling
          ELSE
*            Perform error-handling (See Note 1)
          END-IF
   END-CALL.
  • Copybook option 
       CALL "CALC" USING  OPERATOR OPERAND1 OPERAND2 RESULT
       ON EXCEPTION
*      Perform error-handling
       NOT ON EXCEPTION
          IF RETURN-CODE = ZERO
*            Perform success-handling
          ELSE
*            Perform error-handling (See Note 2)
          END-IF
   END-CALL.

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.
  2. Because the RPC communication area is not used for data exchange between the client application and the client interface objects, 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 COBEXIT copybook (see folder include).