This document covers the following topics:
To call an existing COBOL server
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.
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.
To write a new COBOL server
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.
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.
To call an existing PL/I server
Use the IDL Extractor for PL/I to extract the Software AG IDL.
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.
To write a new PL/I server
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.
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.
This section covers the following topics:
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
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.
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.
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:
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.
 |
The customer server program is invoked within the user task. |
 |
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.
|
 |
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.
|
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
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)
This approach applies to the following CICS scenarios:
CICS with DFHCOMMAREA Calling Convention (COBOL Wrapper | Extractor)
CICS with DFHCOMMAREA Large Buffer Interface (COBOL Wrapper | Extractor)
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.
To set up your server to be able to return application
errors manually
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.
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.
Compile the RCCALL program with a COBOL compiler supported by the
COBOL Wrapper.
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.
To 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
modify RCCALL as needed (step 1 from the manual approach, see
above),
add the modified RCCALL code to your COBOL input source (step 2
from the manual approach, see above),
link edit with ERXRCSRV (step 3 from the manual approach, see
above).
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.
This RPC Server for CICS supports the Large Buffer interface with the following methods:
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
COBOL Wrapper, see Server Interface Types
IDL Extractor for COBOL, see CICS with DFHCOMMAREA Large Buffer Interface - In same as 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.