Installing EntireX Broker under z/OS

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

Step 1: Set up the Attribute File

(SMA Job I070 / Step 7604)

The EXB990.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 EXX990.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 Step
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.
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

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

Step 4: Authorize the Broker STEPLIB Data Sets

The Broker DIV persistent store facility and the NET transport require that all data sets in the STEPLIB DD be APF-authorized. If one of these data sets is not APF-authorized, the network will not initialize, and will result in the following error message: 

ETBE0090 EntireX Broker is not APF-authorized

A standard Broker will have the following data sets in the STEPLIB concatenation:

  • EXX990.LOAD

  • EXB990.LOAD

  • WAL826.LOAD

Step 5: Configure Time Zone Settings

Perform the following to configure time zone settings.

Step 5a: Give Broker Access to the /etc/profile File

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 the PSTORE-TYPE=ADABAS attribute. Use the supplied job EXBJ015 from data set EXX990.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 under Managing the Broker 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 EXX990.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 under Managing the Broker Persistent Store for more information.

See also DIV-specific Attributes under Broker Attributes.

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

(SMA Job I061 / Steps 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 (EXB990.INPL and EXB990.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.