The EntireX RPC Server for BS2000 allows standard RPC clients to communicate with RPC servers on the operating system BS2000. It supports the programming languages COBOL and C.
This document covers the following topics:
The following elements are used for setting up the RPC Server for BS2000:
When the RPC Server for BS2000 calls COBOL or C server programs, the BS2000 Common Runtime Environment (CRTE) is loaded dynamically into the corresponding address space of the worker task.
There is no need to bind the CRTE statically to the called server object modules. If this is needed for any reason, the CRTE must be linked as a subsystem. All entries must be hidden to prevent duplicates. Linking the CRTE statically will occupy resources and slow down the load time of the server object modules.
The CRTE is not delivered with this package. For a detailed description, see the CRTE (BS2000) User's Guide.
The name of the delivered example configuration file is "RPC-CONFIG". The configuration file contains the configuration for the RPC Server for BS2000. 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.
The name of the start S-procedure for the RPC Server for BS2000 is "START-RPC-SERVER". The start procedure contains the following:
the location of the Common Runtime Environment (CRTE)
the target server library name of the called COBOL or C server
the configuration file used; see Configuration File
etc.
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: |
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: |
R | ||||||||||||||||
codepage |
no codepage transferred |
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. 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=EDF041 Enable character conversion in the broker by setting the service-specific attribute |
R | ||||||||||||||||
compresslevel |
N |
Enforce compression when data is transferred between
broker and server. See Data Compression in EntireX Broker.
Example: |
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 EntireX Workbench documentation.
Example: |
O | ||||||||||||||||
init_exit |
Initialization exit. The
RPC Server for BS2000 provides user exits that allow you to plug in code
during initialization and termination of RPC worker tasks. This parameter
specifies the name of an executable module that is loaded and executed during
initialization of each worker task. See also term_exit .
Example: |
O | |||||||||||||||||
extractor |
NO |
The extractor service is a prerequisite
for remote extractions. See Extractor Service.
Example: |
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.
Example: |
O | ||||||||||||||||
marshalling |
COBOL |
The
RPC Server for BS2000 can be configured to support either COBOL or C. See also Locating and Calling the Target Server. marshalling=(LANGUAGE=COBOL|C)
|
O | ||||||||||||||||
password |
no default | Password for broker logon. Case-sensitive, up to 32
characters. For more information see broker ACI control block field
PASSWORD .
Example: |
O | ||||||||||||||||
restartcycles |
15 | Number of restart attempts if the broker is not available.
This can be used to keep the RPC Server for BS2000 running while the broker is down for a short time.
A restart cycle will be repeated every 60 seconds.
When the number of specified cycles is reached and a connection to the broker is not possible, the RPC Server for BS2000 stops. Example: The server waits up to 30 minutes 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: |
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: |
R | ||||||||||||||||
svm |
PREFERRED |
Usage of server mapping files. See Server-side Mapping Files in the RPC Server.
Example for BS2000: See also Usage of Server Mapping Files. |
O | ||||||||||||||||
term_exit |
Termination exit. The
RPC Server for BS2000 provides user exits that allow you to plug in code
during initialization and termination of RPC worker tasks. This parameter specifies
the name of an executable module that is loaded and executed during termination
of each worker task. See also init_exit .
Example: |
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: |
O | ||||||||||||||||
tracedestination |
ERXTrace.nnn.log |
Trace output is written to |
O | ||||||||||||||||
tracelevel |
None |
Trace level for the server. See also Activating Tracing for the RPC Server.
tracelevel = None | Standard | Advanced | Support
Example: |
O | ||||||||||||||||
userid |
ERX-SRV |
Used to identify the server to the broker.
See broker ACI control block field USER-ID . Case-sensitive, up to 32 characters.
The default ERX-SRV will be used if this parameter is omitted or specified as a null value, for example "userid= ".
Example: |
O | ||||||||||||||||
workermodel |
SCALE,1,3,slowshrink |
|
O |
Target server programs are loaded dynamically, using the BS2000 BLSLIB
chain. The target server library name needs to be set up as
PROGRAM-LIB
in the parameter declaration section of the
START-RPC-SERVER S-procedure, see Start Procedure.
Different mechanisms are used depending on the language:
The approach used to derive the COBOL object module name for the RPC server depends on whether server mapping is used or not. See Usage of Server Mapping Files for an introduction.
If the RPC client sends a client-side type of server mapping with the RPC request, this server mapping is used first.
If no server mapping is available from step 1 above, and if server-side type of server mapping is used, the IDL library and IDL program names are used to form a key to locate the server mapping in the server-side mapping container. If a server mapping is found, this is then used.
If a server mapping is available from step 1 or 2 above, the COBOL object module name of the RPC server is derived from this mapping. In this case the IDL program name can be different to the COBOL object module name if it is renamed during wrapping process (see Customize Automatically Generated Server Names) or during the extraction process in the COBOL Mapping Editor.
If no server mapping is used at all, the IDL program name is used as the COBOL object module name of the RPC server (the IDL library name is ignored).
See also Scenario I: Calling an Existing COBOL Server or Scenario II: Writing a New COBOL Server.
To use the RPC Server for BS2000 with COBOL
Make sure that all target server programs called as RPC servers
are COBOL object modules
use COBOL calling conventions
Configure the parameter marshalling
for COBOL, for example:
marshalling=COBOL
To use the RPC Server for BS2000 with C
Make sure that all target server programs called as RPC servers
are C object modules
use C calling conventions
Configure the parameter marshalling
for C, for example:
marshalling=C
See Scenario III: Writing a New C Server.
To start the RPC Server for BS2000
Use the following SDF command:
/ENTER-PROCEDURE *LIB(LIB=EXP811.JOBS,ELE=START-RPC-SERVER), - /JOB-NAME=RPCMAIN,LOG=*NO
To stop the RPC Server for BS2000 from a privileged user ID
Enter the command:
/INFORM-PROGRAM MSG='STOP',JOB-IDENTIFICATION=*TSN(TSN=tsn)
where | tsn | is
the task number associated with the RPC Server for BS2000 main task (in the example
above the TSN of RPCMAIN )
|
All other tasks that were created as a result of starting the RPC Server for BS2000 will be stopped automatically.
To stop the RPC Server for BS2000 from an operator console
Enter the command:
/INTR tsn,STOP
where | tsn | is
the task number associated with the RPC Server for BS2000 main task (in the example
above the TSN of RPCMAIN )
|
All other tasks that were created as a result of starting the RPC Server for BS2000 will be stopped automatically.
To stop the RPC Server for BS2000 from a non-privileged user ID
Use S-procedure STOP-RPC-SERVER in EXP811.JOBS.
Startup Parameter | Description | Default | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
BROKER-ID | Depending on the communication method, the broker
ID can be specified in two different formats:
|
none | ||||||||||||||||||
CLASS | The class name under which the RPC server is registered at the EntireX Broker. | RPC | ||||||||||||||||||
SERVER | The server name under which the RPC server is registered at the EntireX Broker. | SRV1 | ||||||||||||||||||
SERVICE | The service name under which the RPC server is registered at the EntireX Broker. | CALLNAT | ||||||||||||||||||
USERID | If EntireX Broker is running with EntireX Security, a user ID needs to be supplied | none | ||||||||||||||||||
PASSWORD | If EntireX Broker is running with EntireX Security, a password needs to be supplied | none | ||||||||||||||||||
EXX-JOBS | EntireX Broker jobs library | EXX811.JOBS | ||||||||||||||||||
EXX-LIB | EntireX Broker module library | EXX811.LIB | ||||||||||||||||||
WAL-MOD | WAL module library | WAL826.MOD |
Set the broker ID in the PARAMETER-DECLARATION
section and
enter following command:
/CALL-PROCEDURE (EXP811.JOBS, STOP-RPC-SERVER)
To switch on tracing for the RPC server
Set the parameter TRACELEVEL
in S-element RPC-CONFIG
in EXP811.JOBS
.
To evaluate the return codes, see Error Messages and Codes.