EntireX Broker provides two internal services: Command Service and Information Services that can be used administer and monitor the EntireX Broker. The command service allows you to issue a set of Broker commands; the information services provide you with various statistics to better administer and tune your Broker. Because these services are implemented internally, nothing has to be started or configured. You can use these services immediately after starting EntireX Broker.
This document covers the following topics:
See also Broker CIS Data Structures.
EntireX Broker provides these predefined internal services:
Command Service
Provides a facility to issue commands against the Broker (e.g.
SHUTDOWN etc.).
Information Services
Provides a query mechanism to obtain various types of information on
the Broker, which is helpful for administration and tuning.
Since these services are implemented internally, nothing has to be started, configured or defined in the Broker attribute file. You can use them immediately after starting the Broker. They can be requested as follows:
| Mode of Request | Tools | Services | Requirements |
|---|---|---|---|
| User-Written Interface | application program |
|
|
| Command-line Utilities | ETBINFO utility
|
|
|
ETBCMD utility
|
|
|
Applicable operating systems: z/OS, UNIX, Windows and z/VSE.
INFO is the full information service. Specify it for the full
information service. All clients, servers and conversations are listed.
USER-INFO is limited to your user-specific information. Specify it
for limited information service. Only the user's own resources are listed.
CMD is the full command service.
PARTICIPANT-SHUTDOWN is limited to shutting down participants.
SECURITY-CMD is limited to EntireX Security-related commands.
Use one of these three modes to request a service:
The method for requesting these services is the same as the method for
requesting any other service. For both types of services, an application issues
a SEND command with appropriate data and retrieves
a reply. The request itself is specified within the SEND buffer; the reply - if
there is one - is specified in the RECEIVE
buffer.
For Information Services requests, RECEIVE operations must be repeated
until the Information Service indicates the end of data with an
EOC return message.
Software AG provides three command-line utility programs for use with EntireX Broker. All utility programs use command-line parameters that specify various options and information to be built into a request. These utility programs are:
ETBINFO
Queries the Broker for different types of information, generating
an output text string with basic formatting. This text output can be further
processed by script languages (or elsewhere). ETBINFO uses data descriptions
called profiles to control the type of data that is returned for a request.
ETBINFO is useful for configuring and administering EntireX Broker efficiently
- e.g., how many users are to run concurrently and whether the number of
specified message containers is large enough.
See ETBINFO under
z/OS |
UNIX |
Windows |
z/VSE |
BS2000 for profiles, examples and utility
parameters.
ETBCMD
Allows you to take actions - e.g., purge a unit of work, stop a
server, shut down a Broker - against EntireX Broker.
See ETBCMD under
z/OS |
UNIX |
Windows |
z/VSE |
BS2000 for utility parameters.
The ETBINFO and ETBCMD CIS command-line utilities are compatible
with all versions of EntireX Broker.
Display keywords applying to a specific version of Broker will not be returned when a call is made to any older version of Broker.
Software AG provides a graphical user interface, Command Central, for displaying information on the Broker and/or executing administrative functions. Software AG Command Central is a tool that enables you to manage your Software AG products remotely from one location. Command Central offers a browser-based user interface, but you can also automate tasks by using commands to remotely execute actions from a terminal or custom script (for example CI servers such as Jenkins, or generic configuration management tools such as Puppet or Chef).
Command Central can assist with the following configuration, management, and monitoring tasks:
Infrastructure engineers can see at a glance which products and fixes are installed, where they are installed, and compare installations to find discrepancies.
System administrators can configure environments by using a single web user interface or command-line tool. Maintenance involves minimum effort and risk.
Release managers can prepare and deploy changes to multiple servers using command-line scripting for simpler, safer lifecycle management.
Operators can monitor server status and health, as well as start and stop servers from a single location. They can also configure alerts to be sent to them in case of unplanned outages.
If you access the Command and Information Services through a user-written application, you must use a defined protocol. This protocol describes the structures needed to communicate with the service(s) so that the request is correctly interpreted by the Broker.
See Writing Applications: Command and Information Services and Broker CIS Data Structures.
The following command requests can be issued, using
ETBCMD. All the functions listed in this table are
applicable to all three request modes; see Modes of Requesting the Services.
Note:
Version numbers in this table refer to the interface version and not
to the Broker version.
| Command Request | Comment | CIS Interface Version |
||
|---|---|---|---|---|
ALLOW-NEWUOWMSGS |
New UOW messages are allowed. | 3 | ||
CLEAR-CMDLOG-FILTER |
Remove the specified command log filter. | 5 | ||
CONNECT-PSTORE |
Connects the persistent store. See Availability of Persistent Store. | 4 | ||
DISABLE-ACCOUNTING |
Disables accounting. Accounting records are discarded until accounting is enabled. | 5 | ||
DISABLE-CMDLOG |
Disable command logging. | 5 | ||
DISABLE-DYN-WORKER |
Disable the
DYNAMIC-WORKER-MANAGEMENT.
DYNAMIC-WORKER-MANAGEMENT=YES must be configured
in the attribute file. The current number of active worker tasks will not be
changed until DYNAMIC-WORKER-MANAGEMENT is
enabled again.
|
7 | ||
DISCONNECT-PSTORE |
Disconnects the persistent store. See Availability of Persistent Store. | 4 | ||
ENABLE-ACCOUNTING |
Enable accounting. | 5 | ||
ENABLE-CMDLOG |
Enable command logging. | 5 | ||
ENABLE-DYN-WORKER |
Enable the
DYNAMIC-WORKER-MANAGEMENT again.
DYNAMIC-WORKER-MANAGEMENT=YES must be configured
in the attribute file. DYNAMIC-WORKER-MANAGEMENT
has been disabled before. Additional worker tasks can be started again, or
stopped if not used.
|
|||
FORBID-NEWUOWMSGS |
New UOW messages are not allowed. | 3 | ||
PRODUCE-STATISTICS |
Output current statistics to the broker log. | 5 | ||
PURGE |
Remove a unit of work from the persistent store. | 2 | ||
RESET-USER |
Clear all cached security information for the specified user ID. | 5 | ||
RESUME |
Transport ID: NET|S. Resume a
suspended transport communicator. If the communicator was not suspended before,
an error message will be returned.
|
|||
SET-CMDLOG-FILTER |
Add the specified command log filter. | 5 | ||
SET-UOW-STATUS |
PSF |
Set the status of postponed UOWs to ACCEPTED or CANCELLED, for example:
etbcmd –b<broker_id> -cSET-UOW-STATUS –dPSF –oACCEPTED –n<class>/<server>/<service> |
10 | |
SHUTDOWN |
BROKER |
Shutdown Broker immediately. | 1 | |
CONVERSATION
<conversation-id> |
Command applies to conversations without units of work only. The security rights shutting down the service are required for shutting down the conversation. | 7 | ||
IMMED |
The specified conversation is immediately removed. All messages of the conversation are lost. | |||
QUIESCE |
An end of conversation is issued. The conversation remains active. | |||
SERVER |
IMMED |
Shutdown server immediately. The server must be
uniquely identified using field P-USER-ID or SEQNO and will be
completely removed from the broker environment. The following steps will be performed: |
1 | |
QUIESCE |
Shutdown server but allow existing conversations
to continue. The termination is signaled to the server by error code 00100051. After this, the next call issued must be a DEREGISTER for all services (SC=*,SN=*,SV=* if
more than one service is active).
|
|||
SERVICE <class/server/service> |
Internal services cannot be shut down. | 7 | ||
IMMED |
Caution: All servers offering this service will
be deregistered and logged off. The following steps will be performed:
|
|||
QUIESCE |
All servers offering this service are
deregistered. Shutdown servers but allow existing conversations to continue.
The termination is signaled to the servers by error code 00100051. After this,
the next call issued must be a DEREGISTER for the
service.
|
|||
PARTICIPANT |
IMMED |
Shutdown participant immediately. The
participant must be identified, using fields P-USER-ID,
UID TOKEN or SEQNO and will be completely removed
from the Broker environment. The following steps will be performed:
|
4 | |
QUIESCE |
Shutdown participant but allow existing conversations to continue. The termination is signaled to the participant by error code 00100051. | |||
START |
TRANSPORT |
Transport ID: NET|S |
Start a transport communicator that was previously stopped. If the communicator was not stopped before, an error message will be returned. | 7 |
STATUS |
TRANSPORT |
Transport ID: NET|S |
Check the current status of the transport communicator. | 7 |
STOP |
TRANSPORT |
Transport ID: NET|S |
Stop an active or suspended transport communicator. The transport communicator will shut down. All transport-specific resources will be freed. User requests receive response code 148. | 7 |
SUSPEND |
TRANSPORT |
Transport ID: NET|S |
Suspend an active transport communicator. | 7 |
SWITCH-CMDLOG |
Force a switch of command logging output files. | 5 | ||
TRACE-FLUSH |
BROKER |
Flush all trace data kept in internal trace
buffers to stderr (DD:SYSOUT). The broker-specific attribute TRMODE=WRAP is
required.
|
7 | |
TRACE-OFF |
BROKER |
Set TRACE-LEVEL off in Broker.
|
1 | |
PSF |
Set TRACE-LEVEL off in persistent store.
|
5 | ||
SECURITY |
Set TRACE-LEVEL off in EntireX Security.
|
5 | ||
TRACE-ON |
BROKER |
Set TRACE-LEVEL on in Broker. Values: 1 | 2 | 3
| 4.
|
1 | |
PSF |
Set TRACE-LEVEL on in persistent store. Values:
1 | 2 | 3 | 4.
|
5 | ||
SECURITY |
Set TRACE-LEVEL on in EntireX Security. Values:
1 | 2 | 3 | 4.
|
5 | ||
TRAP-ERROR |
BROKER |
Error number: nnnn |
Modifies the setting of the broker-specific
attribute TRAP-ERROR.
|
7 |
The following information requests can be returned. All the functions listed in this table are applicable to all three request modes (see Modes of Requesting the Services). The returned data is described under Information Reply Structures in the ACI Programming documentation.
Note:
Version numbers in this table refer to the interface version and not
to the Broker version.
| Information Request | Comment | Interface Version |
|---|---|---|
BROKER |
Global information on this Broker. No additional selection criteria are needed. Other selection criteria fields are ignored. | 1 |
CLIENT |
Information on active clients. | 1 |
CMDLOG-FILTER |
Information on command log filters. | 5 |
CONVERSATION |
Information on active conversations. | 1 |
NET |
Information on the Entire Net-Work communicator. | 5 |
POOL |
Information on Broker pool usage and dynamic memory management. | 7 |
PSF |
Information on a unit of work's status and Information for persistent store. | 2 |
PSFDIV |
Global information on the DIV persistent store. | 2 |
PSFADA |
Global information on the Adabas persistent store. | 3 |
PSFCTREE |
Global information on the c-tree persistent store. | 5 |
RESOURCE |
Information on Broker resource usage. | 7 |
SECURITY |
Global information on EntireX Security. | 5 |
SERVER |
Information on active servers. | 1 |
SERVICE |
Information on active services. | 1 |
SSL |
Information on the SSL communicator. | 5 |
STATISTICS |
Statistics on selected Broker resources. | 7 |
TCP |
Information on the TCP/IP communicator. | 5 |
UOW-STATISTICS |
Statistics on UOWs of selected services. | 9 |
USER |
Information on all users of Broker regardless of the user type. | 7 |
WORKER |
Global information on all workers. No additional selection criteria are needed. Other selection criteria fields are ignored. | 1 |
WORKER_USAGE |
Information on usage of worker tasks and dynamic worker management. | 7 |