The EntireX RPC-ACI Bridge allows standard RPC clients to communicate with an ACI server. The RPC-ACI Bridge transforms RPC requests from clients into ACI messages.

• Customizing the RPC Server

• Configuring the RPC Server Side

• Configuring the ACI Client Side

• Starting the RPC-ACI Bridge

• Stopping the RPC-ACI Bridge

• Using SSL/TLS with the RPC-ACI Bridge

• Running an EntireX RPC Server as a Windows Service

• Application Identification

---

Customizing the RPC Server

The following elements are used to set up the RPC-ACI Bridge:

• Configuration File

• Start Script

Configuration File

The default name of the configuration file is entirex.rpcacibridge.properties. The RPC-ACI Bridge 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-ACI Bridge.

Configuring more than one RPC-ACI Bridge

If you configure more than one RPC-ACI Bridge that connect to the same EntireX Broker, the following items must be distinct:

• The user for the ACI client side (property entirex.rpcacibridge.userid).

• 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 RPC-ACI Bridge is called jrpcacibridge.bsh (Linux) or jrpcacibridge.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file. The RPC-ACI Bridge itself is contained in the file entirex.jar.

Configuring the RPC Server Side

The RPC-ACI Bridge 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.codepage	-codepage		Specify the encoding which corresponds to the ACI server the RPC-ACI Bridge is talking to. The codepage is used for both sides of the communication: When communicating as an RPC server to receive incoming requests from RPC clients and as ACI client to transfer them to the ACI server. 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.
entirex.server.compresslevel	-compresslevel	0 (no compression)	Enter the text or the numeric value: BEST_COMPRESSION  9 BEST_SPEED  1 DEFAULT_COMPRESSION   (mapped to -1  6) DEFLATED  8 NO_COMPRESSION  0 N  0 Y  8  More info
entirex.server.fixedservers		no	NO The number of worker threads balances between what is specified in entirex.server.minservers and what is specified in entirex.server.maxservers. This is done by a so-called attach thread. At startup, the number of worker threads is the number specified in entirex.server.minservers. A new worker thread starts if the broker has more requests than there are worker threads waiting. If more than the number specified in entirex.server.minservers are waiting for requests, a worker thread stops if its receive call times out. The timeout period is configured with entirex.server.waitserver. See worker model DYNAMIC. YES The number of worker threads specified in entirex.server.minservers is started and the server can process this number of parallel requests. See worker model FIXED.
	-help		Display usage of the command-line parameters.
entirex.server.logfile	-logfile	standard output	Name of the log file.
entirex.server.minservers		1	Minimum number of server threads.
entirex.server.maxservers		32	Maximum number of server threads.
entirex.server.name			Server name.
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. To change the password, set the new password in the properties file. To disable password encryption, set entirex.server.passwordencrypt=no. Default=yes.
entirex.server.properties	-propertyfile	entirex.rpcacibridge.properties	The name of the property file.
entirex.server.restartcycles	-restartcycles	15	Number of restart attempts if the Broker is not available. This can be used to keep the RPC-ACI Bridge running while the Broker is down for a short time.
entirex.server.security	-security	no	Valid values: no | yes | auto | name of BrokerSecurity object.
entirex.server.serveraddress	-server	RPC/SRV1/CALLNAT	Server address.
entirex.server.serverlog	-serverlog		Name of the file where start and stop of the worker threads is logged. Used by the Windows RPC Service.
entirex.server.userid	-user	JavaServer	The user ID for access to the broker.
entirex.server.waitattach		600S	Wait timeout for the attach server thread.
entirex.server.waitserver		300S	Wait timeout for the worker threads.
entirex.timeout	-timeout	20	TCP/IP transport timeout.  More info
entirex.trace	-trace	0	Trace level.  More info 0 No tracing, default. 1 Trace all broker calls and other major actions. 2 Dump the send and receive buffer. 3 Dump the buffers sent to the broker and received from the broker.

Configuring the ACI Client Side

These properties are used to configure the connection to the Broker for ACI.

Alternatively, you can use the command-line option. The command-line options 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	Command-line Option	Default Value	Explanation
entirex.rpcacibridge.brokerid	-acibroker	localhost	Broker ID of the Broker for ACI. See URL-style Broker ID.
entirex.rpcacibridge.compresslevel	-acicompresslevel	0 (no compression)	Enter the text or the numeric value: BEST_COMPRESSION  9 BEST_SPEED  1 DEFAULT_COMPRESSION   (mapped to -1  6) DEFLATED  8 NO_COMPRESSION  0 N  0 Y  8
entirex.rpcacibridge.marshalling	-acimarshalling		This is for arrays of groups. Set this property to "cobol" if the ACI server is a COBOL program. Set this property to "natural" if the ACI server is a Natural program.
entirex.rpcacibridge.password	-acipassword		The password of the Broker for ACI. 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.rpcacibridge.properties). To disable password encryption set entirex.server.passwordencrypt=no. Default: yes.
entirex.rpcacibridge.security	-acisecurity	auto	no/yes/auto/Name of BrokerSecurity object.
entirex.rpcacibridge.serveraddress	-aciserver	ACLASS/ASERVER/ ASERVICE	Server Address for the Broker for ACI.
entirex.rpcacibridge.userid	-aciuser	Value of system property user.name.	The user ID of the Broker for ACI. Use different user IDs for different RPC-ACI Bridges on the same Broker.
entirex.rpcacibridge.waittime		60S	The wait time to receive requests. Permitted values are nS|nM|nH, where n is the number of seconds or minutes or hours.

Starting the RPC-ACI Bridge

To start the RPC-ACI Bridge

• Use the Start Script.

  Or:
  Under Windows you can use the RPC-ACI Bridge as a Windows Service. See Running an EntireX RPC Server as a Windows Service.

Stopping the RPC-ACI Bridge

To stop the RPC-ACI Bridge

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

Using SSL/TLS with the RPC-ACI Bridge

To use SSL with RPC-ACI Bridge, you need to configure two sides, the RPC server side and the ACI client side.

• For the ACI client side
  ACI applications 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. ACI-based clients or servers are always SSL clients. The SSL server can be either the EntireX Broker or the Broker SSL Agent. For an introduction see SSL/TLS, HTTP(S), and Certificates with EntireX in the platform-independent Administration documentation.

• For the RPC server side
  The same is true for the RPC server side. Additionally, Direct RPC in webMethods Integration Server (IS inbound) can be used as the SSL server.

To set up SSL

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 ACI side and RPC side for an SSL connection.

   For both sides, 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.

3. Make sure the SSL server to which the ACI 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 | Linux | Windows

   • Broker SSL Agent (Linux | Windows)

4. 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, 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)

Running an EntireX RPC Server as a Windows Service

For general information see Running an EntireX RPC Server as a Windows Service in the Windows Administration documentation.

To run the RPC-ACI Bridge as a Windows Service

1. 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.rpcbridge.RPCACIBridge %*

   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.

2. Test your RPC server to see whether it will start if you run your script file.

3. Use the EntireX RPC Service Tool and install the RPCService with some meaningful extension, for example MyServer. If your Start Script is jrpcacibridge.bat, the command will be

   RPCService -install -ext MyServer -script install_path\EntireX\bin\jrpcacibridge.bat

   The log file will be called RPCservice_MyServer.log.

4. 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 RPC-ACI Bridge to the Broker. It is visible with Broker Command and Info 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-ACI Bridge these values are:

Application name:	ANAME=RPC ACI Bridge
Node name:	ANODE=<host name>
Application type:	ATYPE=Java
Version:	AVERS=10.9.0.0