Reliable RPC for COBOL Wrapper

Writing a Client

The following steps describe how to write a COBOL reliable RPC client program with the scenario Using the COBOL Wrapper for CICS with DFHCOMMAREA Calling Convention (z/OS and z/VSE):

Note:
Reliable RPC requires an explicit broker logon. See Using Broker Logon and Logoff.

Step 1: Declare the Data Structures and RPC Communication Area

The customer data structures (all below COBOL label SM-COMA) must match the interfaces of the generated client interface objects with regard to format and lengths, otherwise unpredictable results will occur. See the following code snippet: 

* Declare the customer data of the generated RPC interface (See Note 1)
 01 SENDMAIL.
    02 SM-COMA.            
       03 SM-TOADDRESS          PIC  X(60).
       03 SM-SUBJECT            PIC  X(20).
       03 SM-TEXT               PIC X(100).
* Declare RPC communication area 
    02 ERX-COMMUNICATION-AREA.
       COPY ERXCOMM.

Notes:

  1. As an alternative the generated IDL Interface copybooks can be used. See Step 1: Declare IDL Structures and RPC Communication Area under Writing EXEC CICS LINK Clients in the COBOL Wrapper documentation for usage examples.

Step 2: Initialize the RPC Communication Area

See the following code snippet and refer to Step 2: Initialize the RPC Communication Area in the COBOL Wrapper documentation for additional hints and information. 

* Initialize RPC communication area 
 INITIALIZE ERX-COMMUNICATION-AREA.
 MOVE "2000"           to COMM-VERSION.

Step 3: Required Settings in the RPC Communication Area

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 your 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 for Broker logon
 MOVE "ERXUSER"        to COMM-USERID.

Step 4: Perform a Broker Logon

MOVE "LO" TO COMM-FUNCTION.                    
EXEC CICS LINK                                 
  PROGRAM  ("COBSRVI")                         
  COMMAREA (ERX-COMMUNICATION-AREA)            
  LENGTH   (LENGTH OF ERX-COMMUNICATION-AREA)  
  RESP     (CICS-RESP1)                        
  RESP2    (CICS-RESP2)                        
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.

Step 5: Enable Reliable RPC with CLIENT_COMMIT

Before reliable RPC can be used, the reliable state must be set to either ERX_RELIABLE_CLIENT_COMMIT or ERX_RELIABLE_AUTO_COMMIT.

  • "C" - CLIENT_COMMIT

  • "A" - AUTO_COMMIT

* Set the reliable RPC mode
 MOVE "C" TO COMM-RELIABLE-STATE.

Step 6: Send the RPC Message

The RPC message is sent using the EXEC CICS LINK interface. 

* Send the RPC message
 MOVE DFHRESP(NORMAL) TO CICS-RESP1.
 MOVE DFHRESP(NORMAL) TO CICS-RESP2.
 MOVE ZEROES           TO COMM-RETURN-CODE.
 EXEC CICS LINK 
   PROGRAM  ("SENDMAIL") 
   RESP     (CICS-RESP1)
   RESP2    (CICS-RESP2)
   COMMAREA (SENDMAIL)
   LENGTH   (LENGTH OF SENDMAIL)
 END-EXEC.
 IF WORKRESP = DFHRESP(NORMAL)
   IF (COMM-RETURN-CODE = 0) THEN
*      Perform success-handling (See Note 1)
   ELSE
*      Perform error-handling (See Note 2)
   END-IF
 ELSE
*  Perform error-handling
 END-IF.

Notes:

  1. After successful call the UOWID is available in the RPC communication area field COMM-ETB-UOW-ID. See The RPC Communication Area (Reference).
  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.

Step 7: Check the Reliable RPC Message Status

To determine that reliable RPC messages are delivered, the reliable RPC message status can be queried. See Understanding UOW Status and Broker UOW Status Transition for more information. 

 MOVE DFHRESP(NORMAL) TO CICS-RESP1.
 MOVE DFHRESP(NORMAL) TO CICS-RESP2.
 MOVE "RS" TO COMM-FUNCTION.
 MOVE ZEROES TO COMM-RETURN-CODE.
 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 (See Note 1)
    ELSE
*       Perform error-handling (See Note 2)
    END-IF
  ELSE
*   Perform error-handling
  END-IF.

Notes:

  1. After successful call the UOW status is available in the RPC communication area field COMM-ETB-UOW-STATUS. See The RPC Communication Area (Reference).
  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.

Step 8: Send a Second RPC Message

Send a second reliable RPC message. See Step 6. 

 
                   
                   
                

               
Step 9: Check the Reliable RPC Message Status

                 
                  
               
Check the reliable RPC message before the commit call. See Step 7.
               

                 
                  
                  
               

               
Step 10: Commit both Reliable RPC Messages
 
                  
                  
               
Now both reliable RPC messages are committed. This will deliver all
                      reliable RPC messages to the server if it is available.
               
 
                  
 MOVE DFHRESP(NORMAL) TO CICS-RESP1.
 MOVE DFHRESP(NORMAL) TO CICS-RESP2.
 MOVE "RC" TO COMM-FUNCTION.
 MOVE ZEROES TO COMM-RETURN-CODE.
 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 (See Note 1)
   ELSE
*      Perform error-handling (See Note 2)
   END-IF
 ELSE
*  Perform error-handling
 END-IF.

 
                    
Notes:

               
    
                        
                  
  1. After successful call, both reliable RPC messages are committed. This will deliver all reliable RPC messages to the server
                     if it is available.
                  
    2. 
                        
                  
  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.
                  
    3. 
                       
               

                   
                   
                
               

               
Step 11: Send a Third RPC Message
 
                  
                  
               
Send a third reliable RPC message. See Step 6.
               
 
                  
 
                   
                   
                

               
Step 12: Check the Reliable RPC Message Status
 
                  
                  
               
Check the reliable RPC message before the rollback call. See Step 7.
               
 
                   
                   
                
               

               
Step 13: Roll Back the Third RPC Message
 
                  
                  
               
Roll back the current reliable RPC message.
 
                  
 MOVE DFHRESP(NORMAL) TO CICS-RESP1.
 MOVE DFHRESP(NORMAL) TO CICS-RESP2.
 MOVE "RR" TO COMM-FUNCTION.
 MOVE ZEROES TO COMM-RETURN-CODE.
 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.
 
                   
                   
                

               
Step 14: Check the Reliable RPC Message Status
 
                  
                  
               
When the rollback call is returned, check whether it was successful or not.
 
                  
 MOVE DFHRESP(NORMAL) TO CICS-RESP1.
 MOVE DFHRESP(NORMAL) TO CICS-RESP2.
 MOVE "RS" TO COMM-FUNCTION.
 MOVE ZEROES TO COMM-RETURN-CODE.
 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.
                  
    2. 
                       
               

                   
                   
                
               

               
Step 15: Perform a Broker Logoff
 
                  
                  
MOVE "LF" TO COMM-FUNCTION.                    
EXEC CICS LINK                                 
  PROGRAM  ("COBSRVI")                         
  COMMAREA (ERX-COMMUNICATION-AREA)            
  LENGTH   (LENGTH OF ERX-COMMUNICATION-AREA)  
  RESP     (CICS-RESP1)                        
  RESP2    (CICS-RESP2)                        
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.
                  
    2. 
                       
               

                 
                  
                 
                
               
               

               
Writing a Server
 
                 
                 
               
There are no server-side methods for reliable RPC. The server does not
                     send back a message to the client. The server can run deferred, thus client and
                     server do not necessarily run at the same time. If the server fails, it returns
                     an error code greater than zero. This causes the transaction (unit of work
                     inside the Broker) to be cancelled, and the error code is written to the user
                     status field of the unit of work. For writing reliable RPC servers, see Using the COBOL Wrapper for the Server Side.
               
 
               
               
               
To execute a reliable RPC service with an RPC server, the parameter logon 
                  (LOGN under CICS) must be set to YES.
                  See logon under z/OS (CICS | Batch | IMS) | BS2000.