This document describes in five steps how to write your first COBOL RPC client program. It uses the standard call interface: CICS | Batch | IMS | Micro Focus.
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.
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.
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:
* 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.
* 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.
* 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.
* 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:
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.
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".
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.
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.
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:
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:
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.
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.
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.
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:
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.
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).