The EntireX z/OS CICS® RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/OS under CICS. It supports the programming languages COBOL and PL/I.
This document covers the following topics:
The following elements are used for setting up the CICS RPC Server:
defines a setup of the CICS RPC Server that is persistent over CICS restarts
is defined with parameters of the ERXMAIN
Macro; see column 1 in the table under Configuring the RPC Server
contains the following important settings:
creates an ERXMAIN
Control Block, a persistent setup of the CICS RPC Server
needs to be assembled to define a setup
is defined in Assembler program EMAINGEN
(in EXP951.SRCE) - use this for assembling; see Build the ERXMAIN Control Block under Installing EntireX RPC Servers under CICS
provides commands (see column 2 in the table below) to vary most of the permanently defined parameters in the ERXMAIN
Control Block currently in use.
All modifications are lost if CICS is restarted. Use ERXMAIN
Macro for permanent modifications
allows you to try out new setups of the CICS RPC Server easily without the need to reassemble the ERXMAIN
Control Block.
supports
starting
stopping
pinging
monitoring
activating trace
of the CICS RPC Server. See RPC Online Maintenance Facility.
Depending on the feature the CICS RPC Server needs to support (see table below) additional runtime options for IBM's Language Environment need to be set. For a full description of LE runtime options, see z/OS V1R4.0 Lang Env Prog Guide.
Feature | LE Runtime Options | Description |
---|---|---|
Trap abends of called RPC server programs | ABTERMENC(RETCODE) (1) |
Required to also trap the LE abends within a server program. |
Level of information if called RPC server program terminates by unhandled condition | TERMTHDACT(UADUMP) (1) |
Forces a U4039 system dump for abends not trapped by the server. |
Force HANDLE ABEND LABEL getting control for COBOL runtime error and others
|
USRHDLR=(CEEWUCHA) (1) |
The server traps abends using CICS HANDLE ABEND . With Enterprise COBOL for z/OS, errors resulting from the COBOL runtime (table overflow, for example) bypass the CICS abend
handler. Setting CEEWUCHA enables the CICS abend handler to also trap the COBOL runtime errors.
|
Call RPC server programs with AMODE 24 as well | ALL31(OFF),STACK(,,BELOW) |
If not specified, AMODE 31 is supported. |
Note:
(1) Set internally by the CICS RPC Server using application-specific CSECT CEEUOPT
.
The options can be changed if CEEUOPT
is replaced on CICS RPC Server load module
RPCSRVC
with IBM Linkage Editor.
There are various ways of specifying LE runtime options, for example installation-specific, region-specific
(CEEROPT
available in the DFHRPL
concatenation) or application-specific (linked CSECT CEEUOPT
) etc.
The followings rules apply for the ERXMAIN
Macro syntax (column 1 in table below):
keywords are given in uppercase
there are no abbreviations for keywords
The followings rules apply for the RPC Online Maintenance Facility commands (column 2 in table below):
Underscored letters in a command indicate the minimum number of letters that can be used for abbreviation.
For example, in brokerid=localhost
, brok
is the
minimum number of letters that can be used as an abbreviation, i.e. the commands
brokerid=localhost
and brok=localhost
are equivalents.
ERXMAIN Macro Syntax | RPC Online Maintenance Facility Commands | Default | Values | Req/ Opt |
||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
BKRN |
brokerid |
ETB001 |
Broker ID used by the server. See Using the Broker ID in Applications.
Example: |
R | ||||||||||||||||
CLZN |
class |
RPC |
Server class part of the server address used by the
server. The server address must be defined as a service in the broker attribute file (see Service-specific Attributes under Broker Attributes).
Case-sensitive, up to 32 characters. Corresponds to CLASS attribute of the broker attribute file.
Example: |
R | ||||||||||||||||
SRVN |
servername |
SRV1 |
Server name part of the server address used by the server.
The server address must be defined as a service in the broker attribute file.
See Service-specific Attributes under Broker Attributes.
Case-sensitive, up to 32 characters.
Corresponds to SERVER of the broker attribute file.
Example: |
R | ||||||||||||||||
SVCN |
service |
CALLNAT |
Service part of the server address used by the server.
The server address must be defined as a service in the broker attribute file.
See Service-specific Attributes under Broker Attributes.
Case-sensitive, up to 32 characters.
Corresponds to SERVICE attribute of the broker attribute file.
Example: |
R | ||||||||||||||||
CODE |
codepage |
no codepage transferred | Depending on the internationalization approach, the codepage (locale string)
where incoming data is provided to the COBOL server. Conversely, the COBOL server must provide outgoing data in the
given codepage, otherwise unpredictable results occur. See What is the Best Internationalization Approach to use? under Internationalization with EntireX for information
on which internationalization approach requires a codepage (locale string).
By default, no codepage is transferred to the broker. For the most popular internationalization approach, ICU Conversion, the correct codepage (locale string) must be provided. This means it must:
Example: |
O | ||||||||||||||||
COMP |
compresslevel |
N |
Enforce compression when data is transferred between
broker and server. See Data Compression in EntireX Broker.
Example: |
O | ||||||||||||||||
CYCL |
restartcycles |
15 |
Number of restart attempts if the broker is not
available. This can be used to keep the CICS RPC Server running while
the broker is down for a short time. A restart cycle will be
repeated at an interval which is calculated as follows:
When the number of cycles is reached and a connection to the broker is not possible, the RPC server stops. Example: |
O | ||||||||||||||||
DPLY |
deployment |
NO |
Activates the deployment service, see Deployment Service. Required to
use the deployment wizard. See Server Mapping Deployment Wizard in the COBOL Wrapper documentation.
Example: |
O | ||||||||||||||||
ENCR |
encryptionlevel |
0 |
Enforce encryption when data is transferred between
client and server. Requires EntireX Security. See ENCRYPTION-LEVEL under Broker ACI Fields.
Example: |
O | ||||||||||||||||
ENDW |
endworker |
TIMEOUT |
This parameter is forced to value Example: |
O | ||||||||||||||||
MINW |
minworker |
1 |
Minimum number of workers active in parallel with worker model SCALE
or number of workers in worker model FIXED .
See also ERXMAIN macro parameter ENDW .
Example: |
O | ||||||||||||||||
MAXW |
maxworker |
10 |
Upper limit of workers active in parallel with worker model SCALE .
See also ERXMAIN macro parameter ENDW .
Example: |
O | ||||||||||||||||
ETBL |
etblnk |
CICSETB |
Define the broker stub to be used. See Administration of Broker Stubs under z/OS for available stubs.
Example: |
O | ||||||||||||||||
EXIT |
n.a. | At startup, the CICS RPC Server will call the user exit to synchronize its version. If successful, the CICS RPC Server will continue and call the user exit for the implemented events. See User Exits. | O | |||||||||||||||||
IMPS |
impersonation |
NO |
|
O | ||||||||||||||||
LOGN |
logon |
YES |
Execute broker functions LOGON/LOGOFF in worker
threads. Must match the setting of the broker attribute
AUTOLOGON .
Reliable RPC requires logon set to YES .
See Reliable RPC.
Example: |
O | ||||||||||||||||
n.a. |
mapname |
Alias for command memory .
|
O | |||||||||||||||||
n.a. |
memory |
Command to load an ERXMAIN Control Block.
See Modifying Parameters of the RPC Server.
|
O | |||||||||||||||||
OPTS |
runoption |
0 |
This parameter is for special purposes. It provides the CICS RPC Server with additional information.
The runoptions are normally set to meet the platform's requirements.
Set this parameter only if a support representive provides you with an option and asks you to do so.
Syntax: Example: |
O | ||||||||||||||||
PSWD |
password |
Password for broker logon. Case-sensitive, up to 32
characters. For more information see broker ACI control block field
PASSWORD .
Example: |
O | |||||||||||||||||
PRELOAD |
preload |
YES |
Enable to call CICS RPC Server with AMODE=24
|
O | ||||||||||||||||
REPL |
replicatename |
ESRV |
CICS transaction ID (uppercase, up to 4 characters) assigned to worker tasks
and as default for user tasks if Impersonation is set. In the START-USER event of the user exit
(see User Exits) the CICS transaction ID for user tasks
can be overridden. See also Inside the RPC Server.
|
O | ||||||||||||||||
SMH |
smhport |
0 |
The port where the server listens for commands from
the System Management Hub (SMH). If this port is 0 (default), no port is used and
management by the SMH is disabled.
See SMH Listener Service for more information. Example: |
O | ||||||||||||||||
SVM |
svmfile |
Usage and location of SVM files. If no SVM parameter is given, the RPC server tries to open the SVM container using CICS file
with name ERXSVM .
If this CICS file is not available, no server mappings are used. For more information see Usage of SVM Files.
Syntax:
Example: The server mapping file VSAM (container) must be installed and configured. See Install the SVM File for a CICS RPC Server (Optional) in the z/OS installation documentation. |
O | |||||||||||||||||
TOUT |
timeout |
600 |
Timeout in seconds,
used by the server to wait for broker requests. See broker ACI control block field
WAIT for more information. Also influences restartcycles .
See worker model Example: |
O | ||||||||||||||||
TRC1 |
tracedestination |
CSSL |
Name of the destination for trace output. A valid CICS transient data queue. | O | ||||||||||||||||
TRLV |
tracelevel |
0 |
Trace level for the server. See also Activating Tracing for the RPC Server.
Syntax:
Example: |
O | ||||||||||||||||
USER |
userid |
ERXSRV1 |
Used to identify the server to the broker.
See broker ACI control block field USER-ID .
Case-sensitive, up to 32 characters.
Example: |
R |
The IDL library and IDL program
names that come from RPC client are used to locate the RPC server.
See library-definition
and
program-definition
.
This two-level concept (library and program) has to be mapped to the CICS RPC Server environment.
Different mechanisms are used depending on the language:
The approach used to derive the CICS program name for the RPC server depends on whether so-called server mapping files are used or not. See Usage of SVM Files for an introduction.
If SVM files are used, the IDL library and IDL program names are used to form a key to locate the SVM entry in the SVM container. If an SVM entry is found, the CICS program name of the RPC server is derived from the SVM entry. In this case the IDL program name can be different to the CICS program name if it is renamed during wrapping process (see Customize Automatically Generated Server Names) or during the extraction process in the COBOL Mapping Editor (see The Software AG IDL Tree Pane).
If no SVM files are used at all, the IDL program name is used as the CICS program name of the RPC server (the IDL library name is ignored).
To use the CICS RPC Server with COBOL
Make sure that all CICS programs called as RPC servers
use an interface type supported by the CICS RPC Server for target language COBOL; see Interface Types Supported by the RPC Server.
can be called with an EXEC CICS LINK PROGRAM
are accessible through the CICS RPL chain
Configure the ERXMAIN
macro parameter SVM
depending on whether SVM files are used or not.
See also Scenario I: Calling an Existing COBOL Server or Scenario II: Writing a New COBOL Server.
There is a simple mechanism to derive the RPC server CICS program name:
The IDL program name is used as the CICS program name.
The IDL library name is not used.
To use the CICS RPC Server with PL/I
Make sure that all CICS programs called as RPC servers
use an interface type supported by the CICS RPC Server for target language PL/I; see Interface Types Supported by the RPC Server.
can be called with an EXEC CICS LINK PROGRAM
are accessible through the CICS RPL chain
See also Scenario III: Calling an Existing PL/I Server or Scenario IV: Writing a New PL/I Server.
The CICS RPC Server does not have direct SSL or TLS support inside. For this purpose, use instead IBM's Application Transparent Transport Layer Security (AT-TLS), where the establishment of the SSL or TLS connection is pushed down the stack into the TCP layer.
See SSL or TLS and Certificates with EntireX for more information.
To set up SSL or TLS with AT-TLS
Set up the CICS RPC Server for a TCP/IP connection.
Configure the rules for the AT-TLS policy agent the CICS RPC Server matches, for example by using the CICS job name and remote port number the CICS RPC Server connects to. Used certificates are also defined with those rules. Refer to your IBM documentation for further information.
Make sure the target the CICS RPC Server connects to is prepared for SSL/TLS connections as well. See the following sections:
This section covers the following topics:
The Developer's Kit RPC source data set EXP951.SRCE of the EntireX z/OS installation
provides the user exit skeleton COBUEX02
for COBOL.
Copy this skeleton so you have your own user exit source for modifications.
Accordingly, a COBOL copybook COBUEX02
is provided in EXP951.INCL.
Please add this library to your COBOL compiler SYSLIB DD
chain.
The most important API parameters of the user exit are described below. Other parameters are informational and are described
in the source code.
The user exit program must comply with the EXEC CICS LINK PROGRAM COMMAREA
conventions.
Parameter | Description |
---|---|
VERSION |
Required for future changes. Do not change the skeleton code. |
ERROR-CODE |
You can terminate the current request: Any number between 1 and 9999 will cause the CICS RPC Server to stop execution of the current RPC request and pass back the given error code with message class 1022 to the RPC client. See Message Class 1022 - CICS RPC Server User Exit Messages. With error code 0000, the CICS RPC Server continues as normal. |
ERROR-TEXT |
If the error code is not zero, an error text of up to 256 characters may be applied. This is passed to the RPC client. |
CICS-TRANSID |
Can be applied in the event START-USER , otherwise it is informational. Apply the TRANSID that your business logic requires.
|
CICS-TERMID |
Can be applied in the event START-USER , otherwise it is informational. In some (rare) cases, RPC server routines require a terminal ID. Apply the TERMID that your business logic requires.
|
USERID |
Can be applied in the event START-USER otherwise it is informational. Under some circumstances, it might be necessary to change the original RPC-USERID from the calling RPC client.
|
DATA-POINTER |
This pointer refers to the payload data for the events CALL-START and CALL-END . The payload to which this pointer is pointing may be inspected as well as modified. The pointer itself must not be changed.
|
START-WORKER event before a CICS worker task is started. This allows you to programatically set the CICS transaction ID. You can terminate
an RPC request by specifying an ERROR-CODE and optional ERROR-TEXT .
|
|
START-USER event. Before an impersonated CICS transaction (worker task) is started, the user exit may change the user ID and CICS transaction
ID of the new impersonated worker. See Impersonation. You can terminate an RPC request by specifying an ERROR-CODE and optional ERROR-TEXT .
|
|
CALL-START event. The RPC request (payload data from the RPC client to the RPC server) may be inspected and modified. You can terminate
an RPC request by specifying ERROR-CODE and optional ERROR-TEXT .
|
|
CALL-END event. The RPC reply (payload data from the RPC server to the RPC client) may be inspected and modified. If an ERROR-CODE and optional ERROR-TEXT is given in the API, this error is returned to the RPC client instead of the payload.
|
Apply the name of your exit routine to the EntireX RPC server ERXMAIN
macro parameter EXIT
. See Configuring the RPC Server.
At startup, the CICS RPC Server will call the named user exit to synchronize its version.
If successful, the RPC Online Maintenance Facility will display the user exit as map field "parameter opts
". See
To display the Server parameters (PF06) under RPC Online Maintenance Facility.
The CICS RPC Server will continue and call the user exit for the implemented events.
The user exit RPCUEX01
aborts an RPC out of a server program of the user application without returning to the RPC server.
If your server program decides to abort with CICS ABEND CANCEL
, it needs to invoke RPCUEX01
directly before informing the RPC server about the imminent abort.
If the server program aborts without calling RPCUEX01
, the client gets a
Broker timeout without any further information about the abort situation at the server.
This section covers the following topics:
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 user exit is only for CICS and if impersonation is used. It is used only if your server program aborts its
execution with CICS ABEND CANCEL
.
The server program is invoked within the user task. | |
The server program decides to abort using CICS ABEND CANCEL immediately before it calls the user exit. Then the server program can perform CICS ABEND CANCEL to abort. The CICS ABEND CANCEL terminates the user task.
|
|
The user exit 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 client. |
The server program calls the exit 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 CICS RPC Server can be started and stopped automatically during start and stop of the CICS region. For manual start/stop, see Starting the RPC Server and Stopping the RPC Server under RPC Online Maintenance Facility.
To start the CICS RPC Server during the initialization of CICS
If the COBOL source ERXSTART
of the EntireX installation library EXP951.SRCE has not been defined in the CICS CSD
data sets by the installation job $INSTALL
, define it.
Customize and compile ERXSTART
if necessary.
Add the following entry to your CICS PLTPI
table (second phase PLT program):
DFHPLT TYPE=ENTRY,PROGRAM=ERXSTART
See also Starting the EntireX RPC Server Automatically on CICS Startup (Optional) under Installing EntireX RPC Servers under CICS.
To stop the CICS RPC Server during the shutdown of CICS
If the COBOL source ERXSTOP
of the EntireX installation library EXP951.SRCE has not been defined in the CICS CSD
data sets by the installation job $INSTALL
, define it.
Customize and compile ERXSTOP
if necessary.
Add the following entry to your CICS PLTSD
table (first phase PLT program):
DFHPLT TYPE=ENTRY,PROGRAM=ERXSTOP
See also Stopping the EntireX RPC Server Automatically on CICS Shutdown (Optional) under Installing EntireX RPC Servers under CICS.
If you need to install multiple instances in the same CICS region, see Installing Multiple EntireX RPC Servers in the same CICS (Optional) under Installing EntireX RPC Servers under CICS.