Administering Broker Stubs

This document covers the following topics:

• Available Stubs

• ARFETB

• BROKER

• CICSETB

• COMETB

• IDMSETB

• MPPETB

• NATETB23

• NATETBZ

• Tracing for Broker Stubs

• Timeout Settings for Broker Stubs

• Transport Methods for Broker Stubs

• SVC Number for Broker Communication

• Considerations for Users without Adabas

• Support of Clustering in a High Availability Scenario

Available Stubs

This table lists all broker stubs available under z/OS are to be used with the programming languages Assembler | C | COBOL | Natural | PL/I.

Your selection of a specific broker stub depends on the following:

• the environment (TP monitor, TSO, Batch, Natural)

• the transport method (NET or TCP)

• the availability of administration features such as trace

• the Software AG product using the stub

Notes:

1. Use IBM's Application Transparent Transport Layer Security (AT-TLS). See Using SSL/TLS with EntireX Components.
2. These stubs may run in SRB mode and are zIIP-eligible. Refer to the related SAG product documentation for further details. Stubs capable of running in SRB mode do not support tracing.
3. The listed stub modules are the front ends for your application. Depending on transport and usage of EntireX Security, additional modules from EXX109.LOAD are loaded dynamically.

ARFETB

This reentrant stub is for exclusive use by Adabas Replication Services.

Prerequisites and Installation Notes

• No linkage is required.

• It may run in SRB mode and is zIIP-eligible.

• The load library containing ARFETB must be added to the STEPLIB chain of the ARF started task.

BROKER

BROKER is the recommended stub for any batch environment except Natural. For Natural, use NATETB23 or NATETBZ.

• Prerequisites and Installation Notes

• Linkage

Prerequisites and Installation Notes

• This stub can be used in a multithreading (subtasking) environment, provided ADAUSER is not linked to the application.

• It is recommended to load BROKER dynamically within the application program and not to link BROKER with any Adabas link routine. BROKER will attempt to load ADALNKR dynamically.

• However, if BROKER has to be statically linked, see the subsection Linkage below.

• At runtime you must ensure that library EXX109.LOAD is in the steplib of the application and that Adabas library WAL842.LOAD (or above) is in the steplib when using NET transport. See Contents of Mainframe Installation Medium in the z/OS Installation documentation.

Linkage

Choose the method most appropriate for your application:

• Method 1: Reentrant (Thread-safe)
• Method 2: Non-reentrant

Method 1: Reentrant (Thread-safe)

Link your application to module BROKER from the EntireX load library (EXX109.LOAD).

Linkage statements:

INCLUDE userlib(mainpgm) Main Program
INCLUDE exxlib(BROKER)  Broker stub
ENTRY mainpgm
NAME ...

The SVC number may be specified as part of the Broker ID, for example:

ETB220:SVC237:NET

Method 2: Non-reentrant

Link your application to module BROKER from the EntireX load library (EXX109.LOAD) and the module ADAUSER from the Adabas load library.

Linkage statements:

INCLUDE userlib(mainpgm) Main Program
INCLUDE exxlib(BROKER)   Broker stub
INCLUDE wallib(ADAUSER)  Adabas batch/TSO front end
ENTRY mainpgm
NAME ...

By linking with ADAUSER you can specify the required SVC in the Adabas DDCARD parameter of the application job, as shown below:

//J020S1   EXEC PGM=PROGRAM
//STEPLIB  DD DISP=SHR,DSN=EXX109.LOAD
//         DD DISP=SHR,DSN=WAL842.LOAD
//ETBPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//DDCARD   DD *
ADARUN MODE=MULTI,PROGRAM=USER,SVC=237
/*

When linking the stub for use in IMS (BMP), substitute the appropriate Adabas link module for this environment.

Make sure the Adabas link routine (ADALNK/ADALNKR) does not contain any exits that assume the length of the Adabas data area UB is extended beyond its default value. Contact Software AG Support if you are unsure about this.

CICSETB

CICSETB is the recommended stub for any CICS environment except Natural. For Natural, use NATETB23 or NATETBZ.

• Prerequisites and Installation Notes

• CICS Socket Pool for CICSETB

• Linkage

Prerequisites and Installation Notes

• EntireX RPC Server for z/OS CICS® uses CICSETB as default.

• It is recommended to load CICSETB dynamically within the application program.

• CICSETB will attempt to load ADACICS dynamically, using EXEC CICS LINK PROGRAM.

• CICSETB, CICSETB2 and EXAGLUE must be available in the CICS RPL search chain if called dynamically. Alter the CICS procedure or job, adding the EXX load library to both the STEPLIB and DFHRPL library concatenations. See also the job EXXCICS in the EXX jobs library for altering the CICS-related entries.

• CICSETB can be used with or without a CICS TWA (transaction work area).

  • With TWA
    At least 24 bytes of transaction work area must be defined in your CICS transaction if you choose to specify a TWA.

  • Without TWA
    Prerequisite is building an Adabas CICS interface, specifying PARMTYP=ALL for either the ADAGSET or LGBLSET MACRO (depending upon the Adabas version). There are no application changes required for using CICSETB without TWA.

  • If the name of your Adabas CICS link routine is different from "ADACICS", please use zap EXX109.ZAPS(EXX0007) to set the site-specific name of your Adabas CICS link routine. By default, the zap will change the name to "ADABAS".

CICS Socket Pool for CICSETB

When you connect a Broker using TCP/IP, each request creates a new TCP/IP connection (a TCP/IP socket). This socket is deleted after the request. Using the CICS Socket Pool allows you to keep created sockets across multiple Broker calls and across multiple clients. A socket created by CICSETB is stored in the socket pool after the Broker call. A subsequent request for the same Broker reuses the socket stored in the socket pool. Reusing sockets savesresources and speeds up Broker calls.

Warning: The sockets are also shared between users. In an SSL or AT-TLS scenario, these user sessions would interfere with each other. As a consequence, the socket pool must not be used if SSL is in use.

By default the socket pool is inactive. To activate the socket pool, define the CICS transaction EXGT. See the job EXXCICS in the library EXX109.JOBS. It contains the CSD definition for EXGT, which is disabled.

If the socket pool is active, the first CICSETB request launches the task EXGT, which is active until CICS terminates. This task keeps the sockets across multiple Broker calls. It creates the CICS TSQ element SagExxAnchor, which must not be deleted. This TSQ element is the anchor for all user tasks to connect to the active socket pool.

Linkage

Link your application to member CICSETB from the EntireX load library (EXX109.LOAD).

Linkage statements for COBOL applications:

INCLUDE cicslib(DFHECI)   CICS Prolog Module
INCLUDE userlib(mainpgm)  Main Program
INCLUDE cicslib(DFHELII)  CICS Module
INCLUDE exxlib(CICSETB)   Broker stub
ENTRY mainpgm
NAME ...

Linkage statements for Assembler applications:

INCLUDE cicslib(DFHEAI)  CICS Prolog Module
INCLUDE userlib(mainpgm) Main Program
INCLUDE cicslib(DFHEAI0) CICS Module
INCLUDE exxlib(CICSETB)  Broker stub
ENTRY mainpgm
NAME ...

COMETB

COMETB is the stub for any Com-plete environment. For Natural, use NATETB23 or NATETBZ.

• Prerequisites and Installation Notes

• Linkage

• EXAENV Environment Store

Prerequisites and Installation Notes

• We recommend you load COMETB dynamically within the application program.

• COMETB must be available in the COMPLIB search chain if called dynamically. Modify the Com-plete procedure or job, adding the EXX load library to the COMPLIB library concatenations.

• COMETB requires about 950 KB storage above the line. Increase the Com-plete SYSPARM THSIZEABOVE by 950 KB.

• If the EXAENV Environment Store is used (DD EXAENV is defined in the Com-plete started task JCL), increase the ULIB region size for your application that calls COMETB by 4 KB storage below the line.

Linkage

It is also possible to link your application to member COMETB from the EntireX load library (EXX109.LOAD).

EXAENV Environment Store

The EXAENV Environment Store is used under Com-plete only. A partitioned data set is assigned by DD EXAENV. It represents the environment store for all Com-plete users. PDS members in the store are used to define variables and assign values. The PDS member name used is the name of the user logged on to Com-plete. If you want to define your own variables, add a text member with your user name and put all variables into it.

A member with the name DEFAULT may contain global variables valid for all users.

The environment store has following data set characteristics:

DSORG=PO
LRECL=80
RECFM=FB

A line in the text member setting a variable and its value looks like:

ETB_STUBLOG=1

Variable name and variable value are left-justified and delimited by an equals sign. The first blank in the line identifies the end of the environment value definition.

See also Prerequisites and Installation Notes.

IDMSETB

Prerequisites and Installation Notes

IDMSETB cannot be called dynamically.

Linkage

Link your application to member IDMSETB from the EntireX load library (EXX109.LOAD).

MPPETB

Prerequisites and Installation Notes

• MPPETB can be called dynamically, but the appropriate ADALNK (ADALNI) must be linked to MPPTB beforehand.

Linkage

Link your application to member MPPETB from the EntireX load library (EXX109.LOAD) and the appropriate Adabas link module from the Adabas load library.

NATETB23

NATETB23 is the recommended stub for Natural. See also NATETBZ.

• Prerequisites and Installation Notes for Natural

• Linkage under Natural

• Installation Verification under Natural

Prerequisites and Installation Notes for Natural

• Set the Natural size parameters so that Natural can provide the stub with 34 KB at runtime.

• Set Natural parameter ETRACE=ON if you want a trace of the NET transport.

• Send/receive buffers of greater than 32 KB can be used with NATETB23 provided that Adabas library WAL842 (or above) is installed. See Contents of Mainframe Installation Medium in the z/OS Installation documentation.

Linkage under Natural

• Linking the stub for use in z/OS Batch, TSO, CICS, IMS(BMP), IMS(MPP) and Com-plete:

  Link NATETB23 in the load library to the environment-independent Natural nucleus. NATETB23 is a reentrant and relocatable module.

• Alternatively, the NATETB23 stub can be dynamically invoked by the following Natural parameters:

  RCA=BROKER,RCALIAS=(BROKER,NATETB23)

Installation Verification under Natural

To verify the installation of the stub under Natural

1. Log on to Natural library SYSRPC and type MENU.

2. Invoke SM Service Directory Maintenance from the main menu.

3. Define the Node and Server and save.

4. Invoke XC Server Command Execution from the main menu for the node and server defined in the previous step.

5. Ping the server with the command PI.

Your environment and the stub are installed correctly if you receive

• 02150148 Connection error, meaning that the broker and the RPC server are down;

• 00070007 Service not registered, meaning that the broker is up and the RPC server is down;

• an answer from the RPC server.

For other return codes, see Error Messages and Codes.

NATETBZ

This reentrant stub is for exclusive use by Natural RPC Server.

Prerequisites and Installation Notes for Natural

• It may run in SRB mode and is zIIP-eligible.

• Set the Natural size parameters so that Natural can provide the stub with 34 KB at runtime.

• Set Natural parameter ETRACE=ON if you want to get a trace.

Linkage under Natural

• To statically link the stub for use in z/OS Batch, link NATETBZ into the load library where the Batch Natural nucleus resides. NATETBZ is a reentrant and relocatable module.

• Alternatively, the NATETBZ stub can be called dynamically with the following Natural parameters:

  RCA=BROKER,RCALIAS=(BROKER,NATETBZ)

Tracing for Broker Stubs

• Setting Trace

• Examples

Setting Trace

//EXALOG1 DD SYSOUT=*
//TRACE1  DD SYSOUT=*

//EXALOG1 DD DUMMY

//EXALOG1 DD DUMMY
//TRACE1  DD SYSOUT=*
//CMTRACE DD SYSOUT=*

EXA_LOG=1
ETB_STUBLOG=1

//EXALOG2 DD SYSOUT=*
//TRACE1  DD SYSOUT=*

//EXALOG2 DD DUMMY

//EXALOG2 DD DUMMY
//TRACE1  DD SYSOUT=*
//CMTRACE DD SYSOUT=*

EXA_LOG=2
ETB_STUBLOG=2

//EXALOG3 DD SYSOUT=*
//TRACE1  DD SYSOUT=*

//EXALOG3 DD DUMMY

//EXALOG3 DD DUMMY
//TRACE1  DD SYSOUT=*
//CMTRACE DD SYSOUT=*

EXA_LOG=3
ETB_STUBLOG=3

Notes:

1. In this approach, DD assignments are checked by the stub module in order to determine the trace level and output location.
2. In this approach, DD assignments are checked by the stub module in order to determine the trace level.
3. In this approach a variable definition in a partitioned data set (PDS) member, the so-called EXAENV environment store is checked in order to determine the trace level. See EXAENV Environment Store.

Examples

To set trace level 3 for stub module BROKER or MPPETB

• Define the following DD statements in your JCL:

  //EXALOG3 DD SYSOUT=*
  //TRACE1 DD SYSOUT=*
       

To set trace level 2 for stub module CICSETB

• Define the following DD statement in the JCL to start CICS:

  //EXALOG2 DD DUMMY

To set trace level 1 for stub module COMETB

• Add the following variable name and value to the EXAENV environment store:

  EXA_LOG=1
  ETB_STUBLOG=1

Timeout Settings for Broker Stubs

Setting timeouts for the transport layer is possible for the transport method TCP. The transport method NET does not support timeouts. This section covers the following topics:

• Setting the TCP/IP Timeout

• Limiting the TCP/IP Connection Lifetime

• SAGTOKEN Utility

Setting the TCP/IP Timeout

If the transport layer is interrupted, communication between the broker and the stub - that is, client or server application - is no longer possible. A client or server might possibly wait infinitely for a broker reply or message in such a situation. To prevent this and return control to your calling application in such a situation, set a timeout value for the transport method.

The timeout value for the transport method is set by the environment variable ETB_TIMEOUT on the stub side. This transport timeout is used together with the broker timeout - which is set by the application in the WAIT field of the broker ACI control block - to calculate the actual value for the transport layer's timeout. This timeout for the transport layer is independent of the timeout settings of the broker kernel.

The following table describes the possible values for the TCP timeout and how to set it per stub module:

//STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,TIMEOUT=0')
//STEPLIB DD DISP=SHR,DSN=EXX109.LOAD

ETB_TIMEOUT=0

//STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,TIMEOUT=n')
//STEPLIB DD DISP=SHR,DSN=EXX109.LOAD

ETB_TIMEOUT=n

//STEP EXEC PGM=SAGTOKEN,PARM=('DELETE LOCAL,TIMEOUT')
//STEPLIB DD DISP=SHR,DSN=EXX109.LOAD

Notes:

1. The actual timeout for transport layer equals broker timeout (WAIT field) + transport timeout.
2. The stub supports this timeout in the connection phase and during data transfer.
3. The stub supports this timeout in the connection phase only.

Limiting the TCP/IP Connection Lifetime

With transport method TCP/IP the broker stub establishes one or more TCP/IP connections to the brokers specified with BROKER-ID.

• On the broker stub side, these connections can be controlled by the transport-specific environment variable ETB_NONACT.
  If ETB_NONACT is not 0, it defines the non-activity time (in seconds) of active TCP/IP connections to any broker. See ETB_NONACT under Environment Variables in EntireX. Whenever the broker stub is called, it checks for the elapsed non-activity time and closes connections with a non-activity time greater than the value defined with ETB_NONACT.
  

• On the broker kernel side, non-activity can be set with the transport-specific attribute CONNECTION-NONACT (SSL | TCP).

Both settings (the stub side and broker kernel side) act independently of each other.

The following table describes the possible values to limit TCP connection lifetime and how to set it per stub module:

//STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,NONACT=0')
//STEPLIB DD DISP=SHR,DSN=EXX109.LOAD

ETB_NONACT=0

//STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,NONACT=n')
//STEPLIB DD DISP=SHR,DSN=EXX109.LOAD

ETB_NONACT=n

//STEP EXEC PGM=SAGTOKEN,PARM=('DELETE LOCAL,NONACT)
//STEPLIB DD DISP=SHR,DSN=EXX109.LOAD

SAGTOKEN Utility

SAGTOKEN allows you to set variables. When setting variables with SAGTOKEN, SAGTOKEN error messages may be displayed on the operator console. The steplib EXB109.LOAD of SAGTOKEN must be APF-authorized. See EntireX SAGTOKEN Messages.

Syntax

//STEP EXEC PGM=SAGTOKEN,PARM=('command scope, variable=value')
//STEPLIB DD DISP=SHR,DSN=EXB109.LOAD

Operands

Transport Methods for Broker Stubs

This section covers the following topics:

• Transport Method Values

• Default Transport Methods

Transport Method Values

For Secure Sockets Layer/Transport Layer Security (SSL/TLS) as transport method, see table Using SSL/TLS with EntireX Components.

Default Transport Methods

For stub module BROKER, DD assignments are checked in order to determine the default transport method.

//EXATCP DD DUMMY

//EXANET DD DUMMY

SVC Number for Broker Communication

Considerations for Users without Adabas

For customers who do not have Adabas installed at their site,

• we recommend installing the Adabas modules (library WAL842) delivered with EntireX. See also Contents of Mainframe Installation Medium in the z/OS Installation documentation.

• the Adabas modules will greatly improve performance if the transport method NET is used and broker kernel and applications (client or server) communicating through the stub to the broker kernel on the same machine locally, see Transport Methods for Broker Stubs.

For information on how to install the Adabas SVC and install Adabas with TP Monitors, see Installing Adabas Components for EntireX under z/OS.

Support of Clustering in a High Availability Scenario

EntireX Broker supports clustering in a high-availability scenario, using the environment variable ETB_SOCKETPOOL. See Environment Variables in EntireX. This section covers the following topics:

• Introduction

• Exceptions

• Default

• Restriction

See also High Availability in EntireX.

Introduction

A TCP/IP connection established between stub and broker is not exclusively assigned to a particular thread. With multithreaded applications, two or more threads may use the same connection. On the other hand, if a connection is busy, another new one is created to exchange data.

In order to access the same broker instance in a clustering environment, an affinity between application thread and TCP/IP connection is needed to always use the same connection within an application thread. Therefore, an environment variable is evaluated to control the handling of TCP/IP connections.

If environment variable ETB_SOCKETPOOL is set to "OFF" (ETB_SOCKETPOOL=OFF), an affinity between threads and TCP/IP connections is established. All requests to one particular broker will use the same TCP/IP connection. ETB_SOCKETPOOL controls all TCP/IP connections.

Stubs ARFETB and NATETBZ always establish an affinity between subtask and TCP/IP connection.

Exceptions

Broker attribute CONNECTION-NONACT is used by the broker to close TCP/IP connections after the elapsed non-activity time. Omit this attribute to keep the TCP/IP connection alive.

Default

ETB_SOCKETPOOL=ON is the default setting. In this case, an established broker connection can be used by any thread if the connection is not busy.

Restriction

Support for this feature is currently not available under CICS, Com-plete, and IDMS/DC.