Installing EntireX Broker under BS2000

This section explains how to install and start the EntireX Broker on BS2000. It covers the following topics:


Introduction

When installing EntireX Broker, all modifications are done to the J and S elements - job control (J-elements) and parameter files (S-elements) - located in EXX103.JOBS. All job control and parameter elements contain a preconfiguration which enables you to install EntireX Broker with much less effort. Using this preconfiguration requires that all libraries be located under the same BS2000 user ID.

Note:
Installation prerequisites are described centrally. See BS2000 Prerequisites. Make sure these are met before you start installation. It is important to upgrade your libraries first.

Overview of Broker Installation Steps

This section describes the following installation steps

Install the License Certificate

There are two types of license file:

  • One is delivered on installation medium (EXX103.LICS)

  • The other, in ASCII format, you may have received by e-mail (EXX103.XML) or on a CD. To make this file available for EntireX, transfer it in binary format to BS2000, using FTP. Make sure that the target file on BS2000 is allocated with FILE-STRUCTURE = SAM and BUF-LEN = STD(2).

    When uploading the license file to BS2000, you can use the following FTP commands to create the required file structure:

    LITERAL FILE EXX103.LICS, RECSIZE=0, RECFORM=V, BLKSIZE=(STD,2), OPEN=UPDATE, FCBTYPE=SAM
    BIN
    PUT EXX103.XML EXX103.LICS

Customize the EntireX Broker Attribute File

ETB-ATTR is a sample broker attribute file. Customize the attribute settings to suit your needs.

To run a minimal configuration of EntireX Broker that is suitable to execute the verification programs BCOC and BCOS, set up the following parameters:

Parameter Description
BROKER-ID=ETB<nnnnn> Identifies the Broker to which the attribute file applies. The Broker ID must be unique per machine.
NODE=<node-id> A DBID under which EntireX Broker is visible in the system.
IDTNAME=ADA<xxxxx> Specifies the ID table name under which EntireX Broker will be accessible.
PORT=<port> A free port number EntireX Broker listens on for TCP/IP communication. Depending on the system settings, free port numbers under BS2000 start with port numbers greater than 4096.

For a full description of all parameters, see Broker Attributes.

Customize the ADALNK Parameters File

The verification programs BCOS and BCOC, the command and information services utilities ETBCMD and ETBINFO as well as the Adabas persistent store require the ADALNK parameter IDTNAME to be set. See also Verifying the Installation of the Broker and step Creating a Broker Persistent Store (optional) below.

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

Customize the EntireX Broker Startup JCL and Start EntireX Broker

The job control delivered with EntireX Broker uses BS2000 S-procedures. We strongly recommend you do not modify START-BROKER. This procedure is recursively called to establish the broker environment. Modifications should only be done to the PARAMETER-DECLARATION section as described below. If all EntireX Broker 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-BROKER are necessary.

Startup Parameter Description Default
LICENSE-FILE License certificate file. EXX103.LICS
EXX-LIB EntireX Broker library. EXX103.LIB
EXX-JOBS EntireX Broker jobs library. EXX103.JOBS
WAL-MOD WAL module library. WAL842.MOD
MLC-MOD Licensing module library. MLC127.MOD
BROKER-ATTRIBUTES EntireX Broker attribute file. ETB-ATTR
BROKER-VARIABLES EntireX Broker attributes variables file. ETB-VARS
ADABAS-PARAMETERS Adabas ADALNK parameter file. ETB-ADAPARM
FILE-PREFIX File name prefix used for all files written to disk. ETB
CONFIG-REPORT-FILE EntireX Broker configuration report file name. file-prefix.tsn.CONFIG.REPORT CONFIG.REPORT
PSTORE-REPORT-FILE EntireX Broker Adabas persistent store report file name.file-prefix.tsn.PSTORE.REPORT PSTORE.REPORT
STORAGE-REPORT-FILE EntireX Broker storage report file name. file-prefix.tsn.STORAGE.REPORT STORAGE.REPORT
LICENSE-REPORT-FILE EntireX Broker license report file name. file-prefix.tsn.LICENSE.REPORT LICENSE.REPORT
ACCOUNTING-FILE EntireX Broker accounting file name. file-prefix.tsn.ACCOUNTING ACCOUNTING
CLOGR1-FILE EntireX Broker TRACE-LEVEL=1 command log file 1. file-prefix.tsn.CLOGR1 CLOGR1
CLOGR2-FILE EntireX Broker TRACE-LEVEL=1 command log file 2. file-prefix.tsn.CLOGR2 CLOGR2
TASK-TYPE Is filled during runtime with the EntireX Broker task type. Do not modify it ! MAIN
MAIN-TASK-TSN Is filled during runtime with the main task TSN. The value is used by subsequently entered Broker tasks. Do not modify it! *ETB

If EntireX Broker requires SERVICE-UPDATES to be set to YES, the attributes file ETB-ATTR cannot be held in LMS. It needs to be located on disk instead. This requires a change the START-BROKER procedure. See SERVICE-UPDATES.

Copy the attribute file to disk.

/ START-LMS                                                              
//  EXTRACT-ELEMENT ELEMENT=*LIB(LIB=EXX103.JOBS,ELEMENT=ETB-ATTR,TYPE=S)      
//END                                                                    

Change the ADD-FILE-LINK  in the section below in START-BROKER in EXX103.JOBS to read the file ETB-ATTR from disk.

...
/  "------------------------------------------------------------------"
/  "  SET UP FILE LINKS                                               "
/  "------------------------------------------------------------------"
/   ADD-FILE-LINK LINK-NAME = ETBLIC,   FILE-NAME = &(LICENSE-FILE)    
/   ADD-FILE-LINK LINK-NAME = ETBFILE,  FILE-NAME = &(BROKER-ATTRIBUTES) 
/   ADD-FILE-LINK LINK-NAME = ETBVARS,  FILE-NAME = #BROKER-VARIABLES  
/   ADD-FILE-LINK LINK-NAME = DDLNKPAR, FILE-NAME = #ADABAS-PARAMETERS
...

Start EntireX Broker

Start of instruction setTo start the broker

  • Enter the following SDF command:

    /ENTER-PROCEDURE *LIB(LIB=EXX103.JOBS,ELE=START-BROKER), -
    /JOB-NAME=ETB,LOGGING=*NO,RESOURCES=*PAR(CPU-LIMIT=*NO)

    We recommend using a three-character job name. The job name is taken as prefix for all subsequently started tasks. Because the job name is limited to eight characters, a longer job name will overwrite the suffix added by EntireX Broker. For example: EntireX Broker running with three worker tasks and NET-TCP communication, JOB-NAME=ETB, CPU-LIMIT=*NO:

    NAME      TSN TYPE       PRI      CPU-USED CPU-MAX ACCOUNT#
    ETB      5397 2 BATCH    9 255      2.2379  NTL    1       
    ETBCOM   5398 2 BATCH    9 255      1.3577  NTL    1       
    ETBWRK00 5399 2 BATCH    9 255      0.8970  NTL    1       
    ETBWRK01 5400 2 BATCH    9 255      0.7571  NTL    1       
    ETBWRK02 5401 2 BATCH    9 255      0.7445  NTL    1       
    ETBTCP00 5402 2 BATCH    9 255      0.6124  NTL    1       
    ETBTCPPX 5403 2 BATCH    9 255      0.5417  NTL    1       
    ETBNET00 5404 2 BATCH    9 255      0.6555  NTL    1       
    ETBTOM   5407 2 BATCH    9 255      6.4044  NTL    1

    The properties assigned to the main task (ETB), e.g. JOB-CLASS, CPU-LIMIT, will be inherited by all subsequently started tasks. For CPU-LIMIT, if specified, only *NO (no time limit) and *STD are inherited.

You can now configure and run the verification jobs BCOS and BCOC. See Verifying the Installation of the Broker.

Stop EntireX Broker

Start of instruction setTo stop the broker from a privileged user ID

  • Enter the following command:

    /INFORM-PROGRAM MSG='ETBSTOP',JOB-IDENTIFICATION=*TSN(TSN=tsn)
    where tsn is the task number associated with the broker main task (in the example above the TSN of job name ETB)

    All other tasks that were created as a result of starting the broker will be stopped automatically.

Start of instruction setTo stop the broker from an operator console

  • Enter the following command:

    /INTR tsn,ETBSTOP
    where tsn is the task number associated with the broker main task (in the example above the TSN of job name ETB)

    All other tasks that were created as a result of starting the broker will be stopped automatically.

Start of instruction setTo stop the broker from a non-privileged user ID

  • Use the S-procedure STOP-BROKER in EXX103.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
    ADABAS-PARAMETERS Adabas parameters used for NET communication method. ETB-ADAPARM
    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-LIB EntireX Broker module library. EXX103.LIB
    EXX-JOBS EntireX Broker jobs library. EXX103.JOBS
    WAL-MOD WAL module library. WAL842.MOD

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

    /CALL-PROCEDURE (EXX103.JOBS, STOP-BROKER)

Creating a Broker Persistent Store (optional)

This step may be skipped if no persistent store is required. See Managing the Broker Persistent Store for more information. The persistent store resides in an Adabas database, which means that Adabas must be installed. See BS2000 Prerequisites.

Customize job CREATE-PSTORE-ADABAS. Add the appropriate values in the PARAMETER-DECLARATION section and run the job.

   /CALL-PROCEDURE (LIB=EXX103.JOBS,ELE=CREATE-PSTORE-ADABAS)

This Adabas ADALOD job loads the Adabas persistent store file FDT from EXX103.SYSF into the database where the Adabas persistent store is to reside.

Set the relevant attributes in the broker attribute file ETB-ATTR. See Adabas-specific Attributes and Managing the Broker Persistent Store.

Note:
The Adabas persistent store requires the ADALNK parameter IDTNAME in ETB-ADAPARM to be set properly. This must be the same ID table as used by the broker. See Customize the EntireX Broker Attribute File and Customize the ADALNK Parameters File.

Set up the EntireX Broker Security Server for BS2000 (optional)

Start of instruction setTo activate authentication

  • Set the following two parameters in the broker attribute file to switch on security:

    • In the DEFAULTS=BROKER section
      SECURITY=YES
    • In the DEFAULTS=SECURITY section
      ACCESS-SECURITY-SERVER=YES

    The Broker Security Server requires administrator rights and must be run under a privileged user ID.

    Note:
    If the parameter ACCESS-SECURITY-SERVER is set to "NO", the broker itself must be run under a privileged user ID to allow authentication. In this case, the Broker Security Server is not needed.

Start of instruction setTo start the Broker Security Server

  1. Set up the correct broker library within START-SECURITY-SERVER, because the server task does not usually run under same user ID where the module library resides.

  2. Issue the following command from a privileged user ID (TSOS) to run the server:

    /ENTER-PROCEDURE *LIB(LIB=$kkk.EXXnnn.JOBS,    - 
    /                 ELE=START-SECURITY-SERVER),  - 
    /                 JOB-NAME=SECUSERV,LOG=*NO

    where $kkk is the user ID under which the broker library resides.

Start of instruction setTo stop the Broker Security Server from a privileged user ID

  • Enter:

    /INFORM-PROGRAM MSG='EOJ',JOB-IDENTIFICATION=*TSN(TSN=tsn)

    where <tsn> is the BS2000 task number associated with the server.

Start of instruction setTo stop the Broker Security Server from an operator console

  • Enter:

    /INTR tsn,EOJ

    where tsn is the BS2000 task number associated with the server.

Start of instruction setTo stop the Broker Security Server from a non-privileged user ID

  • Enter the following SDF command:

    /CALL-PROCEDURE (EXX103.JOBS, STOP-SECURITY-SERVER)

    Note:
    This works from all user IDs in the system.

Verifying the Installation of the Broker

Start of instruction setTo test the EntireX Broker installation

  1. The client and server programs that are executed by the installation verification need the following to be defined in the Broker attribute file (if the delivered attribute file is used, no changes are needed):

    CLASS = ACLASS, SERVER = ASERVER, SERVICE = ASERVICE

    See Broker Attributes for more information.

  2. Start EntireX Broker. See Starting and Stopping the Broker in the BS2000 Administration documentation.

  3. The procedures to execute the sample programs are located in library EXX103.JOBS. They, in turn, execute the BCOC (client) and BCOS (server) test programs. Customize the verification jobs before you run them. BCOC and BCOS require a BROKER-ID to be set up in the job control's PARAMETER-DECLARATION section. Since they may access an Adabas ID table (communication method XCOM), an IDTNAME must be provided. This IDTNAME is read from the ETB-ADAPARM element (see Customize the ADALNK Parameters File).

  4. Start BCOS server program using following command:

    /CALL-PROCEDURE (LIB=EXX103.JOBS,ELE=BCOS)

    Wait until BCOS has registered the service.

  5. Then start the BCOC client program in a different session using following command:

    /CALL-PROCEDURE (LIB=EXX103.JOBS,ELE=BCOC)

    Since BCOS sets a WAIT value of 60 seconds, it will terminate with a "WAIT timeout" if BCOC is not started within this time frame. See WAIT under Broker ACI Fields.

  6. Both should now run through 10 iterations of exchanging messages.

If the initialization messages appear but the verification program fails, check for either a TCP port conflict or a problem with the ID table name or version.

Sample Programs for Client (BCOC) and Server (BCOS)

The programs BCOC and BCOS are client and server programs provided for test purposes.

BCOC Parameters

Parameter Description ACI Field
-alocale locale_string,environment LOCALE-STRING, ENVIRONMENT
-bbroker_id Broker ID (same as the database ID). This is an EntireX Broker configuration parameter. Example:
BCOC -bETB045
BROKER-ID
-cclass Server class (part of the server definition). Default is ACLASS. Value must be configured in the Broker Attributes. Together with server and service it forms the fully qualified server name. SERVER-CLASS
-ginput_file_name Use a file as send buffer.  
-h Display usage information.  
-inum_messages[,num_uows] If num_uows is not specified, the number of messages sent. If num_uows is specified, the number of UOWs and messages therein sent. Example:
bcoc -i10
 
-jreply_error Test REPLY-ERROR.  
-kconversation_flag Using conversational mode.  
-l Silent mode. Suppress output.  
-ntoken Specify the security token, if desired. TOKEN
-pmessage_size The size, in bytes, of the packets that will be transmitted. Used to specify send and receive length in the broker API. Example:
BCOC -p10000
 
-rcompress Compression level. Values: N|Y|0-9. COMPRESSLEVEL
-sserver Name of server. Default is ASERVER. Value must be configured in Broker Attributes. Together with class and service it forms the fully qualified server name. SERVER-NAME
-twait_time Set the wait time. WAIT
-uuser_id User ID. With a secure broker, this will be used to perform authentication. USER-ID
-vservice Name of service (part of the server definition). The default is ASERVICE. Value must be configured in Broker Attributes. Together with class and server it forms the fully qualified server name. SERVER-NAME
-wpassword Password. With a secure broker, this will be used to perform authentication. PASSWORD
-ysleep_time Delay between messages in seconds.  
-zstore[uwstatp[,uowtime]] Test unit of work.  
-1..12 By default, if omitted, the highest possible API version is used. Note that if you specify the API version, certain features might depend on a minimum API version. API-VERSION

BCOS Parameters

Most BCOC parameters apply to BCOS, too. The following table lists additional parameters or parameters that have a different meaning.

Parameter Description ACI Field
-goutput-file-name Name of output file for receive buffer (if not running in silent mode).  
-inum_messages[,num_uows] If num_uows is not specified, the number of messages accepted. If num_uows is specified, the number of UOWs and messages therein that are accepted before deregistration.
Example: bcos -i10
 
-iunit_of_work_flag Test unit of work.