Installing the RPC Server for BS2000

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:

For Natural RPC servers, see Setting Up a Natural RPC Environment in your Natural documentation.

Step 1: Define a Server-side Mapping Container

You can skip this step if you are a new customer or have never used server-side mapping files (Designer files with extension .svm) from previous EntireX versions.

If you are using server-side mapping files (Designer files with extension .svm) at runtime, you need to set up a server-side mapping container.

The server-side mapping container stores the content of server-side mapping files (.svm), which are used at runtime to marshal and unmarshal the RPC data stream. This enables the RPC server to support special COBOL syntax. The server-side mapping container is technically an ISAM file that needs to be defined and initialized. Each RPC server requires its own server-side mapping container.

Customize S-procedure CREATE-SVM-FILE in EXP103.JOBS.

Procedure Parameter Description Default
EXP-LIB RPC Server for BS2000 load library. EXP103.LIB
SVM-FILE Name of server-side mapping container (ISAM file) to store the contents of Designer server-side mapping files. SVMFILE
SYSOUT-FILE SYSOUT file name. RPC.SYSOUT.CREASVM

The name of the server-side mapping container (ISAM file) must correspond to the SVM-FILE parameter specified in the RPC Server for BS2000 startup job control. See Step 4: Customize the RPC Server for BS2000 Startup JCL.

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.

See also Server Mapping Files for COBOL | Server-side Mapping Files.

Step 2: Customize the RPC Server for BS2000 Configuration File RPC-CONFIG

RPC-CONFIG in EXP103.JOBS contains the RPC server parameters. If the default settings are used, only the BROKERID parameter needs to be set up according to your environment. The RPC Server for BS2000 will then run in a default configuration.

Depending on the communication method, the Broker ID has two 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

If the provided parameter file is used, the RPC server will run as a COBOL server. Besides the RPC service (RPC/SRV1/CALLNAT), it will register the DEPLOYMENT and the EXTRACTOR service. This corresponds to the delivered settings in the broker attribute file on BS2000 and other platforms. The server is configured to run with a fixed number of 3 worker task replicates. Security is turned off.

See also Configuring the RPC Server.

The default configuration file RPC-CONFIG: 

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*                                                                     *
*            EntireX RPC Server v8.1 Configuration File               *
*                                                                     *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
*
* * * * * * * * * * EntireX Broker Parameters * * * * * * * * * * * * *
*
BROKERID=<ipaddr>:<port>:TCP                Broker ID if TCPIP is used
* BROKERID=ETB<nnnnn>::NET                  Broker ID if NET is used
*
SERVERNAME=SRV1
SERVICE=CALLNAT
CLASS=RPC
*
TIMEOUT=300                                 Seconds
LOGON=YES                                   EntireX Broker Logon
*
* CODEPAGE=EDF041
*
* KERNELSECURITY=YES                        EntireX Broker Security
* USERID=<userid>
* PASSWORD=<password>
*
*
* * * * * * * * * * EntireX RPC Server Parameter  * * * * * * * * * * *
*
RESTARTCYCLES=3                             default is 15
* TRACELEVEL=NONE                           NONE, STANDARD or ADVANCED
*
* EntireX RPC Cobol Server Configuration
* ---------------------------------------------------------------------
SVM=PREFERRED
DEPLOYMENT=YES
EXTRACTOR=YES
MARSHALLING=(LANGUAGE=COBOL)
*
* EntireX RPC C Server Configuration
* ---------------------------------------------------------------------
* EXTRACTOR=YES
* MARSHALLING=(LANGUAGE=C)
*
* Start up a fixed number of workers
* ---------------------------------------------------------------------
WORKERMODEL=(FIX,3)
*
* Balance the load of available workers
* ---------------------------------------------------------------------
* WORKERMODEL=(SCALE,2,5)
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Step 3: Customize ADALNK Parameter File RPC-ADAPARM

The RPC Server for BS2000 requires ADALNK parameters when a local communication with an EntireX Broker on same machine is desired (XCOM communication). Set up the IDTNAME in RPC-ADAPARM in EXP103.JOBS under which the broker has registered at the Adabas ID table.

Parameter Description
ADALNK IDTNAME=ADA<xxxxx> Specifies the ID table name under which EntireX Broker is accessible.

Step 4: Customize the RPC Server for BS2000 Startup JCL

The job control delivered with RPC Server for BS2000 makes use of BS2000 S-procedures. We strongly recommend you do not modify START-RPC-SERVER. This procedure is recursively called to establish the RPC server environment. Modifications should only be done to the PARAMETER-DECLARATION section as described below. If all RPC server components are installed under the same BS2000 user ID and all previous installation steps have been done using the default settings, no modifications to START-RPC-SERVER are necessary to run a COBOL server and execute the delivered examples.

Procedure Parameter Description Default
EXP-JOBS RPC Server jobs library. EXP103.JOBS
EXP-LIB RPC Server load library. EXP103.LIB
EXX-LIB EntireX Broker load library. EXX103.LIB
WAL-MOD WAL library. WAL842.MOD
PROGRAM-LIB Server module library. Additional server module libraries can be included in the BLSLIB chain. (See the SET UP FILE LINKS section in the START-RPC-SERVER job control.) There are two sample server libraries delivered:
EXP103.COBS COBOL sample server module library. See Client and Server Examples for BS2000 in the COBOL Wrapper documentation.
EXP103.CSRV C sample server module library.
EXP103.COBS
ADABAS-PARAMETERS Adabas parameters used for XCOM communication method. RPC-ADAPARM
RPC-CONFIG-FILE RPC configuration parameter file. RPC-CONFIG
SVM-FILE Server-side mapping container (ISAM file) to store server-side mapping files. SVMFILE
PROC-NAME The name of the START-RPC-SERVER procedure. START-RPC-SERVER
WORKER-JOB-NAME Job name of the worker tasks. RPCWORK
LOG-FILE-PREFIX File name prefix used for the SYSOUT files of the main and worker tasks. The following SYSOUT files are generated:
for the main task: log-file-prefix.tsn.RPCMAIN
for each worker task:  log-file-prefix.tsn.RPCWORK
RPC.
WORKER-JOB-CLASS Job class of the worker tasks *STD
WORKER-CPU-LIMIT CPU limit of the worker tasks. If this parameter is set to *NO, the user ID requires the permission to run jobs with TIME='NTL' in the job class assigned *STD
CRTE-LIB BS2000 Common Runtime Environment (CRTE) library $.SYSLNK.CRTE
STUB-TRACE-LEVEL Trace level of the EntireX Broker stub. For diagnostic purposes it can be set to 1, 2 or 3 0
LOGGING The logging parameter is passed to the worker task job control and the SYSJ elements executed *NO
WORKER-PARMS Is filled at runtime with the worker task parameters. Note: Do not modify it ! *RPC
MAIN-TASK-TSN Is filled at runtime with the main task TSN. Note: Do not modify it! *RPC

Starting the RPC Server

Start of instruction setTo start the RPC Server for BS2000

  • Use the following SDF command:

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

Stopping the RPC Server

Start of instruction setTo 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.

Start of instruction setTo 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.

Start of instruction setTo stop the RPC Server for BS2000 from a non-privileged user ID

  • Use S-procedure STOP-RPC-SERVER in EXP103.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. EXX103.JOBS
    EXX-LIB EntireX Broker module library. EXX103.LIB
    WAL-MOD WAL module library. WAL842.MOD

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

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

Verifying the Installation of the RPC Server for BS2000

On platform BS2000 the basic COBOL RPC server example CALC is also delivered in LMS library EXP103.COBS. To verify the installation, use this example together with the EntireX IDL Tester. The example also corresponds to the RPC examples delivered on other platforms, for example Linux and Windows. For more information, see CALC under Client and Server Examples for BS2000 in the COBOL Wrapper documentation.