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:

• Customizing the RPC Server

• Configuring the RPC Server

• Locating and Calling the Target Server

• Using SSL/TLS with the RPC Server

• User Exit COBUEX02

• Autostart/Stop during CICS Start/Shutdown

• Multiple RPC Servers in the same CICS

---

Customizing the RPC Server

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:

• ERXMAIN Control Block

• ERXMAIN Macro

• RPC Online Maintenance Facility

• IBM LE Runtime Options

• CICS Settings

ERXMAIN Control Block

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

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

  • 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 RPC Servers for CICS 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 RPC Server for CICS

• needs to be assembled to define a setup

• is defined in Assembler program EMAINGEN (in EXP109.SRCE) - use this for assembling; see Build the ERXMAIN Control Block in the z/OS installation documentation

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

IBM LE Runtime Options

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 IBM Z Publications Library Archive.

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.

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 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.	Use resource definition online (RDO), CICS transaction CEDA. See member DFHERX in EXP109.SRCE data set. See Updating 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, 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: 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). 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. 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. Case-sensitive, up to 32 characters. Corresponds to SERVICE attribute of the broker attribute file. Example: SVCN=MYSERVICE	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 CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.	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 RPC Server for CICS running while the broker is down for a short time. A restart cycle will be repeated every 60 seconds. Note: Internally, the server waits in periods of 10 seconds (performing six times more cycles), which you can see in the server output. When the number of specified cycles is reached and a connection to the broker is not possible, the RPC Server for CICS stops. Example: CYCL=30 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. 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
ENDW	endworker	TIMEOUT	NEVER Defines worker model FIXED with a fixed number of worker threads. The number of worker threads is defined with ERXMAIN macro parameter MINW. It does not increase or decrease during the lifetime of an RPC server instance. TIMEOUT Defines slow-shrinking worker model DYNAMIC, 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 DYNAMIC, 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 worker threads. For worker model DYNAMIC: minimum number of active worker threads, even if no RPC client requests have to be processed. This allows you to define a certain number of worker threads - not used by the currently executing RPC request - to wait for new RPC client requests to process. In this way the RPC server is ready to handle many RPC client requests arriving at the same time. Do not set a value higher than ERXMAIN macro parameter MAXW. For worker model FIXED: number of active worker threads. 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 worker threads and impersonated user tasks. For worker model DYNAMIC: used to restrict the system load. Do not set a value higher than 31 without adjusting ERXMAIN macro parameter SIZE. See also ERXMAIN macro parameter ENDW. For Impersonation: worker threads 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	CICSETB	Define the broker stub to be used. See Administering Broker Stubs for available stubs. Example: ETBL=CICSETB	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	Defines if RPC requests are executed under the RPC user ID of the calling RPC client. For how to send the RPC user ID/password pair from an RPC client, see Using the Broker and RPC User ID/Password (.NET Wrapper | Java Wrapper | C Wrapper | PL/I Wrapper | DCOM Wrapper | Web Services Wrapper | IDL Tester | Listener for XML/SOAP | Listener for IBM MQ). For the COBOL Wrapper, refer to Using Broker Logon and Logoff and Using RPC Authentication (Natural Security, Impersonation, Integration Server). For non-RPC clients, see Using the Broker and RPC User ID/Password under EntireX XML Tester in the XML/SOAP Wrapper documentation. Depending on settings, different levels of checks are done prior to RPC server execution. See also Impersonation under Introduction to the RPC Server for CICS. impersonation=NO|YES|AUTO[,sameuser|,anyuser] NO The RPC request is executed anonymously, which means the user ID of the calling 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 RPC Server for CICS starts a separate impersonated user task, that is, the client must be known to CICS and the supplied password is validated against CICS. The worker model DYNAMIC is forced; for details see Impersonation. AUTO Same as option YES above, except that no password validation is performed, that is, the calling RPC 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 calling RPC client using the RPC client user ID). The following options are available for AUTO: sameuser The RPC Server for CICS 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. 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 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: OPTS=(<option-list>) <option-list> = [<option-list>,] <option> Example: OPTS=(RUNOPT1,RUNOPT2)	O
PSWD	password		The password for secured access to the broker. Example: PSWD=MyPwd	O
PRELOAD	preload	YES	Enable to call RPC Server for CICS with AMODE=24 YES Enable to call RPC server with AMODE 24 or 31. Internally the RPC Server for CICS 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 RPC Server for CICS 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 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: The theoretical maximum number of tasks can be calculated using the formula: maximum = integer part of ((SIZE-2036)/864-1). For tasks in intermediate states (starting or ending), the theoretical maximum number must be reduced. We recommend reserving at least 10% for this purpose. If impersonation is used, the theoretical maximum number must be halved. This means: For the default SIZE value of 32768, the theoretical maximum number of tasks (see rule 1 above) is 34 ((32768-2036)/864-1). Reducing this value by at least 10% (see rule 2 above) gives 31 for MAXW if no impersonation is used. If impersonation is used, MAXW should be no more than 15 (see rule 3 above).	O
SVM	svmfile		Usage and location of server-side mapping files (Designer files with extension .svm at runtime). See Server-side Mapping Files in the RPC Server. If the SVM parameter is omitted, 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 at runtime, 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. Server mapping files with extension .svm are no longer supported at design time by the Designer. You can still use them at runtime in a server-side mapping container. All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping files with extension .cvm. See When is a Server Mapping File Required? We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation. 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
SYNC		Y	Determines whether a CICS SYNCPOINT COMMIT command is issued. YES Execute CICS SYNCPOINT COMMIT. If running without Impersonation, the server issues a SYNCPOINT COMMIT command after a successful non-conversational request or an end-of-conversation. NO Do not execute CICS SYNCPOINT COMMIT. If running with Impersonation, a SYNCPOINT COMMIT command is issued by CICS when the user task ends. This cannot be disabled. See also Automatic Syncpoint Handling.	O
TOUT	timeout	600	Timeout in seconds, used by the server to wait for broker requests. See WAIT under Broker ACI Fields for more information. Also influences restartcycles and worker model DYNAMIC. Example: TOUT=300	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: 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. Use only when requested by Software AG Support. Example: TRLV=standard	O
TROP	traceoption	none	Additional trace option if trace is active. See also Activating Tracing for the RPC Server for CICS. None No additional trace options. STUBLOG If tracelevel is Advanced or Support, the trace additionally activates the broker stublog. NOTRUNC Normally if a data buffer larger than 8 KB is traced, the buffer trace is truncated. Set this option to write the full amount of data without truncation. Note: This can increase the amount of trace output data dramatically if you transfer large data buffers. Example: TROP=(STUBLOG,NOTRUNC)	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: USER=MyUid	O

Locating and Calling the Target Server

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:

• COBOL

• PL/I

COBOL

The CICS program name for the RPC server called is taken from the server mapping if one is available. See Usage of Server Mapping Files for an introduction. If no server mapping is used, the IDL program name is used as the CICS program name of the RPC server and the IDL library name is ignored.

To use the RPC Server for CICS with COBOL

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

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:

• 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

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

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, HTTP(S), 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.

Using IBM's Application Transparent Transport Layer Security (AT-TLS)

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:

1. The client may vary per operating system, for example a Web browser for z/OS 2.1.
2. z/OSMF includes other administration and management tasks in addition to policy management.
3. Policy Management includes other rules, such as IP filtering, network address translation etc.

To set up SSL with AT-TLS

1. To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

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

3. 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) See z/OSMF Considerations in the z/OS Administration documentation. 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.

4. 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:

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

   • Broker SSL Agent (Linux | Windows)

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

User Exit COBUEX02

The RPC Server for CICS 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:

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:

1. An RPC request can be terminated if an error is given in the fields ERROR-CODE and ERROR-TEXT. The RPC request is already executed.
2. If an error is given in the fields ERROR-CODE and ERROR-TEXT, this error is returned to the RPC client. The RPC request is already executed.

Writing the User Exit

EntireX provides the following resources for COBOL:

• User exit skeleton COBUEX02 in data set EXP109.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 EXP109.INCL. Add EXP109.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: 0 Success. Continue this RPC request. 1..9999  Stop the RPC request. Reply with error class 1022 together with field ERROR-TEXT to the calling RPC client.   Example: Error code value nnnn results in the following error message: 1022nnnn error-text. See Message Class 1022 - RPC Server for CICS User Exit Messages.
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: START‑WORKER  Transaction ID to start the WORKER-TASK. START‑USER Transaction ID to start the USER-TASK. Requires Impersonation.
CICS-TERMID	PIC X(4)	O	Available for the following event: START‑USER If applied on output, starts the USER-TASK with the supplied terminal ID. Requires Impersonation.
USERID	PIC X(32)	I/O	RPC user ID supplied by calling RPC client. For how to send the RPC user ID/password pair from an RPC client, see Using the Broker and RPC User ID/Password (.NET Wrapper | Java Wrapper | C Wrapper | PL/I Wrapper | DCOM Wrapper | Web Services Wrapper | IDL Tester | Listener for XML/SOAP | Listener for IBM MQ). For the COBOL Wrapper, refer to Using Broker Logon and Logoff and Using RPC Authentication (Natural Security, Impersonation, Integration Server). For non-RPC clients, see Using the Broker and RPC User ID/Password under EntireX XML Tester in the XML/SOAP Wrapper documentation. Available for the following event: START‑USER If applied on output, starts the USER-TASK with the supplied user ID. Requires Impersonation.
RPC-LIBRARY	PIC X(128)	I	IDL library name. Informational. Availability depends on event and VERSION: START‑USER If field VERSION >=2 has been set on WHICH-VERSION. CALL-START All supported field VERSIONs. CALL-END All supported field VERSIONs.
RPC-PROGRAM	PIC X(128)	I	IDL program name. Informational. Availability depends on event and VERSION: START‑USER If field VERSION >=2 has been set on WHICH-VERSION. CALL-START All supported field VERSIONs. CALL-END All supported field VERSIONs.
INTERFACE-TYPE	PIC X	I	Type of interface. Informational. Available for events CALL-START and CALL-END. Possible values: D  DFHCOMMAREA C Channel Container W Large Buffer
RPC-SERVER	PIC X(8)	I	Target CICS program to call. Informational. Available for the following events: CALL-START All supported field VERSIONs. CALL-END All supported field VERSIONs.
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: CALL-START All supported field VERSIONs. CALL-END All supported field VERSIONs.
CHAIN-COUNTER	PIC S9(9) BINARY	I	Number of DATA-ENTRY elements describing payload data. Informational. Content depends on event and interface type: Event Interface Type Chain Counter CALL‑START DFHCOMMAREA 1 CALL-END DFHCOMMAREA 1 CALL-START Channel Container number-input-containers CALL-END Channel Container number-output-containers CALL-START Large Buffer 1 CALL-END Large Buffer 1
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: CALL‑START  The table or chain of elements (structure DATA-ENTRY) contains descriptions of input payload data. CALL-END The table or chain of elements (structure DATA-ENTRY) contains descriptions of output payload data.
CHAIN-COUNTER-OUT	PIC S9(9) BINARY	I	Similar to CHAIN-COUNTER. Number of DATA-ENTRY elements describing payload data. Informational. Content depends on event and interface type: CALL‑START  DFHCOMMAREA 1 CALL-START Channel Container number-output-containers CALL-START Large Buffer 1
CHAIN-POINTER-OUT	POINTER	I	Similar to CHAIN-POINTER. Informational. See structure DATA-ENTRY. Available for the following event: CALL‑START If field VERSION >=2 has been set on WHICH-VERSION. The table or chain of elements (structure DATA-ENTRY) contains descriptions of expected output payload data with maximum length for variable length data, for example OCCURS DEPENDING ON ...
RPC-RETCODE	PIC 9(9) BINARY	I	RPC error code. Informational. 1001 0045 CICS abend code. 1002 nnnn User-definable server message. ...   See Error Messages and Codes.
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	Name of element. Content depends on INTERFACE-TYPE. The main purpose is to deliver the container names for the interface type Channel Container. Event Interface Type Container Name CALL‑START DFHCOMMAREA 'DFHCOMMAREA' CALL-END DFHCOMMAREA 'DFHCOMMAREA' CALL-START Channel Container input-container-name or output-container-name CALL-END Channel Container output-container-name CALL-START Large Buffer 'WM-LCB-INPUT' CALL-END Large Buffer 'WM-LCB-OUTPUT'
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.

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

Autostart/Stop during CICS Start/Shutdown

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

1. If the COBOL source ERXSTART of the EntireX installation library EXP109.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 the RPC Server for CICS in the z/OS Installation documentation.

To stop the RPC Server for CICS during the shutdown of CICS

1. If the COBOL source ERXSTOP of the EntireX installation library EXP109.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 the RPC Server for CICS in the z/OS Installation documentation.

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) in the z/OS Installation documentation.