This document explains how clients built with the COBOL Wrapper use conversational RPC.
RPC conversations are supported when communicating with an RPC server. It is further assumed that you are familiar with the concepts of conversational RPC and non-conversational RPC. To use conversational RPC, you need the following components:
the Delivered Modules are provided to open, close or abort conversations
The code you write depends on the interface type:
This interface type applies to the scenarios CICS | Batch | IMS | Micro Focus.
To use conversational RPC
Declare and initialize the RPC communication area with one of the approaches described under
Step 1: Declare and Initialize the RPC Communication Area in section Writing Standard Call Interface Clients.
Here you can use copybook ERXCOMM
only, or
both copybooks ERXCOMM
and ERXVSTR
.
Open a conversation with the function Open Conversation
OC
provided by the generic RPC services module.
The code snippet below illustrates the variant where only copybook ERXCOMM
is used.
If you are using both copybooks ERXCOMM
and ERXVSTR
, see Note 1.
MOVE "OC" TO COMM-FUNCTION. * Call generic RPC service module to use conversational mode (Note 1) CALL "COBSRVI" USING ERX-COMMUNICATION-AREA ON EXCEPTION * Perform error-handling NOT ON EXCEPTION IF (COMM-RETURN-CODE = 0) THEN * Perform success-handling ELSE * Perform error-handling (See Note 2) END-IF END-CALL.
Issue your RPC requests as within non-conversational mode using the generated client interface objects. Different client interface objects can participate in the same RPC conversation.
To abort conversational RPC communication
Abort an unsuccessful RPC conversation with the function Close
Conversation CB
provided by the generic RPC services
module.
The code snippet below illustrates the variant where only copybook ERXCOMM
is used.
If you are using both copybooks ERXCOMM
and ERXVSTR
, see Note 1.
MOVE "CB" TO COMM-FUNCTION. * Call generic RPC service module to use conversational mode (Note 1) CALL "COBSRVI" USING ERX-COMMUNICATION-AREA ON EXCEPTION * Perform error-handling NOT ON EXCEPTION IF (COMM-RETURN-CODE = 0) THEN * Perform success-handling ELSE * Perform error-handling (See Note 2) END-IF END-CALL.
To close and commit a conversational RPC communication
Close the RPC conversation successfully with the function Close
Conversation and Commit CE
provided by the generic RPC
services module.
The code snippet below illustrates the variant where only copybook ERXCOMM
is used.
If you are using both copybooks ERXCOMM
and ERXVSTR
, see Note 1.
MOVE "CE" TO COMM-FUNCTION. * Call generic RPC service module to use conversational mode (Note 1) CALL "COBSRVI" USING ERX-COMMUNICATION-AREA ON EXCEPTION * Perform error-handling NOT ON EXCEPTION IF (COMM-RETURN-CODE = 0) THEN * Perform success-handling ELSE * Perform error-handling (See Note 2) END-IF END-CALL.
Notes:
ERXCOMM
and ERXVSTR
are used, you need to pass both parameters:
CALL "COBSRVI" USING ERX-COMMUNICATION-AREA ERX-COMMUNICATION-VSTR.
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.
This interface type applies to the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA
Calling Convention (z/OS and z/VSE).
To use conversational RPC
Declare the RPC communication area as described under Step 1: Declare IDL Structures and RPC Communication Area in section Writing EXEC CICS LINK
Clients.
Initialize the RPC communication area as described under Step 2: Initialize the RPC Communication Area under Writing EXEC CICS LINK
Clients.
Open a conversation with the function Open Conversation
OC
provided by the generic RPC services module:
MOVE "OC" TO COMM-FUNCTION. EXEC CICS LINK PROGRAM ("COBSRVI") RESP (CICS-RESP1) RESP2 (CICS-RESP2) COMMAREA (ERX-COMMUNICATION-AREA) LENGTH (LENGTH OF ERX-COMMUNICATION-AREA) 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.
Issue your RPC requests as within non-conversational mode using the generated client interface objects. Different client interface objects can participate in the same RPC conversation.
To abort conversational RPC communication
Abort an unsuccessful RPC conversation with the function Close
Conversation CB
provided by the generic RPC services
module:
MOVE "CB" TO COMM-FUNCTION. EXEC CICS LINK PROGRAM ("COBSRVI") RESP (CICS-RESP1) RESP2 (CICS-RESP2) COMMAREA (ERX-COMMUNICATION-AREA) LENGTH (LENGTH OF ERX-COMMUNICATION-AREA) 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.
To close and commit a conversational RPC communication
Close the RPC conversation successfully with the function Close
Conversation and Commit CE
provided by the generic RPC
services module:
MOVE "CE" TO COMM-FUNCTION. EXEC CICS LINK PROGRAM ("COBSRVI") RESP (CICS-RESP1) RESP2 (CICS-RESP2) COMMAREA (ERX-COMMUNICATION-AREA) LENGTH (LENGTH OF ERX-COMMUNICATION-AREA) 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:
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.