Administering the EntireX CICS® ECI RPC Server

The EntireX CICS® ECI RPC Server allows standard RPC clients to communicate with CICS programs running on IBM CICS®. It supports the programming languages COBOL and PL/I and transforms the RPC requests from clients into messages to CICS ECI.

This document covers the following topics:

Customizing the CICS ECI RPC Server
Configuring the RPC Server Side
Configuring the CICS ECI Side
Using SSL/TLS with the RPC Server
Starting the CICS ECI RPC Server
Stopping the RPC Server
Running the RPC Server as a Windows Service
Application Identification

Customizing the CICS ECI RPC Server

The following are used to set up the CICS ECI RPC Server:

Configuration File
Start Script

Configuration File

The default name of the configuration file is entirex.cicseci.properties. The CICS ECI RPC Server searches for this file in the current working directory.

You can set the name of the configuration file with -Dentirex.server.properties=<your file name> with "/" as file separator.

The configuration file contains the configuration for both parts of the CICS ECI RPC Server.

graphics/cicsEci_config.png

Configuring more than one CICS ECI RPC Server

If you configure more than one CICS ECI RPC Server that connect to the same broker, the following items must be distinct:

the trace output file (property entirex.server.logfile)
the log for the Windows Service (property entirex.server.serverlog)

Start Script

The start script for the CICS ECI RPC Server is called cicseciserver.bsh (UNIX) or cicseciserver.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file. The CICS ECI RPC Server itself is contained in the file entirex.jar.

Configuring the RPC Server Side

The CICS ECI RPC Server uses the properties that start with "entirex.server" for configuring the RPC server side.

Alternatively to the properties, you can use the command-line options. These have a higher priority than the properties set as Java system properties, and these have higher priority than the properties in the configuration file.

Property Name Command-line Option Default Explanation

entirex.bridge.verbose no Verbose/trace mode of CICS ECI RPC Server. Set this to "yes" to trace sent to CICS ECI.

entirex.server.brokerid -broker localhost Broker ID. See URL-style Broker ID.

entirex.server.serveraddress -server RPC/SRV1/CALLNAT Server address.

entirex.server.userid -user CICSECIRPCServer The user ID for the Broker for RPC. See entirex.server.password.

entirex.server.fixedservers no If no, use attach thread to manage worker threads; see SCALE. Otherwise run a fixed number of worker threads; see FIXED.

entirex.server.minservers 1 Minimum number of server threads.

entirex.server.maxservers 32 Maximum number of server threads.

entirex.server.restartcycles -restartcycles 15 Number of restart attempts if the Broker is not available. This can be used to keep the CICS ECI RPC Server running while the Broker is down for a short time.

entirex.server.password -password The password for secured access to the Broker.
The password is encrypted and written to the property entirex.server.password.e.
To change the password, set the new password in the properties file (default is entirex.cicseci.properties).
To disable password encryption set entirex.server.passwordencrypt=no. Default for this property is "yes".

entirex.server.security -security no no|yes|auto|name of BrokerSecurity object

entirex.server.compresslevel

-compresslevel

0

Permitted values (you can enter the text or the numeric value)

`BEST_COMPRESSION`	`9`
`BEST_SPEED`	`1`
`DEFAULT_COMPRESSION`	`-1`, mapped to `6`
`DEFLATED`	`8`
`NO_COMPRESSION`	`0`
`N`	`0`
`Y`	`8`

entirex.server.waitattach 600S Wait timeout for the attach server thread.

entirex.server.waitserver 300S Wait timeout for the worker threads.

entirex.timeout 20 TCP/IP transport timeout. See Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI.

entirex.server.verbose -verbose no Enable verbose output to the log file.

-help Display usage of the command-line parameters.

entirex.server.logfile -logfile Name of the log file, default is standard output.

entirex.trace -trace 0 Trace level (1,2,3).

Configuring the CICS ECI Side

These properties are used to configure the connection to CICS ECI.

Alternatively, you can use the command-line options. These have a higher priority than the properties set as Java system properties, and these have higher priority than the properties in the configuration file.

Name	Default Value	Explanation
`cics.host`		Host name of CICS ECI. Mandatory.
`cics.port`		Port number of CICS ECI. Mandatory.
`cics.transaction`		Name of the CICS mirror transaction that will receive transactions. Mandatory.
`entirex.bridge.targetencoding`	`cp037`	Specify the appropriate EBCDIC encoding used by your CICS ECI. This codepage is also used when communicating with the EntireX Broker. Note: Enable conversion in the Broker attribute file so the data can be converted correctly, typically by setting service-specific attribute `CONVERSION` to "`SAGTCHA`". Default "`cp037`" is EBCDIC codepage with full Latin-1 character set.
`cics.sockettimeout`	`10000`	Socket timeout for connection to CICS ECI (in milliseconds).
`cics.userid`		RACF user ID. Maximum 8 bytes (optional).
`cics.password`		RACF password/PassTicket. Maximum 8 bytes (optional).
`cics.sslparams`		SSL parameters (optional). Same syntax as Broker ID.
`cics.mapping.folder`		The folder where the RPC server expects server-side mapping files (EntireX Workbench files with extension .svm). See Deploying Server-side Mapping Files to the RPC Server and Undeploying Server-side Mapping Files from the RPC Server. There are also client-side mapping files that do not require configuration here. See Server Mapping Files for COBOL. If no server requires server-side mapping, you can omit this property. If one server requires server-side mapping, this property must be specified.

Using SSL/TLS with the RPC Server

To use SSL with the CICS ECI RPC Server, you need to configure two sides:

CICS ECI Side
See parameter cics.sslparams under Configuring the CICS ECI Side.
RPC Server Side
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 or Broker SSL Agent. For an introduction see SSL/TLS and Certificates with EntireX in the EntireX Security documentation.

To use SSL
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 SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
2. Set up the CICS ECI RPC Server for an SSL connection.
  
  Use the URL-style Broker ID with protocol ssl:// for the Broker ID. If no port number is specified, port 1958 is used as default. Example:
```
ssl://localhost:22101?trust_store=C:\SoftwareAG\EntireX\etc\ExxCACert.jks?verify_server=no
```
  If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store parameter specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of the SSL server. By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the connection will be refused. You can disable this check with SSL parameter verify_server=no.
  
  If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server). Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd. This keystore must contain the private key of the SSL client. The password that protects the private key is specified with key_passwd.
  
  The ampersand (&) character cannot appear in the password.
  
  SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.
3. Make sure the SSL server to which the RPC side connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Broker SSL Agent. 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

Starting the CICS ECI RPC Server

Start of instruction set To start the CICS ECI RPC Server

Use the Start Script.

Or:
Under Windows you can use the CICS ECI RPC Server as a Windows Service. See Running the RPC Server as a Windows Service.

Stopping the RPC Server

Start of instruction set To stop the CICS ECI RPC Server

Use the command stopServer. See Stop EntireX Broker Server Instances in Command Central's Command-line Interface.

Or:
Stop the server instance using Command Central's Graphical User Interface. See Stopping a Server Instance.

Or:
Use the command stopService. See Stop Running EntireX Broker Services in Command Central's Command-line Interface.

Or:
Stop the service using Command Central's Graphical User Interface. See Stopping a Service.

Or:
Use the command-line utility etbcmd. See ETBCMD under z/OS | UNIX | Windows | z/VSE | BS2000.

Or:
Use CTRL-C in the session where you started the RPC server instance.

Or:
Under UNIX, enter command kill -process-id.

Running the RPC Server as a Windows Service

For general information see Running an EntireX RPC Server as a Windows Service.

Start of instruction set To run the CICS ECI RPC Server as a Windows Service

Customize the Start Script according to your system installation.
Note:
The script must pass external parameters to the RPC server and use the reduced signaling of the JVM (option -Xrs):
```
java -Xrs com.softwareag.entirex.cics.bridge.CicsRPCServer %*
```
If -Xrs is not used, the JVM stops and an entry 10164002 is written to the event log when the user logs off from Windows.
See also Starting the RPC Server.
Test your RPC server to see whether it will start if you run your script file.
Use the EntireX RPC Service Tool and install the RPCService with some meaningful extension, for example MyServer. If your Start Script is cicseciserver.bat, the command will be
```
RPCService -install -ext MyServer -script install_path\EntireX\bin\cicseciserver.bat
```
The log file will be called RPCservice_MyServer.log.
In Windows Services menu (Control Panel > Administrative Tools > Services) select the service: Software AG EntireX RPC Service [MyServer] and change the property Startup Type from "Manual" to "Automatic".

Application Identification

The application identification is sent from the CICS ECI RPC Server to the Broker. It is visible with Broker Command and Information Services.

The identification consists of four parts: name, node, type, and version. These four parts are sent with each Broker call and are visible in the trace information.

For the CICS ECI RPC Server, these values are:

Identification Part	Value
Application name	`ANAME=CICS ECI RPC Server`
Node name	`ANODE=<host name>`
Application type	`ATYPE=Java`
Version	`AVERS=9.12.0.0`