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:

• Customizing the RPC Server

• Configuring the RPC Server

• Locating and Calling the Target Server

• Starting the RPC Server

• Stopping the RPC Server

• Activating Tracing for the RPC Server

---

Customizing the RPC Server

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

• Common Runtime Environment (CRTE)

• Configuration File

• Start Procedure

Common Runtime Environment (CRTE)

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.

Configuration File

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)

• scalability parameters

• trace settings

• etc.

For more information see Configuring the RPC Server.

Start Procedure

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.

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 case-insensitive.

• 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 in the RPC Programming documentation. 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 attribute of the broker attribute file. Example: class=MyRPC	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 CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | Linux | Windows | BS2000. More information can be found under Internationalization with EntireX.	R
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
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: init_exit=myExit	O
extractor	NO	The extractor service is a prerequisite for remote extractions. See Extractor Service. extractor=YES|NO Example: extractor=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 BS2000 can be configured to support either COBOL or C. See also Locating and Calling the Target Server. marshalling=(LANGUAGE=COBOL|C) COBOL The RPC Server for BS2000 supports COBOL. The COBOL servers are called directly without a server interface object. The COBOL server modules may be compiled as OM or LLM modules. So-called server mapping files are used to call the COBOL server correctly if one is available. See Usage of Server Mapping Files. C The RPC Server for BS2000 supports C. The modules are called using a server interface object built with the C Wrapper.	O
password	no default	The password for secured access to the broker. 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 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: restartcycles=30 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: 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
svm	PREFERRED	Usage of server-side mapping files (Designer files with extension .svm) at runtime. See Server-side Mapping Files in the RPC Server. If you use server-side mapping files, the server-side mapping container must be installed and configured. See Step 1: Define a Server-side Mapping Container in the BS2000 Installation documentation. Server mapping files with extension .svm are no longer supported at design time by the Designer. You can still use them at runtime in a server-side mapping container. All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping files with extension .cvm. See When is a Server Mapping File Required? We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation. SVM=PREFERRED|NO PREFERRED This setting is to support COBOL server programs that do not have server-side mapping, as well as COBOL server programs built with a server-side mapping file. NO Server-side mapping files are not used. Example: SVM=NO 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: term_exit=myExit	O
timeout	60	Timeout in seconds, used by the server to wait for broker requests. See WAIT under Broker ACI Fields for more information. Also influences restartcycles and worker model DYNAMIC. Example: timeout=300	O
tracedestination	ERXTrace.nnn.log	Trace output is written to SYSOUT. See also Activating Tracing for the RPC Server.	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. Use only when requested by Software AG Support. Example: tracelevel=standard	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 BS2000 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]) use a FIXED number of worker threads: workermodel=(FIXED,number) FIXED A fixed number of worker threads is used by the RPC Server for BS2000. 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. Example: workermodel=(SCALE,2,5)	O

Locating and Calling the Target Server

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:

• COBOL

• C

COBOL

The COBOL object module name for the RPC server called is taken from the server mapping if one is available. See Usage of Server Mapping Files for an introduction. If no server mapping is used, the IDL program name is used as the COBOL object module name of the RPC server and 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

1. Make sure that all target server programs called as RPC servers

   • are COBOL object modules

   • use COBOL calling conventions

2. Configure the parameter marshalling for COBOL, for example:

   marshalling=COBOL

C

To use the RPC Server for BS2000 with C

1. Make sure that all target server programs called as RPC servers

   • are C object modules

   • use C calling conventions

2. Configure the parameter marshalling for C, for example:

   marshalling=C

See Scenario III: Writing a New C Server in the RPC Server for BS2000 documentation.

Starting the RPC Server

To start the RPC Server for BS2000

• Use the following SDF command:

  /ENTER-PROCEDURE *LIB(LIB=EXP109.JOBS,ELE=START-RPC-SERVER), -
  /JOB-NAME=RPCMAIN,LOG=*NO

Stopping the RPC Server

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 EXP109.JOBS.

  Startup Parameter	Description	Default
  BROKER-ID	Depending on the communication method, the broker ID can be specified in two different formats: TCP Transport Method ip:port:TCP where ip is the address or DNS host name,   port is the port number that EntireX Broker is listening on, and   TCP is the protocol name NET Transport Method ETBnnn:SVCmmm:NET where nnn is the ID under which EntireX Broker is connected to the Adabas ID table,   mmm is the SVC number under which the Adabas ID table can be accessed, and   NET is the protocol name	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.	EXX109.JOBS
  EXX-LIB	EntireX Broker module library.	EXX109.LIB
  WAL-MOD	WAL module library.	WAL842.MOD

  Set the broker ID in the PARAMETER-DECLARATION section and enter following command:

  /CALL-PROCEDURE (EXP109.JOBS, STOP-RPC-SERVER)

Activating Tracing for the RPC Server

To switch on tracing for the RPC server

• Set the parameter TRACELEVEL in S-element RPC-CONFIG in EXP109.JOBS.

  To evaluate the RPC server return codes, see EntireX RPC Server Return Codes.