This document contains information on setting up the Broker under z/VSE. It assumes that you have completed the relevant steps described under Installing EntireX under z/VSE. It covers the following topics:
The recommended way to set up the TCP/IP communicator is to define
PORT=nnnn and optionally
HOST=x.x.x.x|host_name under
TCP/IP-specific Attributes under Broker Attributes.
However, if no port number is specified in the broker attribute file, the broker kernel will use default port number of 1971. This is the same default port number that the stubs use.
To set up EntireX Net-Work communication mechanism
Ensure that appropriate values are supplied in the broker attribute
file section DEFAULTS=NET, paying particular
attention to the IUBL parameter - which
specifies the maximum send/receive buffer length that can be sent between an
application and Broker kernel within a single request - and
NABS, which governs the total amount of storage
available concurrently for all users communicating over this transport
mechanism. See Adabas SVC/Entire Net-Work-specific Attributes under Broker Attributes.
Ensure that communication with the broker is possible by running the
installation verification programs (BCOC, BCOS) using transport type NET.
To start the broker
Run job RUNETB.J.
If the UPSI bit is not set (see Broker installation step
Step 4: Customize the EntireX Broker Startup Job Control (RUNETB.J)) you will be prompted on the
console with following message: Broker V9.6.0.00 ready for
communication: ETB00001.
To stop the broker
Use the following console command:
task_id ETBSTOPIf the console prompt is suppressed, enter an MSG command before the console command:
MSG partition_id
This section covers the following topics:
The Broker TRACE-LEVEL attribute determines the level of
tracing to be performed while Broker is running. The Broker has a master
TRACE-LEVEL specified in the Broker section of
the attribute file as well as several individual
TRACE-LEVEL settings that are specified in the
following sections of the attribute file. You can also modify the different
TRACE-LEVEL values while Broker is running,
without having to restart the Broker kernel for the change to take effect.
| Individual Settings | Specified in Attribute File Section |
|---|---|
| Master trace level | DEFAULTS=BROKER |
| Conversion trace level | Trace option of the CONVERSION
parameter that can be defined in DEFAULTS=SERVICE |
TOPIC
|
| Security trace level | DEFAULTS=SECURITY |
| Transport trace level | DEFAULTS=NET | TCP |
These individual TRACE-LEVEL values
determine the level of tracing within each subcomponent. If not specified, the
master TRACE-LEVEL is used.
| Trace Level | Description |
|---|---|
| 0 | No tracing. Default value. |
| 1 | Traces incoming requests, outgoing replies, and resource usage. |
| 2 | All of Trace Level 1, plus all main routines executed. |
| 3 | All of Trace Level 2, plus all routines executed. |
| 4 | All of Trace Level 3, plus Broker ACI control block displays. |
Note:
Trace levels 2 and above should be used only when requested by
Software AG support.
It is not always convenient to run with
TRACE-LEVEL defined, especially when higher
trace levels are involved. Deferred tracing is triggered when a specific
condition occurs, such as an ACI response code or a broker subtask abend. Such
conditions cause the contents of the trace buffer to be written, showing trace
information leading up the specified event. If the specified event does not
occur, the Broker trace will contain only startup and shutdown information
(equivalent to TRACE-LEVEL=0). Operating the
trace in this mode requires the following additional attributes in the broker
section of the attribute file. Values for
TRBUFNUM and
TRAP-ERROR are only examples.
| Attribute | Value | Description |
|---|---|---|
TRBUFNUM |
3 | Specifies the deferred trace buffer size = 3 * 64 K. |
TRMODE |
WRAP | Indicates trace is not written until an event occurs. |
TRAP-ERROR |
322 | Assigns the event ACI response code 00780322 "PSI: UPDATE failed". |
An optional feature of EntireX Broker is available to protect a broker
running with SECURITY=YES against
denial-of-service attacks. An application that is running with invalid user
credentials will get a security response code. However, if the process is doing
this in a processing loop, the whole system could be affected. If
PARTICIPANT-BLACKLIST
is set to YES, EntireX Broker maintains a
blacklist to handle such "attacks". If an application causes ten
consecutive security class error codes within 30 seconds, the blacklist handler
puts the participant on the blacklist. All subsequent requests from this
participant are blocked until the
BLACKLIST-PENALTY-TIME
has elapsed.
Here is a scenario illustrating another use of this feature that is not security-related.
An RPC server is to be shut down immediately, using Broker Command and Information
Services (CIS), and has no active request in the broker. The shutdown results
in the LOGOFF of the server. The next request that
the server receives will probably result in message 00020002 "User
does not exist", which will cause the server to reinitialize
itself. It was not possible to inform the server that shutdown was meant to be
performed.
With the blacklist, this is now possible. As long as the blacklist is not switched off, when a server is shut down immediately using CIS and when there is no active request in the broker, a marker is set in the blacklist. When the next request is received, this marker results in message 00100050 "Shutdown IMMED required", which means that the server is always informed of the shutdown.