Scenarios and Programmer Information

This document covers the following topics:


COBOL Scenarios

Scenario I: Calling an Existing COBOL Server

Start of instruction setTo call an existing COBOL server

  1. Use the IDL Extractor for COBOL to extract the Software AG IDL and, depending on the complexity, also a server mapping file. See When is a Server Mapping File Required? in the Designer documentation.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

    • use the IDL Tester; see EntireX IDL Tester in the Designer documentation

    • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester in the XML/SOAP Wrapper documentation

See Client and Server Examples for z/OS CICS in the COBOL Wrapper documentation for COBOL RPC Server examples.

Scenario II: Writing a New COBOL Server

Start of instruction setTo write a new COBOL server

  1. Use the COBOL Wrapper to generate a COBOL server skeleton and, depending on the complexity, also a server mapping file. See When is a Server Mapping File Required? in the Designer documentation. Write your COBOL server and proceed as described under Using the COBOL Wrapper for the Server Side.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

    • use the IDL Tester; see EntireX IDL Tester in the Designer documentation

    • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester in the XML/SOAP Wrapper documentation

See Client and Server Examples for z/OS CICS in the COBOL Wrapper documentation for COBOL RPC Server examples.

PL/I Scenarios

Scenario III: Calling an Existing PL/I Server

Start of instruction setTo call an existing PL/I server

  1. Use the IDL Extractor for PL/I to extract the Software AG IDL.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

    • use the IDL Tester; see EntireX IDL Tester in the Designer documentation

    • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester in the XML/SOAP Wrapper documentation

See Client and Server Examples for z/OS CICS in the PL/I Wrapper documentation for PL/I RPC Server examples.

Scenario IV: Writing a New PL/I Server

Start of instruction setTo write a new PL/I server

  1. Use the PL/I Wrapper to generate a PL/I server skeleton. Write your PL/I server and proceed as described under Using the PL/I Wrapper for the Server Side.

  2. Build an EntireX RPC client using any EntireX wrapper. See EntireX Wrappers. For a quick test you can:

    • use the IDL Tester; see EntireX IDL Tester in the Designer documentation

    • generate an XML mapping file (XMM) and use the XML Tester for verification; see EntireX XML Tester in the XML/SOAP Wrapper documentation

See Client and Server Examples for z/OS CICS in the PL/I Wrapper documentation for PL/I RPC Server examples.

Aborting RPC Server Customer Code and Returning Error to RPC Client

This section covers the following topics:

Using EXEC CICS ABEND ABCODE

This approach applies to all CICS scenarios (all programming languages and all interface types); see Supported Interface Types.

The CICS feature EXEC CICS ABEND ABCODE(myabend) may be used to indicate application error codes. According to IBM CICS standards, ABEND codes starting with the letter A are reserved for CICS itself and should not be used in your RPC server.

The RPC Server for CICS follows these IBM CICS standards and sends back the RPC protocol message

  1. 10010018 Abnormal termination during program execution. This is returned when an ABEND code starting with the letter "A" is received from CICS, which is a CICS ABEND.

  2. 10010045 CICS ABEND myabend was issued. This is returned when an ABEND code starting with a letter other than "A" is received from CICS, which is an application error situation forced by your RPC server.

Using EXEC CICS ABEND CANCEL

This approach applies to all CICS scenarios (all programming languages and all interface types) if impersonation is used (YES|AUTO). See Supported Interface Types and Impersonation. If impersonation is not set, EXEC CICS ABEND CANCEL cannot be used.

If the customer server code uses the CICS feature EXEC CICS ABEND CANCEL to abort for particular error situations, the RPC server cannot trap the abort and is not able to send back an error to the RPC client. The RPC client gets a Broker timeout without any further information about the RPC server abort. In this case, to notify the RPC client you need to call RPCUEX01 (immediately before CICS ABEND CANCEL) in the customer server code to inform the RPC Server for CICS that your program is about to abort with CICS ABEND CANCEL. EntireX does not recommend using EXEC CICS ABEND CANCEL. However, if you do need to call an existing COBOL program with EXEC CICS ABEND CANCEL, this can be done if the RPCUEX01 call is added. Whenever possible use EXEC CICS ABEND ABCODE instead. See Using EXEC CICS ABEND ABCODE.

This section covers the following topics:

Process Flow

The server invokes the server program using CICS LINK PROGRAM and expects that the program returns with CICS RETURN. However, if the program uses CICS ABEND CANCEL to abort for particular error situations, the RPC server cannot trap the abort. If your server program uses CICS ABEND CANCEL you need to call the delivered RPCUEX01 to inform the server that your program is about to abort with CICS ABEND CANCEL.

graphics/scenarios_returnError_cancel.png

graphics/no1.gif The customer server program is invoked within the user task.
graphics/no2.gif The customer server program decides to abort using CICS ABEND CANCEL. Immediately before calling CICS ABEND CANCEL it calls the RPCUEX01. After returning from RPCUEX01 it performs CICS ABEND CANCEL to abort. The CICS ABEND CANCEL terminates the user task.
graphics/no3.gif RPCUEX01 posts the worker task and informs it about the abort of its associated user task. The worker task sends back the abort information to the RPC client.

Usage

The server program calls RPCUEX01 with:

EXEC CICS LINK PROGRAM('RPCUEX01')
    COMMAREA(rpcuex01-commarea)

After execution, the server program is responsible for aborting the task. If the server program ends without terminating the task, unpredictable results may occur.

Layout of rpcuex01-commarea:

  • Return code
    4-byte integer value. Value of -1 indicates failure.

  • Error text
    128-byte text field containing the error description.

If the call of RPCUEX01 fails, the user program must not abort the task.

COBOL example for calling RPCUEX01:

  01 UEX01-AREA.
    05 RETCODE                           PIC  S9(9) BINARY.
    05 ERRORTEXT                         PIC  X(128).
 ...
    MOVE -1 TO RETCODE
    MOVE 'ERX: No Commarea access' TO ERRORTEXT
    EXEC CICS LINK PROGRAM('RPCUEX01')
             COMMAREA(UEX01-AREA)
             RESP(RESP)
             RESP2(RESP2)
             END-EXEC
    IF RESP NOT = 0
        DISPLAY 'Error invoking RPCUEX01:'
        GO TO MAIN-EXIT
    END-IF
    IF RETCODE IS < 0
        DISPLAY 'Error from RPCUEX01:'
             ' ERRTXT  = ' ERRORTEXT
        GO TO MAIN-EXIT
    END-IF
*   Now cancel the task...
    EXEC CICS ABEND CANCEL END-EXEC

Installation

The program RPCUEX01 must reside in the CICS load library concatenation. The following PPT entry is required:

DEFINE PROGRAM(RPCUEX01) GROUP(EXX)                         
  DESCRIPTION(RPC user exit to abort RPC programs)                    
  LANGUAGE(C)

Using RETURN-CODE Special Register (COBOL only)

This approach applies to the following CICS scenarios:

CICS applications that use the DFHCOMMAREA as communication area (EXEC CICS LINK applications) may return error codes if the LINKed application has a C main entry and if this application is running in the same CICS (non-DPL program) as the RPC Server for CICS. Under these circumstances, IBM's Language Environment for C provides the application return code to EIBRESP2, where it can be detected by the RPC Server for CICS.

The following provided modules need to be linked to your application.

  • ERXRCSRV, a C main module that calls the intermediate COBOL subroutine RCCALL and catches the error from your RPC server and provides it to the RPC Server for CICS. This module is available as source in the source data set EXP103.SRCE as well as precompiled in the load data set EXP103.LD00, so a C compiler is not needed.

  • RCCALL, a COBOL subroutine calling your RPC server. This module is available as source in the CICS example server data set EXP103.DVCO.

A step-by-step description is given below, but for ease of use we recommend using the job RCIGY. See below.

Start of instruction setTo set up your server to be able to return application errors manually

  1. Change the CALL statement of the RCCALL program below which your RPC server is called instead of "MyCobol" below

     IDENTIFICATION DIVISION.
       PROGRAM-ID.    RCCALL.
    
    ****************************************************************
    *                                                               
    *  CICS RPC Server                                              
    *                                                               
    *  Returning Application Errors from RPC Server to RPC Client   
    *                                                               
    *  This program calls your target COBOL Server.                 
    *                                                               
    *  For further information and explanation refer to             
    *  - "Writing Applications with the COBOL Wrapper"              
    *  in the delivered documentation.                              
    *                                                               
    *  $Revision: n.n $  
    *                                                               
    *                                                               
    *  Copyright (C) 1997 - 20nn Software AG, Darmstadt, Germany    
    *  and/or Software AG USA, Inc., Reston, VA, United States of   
    *  America, and/or their licensors.                             
    *                                                               
    ****************************************************************
    
     ENVIRONMENT DIVISION.
    
     DATA DIVISION.
       WORKING-STORAGE SECTION.
    
       LINKAGE SECTION.
    
       01 DFHCOMMAREA.
          10 DFHCOMM-DUMMY                  PIC X.
    
     PROCEDURE DIVISION USING DFHCOMMAREA.
    
     MAIN SECTION.
          CALL "my-cobol" USING DFHEIBLK DFHCOMMAREA.
    
     MAIN-EXIT.
          EXIT PROGRAM.
    
     END PROGRAM RCCALL.
  2. In your RPC server, do not use EXEC CICS RETURN, because this prevents the return of the application error code to the RPC Server for CICS. If you are using a COBOL RPC server generated with the COBOL Wrapper, comment out or remove this line.

  3. Compile the RCCALL program with a COBOL compiler supported by the COBOL Wrapper.

  4. Link the compiled RCCALL program, the delivered ERXRCSRV module and your RPC server together to a CICS program to be called by the RPC Server for CICS. See also Using the COBOL Wrapper for the Server Side for supported CICS scenarios.

Start of instruction setTo set up your server to be able to return application errors using job RCIGY

  • Execute RCIGY as provided in the CICS example source data set EXP103.DVCO.

    This enhanced job will

    1. modify RCCALL as needed (step 1 from the manual approach, see above),

    2. add the modified RCCALL code to your COBOL input source (step 2 from the manual approach, see above),

    3. link edit with ERXRCSRV (step 3 from the manual approach, see above).

Automatic Syncpoint Handling

The RPC Server for CICS issues a SYNCPOINT command under the following circumstances:

  • If you are running under CICS without Impersonation, the server issues a SYNCPOINT COMMIT command after a successful non-conversational request or an end-of-conversation. This can be disabled with the SYNC parameter.

  • If you are running under CICS with Impersonation, this SYNCPOINT command is not executed by the server, but by CICS when the user task is terminated.

  • After abnormal termination of a non-conversational request or a conversation due to an error, the server performs a SYNCPOINT ROLLBACK command to back out any pending database modifications.

RPC Server Support of CICS with Large Buffer Interface

This RPC Server for CICS supports the Large Buffer interface with the following methods:

In Same as Out

In this scenario, the input buffer is same as the output buffer. The server application data has only one interface structure that is used for input as well as output.

LINKAGE SECTION.

 01 DFHCOMMAREA.
    10 WM-LCB-MARKER                         PIC X(4).
    10 WM-LCB-INPUT-BUFFER                   POINTER.
    10 WM-LCB-INPUT-BUFFER-SIZE              PIC S9(8) BINARY.
    10 WM-LCB-OUTPUT-BUFFER                  POINTER.
    10 WM-LCB-OUTPUT-BUFFER-SIZE             PIC S9(8) BINARY.
    10 WM-LCB-FLAGS                          PIC X(1).
       88 WM-LCB-FREE-OUTPUT-BUFFER     VALUE 'F'.
    10 WM-LCB-RESERVED                       PIC X(3).
 01 INOUT-BUFFER.
    02 OPERATION                             PIC X(1).
    02 OPERAND-1                             PIC S9(9) BINARY.
    02 OPERAND-2                             PIC S9(9) BINARY.
    02 FUNCTION-RESULT                       PIC S9(9) BINARY.
  . . .
 PROCEDURE DIVISION USING DFHCOMMAREA.
  . . .
    SET ADDRESS OF INOUT-BUFFER TO WM-LCB-INPUT-BUFFER.
Variable Description
WM-LCM-MARKER Has eye-catcher "XXXX".
WM-LCB-INPUT-BUFFER Has pointer to server application data.
WM-LCB-INPUT-BUFFER-SIZE Contains size of application data.
WM-LCB-OUTPUT-BUFFER Same as WM-LCB-INPUT-BUFFER.
WM-LCB-OUTPUT-BUFFER-SIZE Same as WM-LCB-INPUT-BUFFER-SIZE.

WM-LCB-OUTPUT-BUFFER, WM-LCB-OUTPUT-BUFFER-SIZE and WM-LCB-FREE-OUTPUT-BUFFER are normally not changed by the application in this scenario. Nevertheless, if WM-LCB-FREE-OUTPUT-BUFFER and WM-LCB-OUTPUT-BUFFER are changed, the RPC server will use the reply data from this WM-LCB-OUTPUT-BUFFER. Afterwards this buffer will be freed (EXEC CICS FREEMAIN).

This scenario is supported by the

In Different to Out

In this scenario, the input buffer is different to the output buffer. The server application data has two fix interface structures: one for the input, the other for the output.

LINKAGE SECTION.
 01 DFHCOMMAREA.
   10 WM-LCB-MARKER                    PIC X(4).
   10 WM-LCB-INPUT-BUFFER              POINTER.
   10 WM-LCB-INPUT-BUFFER-SIZE         PIC S9(8) BINARY.
   10 WM-LCB-OUTPUT-BUFFER             POINTER.
   10 WM-LCB-OUTPUT-BUFFER-SIZE        PIC S9(8) BINARY.
   10 WM-LCB-FLAGS                     PIC X(1).
      88 WM-LCB-FREE-OUTPUT-BUFFER  VALUE 'F'.
   10 WM-LCB-RESERVED                  PIC X(3).
 01 IN-BUFFER.
    02 OPERATION                       PIC X(1).
    02 OPERAND-1                       PIC S9(9) BINARY.
    02 OPERAND-2                       PIC S9(9) BINARY.
 01 OUT-BUFFER.
    02 FUNCTION-RESULT                 PIC S9(9) BINARY.
  . . .
 PROCEDURE DIVISION USING DFHCOMMAREA.
  . . .
    SET ADDRESS OF IN-BUFFER  TO WM-LCB-INPUT-BUFFER.
    SET ADDRESS OF OUT-BUFFER TO WM-LCB-OUTPUT-BUFFER.
Variable Description
WM-LCM-MARKER Has eye-catcher "XXXX".
WM-LCB-INPUT-BUFFER Has pointer to server input application data.
WM-LCB-INPUT-BUFFER-SIZE Contains size of input application data.
WM-LCB-OUTPUT-BUFFER Has buffer for server output application data.
WM-LCB-OUTPUT-BUFFER-SIZE Size of WM-LCB-OUTPUT-BUFFER.

Normally, the output data can be written by the application to the WM-LCB-OUTPUT-BUFFER provided. Nevertheless, if WM-LCB-FREE-OUTPUT-BUFFER and WM-LCB-OUTPUT-BUFFER pointer are changed by the application, the RPC server will use the reply data from this WM-LCB-OUTPUT-BUFFER. Afterwards this buffer will be freed by the RPC Server for CICS (EXEC CICS FREEMAIN).

This scenario is supported by the IDL Extractor for COBOL. See CICS with DFHCOMMAREA Large Buffer Interface - In different to Out.