The UNIX RPC Server enables you to call shared objects/libraries as servers. The preferred language to implement servers under UNIX is C. This document covers the following topics:
See also Administering the EntireX RPC Servers using System Management Hub.
The library and program names that come from the client are used to locate the target server. This two-level concept (library and program) has to be mapped in some way to the RPC Server environment. The target servers and their stubs are implemented as UNIX shared libraries/objects. UNIX shared libraries/objects also have a two-level concept. The library and program names that come from the client are mapped as follows:
The library name is used to form the file names of the target server shared library/object and stub shared library/object.
The program name is used to form the entry point names for the target server shared library/object and stub shared library/object.
The stub shared library/object as well as the target server shared library/object must be accessible through the standard UNIX shared library/object load mechanism.
To locate the target server, the Possible Values for Libraries is also
used as a kind of search sequence. The default for the library parameter is set
PREFIX(D) - PREFIX() to be compatible with server stubs and target servers
written according to C Wrapper.
Under normal circumstances it is not necessary to change the library parameter. There may, nevertheless, be occasion to do so:
Changing the platform default of the library parameter gives you control and independence over the library name that comes from the client.
By changing it to a setting of FIX(DMYLIB) - FIX(MYLIB) and renaming
the server stub and target server built according to
EntireX C Wrapper to
DMYLIB and MYLIB, you can tailor all
or part of the target servers to these libraries regardless of what the client
sends.
Changing the platform default can also make sense when Natural is the client environment, since it always sends SYSTEM as the library name.
Assume the following situations:
A client sends Example as the library name and CALC as the program name.
A stub shared library/object with DExample.so|sl built with the delivered makefile Server.mak or a corresponding one exists and can be accessed through the standard UNIX shared library/object load mechanism.
A target server shared library/object with the name Example.so|sl built with the delivered makefile Server.mak or a corresponding one exists and can be accessed through the standard UNIX shared library/object load mechanism.
The default value for UNIX of PREFIX(D) - PREFIX() for the
library parameter is not changed.
The RPC Server under UNIX searches for a stub shared library/object with:
An entry point derived from the program name that comes from the client by adding a prefix D. For our example the entry point is DCALC. This prefix has nothing to do with any library parameter configuration and is always D.
Names formed by the instructions of the library parameter from left
to right. The first library parameter PREFIX(D) means:
take the library name that comes from the client and add the prefix. For our
example above, the shared library/object name is
DExample.so|sl.
If in step 1 such a shared library/object can be located through the normal shared library/object load mechanism, it is taken as the stub; otherwise the next shared library/object name is formed using the next library parameter entry (step 2). If all library parameter entries have been worked off and the stub is not located, an error is returned to the client.
For our example above, the stub DExample.so|sl is found with the first library parameter entry.
The RPC Server under UNIX searches for the target server shared library/object with:
An entry point using the program name that comes from the client request directly. For our example above, the entry point is CALC.
Names formed by the instructions of the library parameter from left
to right. The first library parameter PREFIX(D) means: take the library that
comes from the client and add the prefix. For our example above, the shared library/object
name is DExample.so|sl.
If in step 1 such a shared library/object can be located through the normal UNIX shared library/object load mechanism, it is taken as the target server; otherwise the next shared library/object name is formed using the next library parameter entry (step 2). If all library parameter entries have been worked off and the target server is not located, an error is returned to the client.
For our example above, the target server Example.so|sl is found with the second library parameter entry.
This section covers the following topics:
Comments must be on a separate line.
Comment lines can begin with '*', '/' and ';'.
Empty lines are ignored.
Headings in square brackets [topic] are ignored.
Keywords are not case-sensitive.
| Configuration File Parameter Syntax (UNIX, Windows, IBM i) | Value | Req. Opt. |
Description | Notes | |||||
|---|---|---|---|---|---|---|---|---|---|
brokerid=localhost |
string | R | Broker ID used by the server. | Corresponds to the BROKER-ID field of the Broker ACI control block.
|
|||||
class=RPC |
case-sensitive, up to 32 characters | R | Server class used by the server. | Corresponds to the SERVER-CLASS field of the Broker ACI control block.
|
|||||
codepage= |
O | This field exposes the Broker ACI field LOCALE-STRING as a parameter to users of the RPC server.
|
See Using Internationalization. | ||||||
compresslevel=0 |
0-9 or Y | N | O | Enforce compression when data is transferred between broker and server. | See Data Compression in EntireX Broker. | |||||
encryptionlevel=0 |
O | Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX. | |||||||
etb_apivers= 0 |
n | O | Determines the Broker API to use. | Corresponds to the API-VERSION field of the Broker
ACI control block. We recommend either not configuring the API Version or
setting it to 0. This allows the EntireX Broker and the EntireX RPC server to
autodetect the best API version to use. For compatibility with older Brokers, the
API version can be set manually.
|
|||||
logon=YES |
YES | NO | O | YES executes the Broker functions LOGON/LOGOFF. NO does not.
|
Specify NO for compatibility with EntireX Broker prior to Version 4.1.1.
|
|||||
servername=SRV1 |
case-sensitive, up to 32 characters | R | Server Name used by the server. | Corresponds to the SERVER-NAME field of the Broker ACI control block.
|
|||||
service=CALLNAT |
case-sensitive, up to 32 characters | R | Service used by the server. | Corresponds to the SERVICE field of the Broker ACI control block.
|
|||||
smhport=0 |
any digit within range 0 to 99999 | O | If greater than zero, starts the RPC server with a separate SMH communication task and listen port <smhport> to the local TCP/IP system. | ||||||
ssl_file= |
O | Set the SSL parameters. | See Using SSL/TLS with the RPC Server. | ||||||
timeout=60 |
n | O | Timeout in seconds, used by the server to wait for Broker requests. | Corresponds to the WAIT field in the Broker ACI control block. See also Scalability of the RPC Server.
|
|||||
userid=ERX-SRV |
case-sensitive, up to 32 characters | R | Used to identify the server to the broker. | Corresponds to the USER-ID field of the Broker ACI control block.
|
|||||
password= |
case-sensitive, up to 32 characters | O | Password for Broker logon. | Corresponds to the PASSWORD field of the Broker ACI control block.
|
|||||
endworkers= timeout |
See Possible Values for Endworkers | O | Defines the behavior of worker tasks on completion of client requests. | See Scalability of the RPC Server. | |||||
minworkers= 1 |
n | O | Minimum number of parallel worker threads started. | ||||||
maxworkers=10 |
n | O | Maximum number of parallel worker threads started. | ||||||
tracelevel=None |
None | Standard | Advanced | Support | O | Select the trace level for this server. | See Activating Tracing for the RPC Server. | |||||
tracedest= |
Default:tracedest=ERXTracennn.log, where nnn is from 001 to 005.
|
O | The name of the destination file for trace output. | ||||||
traceoption= |
None | STUBLOG | NOTRUNC | O | Additional trace option if trace is active.
Example: |
||||||
library= |
library = PREFIX(D) - PREFIX() |
O | Specifies criteria to locate target servers and any stubs. | See Possible Values for Libraries and Locating and Calling the Target Server. | |||||
restartcycles=15 |
n | O | Number of restart cycles the RPC Server will try to connect to the Broker. 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. | This may occur when the RPC Server is started prior to the Broker or when the Broker is shut down before the RPC Server is shut down. |
The server is able to adjust the number of worker threads to the current number of client requests. This is configured with the parameter endworkers and several others. See Scalability of the RPC Server for information on how the various parameters work together and what combinations can be specified.
| Value | Explanation |
|---|---|
| N |
Never The number of worker threads is
fixed. No additional worker threads are started. Minworkers determines the
number of workers started.
|
| T |
Timeout is used The number of worker
threads ranges between the minworkers and maxworkers settings, depending on the
number of currently active client requests. Until maxworkers has been reached,
the server tries to maintain enough free worker threads to accept all incoming
clients.
The server stops all worker threads not used in the time specified by
the |
| I |
Immediately The number of worker threads
ranges between the minworkers and maxworkers settings, depending on the number
of client requests currently active. Until maxworkers has been reached, the
server tries to maintain enough free worker threads to accept all incoming
clients.
The server stops a thread immediately as soon as it has finished its
conversation. When the number of active workers falls below the number of
workers specified in |
The library parameter defines how the RPC Server locates the target server and any stubs on the platform.
The following coding rules apply to the library parameter:
Up to five library entries can be specified as a sequence.
Library entries are separated by a hyphen "-".
Library entries are used from left to right by the RPC Server.
The meaningful combinations vary per platform and the type of target server:
| Operating System | Type of Target Server | Configuration | Description |
|---|---|---|---|
| IBM i | Target servers in ILE COBOL compatible with
Mapping IDL Data Types to COBOL Data Types in the COBOL Wrapper documentation or Target servers ILE RPG compatible with Using EntireX RPC for RPG under IBM i or Target servers ILE CL compatible with Software AG IDL to CL Mapping. |
FIX(library) F(library) |
The library sent with the client request is ignored. The configured
library library is used to locate the target
server.
|
|
UNIX |
Target servers and their stubs compatible with EntireX C Wrapper. | FIX() or F() |
The library name sent with the client request is ignored. The program name sent with the client request is used to locate the target server. |
FIX(library) or F(library) |
The library sent with the client request is ignored. The configured
library library is used to locate the target server
and any stubs on the platform.
|
||
PREFIX() or P() |
The library name sent with the client request is used to locate the target server and any stubs on the platform. | ||
PREFIX(prefix) or P(prefix) |
The library name sent with the client request is prefixed with the
value in "prefix" before locating the target server and any stubs
on the platform.
|
Example: library = PREFIX(D) - PREFIX()
The default for the library parameter is set to satisfy the environment
specifics best. Under normal circumstances it is not necessary to change the
library parameter.
For an explanation of the approach to locating the target server on your platform, see Locating and Calling the Target Server.
The RPC server can be configured to adjust the number of worker threads to the current number of client requests. When more clients are active, more worker threads are needed to achieve the best throughput. Depending on the configuration, worker threads are started on demand and stopped as soon as they are no longer needed.
This mechanism can be configured with the following parameters:
| EntireX RPC Server under operating system: | Configuration | endworkers | minworkers | maxworkers | timeout |
|---|---|---|---|---|---|
|
UNIX |
Fixed number of workers. | Never. | Determines the number of workers started. | Unused. | Not used with this configuration. |
|
UNIX |
Scaling number of workers between minworkers and maxworkers without
any idle time.
|
Immediately. | Determines the minimum number of workers started. | The upper limit of workers started. | Not used with this configuration. |
|
UNIX |
Scaling number of workers between minworkers and maxworkers with
configurable idle time.
|
Timeout. | The idle time for workers can be configured, i.e. a worker is stopped when, for the period defined by timeout, no client request has to be served and the minimum number of workers has not been reached. |
endworkers=T (timeout)
timeout=600
minworkers=1
maxworkers=10
The endworkers parameter determines the condition under which a worker
will be stopped. The value is the period of time specified by the parameter
timeout (600 seconds, i.e. 10 minutes). Active workers will be stopped if no
client requests arrive within the timeout period, except for the number of
threads specified in minworkers.
Minworkers specifies the minimum number of workers that must be available
to handle incoming client requests. The server is started (manually) and the
first worker (minworkers=1) waits for client requests. When the first client
request arrives, a second worker is started. This ensures that there will be at
least one free worker (minworkers=1) to handle the next incoming client
request.
When the first client request has been worked off (in conversational mode when the conversation has been ended, and in non-conversational mode when the request has been answered), there will be two workers active. For the next incoming client request (second request) no additional worker will be started because the second worker is still free. A third worker will only be started if a third client request arrives before the second request has been finished, in which case there will be three active workers, and so on.
The maxworkers parameter specifies the maximum number of active worker
tasks permitted (default is 10).
endworkers=I (immediately)
timeout=600
minworkers=1
maxworkers=10
In this example the endworkers parameter has been set to "I" (immediately).
This setting will stop worker threads immediately when client requests are
completed, except for the number of threads specified in minworkers. All other
behavior is the same as for Configuration 1: Medium Lifespan of Worker Threads.
endworkers=N (never)
timeout=600
minworkers=10
maxworkers=
This configuration determines a fixed number of workers. The maxworkers
parameter is ignored and the endworkers parameter is set to "N" (never).
All worker threads are started immediately with the server and
will never stop. This method is useful in minimizing system resources.
When you first start using RPC server, we suggest the following settings for scaling the server:
endworkers=T (timeout)
the timeout parameter can be set, for example, to 2 minutes (timeout=120).
low value for minworkers is suggested (e.g. minworkers=2)
the maxworkers setting depends on the expected maximum number of clients active in parallel (e.g. maxworkers=10)
It is assumed that you have read the document Internationalization with EntireX and are familiar with the various internationalization approaches described there.
The RPC Server running under UNIX
does not, by default, send a codepage as part of the locale string to the broker
assumes that the broker's locale string defaults match; see Broker's Locale String Defaults. If they do not match, provide the codepage explicitly.
When setting the codepage manually with the parameter codepage,
the following rules apply:
You can provide a codepage in the locale string sent to the broker. If a codepage is provided, it must follow the rules described under Locale String Mapping.
The RPC server itself does not convert your application data (contained in RPC IDL type A, K, AV and KV fields) received from the broker before giving them to your server application. Under normal circumstances, it is not possible to configure a codepage other than the codepage used in your environment for file and terminal IO. If this is not adhered to, unpredictable results may occur.
The codepage used must also be a codepage supported by the broker, depending on the internationalization approach.
Before starting the RPC Server, set the locale string with the parameter
codepage.
Example:
codepage=LOCAL
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.
To use SSL
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.
Specify the Broker ID, using one of the following styles:
URL Style, for example:
ssl://localhost:2010
Transport-method Style, for example:
ETB024:1609:SSL
If no port number is specified, port 1958 is used as default.
Specify SSL parameters, using one of the methods below:
As part of the Broker ID
The simplest way to specify short SSL parameter is to add them to the Broker ID.
Example with URL-style Broker ID:
ssl://localhost:2010?VERIFY_SERVER=N&TRUST_STORE=c:\\certs\\CaCert.pem
Example with transport-method-style Broker ID:
ETB024:1609:SSL?VERIFY_SERVER=N&TRUST_STORE=c:\\certs\\CaCert.pem
In the SSL file
Complex SSL parameters can be specified in a so-called SSL file, a text file containing the parameters.
Define the SSL file with the SSL parameters, for example file mySSLParms.txt with the following contents:
VERIFY_SERVER=N TRUST_STORE=c:\\certs\\CaCert.pem
Define the SSL file in the configuration file of the RPC server. See parameter ssl_file under Configuring the RPC Server. Example:
ssl://localhost:2010 . . ssl_file=C:\mySSLdirectory\mySSLParms.txt
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 EntireX Clients and Servers.
Make sure the SSL server to which the 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:
Before starting the EntireX RPC server, ensure that all shared libraries/objects (server stubs and server) can be accessed using the search path.
To start the EntireX RPC server
Use
RPCserver CFG=<name> [-option]&
where <name> determines the configuration file in use. Option: -s[ilent]: Run server in silent mode, that is: no terminal input will be required (e.g. acknowledge error messages). The job will terminate automatically. Recommended for background jobs.
Note:
For reasons of compatibility with versions before 5.1.1, the previous
command to start the server
RPCserver <Brokerid> <Class> <ServerName> <Service>
will continue to be supported. However, a server started with this call will use the default parameters as listed in the table above. Parameters other than Broker ID, Class, ServerName, Service require the CFG= form of the server start command.
To stop the EntireX RPC Server
Use the function Deregister a Service or Deregister a Server of the System Management Hub. This method ensures that the deregistration from the Broker is correct.
See also EntireX RPC Server Return Codes.
To switch on tracing for the RPC Server
Set the parameters tracelevel and tracedestination, see
Table of Server Parameters.
To evaluate the return codes, see Error Messages and Codes.
See also Tracing the RPC Server.