Installing Broker Stubs under z/VM

This document covers the following topics:

See also Administration of Broker Stubs under z/VM.


Prerequisites

Component Prerequisites
Broker Stubs
  • Virtual Storage
    The z/VM Broker stub runs within an IBM Language Environment enclave. This means that if the calling program is not an IBM Language Environment, program an enclave will be automatically created, invisible to the application. However, you must allow sufficient virtual storage to allow the Language Environment enclave to be created. A storage size of 16 MB is recommended.

  • ESIZE
    When using SYSETB under z/VM you must allow sufficient ESIZE. We recommend setting ESIZE=64 KB.

Contents of Installation Medium

Data Set Description
EXX730.TAPE CMS installation data set: TAPE DUMP format and must be loaded onto the installation mini-disk
EXB730.INPL Contains Natural-based tutorial for use with Entire Broker.
EXB730.ERRN Error messages for tutorial.

Note:
In the table above, 730 represents the version, release and service pack. Make sure you install the highest patch level available.

Installation Steps

This section comprises the following steps:

Step 1: Load the Contents of the DUMP Medium to Disk

We recommend that you keep the EntireX Broker environment in a z/VM disk named EXX730. To position the tape for the TAPE LOAD command, calculate the number of tape marks as follows: If the sequence number of EXX730.TAPE, as shown by the Software AG Product Delivery Report, is n, you must position over 3n-2 marks (that is FSF 1 if it's the first data set, FSF 4 if it's the second, etc.).

  1. Access the disk that is to contain the EntireX files as disk A.

  2. Ask the system operator to attach a tape on drive to your virtual machine on address 181 and mount the installation tape.

  3. Position the tape, to tape mark n as calculated above, by issuing TAPE FSF n.

  4. Load the tape contents by issuing TAPE LOAD * * A.

Step 2: Load SYSETB INPL and ERRN Files

This requires Adabas and Natural environments in your z/VM environment to be available.

  1. Use the INPL system command (described in Natural reference documentation) to load SYSETB objects.

  2. Set the Natural profile parameter ESIZE=64.

  3. Load the tutorial error messages using the Natural system utility ERRLODUS.

Step 3: Link ADAENTRY for Adabas / Entire Net-Work Transport (Optional)

This step links ADAENTRY against the Adabas link module ADALNK and is needed only if you are going to use the transport mechanism NET to communicate between z/VM and a Broker kernel executing on another mainframe. This step requires Adabas to be already installed in your z/VM environment and for your Adabas text library to be available.

LOAD ETBADUSR (RLDSAVE RESET ETBADUSR) 
GENMOD ADAENTRY (AMODE 31 RMODE ANY)

Step 4: Rename SECUEXI0 to SECUEXIT for Security (Optional)

This step is needed only if your Broker kernel is running under EntireX Security and if the application is using ACI version 7 or below.

Installation Verification

This package contains the Natural tutorial SYSETB and the C test programs BCOS BCOC. Either of these provided applications can be used for installation verification. Prerequisite for installation verification is a running remote Broker kernel. To proceed, you need to know the IP address and port number of your Broker kernel for TCP/IP communications, or the Entire Net-Work Broker ID if using Adabas / Entire Net-Work transport.

Using SYSETB

Start of instruction setTo execute Natural and load the Broker stub dynamically

  • Enter the following command:

    NAT42 RCA=BROKER,RCALIAS=(BROKER,BKIMBCMS),ESIZE=64,STACK=(LOGON SYSETB)

Using BCOS BCOC

BCOS and BCOC are Language Environment programs provided in C source and also in MODULE format. The modules can be executed without rebuilding them (REXX script MAKEBCO is provided if you do want to rebuild these programs).

  1. Logon to z/VM with two sessions.

  2. Check you have access to the EXX730 disk where EntireX was installed.

  3. In session 1, execute the following on the z/VM command line:

    bcoc ENVAR(ETB_STUBLOG=1)/-b<ip-address>:<port-number>:TCP -i10
  4. In session 2, execute the following on the z/VM command line:

    bcos ENVAR(ETB_STUBLOG=1)/-b<ip-address>:<port-number>:TCP -i10

With Broker kernel API version 9, the screen output of BCOC will look similar to this:

CLIENT: ETB Version 9 
CLIENT: Number of repeats (10)
CLIENT: Broker ID <ip-address>:<port-number>
CLIENT: Using default class ACLASS
CLIENT: Using default server ASERVER
CLIENT: Using default service ASERVICE
CLIENT: Maximum stub ACI version: 9
CLIENT: Maximum kernel ACI version: 9
CLIENT: Kernel Version 8.0.0.00 Platform z/OS

CLIENT: Using ACI version: 9
Request issued (9, 2037)
Request issued (8, 2037)
Request issued (7, 2037)
Request issued (6, 2037)
Request issued (5, 2037)
Request issued (4, 2037)
Request issued (3, 2037)
Request issued (2, 2037)
Request issued (1, 2037)
Request issued (0, 2037)
CLIENT: Test successfully performed 
Press ENTER to end terminal session.

The screen output of BCOS will look similar to this:

SERVER: ACI Version 9 
SERVER: Number of repeats (10) 
SERVER: Broker ID <ip-address>:<port-number>
SERVER: Using default class ACLASS
SERVER: Using default server ASERVER
SERVER: Using default service ASERVICE
SERVER: Maximum stub ACI version: 9
SERVER: Maximum kernel ACI version: 9
SERVER: Kernel Version 8.0.0.00 Platform UNIX

SERVER: Using ACI version: 9
Incoming data (2037, 9)
Incoming data (2037, 8)
Incoming data (2037, 7)
Incoming data (2037, 6)
Incoming data (2037, 5)
Incoming data (2037, 4)
Incoming data (2037, 3)
Incoming data (2037, 2)
Incoming data (2037, 1)
Incoming data (2037, 0)
SERVER: Test successfully performed 
Press ENTER to end terminal session.

If this is the case, the test with the remote Broker was successful.

Installing the Broker Stub with Natural Applications

You can link the Broker stub BKIMBCMS with the Natural nucleus or load it dynamically using the following parameter at Natural startup:

NAT42 RCA=BROKER,RCALIAS=(BROKER,BKIMBCMS)

You must not link the Broker stub into the Natural nucleus if it is intended to execute this in a shared segment.

Installing the Broker Stub with 3GL Applications

Link your application with the Broker stub BKIMBCMS.