Installing EntireX Broker under z/VSE

This document describes the steps for installing EntireX Broker under z/VSE and covers the following topics:

Prerequisites for EntireX Broker

Prerequisites for EntireX components are described centrally. See z/VSE Prerequisites.

For customers who do not have Adabas installed at their site, the Adabas modules delivered with EntireX in the library WAL826 for the Broker kernel must be installed.

For information on how to install Adabas SVC and configure Adabas cross memory services in batch and CICS, refer to your Adabas documentation.

Contents of Sublibrary EXX960

EntireX Broker, Configuration, Startup JCL and Executables

File Description
RUNETB.J EntireX Broker startup JCL.
PSFADA.J Adabas COMPRESS and ADALOD sample JCL for persistent store creation.
ETBnnn.ATR EntireX Broker Attribute File.
USRTCHA.A Sample user translation routine.
ETBSTART.PHASE
ETBNUC.PHASE
ETBCEE.PHASE		 EntireX Broker kernel.
EXXICU.PHASE International components for Unicode.
USERSEC.PHASE
SECUEXI0.PHASE
ETBENC.OBJ
ETBTB.OBJ
ETBUEVA.OBJ
ETBUPRE.OBJ
ETBVEVA.OBJ
ETBVPRE.OBJ
 Security exit modules.
BKIMB.OBJ
BKIMB.PHASE
BROKERB.PHASE
BKIMC.OBJ
BKIMC.PHASE
BROKERC.PHASE
 EntireX Broker stubs.

Samples, Utilities and Sources

File Description
RUNBCOC.J Client sample JCL.
BCOC.PHASE Client sample executable.
RUNBCOS.J Server sample JCL.
BCOS.PHASE Server sample executable.
RUNCMD.J Command Services JCL.
ETBCMD.PHASE Command Services executable.
RUNINFO.J Information Services JCL.
ETBINFO.PHASE Information Services executable.
BROKER.PRO
CLIENT.PRO
CLOGFLT.PRO
CONV.PRO
NET.PRO
POOL.PRO
PSF.PRO
PSFADA.PRO
PSFFILE.PRO
PUBLIC.PRO
PUBSHR.PRO
RESOURCE.PRO
SECURITY.PRO
SERVER.PRO
SERVICE.PRO
STATIS.PRO
SUBSCBR.PRO
TCP.PRO
TOPIC.PRO
USER.PRO
WKRUSAGE.PRO
WORKER.PRO
 Information Services Profiles.
RUNPUB.J Publisher sample JCL.
PUB.PHASE Publisher sample executable.
RUNSUB.J Subscriber sample JCL.
SUB.PHASE Subscriber sample executable.
COBDEF.C COBOL ACI control block definitions.
COBINF.C COBOL CIS definitions
ETBCDEF.H C language ACI control block definitions.
ETBCINF.H C language Command and Information Services API definitions.
ASMDEF.A Assembler control block definitions.
ASMINF.A Assembler CIS definitions.

EntireX Broker Stubs, Sample JCL, Objects and Executables

See Administration of Broker Stubs under z/VSE.

File Description
BKIMB.J Sample JCL for linking the batch stub for use with external security
BKIMC.J Sample JCL for linking the CICS stub for use with external security

Copying the Contents of the Installation Medium to Disk

Note:
If you are using SMA, please refer to the System Maintenance Aid Manual, chapter Installing Software AG Products with SMA. If you are not using SMA, please follow the instructions below.

This section explains how to:

  • Copy data set COPYTAPE.JOB from the installation medium to library.

  • Modify this member to conform with your local naming conventions.

The JCL in this member is then used to copy all data sets from installation medium to disk.

If the data sets for more than one product are delivered on the installation medium, the member COPYTAPE.JOB contains the JCL to unload the data sets for all delivered products from the installation medium to your disk, except the data sets that you can directly install from the installation medium, for example, Natural INPL objects.

After that, you will have to perform the individual install procedure for each component.

Step 1: Copy Data Set COPYTAPE.JOB from Installation Medium to Disk

The data set COPYTAPE.JOB (file 5) contains the JCL to unload all other existing data sets from installation medium to disk. To unload COPYTAPE.JOB, use the following sample JCL: 

* $$ JOB JNM=LIBRCAT,CLASS=0, + 
* $$ DISP=D,LDEST=(*,UID),SYSID=1 
* $$ LST CLASS=A,DISP=D 
// JOB LIBRCAT 
* ***************************************** 
* CATALOG COPYTAPE.JOB TO LIBRARY 
* ***************************************** 
// ASSGN SYS004,NNN                        <------ tape address 
// MTC REW,SYS004 
// MTC FSF,SYS004,4 
ASSGN SYSIPT,SYS004 
// TLBL IJSYSIN,'COPYTAPE.JOB' 
// EXEC LIBR,PARM='MSHP; ACC S=lib.sublib' <------- for catalog
/*
// MTC REW,SYS004 
ASSGN SYSIPT,FEC 
/* 
/& 
* $$ EOJ
where NNN is the installation medium address and
lib.sublib is the library and sublibrary of the catalog

Step 2: Modify COPYTAPE.JOB

Modify COPYTAPE.JOB to conform with your local naming conventions and set the disk space parameters before submitting this job.

Step 3: Submit COPYTAPE.JOB

Submit COPYTAPE.JOB to unload all other data sets from the installation medium to your disk.

Preparing for Installation

Before the following steps can be performed, the EntireX installation medium must be copied to disk. If this has not yet been done, go to Step 1: Copy Data Set COPYTAPE.JOB from Installation Medium to Disk and follow the instructions there.

To use Software AG's System Maintenance Aid (SMA), you must modify SMA parameter values to suit your environment. Refer to the System Maintenance Aid Readme file (P060).

This installation procedure contains the following SMA jobs and steps:

Install Step Activity SMA Job Job Step
1 Adapt the SMA Parameters (P060)  
2 Install the EntireX License File I070 7610
3 Customize the Broker Attribute File I070 7604
4 Customize the Broker Startup Job Control I070 7606
5 Define an Adabas Persistent Store I050 7600 / 7610
6 Load the INPL and ERRN Files (Broker Tutorial) I061 7600 / 7602
7 Install the Stubs - -

Installing EntireX Broker

Step 1: Adapt the SMA Parameters

When using Software AG's System Maintenance Aid (SMA), you must modify SMA parameter values to suit your environment. Refer to the System Maintenance Aid readme file (P060).

Step 2: Install the EntireX License File

(SMA Job I070 / Step 7610)

The EntireX license file EXX960.LICS is delivered on the installation medium and/or CD.

The license file may reside in a sublibrary. The following FTP command sequence can be used to upload the file to z/VSE and place it into a sublibrary. Please note that the file needs to be uploaded in binary format and requires the record format "stream" on the target system. 

ftp>
bin
quote site RECFM S
cd SAGLIB.EXX960
put <license_file> EXX960.LICS

The license file can then be referenced in the EntireX Broker startup procedure (RUNETB.J) by using a SETPARM JCL control statement. 

// SETPARM ETBLIC=SAGLIB.EXX960(EXX960.LICS)

Alternatively, the JCL provided in file EXX960.LIBJ on the installation medium can be used to copy the license file to a sequential disk file. Make sure the sequential disk file is referenced in the EntireX Broker startup procedure (RUNETB.J). 

// ASSGN  SYS002,DISK,VOL= VSEnnn,SHR
// DLBL   ETBLIC,'SAG.ETBLIC',0
// EXTENT SYS002 ,VSEnnn,,,xxxxx,yy

Step 3: Customize the EntireX Broker Attribute File (ETBnnn.ATR)

(SMA Job I070 / Step 7604)

Customize the delivered EntireX Broker attribute file (ETBnnn.ATR) to suit your environment. Specify at least the following four parameters: 

BROKER-ID = ETBnnn
PORT   = port_number
ADASVC = svc_number
NODE   = node_number

Parameters ADASVC and NODE can be omitted with transport method TCP/IP (TRANSPORT=TCP). See Broker Attributes.

Please ensure the partition size is adequate for running EntireX Broker, taking into consideration the resource specified in the particular attribute file you are using. See also Broker Resource Allocation.

Step 4: Customize the EntireX Broker Startup Job Control (RUNETB.J)

(SMA Job I070 / Step 7606)

Customize the delivered EntireX Broker startup job control (RUNETB.J) to suit your environment. Ensure that license and attribute file are referenced correctly.

RUNETB.J

* $$ JOB JNM=RUNETB,CLASS=0,DISP=D
* $$ LST CLASS=A,DISP=H
// JOB RUNETB
*
* BROKER START UP JOB CONTROL
*
// LIBDEF *,SEARCH=(SAGLIB.EXX960,SAGLIB.MLC127,SAGLIB.WAL826)
/*
/* ATTRIBUTE FILE
/*
// SETPARM ETBATTR='DD:SAGLIB.EXX960(ETBnnn.ATR)'
/* / ASSGN SYS000,DISK,VOL=VSEnnn,SHR
/* / DLBL ETBATTR,'SAG.ETBATTR',0
/* / EXTENT SYS000,VSEnnn,,,xxxxx,yy
/*
/* TRACE DESTINATION
/*
// SETPARM ETBLOG='DD:SYSLST'
/* / ASSGN SYS001,DISK,VOL=VSEnnn,SHR
/* / DLBL ETBLOG,'SAG.ETBLOG',0
/* / EXTENT SYS001,VSEnnn,,,xxxxx,yy
/*
/* LICENSE FILE
/*
// SETPARM ETBLIC='DD:SAGLIB.EXX960(EXX960.LICS)'
/* / ASSGN SYS002,DISK,VOL= VSEnnn,SHR
/* / DLBL ETBLIC,'SAG.ETBLIC',0
/* / EXTENT SYS002 ,VSEnnn,,,xxxxx,yy
/*
/* TURN OFF CONSOLE PROMPT
/*
/* / UPSI 00000001
/*
// EXEC ETBSTART
// EXEC LISTLOG
/&
* $$ EOJ

If the subsequent optional installation steps are not required, you may now run job RUNETB.J to start the EntireX Broker.

To test your installation, see Installation Verification.

Step 5: Define an Adabas Persistent Store (Optional)

(SMA Job I050 / Step 7600 / 7610)

To create an Adabas Persistent Store, adapt and run job PSFADA.J in sublibrary EXX960. Running this job will load an empty Adabas persistent store file into your Adabas database. To activate the Adabas persistent store, set up at least following parameters in the broker attribute file. See Broker Attributes. 

DEFAULTS=BROKER
  STORE        = BROKER
  PSTORE       = HOT/COLD
  PSTORE-TYPE  = ADABAS
DEFAULTS=ADABAS
  DBID         = dbid
  FNR          = pstore_file_number
DEFAULTS=NET
  ADASVC       = svc_number

See Managing the Broker Persistent Store for more information.

Step 6: Load the INPL and ERRN Files: Install the Natural-based EntireX Broker Tutorial Job JSYSETB (Optional)

(SMA Job I061 / Step 7600, 7602)

Note:
Perform this step only if you want to install the sample Natural programs.

  1. Use the Natural system command INPL and ERRLODUS (see Natural User's Guide) to load the EntireX Broker system objects (EXB960.INPL and EXB960.ERRN).

    This loads the following library:

    Library File Contents
    SYSETB FNAT Sample Natural programs.

  2. Set the Natural profile parameter ESIZE=40.

  3. Invoke Natural, logon to library SYSETB and edit the member PARM on library SYSETB to set parameters as required at your site, especially the BROKER-ID.

Parameter members can also be made user-dependent. Copy the PARM member and save it in a member with a user ID as name (Natural variable *USER). If a user logs on with this user ID, these parameters take effect instead of the PARM member.

Step 7: Install the Stubs

If you will be using the EntireX Broker stubs on z/VSE, see Administration of Broker Stubs under z/VSE. The EntireX Broker stubs are installed as part of the Developer's Kit under UNIX and Windows (these are delivered with the EntireX Developer's Kit).

Installation Verification

You can use the sample client and server programs BCOC and BCOS to test the EntireX Broker installation. First start the server program, then the client program.

Customize the delivered job control samples RUNBCOS.J and RUNBCOC.J. Choose the desired transport method and replace all placeholder values (in italic font).

Specifying the Broker ID

Depending on the transport method, the Broker ID can be specified in 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

RUNBCOS.J

* $$ JOB JNM=RUNBCOS,CLASS=0,DISP=D
* $$ LST CLASS=A,DISP=H
// JOB RUNBCOS
*
* BCOS (SERVER) SAMPLE JCL
*
// LIBDEF *,SEARCH=(SAGLIB.EXX960,SAGLIB.WAL826)
/*
/* / EXEC BCOS,PARM='-b<ip>:<port>:TCP -i50 -p2000'
// EXEC BCOS,PARM='-bETB<nnn>:SVC<mmm>:NET -i50 -p2000'
/*
// EXEC LISTLOG
/&	
* $$ EOJ

RUNBCOC.J

* $$ JOB JNM=RUNBCOC,CLASS=0,DISP=D
* $$ LST CLASS=A,DISP=H
// JOB RUNBCOC
*
* BCOC (CLIENT) SAMPLE JCL
*
// LIBDEF *,SEARCH=(SAGLIB.EXX960,SAGLIB.WAL826)
/*
/* / EXEC BCOC,PARM='-b<ip>:<port>:TCP -i50 -p2000'
// EXEC BCOC,PARM='-bETB<nnn>:SVC<mmm>:NET -i50 -p2000'
/*
// EXEC LISTLOG
/&
* $$ EOJ

Verification Steps

Run job RUNBCOS.J. It will register as ASERVER, ASERVICE, ACLASS at EntireX Broker. Run job RUNBCOC.J in a different z/VSE partition. This client sample program will exchange some test data with the previously registered server ASERVER.

RUNBCOS Sample Server Output

CLIENT: Message size 2000
CLIENT: Number of messages (10)
CLIENT: Broker ID localhost:1971:TCP
CLIENT: Using default class ACLASS
CLIENT: Using default server ASERVER
CLIENT: Using default service ASERVICE
CLIENT: Using default ACI version 10
CLIENT: Maximum stub ACI version: 10
CLIENT: Max kernel ACI version: 10
CLIENT: Kernel Version 9.6.0.00 Platform z/VSE 5.1.2
CLIENT: Using ACI version: 10
Request returns (900000000,8386100000000000000000000000000)
Request returns (800000000,8386100000000000000000000000000)
Request returns (700000000,8386100000000000000000000000000)
Request returns (600000000,8386100000000000000000000000000)
Request returns (500000000,8386100000000000000000000000000)
Request returns (400000000,8386100000000000000000000000000)
Request returns (300000000,8386100000000000000000000000000)
Request returns (200000000,8386100000000000000000000000000)
Request returns (100000000,8386100000000000000000000000000)
Request returns (000000000,8386100000000000000000000000000)
CLIENT: Test successfully performed

RUNBCOC Sample Client Output

SERVER: Userid EXXUSER
SERVER: Message size 2000
SERVER: Number of messages (10)
SERVER: Broker ID localhost:1971:NET
SERVER: Using default class ACLASS
SERVER: Using default server ASERVER
SERVER: Using default service ASERVICE
SERVER: Using default ACI version 10
SERVER: Maximum stub ACI version: 10
SERVER: Max kernel ACI version: 10
SERVER: Kernel Version 9.6.0.00 Platform z/VSE 5.1.2
SERVER: Using ACI version: 10
Incoming data (0000000000000000000000000016838,000000009)
Incoming data (0000000000000000000000000016838,000000008)
Incoming data (0000000000000000000000000016838,000000007)
Incoming data (0000000000000000000000000016838,000000006)
Incoming data (0000000000000000000000000016838,000000005)
Incoming data (0000000000000000000000000016838,000000004)
Incoming data (0000000000000000000000000016838,000000003)
Incoming data (0000000000000000000000000016838,000000002)
Incoming data (0000000000000000000000000016838,000000001)
Incoming data (0000000000000000000000000016838,000000000)
SERVER: Test successfully performed

Hints for Setting up Broker JCL in z/VSE

Where the Files Reside

  • ETBLIC and ETBATTR can reside in z/VSE libraries as members (recommended) or they can reside as sequential disk files (SD files).

  • ETBLOG, including possible traces, can go to SYSLST (recommended) or to an SD file.

Informing Broker where the Files Reside

  • Supply the information with SETPARM JCL control statements 

// SETPARM ETB(LIC|ATTR|LOG)='DD:dlbl_name'

for SD files, and for library members:

'DD:lib.sublib(member.type)'

  • Supply the information as PARM in the EXEC card: 

    // EXEC ETBSTART,                    +
PARM='ENVAR("ETB_ATTR=DD:lib.sublib(member.type)")/'

If files reside in SD files, the necessary z/VSE JCL statements DLBL, EXTENT and ASSGN must be provided for each file too.

The shortest way

See also Step 4: Customize the EntireX Broker Startup Job Control (RUNETB.J). 

01 * $$ JOB JNM=RUNETB,CLASS=0,DISP=D
02 * $$ LST CLASS=A,DISP=H
03 // JOB RUNETB
04 // LIBDEF *,SEARCH=(SAGLIB.EXX960,SAGLIB.MLC127,SAGLIB.WAL826)
05 // UPSI 00000001
06 // SETPARM ETBLOG='DD:SYSLST'
07 // SETPARM ETBATTR='DD:SAGLIB.EXX960(ETBnnn.ATR)'
08 // SETPARM ETBLIC='DD:SAGLIB.EXX960(EXX960.LICS)'
09 // EXEC ETBSTART
10 // EXEC LISTLOG
11 /&
12 * $$ EOJ

To line 6:

This avoids message "4881I NO LABEL INFORMATION FOUND" during Broker startup.

To lines 7 and 8:

If z/VSE JCL parameters ETBATTR and ETBLIC are defined, the Broker retrieves the values of these parameters and derives the location of the attribute and license files from there.

Start of instruction setTo define ETBLIC, ETBATTR and ETBLOG as SD files

  • // ASSGN  SYS000,DISK,VOL=VSEnnn,SHR
// DLBL   ETBATTR,'SAG.ETBATTR',0
// EXTENT SYS000 ,VSEnnn,,,xxxxx,yy
/*
// ASSGN SYS001,DISK,VOL= VSEnnn,SHR
// DLBL ETBLOG,'SAG.ETBLOG',0
// EXTENT SYS001,VSEnnn,,,xxxxx,yy
/*
// ASSGN  SYS002,DISK,VOL= VSEnnn,SHR
// DLBL   ETBLIC,'SAG.ETBLIC',0
// EXTENT SYS002 ,VSEnnn,,,xxxxx,yy
/*

The following table describes the file assignment names:

File Assignment DLBL Name Description See also Step
SYS000 ETBATTR EntireX Broker attribute file. Step 3: Customize the EntireX Broker Attribute File (ETBnnn.ATR)
SYS001 ETBLOG Log file to which EntireX Broker writes trace output. Omitting this file assignment will route a trace output to SYSLST.  
SYS002 ETBLIC EntireX License Certificate File.  

Using the BSI TCP/IP Stack

In addition to CSI's TCP/IP stack, EntireX Broker also supports the BSI TCP/IP stack. For this, the BSI library must be included in the LIBDEF search chain.

If multiple stacks are installed (for example, both CSI and the BSI stack are installed in parallel) specify the corresponding stack ID. See the sample job control for Broker startup below: 

* $$ JOB JNM=RUNETB,CLASS=0,DISP=D
* $$ LST CLASS=A,DISP=H
// JOB RUNETB
*
* BROKER START UP JOB CONTROL
*
// LIBDEF *,SEARCH=(SAGLIB.EXX960,SAGLIB.MLC127,SAGLIB.WAL826,BSILIB.BSIvrs)
/*
/* ATTRIBUTE FILE
/*
// SETPARM ETBATTR='DD:SAGLIB.EXX960(ETBnnn.ATR)'
/* / ASSGN SYS000,DISK,VOL=VSEnnn,SHR
/* / DLBL ETBATTR,'SAG.ETBATTR',0
/* / EXTENT SYS000,VSEnnn,,,xxxxx,yy
/*
/* TRACE DESTINATION
/*
// SETPARM ETBLOG='DD:SYSLST'
/* / ASSGN SYS001,DISK,VOL=VSEnnn,SHR
/* / DLBL ETBLOG,'SAG.ETBLOG',0
/* / EXTENT SYS001,VSEnnn,,,xxxxx,yy
/*
/* LICENSE FILE
/*
// SETPARM ETBLIC='DD:SAGLIB.EXX960(EXX960.LICS)'
/* / ASSGN SYS002,DISK,VOL= VSEnnn,SHR
/* / DLBL ETBLIC,'SAG.ETBLIC',0
/* / EXTENT SYS002 ,VSEnnn,,,xxxxx,yy
/*
/* TURN OFF CONSOLE PROMPT
/*
/* / UPSI 00000001
/*
/*
/* SET STACK ID
/*
// OPTION SYSPARM='BSI_stack_id'
/*
// EXEC ETBSTART
// EXEC LISTLOG
/&
* $$ EOJ