Version 9.5 SP1
 —  EntireX z/OS CICS® RPC Server  —

Administering the CICS RPC Server

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:


Customizing the RPC Server

The following elements are used for setting up the CICS RPC Server:

ERXMAIN Control Block

ERXMAIN Macro

RPC Online Maintenance Facility

IBM LE Runtime Options

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.

Top of page

Configuring the RPC Server

The followings rules apply for the ERXMAIN Macro syntax (column 1 in table below):

The followings rules apply for the RPC Online Maintenance Facility commands (column 2 in table below):

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:
BKRN=myhost.com:1971

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:
CLZN=MyRPC

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:
SRVN=mySrv

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:
SVCN=MYSERVICE

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:

  • follow the rules described under Locale String Mapping

  • be a codepage supported by the broker

  • be the codepage used in your environment for file and terminal IO, otherwise unpredictable results may occur.

Example:
CODE=ibm-273

O
COMP compresslevel N Enforce compression when data is transferred between broker and server. See Data Compression in EntireX Broker.

compresslevel= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8| 9 | Y | N

0-9 0=no compression
9=max. compression
N No compression.
Y Compression level 6.

Example:
COMP=6

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:

timeout + ETB_TIMEOUT + 60 seconds

where timeout is the RPC server parameter (see this table), and
  ETB_TIMEOUT is the environment variable (see Environment Variables in EntireX)

When the number of cycles is reached and a connection to the broker is not possible, the RPC server stops.

Example:
CYCL=30

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.
YES Activates the deployment service. The RPC server registers the deployment service in the broker.
NO The deployment service is deactivated. The RPC server does not register the deployment service in the broker.

Example:
DPLY=YES

O
ENCR encryptionlevel 0 Enforce encryption when data is transferred between client and server. Requires EntireX Security. See ENCRYPTION-LEVEL under Broker ACI Fields.
0 Encryption is enforced.
1 Encryption is enforced between server and broker kernel.
2 Encryption is enforced between server and broker kernel, and also between client and broker.

Example:
ENCR=2

O
ENDW endworker TIMEOUT
NEVER Defines worker model FIXED with a fixed number of worker threads. The number of active workers is defined with ERXMAIN macro parameter MINW.
TIMEOUT Defines slow-shrinking worker model SCALE, where the number of worker threads is adjusted to the current number of client requests. With value TIMEOUT, all worker threads not used are stopped in the time specified by the ERXMAIN macro parameter TOUT, except for the minimum number of active workers specified with ERXMAIN macro parameter MINW. The upper limit of workers parallel active is restricted with ERXMAIN macro parameter MAXW.
IMMEDIATE Defines fast-shrinking worker model SCALE, where the number of worker threads is adjusted to the current number of client requests. With value IMMEDIATE, worker threads not used are stopped immediately as soon as they have finished their conversation, except for the minumum number of active workers defined with ERXMAIN macro parameter MINW. The upper limit of workers active in parallel is restricted with ERXMAIN macro parameter MAXW.

This parameter is forced to value TIMEOUT if impersonation is switched on, see Impersonation and ERXMAIN macro parameter IMPS.

Example:
ENDW=IMMEDIATE,MINW=2,MAXW=6

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:
MINW=2

O
MAXW maxworker 10 Upper limit of workers active in parallel with worker model SCALE. See also ERXMAIN macro parameter ENDW.

Example:
MAXW=2

O
ETBL etblnk CICSETB Define the broker stub to be used. See Administration of Broker Stubs under z/OS for available stubs.

Example:
ETBL=CICSETB

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
Defines if RPC requests are executed under the user ID of the RPC client. Depending on settings, different levels of checks are done prior to RPC server execution. See also Impersonation.

impersonation= NO | AUTO [, sameuser | , anyuser ]
 

NO The RPC request is executed anonymously, which means the user ID of the RPC client is not used. RPC requests are executed under the user ID of the RPC server.
AUTO The RPC request runs impersonated under the supplied RPC client user ID. For execution of the RPC request, the CICS RPC Server starts a separate impersonated user task with the RPC client user ID. This means the user ID must be known to CICS, but no password check is performed. The worker model SCALE is forced; for details see Impersonation.

For this setting you have to take care the RPC client is correctly authenticated: use either a secure EntireX Broker (validation must be against the correct mainframe security repository where the user IDs are defined) and option sameuser, or use your own security implementation (option anyuser is supported for compatibility reasons if you need different broker and server user IDs - the customer-written security implementation must validate the RPC client using the RPC client user ID).

sameuser The CICS RPC Server checks whether the broker client user ID matches the RPC client user ID. This is the default if AUTO is used.
anyuser The RPC client user ID is used for authentication. The broker client user ID is ignored.

Notes:

  1. EntireX supports two user ID/password pairs: a broker client user ID/password pair and an (optional) RPC user ID/password pair sent from RPC clients to the RPC server.
  2. With EntireX Security, the broker client user ID/password pair is checked. The RPC user ID/password pair is designed to be checked by the target RPC server. Thus it is possible to use different user IDs in the broker and target RPC server.
  3. RPC clients send the (optional) RPC user ID/password pair in the same way as specifying the Natural user ID/password pair for a Natural RPC Server. See for example Using Natural Security for applications in C | COBOL | PL/I | Web Services | SOAP/XML | Java.
  4. If the RPC client does not specify the optional RPC user ID/password pair, the broker client user ID/password pair is inherited to the RPC user ID/password pair and thus used for impersonation by the CICS RPC Server.

Example:
IMPS=auto

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.
NO No logon/logoff functions are executed.
YES Logon/logoff functions are executed.

Example:
LOGN=no

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:
OPTS=(<option-list>)
<option-list> = [<option-list>,] <option>

Example:
OPTS=(RUNOPT1,RUNOPT2)

O
PSWD password   Password for broker logon. Case-sensitive, up to 32 characters. For more information see broker ACI control block field PASSWORD.

Example:
PSWD=MyPwd

O
PRELOAD preload YES Enable to call CICS RPC Server with AMODE=24
YES Enable to call RPC server with AMODE 24 or 31. Internally the CICS RPC Server preloads the called RPC server before execution to check the AMODE and releases the RPC server after this. The disadvantage of this approach is the CICS USECOUNT of the called RPC server program is increased by 2 for every executed RPC call.
NO The CICS RPC Server does not preload the called RPC server to check its AMODE. All RPC servers are called as running in AMODE 31. This option is useful for customers who require the CICS USECOUNT in their accounting (increased by 1 for every executed RPC call) but prevents usage of calling 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:
SMH=3001

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:
SVM=NO | cicsname

cicsname The RPC server tries to open the SVM container using the CICS file with name cicsname.
no No server mappings are used.

Example:
SVM=MYSVM

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 SCALE to define the lifetime of worker threads in slow-shrinking worker model SCALE.

Example:
TOUT=300

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:
TRLV= None | Standard | Advanced | Support

None No trace output.
Standard For minimal trace output.
Advanced For detailed trace output.
Support This trace level is for support diagnostics and should only be switched on when requested by Software AG support.

Example:
TRLV=standard

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:
USER=MyUid

R

Top of page

Locating and Calling the Target Server

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:

COBOL

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.

Start of instruction setTo use the CICS RPC Server with COBOL

  1. Make sure that all CICS programs called as RPC servers

  2. 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.

PL/I

There is a simple mechanism to derive the RPC server CICS program name:

Start of instruction setTo use the CICS RPC Server with PL/I

  1. Make sure that all CICS programs called as RPC servers

See also Scenario III: Calling an Existing PL/I Server or Scenario IV: Writing a New PL/I Server.

Top of page

Using SSL or TLS with the RPC 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.

Start of instruction setTo set up SSL or TLS with AT-TLS

  1. Set up the CICS RPC Server for a TCP/IP connection.

  2. 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.

  3. Make sure the target the CICS RPC Server connects to is prepared for SSL/TLS connections as well. See the following sections:

Top of page

RPC User Exits

This section covers the following topics:

Writing and Configuring User Exit COBUEX02

Writing User Exit COBUEX02

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.

User Exit Events

graphics/intro_inside_userExits.png

graphics/no1.png 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.
graphics/no2.png 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.
graphics/no3.png 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.
graphics/no4.png 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.

Configuring User Exit COBUEX02

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.

Using User Exit RPCUEX01

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:

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) 

Restrictions

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.

Process Flow

graphics/intro_inside_userExits_rpc.png

graphics/no1.png The server program is invoked within the user task.
graphics/no2.png 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.
graphics/no3.png 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.

Usage

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:

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

Top of page

Autostart/Stop during CICS Start/Shutdown

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.

Start of instruction setTo start the CICS RPC Server during the initialization of CICS

  1. 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.

  2. Customize and compile ERXSTART if necessary.

  3. 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.

Start of instruction setTo stop the CICS RPC Server during the shutdown of CICS

  1. 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.

  2. Customize and compile ERXSTOP if necessary.

  3. 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.

Top of page

Multiple RPC Servers in the same 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.

Top of page