Using Conversational RPC

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 code you write depends on the interface type:

See Client Interface Types.


Call Interface

This interface type applies to the scenarios CICS | Batch | IMS.

Start of instruction setTo use conversational RPC

  1. 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.

  2. 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.
  3. 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.

Start of instruction setTo 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.

Start of instruction setTo 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:

  1. If both copybooks ERXCOMM and ERXVSTR are used, you need to pass both parameters:
      CALL "COBSRVI" USING ERX-COMMUNICATION-AREA
                           ERX-COMMUNICATION-VSTR.
  2. 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.

EXEC CICS LINK Interface

This interface type applies to the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE).

Start of instruction setTo use conversational RPC

  1. Declare the RPC communication area as described under Step 1: Declare IDL Structures and RPC Communication Area in section Writing EXEC CICS LINK Clients.

  2. Initialize the RPC communication area as described under Step 2: Initialize the RPC Communication Area under Writing EXEC CICS LINK Clients.

  3. 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.
  4. 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.

Start of instruction setTo 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.

Start of instruction setTo 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:

  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.