The EntireX RPC Server for CICS® Socket Listener allows standard RPC clients to communicate with CICS programs running on IBM CICS®. All CICS interface types are supported: (DFHCOMMAREA, Channel Container and Large Buffer).
The following are used to set up the RPC Server for CICS Socket Listener:
The default name of the configuration file is cicssocketlistener.properties. The RPC Server for CICS Socket Listener 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 RPC Server for CICS Socket Listener.
If you configure more than one RPC Server for CICS Socket Listener 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
)
The start script for the RPC Server for CICS Socket Listener is called cicssocketlistenerserver.bsh (Linux) or cicssocketlistenerserver.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file.
The RPC Server for CICS Socket Listener 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.server.brokerid |
-broker |
localhost |
Broker ID. More info | ||||||||||||||
entirex.server.serveraddress |
-server |
RPC/SRV1/CALLNAT |
Server address. | ||||||||||||||
entirex.server.userid |
-user |
CICSSLRPCServer |
The user ID for access to the broker. | ||||||||||||||
entirex.server.fixedservers |
no |
|
|||||||||||||||
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 RPC Server for CICS Socket Listener running while the Broker is down for a short time. | ||||||||||||||
entirex.server.password |
-password |
yes |
The password for secured access to the broker. The password is encrypted and written to the property entirex.server.password.e .
|
||||||||||||||
entirex.server.security |
-security |
no |
Valid values:no | yes | auto | name of BrokerSecurity object.
|
||||||||||||||
entirex.server.compresslevel |
-compresslevel |
0 (no compression)
|
Enter the text or the numeric value:
|
||||||||||||||
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. More info | |||||||||||||||
-help |
Display usage of the command-line parameters. | ||||||||||||||||
entirex.server.logfile |
-logfile |
standard output | Name of the log file. | ||||||||||||||
entirex.trace |
-trace |
0 |
Trace level. More info
|
These properties are used to configure the connection to CICS. As a prerequisite, the CICS Socket Listener must be installed. See Preparing for CICS Socket Listener.
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.sl.host |
Hostname of CICS Socket Listener. | |
cics.sl.port |
CICS Socket Listener Port. | |
cics.sl.transaction |
XRFE |
Required. Transaction ID (1-4 characters) defined for the RPC CICS RFE. Default is XRFE .
|
entirex.bridge.targetencoding |
cp037 |
Specify the appropriate EBCDIC encoding used by your CICS Socket Listener. Default is codepage cp037 with full Latin-1 character set.
|
cics.sl.sockettimeout |
20 |
Socket timeout (in seconds). |
cics.sl.userid |
The user ID (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF). | |
cics.sl.password |
Password/passphrase as defined in your underlying mainframe security system (e.g. RACF).
The password or passphrase is encrypted and written to the property
|
|
cics.sl.sslparams |
SSL parameters. Same syntax as Broker ID. | |
cics.sl.application.name (1,3) |
Required if PassTicket is to be used instead of a password. Application name (1-8 chars) as defined in your RACF system. This property is ignored if RACF password is set. | |
cics.sl.secured.signonkey (1,3) |
Required if PassTicket is to be used instead of a password. Secured signon key as defined in your RACF system. Must be exactly
16 characters long.
The secured signon key is encrypted and written to the property
|
|
cics.sl.synconreturn (2) |
no |
If yes , the CICS program is called with the CICS LINK option SYNCONRETURN . Refer to the IBM CICS Transaction Server for z/OS documentation for more information on the SYNCONRETURN option. This option is only useful if the CICS program is defined as DPL. See note.
|
cics.sl.userexit |
Class name of user exit implementation. See User Exit. | |
cics.sl.userexit.classpath |
URL of the classpath for user exit implementation, for example file://myexit.jar or http://host/path/to/my/exit .
|
Notes:
yes
with DPL impacts the syncpoint handling of the EntireX CICS® Socket Listener. Usually the syncpoint is performed after a
reply has been sent to the request. Using this option, the syncpoint is now performed after program execution. This means
that if the reply fails, the syncpoint has already been performed. Using conversational requests (multiple requests with one
syncpoint after the last request) the SyncOnReturn
option is just ignored without further notice.
By default, PassTickets can only be used once during a one-second time interval. They are protected against replay. This limits the workload to one request per second.
Warning: IBM provides a mechanism to bypass the PassTicket's replay mechanism, allowing higher workloads, but this introduces security risks. The option to bypass the PassTicket's replay mechanism should only be used in secure environments where access to generated PassTickets is limited to a secure or internal network. See your IBM documentation for more information. |
To use SSL with the RPC Server for CICS Socket Listener, you need to configure two sides:
CICS Side
See parameter cics.sl.sslparams
.
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, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.
To use SSL
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.
Set up the RPC Server for CICS Socket Listener 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.p12&trust_passwd=ExxCACert&verify_server=no
If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. Two SSL parameters must be specified on the SSL client side: trust_store
and trust_passwd
. The mandatory trust_store
parameter specifies the file name of a PKCS#12 certificate store that must contain the certificate chain of the trusted certificate
authority (CA) that issued the SSL server's certificate.
To unlock this certificate store, the password has to be set with SSL parameter trust_passwd
.
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.
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:
To start the RPC Server for CICS Socket Listener
Use the Start Script.
To stop the RPC Server for CICS Socket Listener
Use the command stopService
. See Stop Running 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 | Linux | Windows | BS2000.
Or:
Use CTRL-C
in the session where you started the RPC server instance.
Or:
Under Linux, enter command kill -
.
process-id
To ping the RPC Server for CICS Socket Listener
Enter the following command:
java -classpath "$EXXDIR/classes/entirex.jar" com.softwareag.entirex.rpcping.RPCServerPing -p <admin_port>
where | admin_port |
is the number of the administration port. |
The ping
command returns "0
" if the server is reachable, and "1
" if the server cannot be accessed.
For general information see Running an EntireX RPC Server as a Windows Service in the Windows Administration documentation.
To run the RPC Server for CICS Socket Listener as a Windows Service
Customize the Start Script according to your system installation.
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 cicssocketlistenerserver.bat, the command will be
RPCService -install -ext MyServer -script install_path
\EntireX\bin\cicssocketlistenerserver.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".
The application identification is sent from the RPC Server for CICS Socket Listener 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 RPC Server for CICS Socket Listener, these values are:
Identification Part | Value |
---|---|
Application name | ANAME=RPC Server for CICS Socket Listener |
Node name | ANODE=<host name> |
Application type | ATYPE=Java |
Version | AVERS=10.9.0.0 |
To enable a user exit, use the property cics.sl.userexit
to specify the class name of the user exit implementation.
The class will be loaded using the standard classpath. You can specify a separate classpath with the property cics.sl.userexit.classpath
.
Note that for the classpath, a file or HTTP URL must be specified, for example file://myexit.jar
or http://host/path/to/my/exit
.
Your user exit class must implement the Java interface com.softwareag.entirex.cics.socketlistener.IUserExit
.
This Java interface has the following method:
/** * Read and modify the CICS Socket Listener request payload before sending the request. * Get access to the ConfigurationParameters. * * The payload layout: * * Name (16 bytes, for example Commarea, LargeBuffer or the name of a container) * Data-length (4 bytes) * Data (number of bytes defined in the previous parameter) * * Channel container data may contain multiple blocks (one for each input container) * * @param requestPayload CICS Socket Listener Payload to be sent to CICS, containing a java.nio.ByteBuffer * @param properties CICS Socket Listener Configuration Parameters with access to the user transaction ID and several * Bridge framework parameters, like IDL program name, IDL library name, target program name etc. */ void beforeSend(Payload requestPayload, ConfigurationParameters properties);