Installing EntireX Broker under z/OS

This document describes the steps for installing EntireX Broker under z/OS. Review these topics carefully before you install:

Step 1: Set up the Attribute File

(SMA Job I070 / Step 7604)

The EXB109.SRCE data set contains a sample Broker attribute file (member EXBATTR). Copy this member to a member of your choice and customize the attribute settings to suit your needs. The file must then be allocated to DD name ETBFILE in the Broker Startup Procedure (see step Step 2: Edit the Broker Startup Procedure). For detailed information about the attributes, see Broker Attributes.

Step 2: Edit the Broker Startup Procedure

(SMA Job I070 / Step 7606)

Copy the example member EXBSTART (the EntireX Broker Startup Procedure) from the EXX109.JOBS data set to your proclib and edit it to suit your naming conventions.

Note on Region Size

We recommend setting the region size for the Broker to "0M". This means the operating system allocates resources as required. If you wish to influence the resources allocated, you can also set the size depending on the amount of fixed virtual memory that is allocated during Broker initialization. This value is displayed in diagnostic message ETBD0284 of the Broker trace output. Add to this value an additional 64M to account for other storage possibly needed during the Broker execution.

Overview of DD Names

The following table describes the DD names used in this file:

DD Name Description See also
CEEDUMP Exception handling will write any dump data to this data set.  
DDCLOGR1 First dual command log data set. Command Logging in EntireX.
DDCLOGR2 Second dual command log data set. Command Logging in EntireX.
ETBCREP Configuration report provides the contents of the variable definition file (optional) and the contents of the attribute file (required).  
ETBFILE Broker attribute file. Step 1: Set up the Attribute File.
ETBLIB All load libraries required for execution of Broker.  
ETBLREP License report provides the contents of the license file and some machine data.  
ETBMREP Module report provides a list of all members in the STEPLIB data set concatenation.  
ETBPREP Persistent store report provides a list of all records added to or deleted from the persistent store.  
ETBVARS EXBVARS file. Step 1: Set up the Attribute File.
LICENSE EntireX License Certificate File.  
STORE01 Persistent store data sets file. Defines the DIV persistent store data set. This DD name is derived from the value specified in the persistent store format parameter DDNAME. Step 6: (Optional) Define the Persistent Store.
ABNLIGNR Needed to suppress ABEND-AIDTM dumps.  

Step 3: Install the Broker Stubs and Bind the Broker Stub Executables

The broker stub executables are distributed prelinked with unresolved references to z/OS components. To resolve these external references, relink them in your environment. Execute job EXBINST located in the EXX109.JOBS data set.

If you will be using the Broker stubs on z/OS, see Administering Broker Stubs in the z/OS Administration documentation.

Step 4: Authorize and Assign the Broker STEPLIB Data Sets

Perform the following steps as required:

Step 4a: Authorize the EXB Data Set

The EXB data set in the STEPLIB DD needs to be APF-authorized in the following situations:

  • Broker running with SECURITY=YES

  • Broker using the DIV persistent store facility

  • NET transport method

If SECURITY=YES is defined and the EXB data set is not APF-authorized, the broker will not initialize and error ETBE0090 is issued.

Note:
Since EntireX 10.9 this is the only data set that needs to be APF-authorized.

Step 4b: Assign all STEPLIB Data Sets

Assign all load libraries via DD name ETBLIB:

  • EXB109.LOAD

  • EXX109.LOAD

  • WAL842.LOAD

  • MLC136.LOAD

EntireX Broker runs in 64-bit addressing mode (AMODE). The Language Environment Runtime Libraries must be defined either in the LNKLST of the system or as STEPLIB data sets:

  • hlq.SCEERUN2

  • hlq.SCEERUN

Step 5: Configure Time Zone Settings

Perform the following to configure time zone settings:

Step 5a: Give Broker Access to the /etc/profileFile

Ensure that your security product (e.g., RACF, ACF/2) permits the Broker kernel to have read access to the /etc/profile file.

The Broker kernel obtains the time zone setting from the TZ environment variable in the /etc/profile file, if possible.

Note:
If the Broker kernel is not allowed read access, daylight savings time (if applicable) will not be automatically recognized in the Broker kernel log messages. A message from the security product will indicate the lack of permission. Example: 

ICH408I USER(QEUSALT1) GROUP(QADEPT  ) NAME(QEUSALT1 STC        )
  /etc/profile CL(FSOBJ   ) FID(01E2E8E2D9C4F500171E000001170000)
  INSUFFICIENT AUTHORITY TO OPEN
  ACCESS INTENT(R--)  ACCESS ALLOWED(OTHER      ---)
  EFFECTIVE UID(0000999999)  EFFECTIVE GID(0000000006)

Step 5b: Verify Correct Time Zone Setting for Broker

Verify that the time zone setting in the TZ environment variable of the /etc/profile file is correct for your site, since the Broker obtains the time zone setting from this file, if possible.

Step 6: (Optional) Define the Persistent Store

The persistent store can be optionally used for storing unit of work messages and message status information to disk.

Important:
For z/OS, the available persistent store types are Adabas file (perform step "a" below) and DIV file implemented with a VSAM linear data set (perform step "b" below).

See Managing the Broker Persistent Store to understand how the persistent store is implemented.

Step 6a: Define a New Adabas Persistent Store

Define the Adabas Persistent Store

(SMA Job I050 / Steps 7600 / 7610)

Use this step if you have not already defined an Adabas persistent store.

The Adabas persistent store driver is contained within the regular Broker load module. It is activated by specifying attribute PSTORE-TYPE=ADABAS. Use the supplied job EXBJ015 from data set EXX109.JOBS to define and install the persistent store file in your Adabas database. This job creates and loads the Adabas file into the database.

See Implementing an Adabas Database as Persistent Store and Adabas-specific Attributes for more information.

Step 6b: Allocate a DIV Persistent Store

To allocate the persistent store, you will need to define a VSAM linear data set (LDS) using the IBM utility IDCAMS. See Implementing a DIV Persistent Store for details on creating the persistent store data sets.

The file containing the persistent store data set must then be allocated to DD name STORE01 in the Broker Startup Procedure (see Step Step 2: Edit the Broker Startup Procedure).

Use the supplied job EXBIDCAMS from data set EXX109.JOBS to define a VSAM linear data set for the persistent store.

Note:
You must allocate a unique persistent store (if used) per Broker.

See Implementing a DIV Persistent Store for more information.

See also DIV-specific Attributes.