Broker Command and Information Services

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.


CIS Overview Table

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

  • USER-INFO

  • CMD

  • PARTICIPANT-SHUTDOWN

  • SECURITY-CMD

  • request structures

Command-line Utilities ETBINFO utility
  • INFO

  • USER-INFO

  • profile

  • command-line parameters

ETBCMD utility
  • CMD

  • PARTICIPANT-SHUTDOWN

  • SECURITY-CMD

  • command-line parameters

Applicable operating systems: z/OS, UNIX, Windows and z/VSE.

Description of Services

INFO and USER-INFO

  • 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, PARTICIPANT-SHUTDOWN and SECURITY

  • CMD is the full command service.

  • PARTICIPANT-SHUTDOWN is limited to shutting down participants.

  • SECURITY-CMD is limited to EntireX Security-related commands.

Modes of Requesting the Services

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.

Command-line Utilities

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.

Version Information

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

Graphical User Interface

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.

User-Written Interface

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.

ETBCMD: Executable Command Requests

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|Snn|Tnn. 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:
  • Error code 00100050 will be returned to the server, if it is waiting.

  • All existing conversations will be finished with EOC.

  • User will be logged off.

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:
  • Error code 00100050 will be replied to all servers, if they are waiting.

  • All existing conversations will be finished with EOC.

  • Users will be logged off.

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:
  • Error code 00100050 will be replied to the participant, if it is waiting.

  • All existing conversations will be finished with EOC.

  • User will be logged off.

    Within EntireX Broker nomenclature, a participant is an application implicitly or explicitly logged on to the Broker as a specific user. A participant could act as client or server.

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|Snn|Tnn 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|Snn|Tnn Check the current status of the transport communicator. 7
STOP TRANSPORT Transport ID: NET|Snn|Tnn 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|Snn|Tnn 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

ETBINFO: Returnable Information Requests

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.

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