Administering Broker Stubs under z/VSE

Note:
Support for EntireX Broker and RPC servers under z/VSE ended on 31 October 2020 for all EntireX versions (including version 9.6, the last released version on z/VSE). See Features Dropped in Version 10.7.


Available Stubs

This table lists all Broker stubs available under the z/VSE operating system that are to be used with the programming languages Natural, COBOL, Assembler and C. The stub you choose depends on your environment (CICS or Batch).

Environment Transport Trace Stub Module
NET TCP SSL
All environments that use Batch Yes Yes (1) Yes (2) BKIMB
All environments that use CICS Yes Yes (1) Yes (2) BKIMC

Notes:

  1. Use BSI's Automatic Transport Layer Security (ATLS). Refer to the BSI SSL Installation, Programming and User's Guide for more information. See also Using SSL/TLS with EntireX Components.
  2. The request needs to use TCP transport method. Tracing is not available with NET transport.

Transport Methods for Broker Stubs

Transport Method Values

Transport Value Tips
TCP
  • Provides remote machine and cross-platform communication.

NET
  • Provides the best performing transport if the application and Broker kernel reside on the same machine.

  • Provides for remote communications if Entire Net-Work is also installed on the application and Broker kernel machines.

  • Requires the installation of Adabas components. We recommend installing the Adabas modules delivered with EntireX installation kit. See your Adabas documentation for more information on installing the Adabas SVC.

  • Tracing is not supported.

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

To use the stubs' internal security functionality, API version 8 or higher needs to be used by the application. (e.g., EntireX RPC Server, NAT42). The delivered phases are linked for use with internal security.

Setting the Timeout for the Transport Method

Introduction

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 settings for transport layers are independent of the timeout settings of the broker.

Setting the timeout for the transport layer is possible for the transport method TCP, and is supported by all broker stubs under z/VSE.

Transport Timeout Values

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. The following table describes the possible values for the transport timeout:

Transport
Timeout
Value
Description
0 Infinite wait for the application.
n The transport method additionally waits this time in seconds. A negative value is treated as TIMEOUT=0 (infinite wait for the application).
nothing set Transport method waits additional 20 seconds.

The actual timeout for transport layer equals broker timeout (WAIT field) + timeout value for transport method.

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.
    Stubs capable of running in SRB mode do not support ETB_NONACT handling.

  • 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.

Transport Non-activity Value Description
0 Infinite lifetime until application is stopped.
n (seconds) Transport connections with non-activity time greater than n will be closed.
Nothing set Infinite lifetime until application is stopped.

Using the Batch Stub Interface Module BKIMB

You can use BKIMB for all batch environments. This stub interface module is delivered as a phase, which can be loaded by your application dynamically, and as an object for linking. At runtime, the EXX960 library and the WAL842 library need to be included into the LIBDEF search chain. If you need to statically link your application with the interface object, include the following objects:

PHASE <appl_phase_name>,*
INCLUDE <app_obj>
INCLUDE BKIMB
INCLUDE ETBVPRE
INCLUDE ETBVEVA
INCLUDE ETBENC
INCLUDE ETBTB
ENTRY <app_entry>

Start of instruction setTo set up a secure environment

  1. Statically link your application with the following interface objects:

    PHASE <appl_phase_name>,*
    INCLUDE <app_obj>
    INCLUDE BKIMB
    INCLUDE ETBUPRE
    INCLUDE ETBUEVA
    INCLUDE ETBVPRE
    INCLUDE ETBVEVA
    INCLUDE ETBENC
    INCLUDE ETBTB
    ENTRY <app_entry>

    Or:
    If BKIMB is to be loaded dynamically, you can relink the phase for use with security. Refer to the delivered job control example BKIMB.J.

  2. Rename phase SECUEXI0 in library EXX960 to SECUEXIT.

Using the CICS Stub Interface Module BKIMC

You can use BKIMC for all CICS environments. This stub interface module is delivered as a phase, which can be loaded by your application dynamically, and as an object for linking. To enable CICS to find the various programs, include the EXX960 sublibrary in the DFHRPL chain and add following definition to your CICS environment:

DEFINE PROGRAM(BKIMC) GROUP(EXX) LANGUAGE(ASSEMBLER)   (only required if not linked to your application)
DEFINE PROGRAM(BROKERC) GROUP(EXX) LANGUAGE(C)

If you need to statically link your application with the interface object, include the following objects:

PHASE <appl_phase_name>,*
INCLUDE <app_obj>
INCLUDE BKIMC
INCLUDE ETBVPRE
INCLUDE ETBVEVA
INCLUDE ETBENC
INCLUDE ETBTB
ENTRY <app_entry>

Start of instruction setTo set up a secure environment

  1. Statically link your application with the following interface objects:

    PHASE <appl_phase_name>,*
    INCLUDE <app_obj>
    INCLUDE BKIMC
    INCLUDE ETBUPRE
    INCLUDE ETBUEVA
    INCLUDE ETBVPRE
    INCLUDE ETBVEVA
    INCLUDE ETBENC
    INCLUDE ETBTB
    ENTRY <app_entry>

    Or:
    If BKIMC is to be loaded dynamically, you can relink the phase for use with security. Refer to the delivered job control example BKIMC.J.

  2. Rename phase SECUEXI0 in library EXX960 to SECUEXIT.

Tracing for Broker Stubs

If transport method TCP is used, a stub trace may be turned on for diagnostic purposes. Set up the following environment variable in your application job control or CICS startup.

//SETPARM STUBLOG=2