This document describes the steps for installing EntireX Broker under z/VSE and covers the following topics:
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.
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 |
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. |
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 RESOURCE.PRO SECURITY.PRO SERVER.PRO SERVICE.PRO STATIS.PRO TCP.PRO USER.PRO WKRUSAGE.PRO WORKER.PRO |
Information Services Profiles. |
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. |
See Administering 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 |
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.
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 |
Modify COPYTAPE.JOB
to conform with your local naming conventions and
set the disk space parameters before submitting this job.
Submit COPYTAPE.JOB
to unload all other data sets from the installation medium to your
disk.
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 | Install the Stubs | - | - |
Step 3: Customize the EntireX Broker Attribute File (ETBnnn.ATR)
Step 4: Customize the EntireX Broker Startup Job Control (RUNETB.J)
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).
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
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.
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 Verifying the Installation of the Broker.
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.
If you will be using the EntireX Broker stubs on z/VSE, see Administering Broker Stubs under z/VSE.
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).
Depending on the transport method, the Broker ID can be specified in two formats:
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 |
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 |
* $$ 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
* $$ 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
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
.
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
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
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.
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.
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.
To 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. |
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