This document covers the following topics:
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
Environment | Supported Transport | Stub Module | Default Transport | Trace | ||||
---|---|---|---|---|---|---|---|---|
NET | TCP | SSL | TCP | NET | ||||
Batch, TSO | Yes | Yes | (1) | BROKER (4) | NET | Setting the Default Transport Method | Setting Trace | |
IMS (BMP) | Yes | Yes | (1) | BROKER (4) | NET | |||
IMS (MPP) | Yes | Yes | (1) | MPPETB (4) | NET | n/a | ||
CICS | Yes | Yes | (1) | CICSETB (4) | NET | n/a | ||
Com-plete | Yes | Yes | (1) | COMETB (4) | NET | n/a | ||
Natural | Yes | Yes | (1) | NATETB23 (4) | NET | n/a | Setting Trace | n/a(3) |
Natural RPC Server | Yes | Yes | (1) | NATETBZ (2) | NET | n/a | n/a(3) | n/a(3) |
Event Replicator for Adabas | Yes | Yes | (1) | ARFETB (2) | NET | n/a | n/a | n/a |
IDMS/DC | No | Yes | (1) | IDMSETB (4) | TCP | n/a | n/a | n/a |
Notes:
This reentrant stub is for exclusive use by Adabas Replication Services.
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 is the recommended stub for any batch environment except Natural. For Natural, use NATETB23 or NATETBZ.
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 EXX105.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.
Choose the method most appropriate for your application:
Link your application to module BROKER from the EntireX load library (EXX105.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
Link your application to module BROKER from the EntireX load library (EXX105.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=EXX105.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), please 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 is the recommended stub for any CICS environment except Natural. For Natural, use NATETB23 or NATETBZ.
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 EXX105.ZAPS(EXX0007) to set the site-specific name of your Adabas CICS link routine. By default, the zap will change the name to "ADABAS".
Link your application to member CICSETB from the EntireX load library (EXX105.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 is the stub for any Com-plete environment. For Natural, use NATETB23 or NATETBZ.
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.
It is also possible to link your application to member COMETB from the EntireX load library (EXX105.LOAD).
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 cannot be called dynamically.
Link your application to member IDMSETB from the EntireX load library (EXX105.LOAD).
MPPETB can be called dynamically, but the appropriate ADALNK (ADALNI) must be linked to MPPTB beforehand.
Link your application to member MPPETB from the EntireX load library (EXX105.LOAD) and the appropriate Adabas link module from the Adabas load library.
NATETB23 is the recommended stub for Natural. See also NATETBZ.
Set the Natural size parameters so that Natural can provide the stub with 34 KB at runtime.
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.
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 shared part of the 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)
To verify the installation of the stub under Natural
Log on to Natural library SYSRPC and type MENU.
Invoke SM Service Directory Maintenance from the main menu.
Define the Node and Server and save.
Invoke XC Server Command Execution from the main menu for the node and server defined in the previous step.
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.
This reentrant stub is for exclusive use by Natural RPC Server.
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.
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)
How to Set Trace | Stub Module | ||||||
---|---|---|---|---|---|---|---|
BROKER, MPPETB |
CICSETB | NATETB23 | COMETB | NATETBZ, ARFETB, IDMSETB |
|||
Define the following DD statements in your JCL (1): | Define the following DD statements in your JCL to start CICS (2): | Define the following DD statements in your JCL (3): | Add the following variables to the EXAENV Environment Store (4): | Trace is not supported. | |||
1 | STANDARD |
Traces initialization, errors, and all ACI request/reply strings. | //EXALOG1 DD SYSOUT=* //TRACE1 DD SYSOUT=* |
//EXALOG1 DD DUMMY |
//EXALOG1 DD DUMMY //TRACE1 DD SYSOUT=* |
EXA_LOG=1 ETB_STUBLOG=1 |
|
2 | ADVANCED |
Used primarily by system engineers, traces everything from level 1 and provides additional information, for example the Broker ACI control block, as well as information from the transports. | //EXALOG2 DD SYSOUT=* //TRACE1 DD SYSOUT=* |
//EXALOG2 DD DUMMY |
//EXALOG2 DD DUMMY //TRACE1 DD SYSOUT=* |
EXA_LOG=2 ETB_STUBLOG=2 |
|
3 | SUPPORT |
This is full tracing through the stub, including detailed traces of control blocks, message information, etc. | //EXALOG3 DD SYSOUT=* //TRACE1 DD SYSOUT=* |
//EXALOG3 DD DUMMY |
//EXALOG3 DD DUMMY //TRACE1 DD SYSOUT=* |
EXA_LOG=3 ETB_STUBLOG=3 |
|
0 | NONE |
No tracing. Switch tracing off. | Do not define EXALOG1 , EXALOG2 and EXALOG3 DD statements in your JCL.
|
Do not define EXALOG1 , EXALOG2 and EXALOG3 DD statements in your JCL to start CICS.
|
Do not define EXALOG1 , EXALOG2 and EXALOG3 DD statements in your JCL.
|
Do not define the variable ETB_STUBLOG and EXA_LOG in EXAENV environment store or set its value to zero.
|
|
Trace Output Location | TCP trace output is written to TRACE1 DD statement while NET trace output is routed to EXALOGn DD statement defined in your JCL.
|
TCP as well as NET trace output is written to CICS TD queue CSSL. This TD queue is typically assigned to DD statement MSGUSER . Refer to the JCL to start CICS.
|
TCP trace output is written to TRACE1 DD statement
|
TCP trace output is controlled by the hardcopy setting in Com-plete. See hardcopy function from the UUTIL menu. If no device
name has been defined, the trace is displayed on the terminal. If HC has been specified, the trace will be written to the
Com-plete spool and routed to the device name supplied using HC=name . NET trace output is written via COMPLETE Printout Spooling, default destination " SYSOUT=X ".
|
Notes:
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
If a stub module for Natural does not support tracing (for example NATETBZ
, NATETB23
for NET transport)
and you want detect errors in broker communication, we recommend using temporarily the platform-specific stub instead.
For CICS, use
RCA=BROKER,RCALIAS=(BROKER,CICSETB)
For Com-plete, use
RCA=BROKER,RCALIAS=(BROKER,COMETB)
Also, PRIVILEG status is required in Com-plete for COMETB.
See Available Stubs for an overview of stub modules and Setting Trace.
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:
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:
How to Set the TCP Timeout | Stub Module | |||
---|---|---|---|---|
BROKER(2), MPPETB(2), BROKER(2), MPPETB(2), NATETB23(2), NATETBZ(3), ARFETB(3) | COMETB(2) | IDMSETB | ||
Use the SAGTOKEN Utility to set the TCP timeout.
|
Add the following variable to the EXAENV Environment Store: | TCP timeout is not supported. | ||
0 | Infinite wait for the application. | //STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,TIMEOUT=0') //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD |
ETB_TIMEOUT=0 |
|
n | The transport method additionally waits this time in seconds. A negative value is treated as TIMEOUT=0 (infinite wait for the application).(1) |
//STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,TIMEOUT=n') //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD |
ETB_TIMEOUT=n |
|
nothing set | Transport method waits additional 20 seconds. (1) | //STEP EXEC PGM=SAGTOKEN,PARM=('DELETE LOCAL,TIMEOUT') //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD |
Do not define the variable ETB_TIMEOUT in EXAENV environment store.
|
Notes:
WAIT
field) + transport timeout.
With transport method TCP/IP the broker stub establishes one or more TCP/IP connections to the brokers specified with BROKER-ID
.
These connections can be controlled by the transport-specific CONNECTION-NONACT
attribute on the
broker side, but also by the transport-specific environment variable ETB_NONACT
on the stub side.
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
.
This timeout for the transport layer is independent of the timeout settings of the broker kernel.
The following table describes the possible values to limit TCP connection lifetime and how to set it per stub module:
How to Limit the TCP Connection Lifetime | Stub Module | |||
---|---|---|---|---|
BROKER, MPPETB, NATETB23 | COMETB | NATETBZ(1), ARFETB(1), IDMSETB(1) | ||
Use the SAGTOKEN Utility to set the TCP timeout.
|
Add the following variable to the EXAENV Environment Store: | TCP connection lifetime cannot be limited. | ||
0 | Infinite wait for the application. | //STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,NONACT=0') //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD |
ETB_NONACT=0 |
|
n | The transport method additionally waits this time in seconds. A negative value is treated as TIMEOUT=0 (infinite wait for the application).(1) |
//STEP EXEC PGM=SAGTOKEN,PARM=('SET LOCAL,NONACT=n') //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD |
ETB_NONACT=n |
|
nothing set | Transport method waits additional 20 seconds. (1) | //STEP EXEC PGM=SAGTOKEN,PARM=('DELETE LOCAL,NONACT) //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD |
Do not define the variable ETB_NONACT in EXAENV environment store.
|
SAGTOKEN
allows you to set variables. When setting variables with SAGTOKEN
,
SAGTOKEN
error messages may be displayed on the operator console. The steplib
EXX105.LOAD of SAGTOKEN
must be APF-authorized. See EntireX SAGTOKEN Messages.
//STEP EXEC PGM=SAGTOKEN,PARM=('command scope, variable=value') //STEPLIB DD DISP=SHR,DSN=EXX105.LOAD
Command | Use |
---|---|
SET |
Set or replace a SAGTOKEN variable.
|
DELETE |
Delete a SAGTOKEN variable.
|
DISPLAY |
Display a SAGTOKEN variable.
|
Scope | Meaning |
---|---|
LOCAL |
Applies to the address space. |
GLOBAL |
Applies to the z/OS image. |
Variable | Value |
---|---|
TIMEOUT |
For information on TIMEOUT values, see Timeout Settings for Broker Stubs.
|
NONACT |
For information on NONACT , see Limiting the TCP Connection Lifetime.
|
Note:
If a job uses SAGTOKEN
to set local tokens in one step, we recommend
that you delete these tokens prior to job termination in order to release all acquired resources.
This section covers the following topics:
Transport Value | Description / Tips | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
NET | Use Adabas Cross-Memory Services as transport method. See Installing Adabas Components for EntireX under z/OS in the z/OS installation documentation.
It is also possible to communicate remotely with the transport method NET from an application (client or server) to the
broker kernel using Entire Net-Work. For remote NET communication, Entire Net-Work must be installed both on the machine where
the broker kernel runs and on the machine where your application (client or server) runs, and a connection must be established.
Using Adabas modules WAL811 or above allows more than 32 KB of data to be communicated. Otherwise the following maximum values are allowed:
Note: |
||||||||||
TCP | Use TCP/IP as transport method. |
For Secure Sockets Layer/Transport Layer Security (SSL/TLS) as transport method, see table Using SSL/TLS with EntireX Components.
For stub module BROKER, DD assignments are checked in order to determine the default transport method.
Transport | How to set Default Transport? |
---|---|
TCP | Define EXATCP as dummy DD statement in your JCL: //EXATCP DD DUMMY |
NET | Define EXANET as dummy DD statement in your JCL: //EXANET DD DUMMY |
Stub | Notes | ||||||
---|---|---|---|---|---|---|---|
ARFETB | See your Event Replicator for Adabas documentation for information on how to specify the SVC number used for Broker communication. | ||||||
BROKER | When Entire Net-Work transport is used, the default SVC number (249) can be overridden in the following ways:
|
||||||
CICSETB | When Entire Net-Work transport is used and the default SVC number (249) has to be changed, the Adabas communications module under CICS determines how the SVC number can be changed. See the Adabas documentation for information on how to change the SVC number. | ||||||
COMETB |
|
||||||
MPPETB | When Entire Net-Work transport is used and the default SVC number (249) has to be changed, the Adabas communications module under IMS/DC determines how the SVC number can be changed. See the Adabas documentation for information on how to change the SVC number. | ||||||
NATETB23 |
|
||||||
NATETBZ | See your Natural documentation for information on how to specify the SVC number used for Broker communication. |
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 in the z/OS installation documentation.
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:
See also High Availability in EntireX.
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.
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.
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.
Support for this feature is currently not available under CICS, Com-plete, and IDMS/DC.