The EntireX RPC Server for z/OS CICS® 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:
By default, the RPC Server for CICS runs as CICS transaction ESRV
. This can be changed with parameter REPL
.
The following elements are used for setting up the RPC Server for CICS:
defines a setup of the RPC Server for CICS 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:
the default name for the control block is ERXMAIN, but any meaningful name can be chosen.
Using this name as input parameter memory
for the RPC Online Maintenance Facility means that multiple RPC Servers for CICS can be started and monitored in parallel.
See Installing Multiple EntireX RPC Servers in the same CICS (Optional) under Installing the RPC Server for CICS.
creates an ERXMAIN
Control Block, a persistent setup of the RPC Server for CICS
needs to be assembled to define a setup
is defined in Assembler program EMAINGEN
(in EXP105.SRCE) - use this for assembling; see Build the ERXMAIN Control Block in the z/OS installation documentation
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 RPC Server for CICS easily without the need to reassemble the ERXMAIN
Control Block.
runs as CICS transaction ERXM
supports
starting
stopping
pinging
monitoring
activating trace
of the RPC Server for CICS. See RPC Online Maintenance Facility.
Depending on the feature the RPC Server for CICS 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 RPC Server for CICS using application-specific CSECT CEEUOPT
.
The options can be changed if CEEUOPT
is replaced on RPC Server for CICS 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.
CICS Parameter | Description | Default | How to change? |
---|---|---|---|
TWASIZE |
Transaction Work Area (TWA) size may be used by target RPC programs called by the RPC Server for CICS. If this is the case, the TWA size set for the RPC Server for CICS must match the largest TWA size required by all called target RPC programs. | TWASIZE(28) This corresponds to 'Adabas Parameter List' if transport method NET is used. See Installing Adabas with TP Monitors for EntireX. |
|
The following rules apply for the ERXMAIN
Macro syntax (column 1 in table below):
keywords are given in uppercase
there are no abbreviations for keywords
The following 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, that is, 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 in the RPC Programming documentation.
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).
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.
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.
Case-sensitive, up to 32 characters.
Corresponds to SERVICE attribute of the broker attribute file.
Example: |
R | |||||||||||||||||||
CODE |
codepage |
no codepage transferred |
The codepage tells the broker the encoding of the data. The application must ensure the encoding of the data matches the codepage. The RPC server itself does not convert your application data. The application's data is shipped and received as given. Often, the codepage must also match the encoding used in the RPC server environment for file and terminal IO, otherwise unpredictable results may occur. By default, no codepage is transferred to the broker. It is assumed the broker's locale string defaults match. See Locale String Mapping If they do not match, provide the codepage here. Example: CODE=ibm-273 Enable character conversion in the broker by setting the service-specific attribute |
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 RPC Server for CICS running while the broker is down for a short time.
A restart cycle will be repeated every 60 seconds.
Note: When the number of specified cycles is reached and a connection to the broker is not possible, the RPC Server for CICS stops. Example: The server waits up to 30 minutes (30*6*10 seconds) before it terminates due to a missing broker connection. |
O | |||||||||||||||||||
DPLY |
deployment |
NO |
Activates the deployment service, see Deployment Service. Required to
use the Server Mapping Deployment Wizard. See Server Mapping Deployment Wizard in the Designer documentation.
Example: |
O | |||||||||||||||||||
ENDW |
endworker |
TIMEOUT |
This parameter is forced to value Example: |
O | |||||||||||||||||||
MINW |
minworker |
1 |
Minimum limit of worker threads.
See also Example: |
O | |||||||||||||||||||
MAXW |
maxworker |
10 |
Upper limit of worker threads and impersonated user tasks.
Example: |
O | |||||||||||||||||||
ETBL |
etblnk |
CICSETB |
Define the broker stub to be used. See Administering Broker Stubs for available stubs.
Example: |
O | |||||||||||||||||||
EXIT |
n/a | At startup, the RPC Server for CICS will call the user exit to synchronize its version.
If successful, the RPC Server for CICS will continue and call the user exit for the implemented events.
See User Exit COBUEX02 .
|
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 for CICS.
|
O | ||||||||||||||||||||
OPTS |
runoption |
0 |
This parameter is for special purposes. It provides the RPC Server for CICS 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 |
The password for secured access to the broker.
Example: |
O | ||||||||||||||||||||
PRELOAD |
preload |
YES |
Enable to call RPC Server for CICS 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 Exit COBUEX02 ) the CICS transaction ID for user tasks
can be overridden. See also Introduction to the RPC Server for CICS.
|
O | |||||||||||||||||||
SIZE |
n/a | 32768 |
Size in bytes to hold work memory for worker tasks and impersonated user tasks if impersonation is used.
Each task (worker and user) requires the same amount of memory.
The following rules apply when calculating the ERXMAIN macro parameter MAXW :
This means:
|
O | |||||||||||||||||||
SVM |
svmfile |
Usage and location of server-side mapping files.
See Server-side Mapping Files in the RPC Server.
If no SVM parameter is given, the RPC server tries to open the server-side mapping container,
using CICS file with name ERXSVM .
If this CICS file is not available, no server-side mapping files are used.
If you use server-side mapping files, the server-side mapping container must be installed and configured;
see Installing the Server-side Mapping Container for an RPC Server for CICS (Optional) under Installing the EntireX RPC Servers under z/OS.
There are also client-side mapping files that do not require configuration here; see Server Mapping Files for COBOL.
Syntax:
Example: See also Usage of Server Mapping Files. |
O | ||||||||||||||||||||
SYNC |
Y |
Determines whether a CICS SYNCPOINT COMMIT command is issued.
See also Automatic Syncpoint Handling. |
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 and worker model DYNAMIC .
Example: |
O | |||||||||||||||||||
TRC1 |
tracedestination |
CSSL |
Name of the destination for trace output. A valid CICS transient data queue. See also Activating Tracing for the RPC Server for CICS. | O | |||||||||||||||||||
TRLV |
tracelevel |
0 |
Trace level for the server. See also Activating Tracing for the RPC Server for CICS.
Syntax:
Example: |
O | |||||||||||||||||||
TROP |
traceoption |
none |
Additional trace option if trace is active. See also Activating Tracing for the RPC Server for CICS.
Example: |
O | |||||||||||||||||||
USER |
userid |
ERXSRV1 |
The user ID for access to the broker. The default ERXSRV1
will be used if this parameter is omitted or specified without a value: "USER= "
Example: |
O |
The IDL library and IDL program
names that come from the 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 RPC Server for CICS 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 server mapping is used or not. See Usage of Server Mapping Files for an introduction.
If the RPC client sends a client-side type of server mapping with the RPC request, this server mapping is used first.
If no server mapping is available from step 1 above, and if server-side type of server mapping is used, the IDL library and IDL program names are used to form a key to locate the server mapping in the server-side mapping container. If a server mapping is found, this is then used.
If a server mapping is available from step 1 or 2 above, the CICS program name of the RPC server is derived from this mapping. 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.
If no server mapping is 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 RPC Server for CICS with COBOL
Make sure that all CICS programs called as RPC servers
use an interface type supported by the RPC Server for CICS for target language COBOL; see Supported Interface Types.
can be called with an EXEC CICS LINK PROGRAM
are accessible through the CICS RPL chain or accessible remotely using CICS DPL
Configure the ERXMAIN
macro parameter SVM
depending on whether server-side mapping files are used or not. See also Usage of Server Mapping Files.
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 RPC Server for CICS with PL/I
Make sure that all CICS programs called as RPC servers
use an interface type supported by the RPC Server for CICS for target language PL/I; see Supported Interface Types.
can be called with an EXEC CICS LINK PROGRAM
are accessible through the CICS RPL chain or accessible remotely using CICS DPL
See also Scenario III: Calling an Existing PL/I Server or Scenario IV: Writing a New PL/I Server.
RPC servers can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based servers are always SSL clients. The SSL server can be either the EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS and Certificates with EntireX in the Platform-independent Administration documentation.
SSL delivered on a z/OS mainframe will typically use the Resource Access Control Facility (RACF) as the certificate authority (CA). Certificates managed by RACF can only be accessed through the RACF keyring container. A keyring is a collection of certificates that identify a networking trust relationship (also called a trust policy). In an SSL client/server network environment, entities identify themselves using digital certificates called through a keyring. Server applications on z/OS that wish to establish network connections to other entities can use keyrings and their certificate contents to determine the trustworthiness of the client or peer entity. Note that certificates can belong to more than one keyring, and you can assign different users to the same keyring. Because of the way RACF internally references certificates, they must be uniquely identifiable by owner and label, and also unique by serial number plus data set name (DSN).
For establishing an SSL connection on z/OS, IBM's Application Transparent Transport Layer Security (AT-TLS) can be used, where the establishment of the SSL connection is pushed down the stack into the TCP layer.
With the RPC Server for CICS you can use IBM's Application Transparent Transport Layer Security (AT-TLS), where the establishment of the SSL connection is pushed down the stack into the TCP layer.
Configure the AT-TLS rules for the policy agent (PAGENT
) using an appropriate client and the z/OS Management Facility (z/OSMF) .
Together with SSL parameters (to provide certificates stored in z/OS as RACF keyrings) define AT-TLS rules, for example by
using the application
job name and remote TCP port number.
If the rules match, the TCP connection is turned into an SSL connection .
Refer to your IBM documentation for more information, for example the IBM Redbook Communications Server for z/OS VxRy TCP/IP Implementation Volume 4: Security and Policy-Based Networking.
Client to interact with z/OS Management Facility (z/OSMF). | |
AT-TLS rules are defined with z/OSMF policy management. | |
Policy Repository with AT-TLS rules stored as z/OS files. | |
Policy Agent, MVS task PAGENT , provides AT-TLS rules through a policy enforcement point (PEP) to TCP/IP stack.
|
|
Application using TCP connection. | |
If AT-TLS rules match, the TCP connection is turned into an SSL connection. |
Notes:
To set up SSL with AT-TLS
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the RPC Server for CICS for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:
ETB024:1699:TCP
Configure AT-TLS to turn the TCP/IP connection to an SSL connection,
using a client to interact with the z/OS Management Facility (z/OSMF).
The outcome of this configuration is a Policy Repository with AT-TLS rules stored as z/OS files.
This file is the configuration file for the Policy Agent, MVS task PAGENT
.
Make sure the SSL server to which the RPC Server for CICS connects is prepared for SSL connections as well. The SSL server can be EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:
The RPC Server for CICS provides a user exit COBUEX02
to influence/control the RPC logic. This section covers the following topics:
The user exit is called on the following events:
The numbers in the graphic correspond to the event numbers in the user exit.
Step | Event | Called | Description | Note |
---|---|---|---|---|
WHICH-VERSION |
During startup of RPC server. | The RPC Server for CICS and the exit decide on the version to use. See field VERSION .
|
||
START-WORKER |
Before starting a worker task. | This allows you to set the CICS transaction ID of the worker task. See field CICS-TRANSID .
|
1 | |
START-USER |
Before starting a user task. | Requires Impersonation. Before an impersonated CICS transaction (user task) is started, the user exit may change the user ID, CICS transaction ID
and CICS terminal ID of the new impersonated user task. See fields USERID , CICS-TRANSID and CICS-TERMID .
|
1 | |
CALL-START |
Before calling the target CICS program. | See field RPC-SERVER . You can inspect and modify the RPC request (payload data from the RPC client to the RPC server).
|
1 | |
CALL-END |
After calling the target CICS program. | See field RPC-SERVER . You can inspect and modify the RPC reply (payload data from the RPC server to the RPC client).
|
2 |
Notes:
ERROR-CODE
and ERROR-TEXT
. The RPC request is already executed.
ERROR-CODE
and ERROR-TEXT
, this error is returned to the RPC client. The RPC request is already executed.
EntireX provides the following resources for COBOL:
User exit skeleton COBUEX02
in data set EXP105.SRCE. Copy this skeleton so you have your own user exit source for modifications. The user exit program
must comply with the EXEC CICS LINK PROGRAM COMMAREA
conventions.
Copybook COBUEX02
in data set EXP105.INCL. Please add EXP105.INCL to your COBOL compiler SYSLIB DD
chain. The copybook also contains further description and usage comments.
The parameters of COBUEX02
are described below.
Parameter | Format | I/O | Description | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
EXIT-FUNCTION |
PIC 9(4) BINARY |
I | Signals the event. See User Exit Events. | |||||||||||||||||||||
VERSION |
PIC 9(4) BINARY |
I/O | For event WHICH-VERSION , see User Exit Events. On input, the RPC Server for CICS provides the maximum supported version; on output, the exit returns the version to be
used. Values 1-2 may be supplied. Some of the fields require a minimum version.
|
|||||||||||||||||||||
TRACE-LEVEL |
PIC 9(4) BINARY |
I | Informational. Value is 0-n . Corresponds to parameter tracelevel .
|
|||||||||||||||||||||
ERROR-CODE |
PIC 9(4) BINARY |
O | Must be set on output. Possible values:
|
|||||||||||||||||||||
ERROR-TEXT |
PIC X(256) |
O | Error text returned to RPC client if an error is supplied in field ERROR-CODE . Up to 256 characters.
|
|||||||||||||||||||||
CICS-TRANSID |
PIC X(4) |
I/O | Input defined by macro EMAINGEN . Default is ESRV . Can be modified on output. Available for the following events:
|
|||||||||||||||||||||
CICS-TERMID |
PIC X(4) |
O | Available for the following event:
|
|||||||||||||||||||||
USERID |
PIC X(32) |
I/O | RPC user ID supplied by calling RPC client.
Available for the following event:
|
|||||||||||||||||||||
RPC-LIBRARY |
PIC X(128) |
I | IDL library name. Informational. Availability depends on event and VERSION :
|
|||||||||||||||||||||
RPC-PROGRAM |
PIC X(128) |
I | IDL program name. Informational. Availability depends on event and VERSION :
|
|||||||||||||||||||||
INTERFACE-TYPE |
PIC X |
I | Type of interface. Informational. Available for events CALL-START and CALL-END . Possible values:
|
|||||||||||||||||||||
RPC-SERVER |
PIC X(8) |
I | Target CICS program to call. Informational. Available for the following events:
|
|||||||||||||||||||||
CHANNEL-NAME |
PIC X(16) |
I | Name of CICS Channel. Informational. Applicable if field INTERFACE-TYPE is 'C' (Channel Container). Available for the following events:
|
|||||||||||||||||||||
CHAIN-COUNTER |
PIC S9(9) BINARY |
I |
|
|||||||||||||||||||||
CHAIN-POINTER |
POINTER |
I | Informational. Pointer to first element of a table (or chain of elements) describing payload data. See structure DATA-ENTRY . Available for the following events:
|
|||||||||||||||||||||
CHAIN-COUNTER-OUT |
PIC S9(9) BINARY |
I |
|
|||||||||||||||||||||
CHAIN-POINTER-OUT |
POINTER |
I | Similar to CHAIN-POINTER . Informational. See structure DATA-ENTRY . Available for the following event:
|
|||||||||||||||||||||
RPC-RETCODE |
PIC 9(9) BINARY |
I | RPC error code. Informational.
|
|||||||||||||||||||||
CICS-ABCODE |
PIC X(4) |
I | CICS abend code. Informational. | |||||||||||||||||||||
DATA-ENTRY |
I | Structure. Informational. Consists of: DATA-NAME , DATA-LENGTH , DATA-POINTER .
|
||||||||||||||||||||||
DATA-NAME |
PIC X(16) |
I |
|
|||||||||||||||||||||
DATA-LENGTH |
PIC 9(9) BINARY |
I | Length or maximum expected length: With event CALL-START and CHAIN-POINTER-OUT : the maximum length of payload data. For all other cases, the actual length of the payload data. |
|||||||||||||||||||||
DATA-POINTER |
POINTER |
I | Pointer to payload for this element. |
Apply the name of your exit routine to the EntireX RPC server ERXMAIN
macro parameter EXIT
. See Configuring the RPC Server.
At startup, the RPC Server for CICS 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 RPC Server for CICS will continue and call the user exit for the implemented events.
The RPC Server for CICS can be started and stopped automatically during start and stop of the CICS region. For manual start/stop, see Starting the RPC Server for CICS and Stopping the RPC Server for CICS under RPC Online Maintenance Facility.
To start the RPC Server for CICS during the initialization of CICS
If the COBOL source ERXSTART
of the EntireX installation library EXP105.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 the RPC Server for CICS in the z/OS Installation documentation.
To stop the RPC Server for CICS during the shutdown of CICS
If the COBOL source ERXSTOP
of the EntireX installation library EXP105.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 the RPC Server for CICS in the z/OS Installation documentation.
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 the RPC Server for CICS in the z/OS Installation documentation.