Administering the RPC Server for Micro Focus

The EntireX RPC Server for Micro Focus COBOL allows standard RPC clients to communicate with COBOL servers written with Micro Focus COBOL. It works together with the COBOL Wrapper and the IDL Extractor for COBOL.

Customizing the RPC Server

The following elements are used for setting up the RPC Server for Micro Focus:

Micro Focus COBOL Runtime

The COBOL runtime, for example Micro Focus Server, has to be installed according to the Micro Focus documentation. It is not delivered with this package. Provide the location of the COBOL runtime in the Start Script.

If a COBOL runtime is not provided, the RPC Server for Micro Focus cannot be started and an error message is given.

Configuration File

The name of the delivered example configuration file is microfocusserver.cfg provided in the config folder. The configuration file contains the configuration for the RPC Server for Micro Focus. The following settings are important:

  • connection information such as broker ID, server address (class, name, service)

  • location and usage of server-side mapping container; see Usage of Server Mapping Files.

  • scalability parameters

  • trace settings

  • etc.

For more information see Configuring the RPC Server.

Start Script

The start script for the RPC Server for Micro Focus is called microfocusserver.bsh (UNIX) or microfocusserver.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file. The start script contains the following:

Configuring the RPC Server

The following rules apply:

  • In the configuration file:

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

  • Underscored letters in a parameter indicate the minimum number of letters that can be used for an abbreviated command.

    For example, in brokerid=localhost, brok is the minimum number of letters that can be used as an abbreviation, that is, the commands/parameters broker=localhost and brok=localhost are equivalents.

Parameter Default Values Req/
Opt
brokerid localhost Broker ID used by the server. See Using the Broker ID in Applications.

Example:
brokerid=myhost.com:1971

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

Example:
class=MyRPC

 R
codepage  

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.

Under the Windows operating system:

  • By default, the Windows ANSI codepage configured for your system is automatically transferred to tell the broker how the data is encoded.

  • If you want to adapt the Windows ANSI codepage, see the Regional Settings in the Windows Control Panel and your Windows documentation.

  • If you want to encode the data different to your Windows ANSI codepage, convert the data in the application and provide the codepage name here. During receive, decode the data accordingly.

Under the UNIX operating system:

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

codepage=iso-8859-1

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | UNIX | Windows | BS2000 | z/VSE. More information can be found under Internationalization with EntireX.

R (UNIX)
O (Windows)
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:
compresslevel=6

 O
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:
deployment=yes

 O
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:
logon=no

 O
marshalling COBOL The RPC Server for Micro Focus supports COBOL. See also Locating and Calling the Target Server.

Marshalling=(LANGUAGE=COBOL, flavor=MF) must be provided. Do not change these settings. The COBOL servers are called directly without a server interface object. So-called server mapping files are used to call the COBOL server correctly if one is available. See Usage of Server Mapping Files. 		O
password no default The password for secured access to the broker. If possible (write access) the password is encrypted and written to parameter password.e. The parameter password is removed. To change the password, add the parameter password with the new password as value.

Example:
password=MyPwd

 O
restartcycles 15 Number of restart attempts if the broker is not available. This can be used to keep the RPC Server for Micro Focus 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 Micro Focus stops.

Example:
restartcycles=30

The server waits up to 30 minutes (30*6*10 seconds) before it terminates due to a missing broker connection.

 O
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:
servername=mySrv

 R
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:
service=MYSERVICE

 R
ssl_file no default Set the SSL parameters. See Using SSL/TLS with the RPC Server for examples and more information. O
svm   Usage and anchor of the server-side mapping container (directory or folder). See Server-side Mapping Files in the RPC Server. The RPC server needs write access to the server-side mapping container. There are also client-side mapping files that do not require configuration here. See Server Mapping Files for COBOL

SVM=(PATH=path)

path The path to the anchor of the server-side mapping container.

Example for UNIX:
SVM=(PATH=../config/svm)

Example for Windows:
SVM=(PATH=..\config\svm)

See also Usage of Server Mapping Files.

O
timeout 60 Timeout in seconds, used by the server to wait for broker requests. See broker ACI control block field WAIT for more information. Also influences restartcycles and worker model DYNAMIC.

Example:
timeout=300

 O
tracedestination ERXTrace.nnn.log

The name of the destination file for trace output. By default the main trace file name is ERXTrace.nnn.log, where nnn can be in the range from 001 to 005. See also Activating Tracing for the RPC Server.

  • Under UNIX, the trace file is located in the current working directory.

  • Under Windows, the trace file is located in a subfolder of the windows folder My Documents.

If the default is not used and a tracedestination is specified, you can use the following variables depending on the operating system:

%...% Windows Environment variable.
$(...) UNIX Environment variable.
@PID UNIX, Windows Process ID.
@TID UNIX, Windows Thread ID.
@RANGE[ n,m ] UNIX, Windows m must be greater than n, range is from 0 - 999
@CSIDL_PERSONAL Windows The user's home directory. The variable will be resolved by Windows shell functions.
@CSIDL_APPDATA Windows The Application Data Directory. The variable will be resolved by Windows shell functions.
@CSIDL_LOCAL_APPDATA Windows The Local Application Data Directory. The variable will be resolved by Windows shell functions.

See also Activating Tracing for the RPC Server.

Example:
tracedestination=ERXTrace.log

 O
tracelevel None Trace level for the server. See also Activating Tracing for the RPC Server. 
tracelevel = 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 and should only be switched on when requested by Software AG support.

Example:
tracelevel=standard

 O
traceoption None Additional trace option if trace is active. See also Activating Tracing for the RPC Server.
None No additional trace options.
STUBLOG If tracelevel is Advanced or Support, the trace additionally activates the broker stub log.
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:
traceoption=(STUBLOG,NOTRUNC)

 O
userid ERX-SRV The user ID for access to the broker. The default ERX-SRV will be used if this parameter is omitted or specified without a value: "userid=".

Example:
userid=MyUid

 O
workermodel SCALE,1,3,slowshrink
The RPC Server for Micro Focus can be configured to

  • use a DYNAMIC worker model, which adjusts the number of worker threads to the current number of client requests: 

    workermodel=(SCALE,from,thru
              [,slowshrink | fastshrink]
              [,noisolation | isolation])

  • use a FIXED number of worker threads: 

    workermodel=(FIXED,number
              [,noisolation | isolation])
FIXED A fixed number of worker threads is used by the RPC Server for Micro Focus.
SCALE The number of worker threads is adjusted to the current number of client requests. With the from value, the minimum number of active worker threads can be set. This allows you to define a certain number of 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. The thru value restricts the maximum number of all worker threads concurrently.
slowshrink Default. The RPC server stops all worker threads not used in the time specified by the timeout parameter, except for the number of workers specified as minimum value.
fastshrink The RPC server stops worker threads immediately as soon as it has finished its conversation, except for the number of workers specified as minimum value.
noisolation Calls to the COBOL server are executed within the RPC Server for Micro Focus. If the COBOL server causes a COBOL runtime error, the RPC Server for Micro Focus stops.
isolation Default. Calls to the COBOL server are executed in separate processes. If the COBOL server causes a COBOL runtime error, the RPC Server for Micro Focus does not stop and continues.
Example:
workermodel=(SCALE,2,5)
O

Locating and Calling the Target Server

Introduction

The RPC Server for Micro Focus is able to call standard libraries (Windows DLLs or UNIX shared objects/libraries); Micro Focus proprietary formats such as intermediate code (*.int); generated code (*.gnt); and intermediate or generated code packaged in libraries (*.lbr). See the following table:

Executable Format File Extension File Name Entry Point Notes Configuration
Operating system standard library with multiple server .so|sl (UNIX) or .dll (Windows) IDL library IDL program 1,2 1
Operating system standard library with single server .so|sl (UNIX) or .dll (Windows) IDL program IDL program 1,3,4 2
Micro Focus proprietary intermediate code .int IDL program   4 2
Micro Focus proprietary generated code .gnt IDL program   4 2
Micro Focus proprietary library with multiple server .lbr IDL library IDL program 2,5 2
Micro Focus proprietary library with single server .lbr IDL program IDL program 3,4,5 2

Notes

  1. This type of library is a standard library (UNIX shared library or Windows DLL).

  2. This type of library may contain multiple COBOL servers. The IDL library name is used to form the operating system file name. The COBOL server names (entry points) are taken as follows:

    • if the COBOL Wrapper is used, by default from the IDL program names. The IDL program name can be different if it is renamed during the wrapping process, see Customize Automatically Generated Server Names

    • if the IDL Extractor for COBOL is used, from the COBOL program IDs. The IDL program name can be different if it is renamed during the extraction process in the COBOL Mapping Editor

    If the IDL program name is different, a server mapping is required, See Usage of Server Mapping Files.

  3. This type of library must contain one COBOL server only.

  4. The IDL library name is not used. The COBOL server name (operating system file name and its entry point) are taken as follows:

    • if the COBOL Wrapper is used, by default from the IDL program name. The IDL program name can be different if it is renamed during the wrapping process, see Customize Automatically Generated Server Names

    • if the IDL Extractor for COBOL is used, from the COBOL program ID. The IDL program name can be different if it is renamed during the extraction process in the COBOL Mapping Editor

    If the IDL program name is different, a server mapping is required, See Usage of Server Mapping Files.

  5. Intermediate (*.int) or generated (*.gnt) code must be packaged in the library.

Configuration Approaches

There are two approaches to access the COBOL server during runtime, which depend on the executable format (see table above):

  1. The operating system's standard call mechanism is used to call libraries. Make sure your server(s) are accessible, for example:

    • under UNIX with the LD_LIBRARY_PATH environment variable

    • under Windows with the PATH environment variable

  2. The Micro Focus environment variable COBPATH must be set before starting the RPC server. It lists all paths where a search for COBOL servers is to be performed. See the Micro Focus documentation for more information.

For both approaches, the start script of the RPC Server for Micro Focus is an appropriate place to set the environment variables. See Start Script.

See also Scenario I: Calling an Existing COBOL Server or Scenario II: Writing a New COBOL 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 and Certificates with EntireX in the Platform-independent Administration documentation.

Start of instruction setTo 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. Specify the Broker ID, using one of the following styles:

    If no port number is specified, port 1958 is used as default.

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

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

      2. Define the SSL file in the configuration file of the RPC Server for Micro Focus. See parameter ssl_file under Configuring the RPC Server. Example: 

        brokerid=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 SSL Clients.

  4. Make sure the SSL server to which the RPC Server for Micro Focus 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:

Starting the RPC Server

Before starting, make sure all your (customer-written) COBOL servers are accessible through the standard Windows DLL or UNIX shared library/object load mechanism. See also Locating and Calling the Target Server.

Start of instruction setTo start the RPC Server for Micro Focus

  • Use the Start Script.

    Or:
    Use the following format: 

    rpcserver CFG=name [-option] [brokerid] [class] [servername] [service]

    Here are some sample options. See Configuring the RPC Server for full list.

    -serverlog file Defines an alternative log file. Under Windows, this is typically used by Windows Services. See Running an EntireX RPC Server as a Windows Service.
    -s[ilent] Run the RPC server in silent mode, that is, no terminal input will be required (for example to acknowledge error messages). The batch scripts will terminate automatically. Under UNIX, this is recommended when running in background mode.
    -TraceDestination file Set the trace destination parameter.
    -TraceLevel None|Standard|Advanced Set the trace level parameter.

    Note:
    The server input arguments are resolved from left to right. Parameters defined in the configuration file may be overridden by parameters applied on the command line and vice versa. See Configuring the RPC Server for full list of options.

    Or:
    Under Windows you can use the RPC Server for Micro Focus as a Windows Service. See Running an EntireX RPC Server as a Windows Service.

Stopping the RPC Server

Start of instruction setTo stop the RPC Server for Micro Focus

See also Component Return Codes in EntireX.

Running an EntireX RPC Server as a Windows Service

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

Start of instruction setTo run the RPC Server for Micro Focus as a Windows Service

  1. Customize the Start Script according to your system installation.

    Note:
    The script file must pass external parameters to the RPC server and use the option –silent: 

    rpcserver CFG=..\config\microfocusserver.cfg  -s %*

    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 microfocusserver.bat, the command will be 

    RPCService -install -ext MyServer -script install_path\EntireX\bin\microfocusserver.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".

Activating Tracing for the RPC Server

Start of instruction setTo switch on tracing for the RPC Server for Micro Focus

  1. Set the parameters tracelevel, traceoption and tracedestination. See Configuring the RPC Server.

  2. Start the RPC Server for Micro Focus. See Starting the RPC Server.

  3. To evaluate the return codes, see Component Return Codes in EntireX.

Start of instruction setTo switch off tracing