This section explains how to install and start the EntireX Broker on BS2000. It covers the following topics:
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.
This section describes the following installation steps
Customize the EntireX Broker Startup JCL and Start EntireX Broker
Set up the EntireX Broker Security Server for BS2000 (optional)
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
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.
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. |
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 ...
To 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.
To 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.
To 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.
To 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:
|
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)
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.
To activate authentication
Set the following two parameters in the broker attribute file to switch on security:
SECURITY=YES
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.
To start the Broker Security Server
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.
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.
To 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.
To stop the Broker Security Server from an operator console
Enter:
/INTR tsn,EOJ
where tsn is the BS2000 task number associated with the server.
To 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.
To test the EntireX Broker installation
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.
Start EntireX Broker. See Starting and Stopping the Broker in the BS2000 Administration documentation.
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).
Start BCOS server program using following command:
/CALL-PROCEDURE (LIB=EXX103.JOBS,ELE=BCOS)
Wait until BCOS has registered the service.
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.
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.
The programs BCOC and BCOS are client and server programs provided for test purposes.
| Parameter | Description | ACI Field |
|---|---|---|
-a |
locale_string,environment |
LOCALE-STRING, ENVIRONMENT |
-b |
Broker ID (same as the database ID). This is an EntireX Broker
configuration parameter. Example: |
BROKER-ID |
-c |
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 |
-g |
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. | |
-n |
Specify the security token, if desired. | TOKEN |
-p |
The size, in bytes, of the packets that will be
transmitted. Used to specify send and receive length in the broker API. Example: |
|
-r |
Compression level. Values: N|Y|0-9.
|
COMPRESSLEVEL |
-s |
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 |
-t |
Set the wait time. | WAIT |
-u |
User ID. With a secure broker, this will be used to perform authentication. | USER-ID |
-v |
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 |
-w |
Password. With a secure broker, this will be used to perform authentication. | PASSWORD |
-y |
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 |
Most BCOC parameters apply to BCOS, too. The following table lists additional parameters or parameters that have a different meaning.
| Parameter | Description | ACI Field |
|---|---|---|
-g |
Name of output file for receive buffer (if not running in silent mode). | |
-i |
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. |