This document explains how clients use the RPC communication area and covers the following topics:
The RPC communication area is not relevant for servers.
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
to assign the COMM-ETB-BROKER-ID and server name, see COMM-ETB-SERVER-CLASS,
COMM-ETB-SERVER-NAME and
COMM-ETB-SERVICE-NAME
to assign the broker's COMM-ETB-USER-ID and
COMM-ETB-TOKEN
for use with conversational RPC (see Using Conversational RPC) to hold, for
example, the conversation ID, see COMM-ETB-CONV-ID
for use with EntireX Security to hold the broker's
COMM-ETB-PASSWORD,
COMM-ETB-SECURITY-TOKEN
and others
to keep the results of the last RPC request, for example the error code
The RPC communication area is also the API to the generic RPC services, for example:
Log on to broker and log off from broker. See Using Broker Logon and Logoff.
Open conversation, close conversation and close conversation with commit. See Using Conversational RPC.
When using reliable RPC function calls, do reliable RPC commit, do reliable RPC rollback, get reliable status. See Reliable RPC for COBOL Wrapper.
Create a Natural Security token. See Using the COBOL Wrapper with Natural Security and Impersonation.
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).
The COBOL Wrapper allows the RPC communication to be used in the following ways:
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.
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.
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.
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.
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.
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.
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:
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:
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:
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.
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:
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 . . .
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.