The EntireX z/VSE CICS® RPC Server allows standard RPC clients to communicate with RPC servers on the operating system z/VSE under CICS. It supports the programming language COBOL. This document covers the following topics:

• Customizing the RPC Server

• Configuring the RPC Server

• Locating and Calling the Target Server

• Using SSL/TLS with the RPC Server

• User Exit COBUEX02

• Multiple RPC Servers in the same CICS

---

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

• CICS Settings

ERXMAIN Control Block

• 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:

  • connection information such as broker ID, see BKRN, server address, see CLZN, SRVN and SVCN

  • location and usage of server-side mapping container, see SVM and Usage of Server Mapping Files

  • scalability parameters such as endworker, minworker and maxworker, see ENDW, MINW and MAXW

  • etc.

• 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 CICS RPC Servers can be started and monitored in parallel. See Installing Multiple EntireX RPC Servers in the same CICS (Optional).

ERXMAIN Macro

• 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 sublibrary EXP960) - use this for assembling; see Build the ERXMAIN Control Block under Installing EntireX RPC Servers under CICS

RPC Online Maintenance Facility

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

CICS Settings

CICS Parameter	Description	Default	How to change?
TWASIZE	Transaction Work Area (TWA) size may be used by target RPC programs called by the CICS RPC server. If this is the case, the TWA size set for the CICS RPC server must match the largest TWA size required by all called target RPC programs.	TWASIZE(28)	Use resource definition online (RDO), CICS transaction CEDA. Use job CICSDEF.J in sublibrary EXP960. See Step 4: Update the CICS Tables.

Configuring the RPC Server

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, 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: 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 every 60 seconds. 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 Server Mapping Deployment Wizard. See Server Mapping Deployment Wizard in the EntireX Workbench 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	Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.	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 minimum 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 limit of tasks active in parallel. For worker model SCALE: minimum number of workers active in parallel. Do not set a value higher than ERXMAIN macro parameter MAXW. For worker model FIXED: number of workers active in parallel. Do not set a value higher than 31 without adjusting ERXMAIN macro parameter SIZE. See also ERXMAIN macro parameter ENDW. Example: MINW=2	O
MAXW	maxworker	10	Upper limit of tasks active in parallel. For worker model SCALE: workers active in parallel. Do not set a value higher than 31 without adjusting ERXMAIN macro parameter SIZE. See also ERXMAIN macro parameter ENDW. For Impersonation: workers and impersonated user tasks active in parallel. Do not set a value higher than 15 without adjusting ERXMAIN macro parameter SIZE. See also ERXMAIN macro parameter IMPS. Example: MAXW=2	O
ETBL	etblnk	BKIMC	Define the broker stub to be used. See Administration of Broker Stubs under z/VSE for available stubs. Example: ETBL=BKIMC	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 Exit COBUEX02.	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 | YES | 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. YES 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, that is, the client must be know to CICS and the supplied password is validated against CICS. The worker model SCALE is forced; for details see Impersonation. AUTO Same as option YES above, except that no password validation is performed, that is, the client is treated as already authenticated. For this setting, make sure the RPC client is correctly authenticated; use either a secure broker (validation must be against the correct mainframe security repository where the user IDs are defined) and option sameuser or 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 impersonation. The broker client user ID is ignored. Notes: 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. 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. 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 under C | COBOL | PL/I | Web Services | SOAP/XML | Java. If the RPC client does not specify the optional RPC user ID/password pair, the broker client user ID is inherited to the RPC user ID 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 Exit COBUEX02) the CICS transaction ID for user tasks can be overridden. See also Introduction to the CICS RPC Server.	O
SIZE	n/a	32768	Upper limit of tasks active in parallel. For worker model SCALE: workers active in parallel. Do not set a value higher than 31 without adjusting ERXMAIN macro parameter SIZE. See also ERXMAIN macro parameter ENDW. For Impersonation: workers and impersonated user tasks active in parallel. Do not set a value higher than 15 without adjusting ERXMAIN macro parameter SIZE. See also ERXMAIN macro parameter IMPS. Example: MAXW=2	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 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 Step 1: Define a Server-side Mapping Container - VSAMDEF.J (Optional) under Installing the z/VSE EntireX RPC Servers. There are also client-side mapping files that do not require configuration here; see Server Mapping Files for COBOL. Syntax: SVM=NO | cicsname cicsname The RPC server tries to open the server-side mapping container using the CICS file with name cicsname. no No server-side mapping files are used. Example: SVM=MYSVM See also Usage of Server Mapping Files.	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

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.

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.

1. If the RPC client sends a client-side type of server mapping with the RPC request, this server mapping is used first.

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

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

4. 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 CICS RPC Server with COBOL

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

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

Using SSL/TLS with the RPC 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 in the Security documentation.

Establishing an SSL connection on z/VSE requires BSI's Automatic Transport Layer Security (ATLS). This facility is similar to z/OS Application Transparent - Transport Layer Security (AT-TLS). ATLS is supported by the BSI stack only.

Using BSI's Automatic Transport Layer Security (ATLS)

Together with SSL parameters (to provide certificates), define ATLS rules for socket interception in the ATLS daemon startup job BSTTATLS . If the rules match, the socket connection is turned into an SSL connection . Refer to your IBM documentation for further information. For an overview, refer to the IBM Redbook Enhanced Networking on IBM z/VSE; for a more detailed description, refer to BSI SSL Installation, Programming and User's Guide.

	BSI TCP/IP Stack, either BSTTINET (IPv4) or BSTT6NET (IPv6).
	ATLS rules are defined manually. See Sample ATLS Daemon Configuration below.
	BSTTATLS is associated with a TCP/IP stack.
	Application using TCP connection.
	BSTTATLS intercepts outbound TCP connection and converts it to SSL connection. For inbound, SSL connections can also be intercepted and converted to TCP connections.

To set up SSL with ATLS

1. 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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the Security documentation.

2. Set up the CICS RPC Server for a TCP/IP connection. On mainframe platforms, use Transport-method-style Broker ID. Example:

   ETB024:1699:TCP

3. Configure ATLS to turn the TCP/IP connection to an SSL connection, see above.

4. Make sure the SSL server to which the CICS RPC Server 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:

   • Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE

   • Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

   • Support for SSL/TLS in the EntireX Adapter documentation (for Direct RPC)

Sample ATLS Daemon Configuration

* Converting inbound EntireX Broker connection 
* Converts listen port 1971 to SSL listen port 1972
OPTION SERVER 
ATTLS 1971 AS 2071 SSL
*
* Converting outbound client connection
* Converts connect to 192.168.2.100:1972:TCP to 192.168.2.100:2072:SSL
OPTION CLIENT
ATTLS 1972 TO 192.168.2.100 AS 2072 SSL

Note:
We recommend setting SETPARM value SUBTASK to a value greater than 0 in the ATLS daemon startup job (valid values 0-16, default=0). For example:

// SETPARM SUBTASK=8

See also BSI SSL Installation, Programming and User's Guide.

User Exit COBUEX02

The CICS RPC Server provides a user exit COBUEX02 to influence/control the RPC logic. This section covers the following topics:

• User Exit Events

• Writing the User Exit

• Configuring the User Exit

User Exit Events

The user exit is called on the following events:

	START-WORKER event before a CICS worker task is started. This allows you to programmatically 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.

Writing the User Exit

The Developer's Kit RPC source data set EXP960.SRCE of the EntireX CICS 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 EXP960.INCL. Please add this library to your COBOL compiler SYSLIB DD chain.

The sublibrary EXP960 of the EntireX CICS installation provides the user exit skeleton COBUEX02.C for COBOL. Copy this skeleton so you have your own user exit source for modifications.

Accordingly, a COBOL copybook COBUEX02.CPY is provided in EXP960.

Hint: The copybook extension CPY might not be understood by the z/VSE COBOL compiler. In this case, copy COBUEX02.CPY into your copybook library and rename it to COBUEX02.C. Add this library to your COBOL compiler LIBDEF 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.

Configuring the User Exit

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.

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 in the z/VSE installation documentation.