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 RPC Communication Area

The code you write depends on the interface type:

• Call Interface

• EXEC CICS LINK Interface

See Client Interface Types.

---

Call Interface

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

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

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:

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

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

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:

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.