EntireX Broker provides an API for Command and Information Services (CIS) that include the following: shutting down conversations, servers and services; switching trace on and off; retrieving information on clients; registering servers and services.
Before you begin to write an application, see Broker Command and Information Services.
This document describes how to use the Command and Information Services from a programmer's point of view. It covers the following topics:
EntireX Broker's Command and Information Services are implemented as
internal services. The method for requesting these services is exactly the same
as the method for requesting any other service. An application issues a
SEND
function with appropriate data, retrieves the response with the receive data of
the SEND function and, in the case of the
information service, with additional
RECEIVE
operations. The RECEIVE operations have to be
repeated until the information service indicates the end of data with an
EOC
return message.
Command and Information Services define a protocol that must be followed by the application. This protocol defines the structures needed to indicate to the service which information is desired and to return this information to the application so that the information can be interpreted.
Several basic rules for command as well as information services are described here.
All fields necessary for a
SEND
function must be provided. The following values for
SERVER-CLASS and SERVER-NAME are
used for CIS:
| Value | Description |
|---|---|
SERVER-CLASS=SAG |
Value is always SAG (Software
AG).
|
SERVER-NAME=ETBCIS |
Value is always ETBCIS (EntireX Broker
Command and Information Services).
|
SERVICE=INFO |
Full information service. Specify this for the full information service. All clients, servers and conversations are listed. See Writing Applications using EntireX Security. |
SERVICE=USER-INFO |
Limited information service. Specify this for limited information service. Only the user's own resources are listed. See Writing Applications using EntireX Security. |
SERVICE=CMD |
Specify this for the command service. |
SERVICE=PARTICIPANT-SHUTDOWN |
Specify this for the participant shutdown functionality. |
SERVICE=SECURITY-CMD |
Specify this for the EntireX Security command service. |
The services do not have to be defined in the broker attribute file. Nothing has to be started or configured. You can use the services immediately after starting the broker.
The request for a command service or an information service is
specified within the SEND buffer; the response - if
there is one - is returned in the RECEIVE
buffer.
Structures are used to describe the request and to return information. The following structures are available:
| Structure | Information Service | Command Service | Description |
|---|---|---|---|
| Information Request Structure | Input | Used by an application to specify an information service request. | |
| Command Request Structure | Input | Used by an application to specify a command service request. | |
| Common Header Structure for Response Data | Returned | Returned | Returned as the first structure in each block from both the information service and the command service. |
| Information Reply Structures | Optionally Returned | The object-specific information reply structures are used to
return information about these object types:
|
Command and Information Services can be accessed from any environment from which EntireX Broker can be accessed. The structures for these services are available for the programming languages Assembler, C, Natural and COBOL.
For an information service request, the send buffer contains the information request structure with selection criteria depending on the requested information. See Information Request Structure.
OBJECT-TYPE = SERVICE
will return a list of all services.
OBJECT-TYPE = CONV, USER-ID = HUGO, TOKEN = FRED
will return a list of all conversations belonging to user with
USER-ID HUGO who specified
TOKEN=FRED within Broker calls.
OBJECT-TYPE = CONV, CONV-ID = 0815
will return information about the one single conversation with ID 0815.
When the SEND request returns, the receive
buffer contains parts or all of the return data, and the
CID field contains a conversation ID.
The return data in the receive buffer includes the common header structure followed by a list of one or more object type structures. See Common Header Structure for Response Data. For each object for which information is returned, there is one information reply structure containing the information.
| Send Buffer | Information Request Structure |
|---|---|
| Receive Buffer | Common Header Structure for Response Data [ Information Reply Structures ] |
The size of the common header structure depends on the CIS interface version used.
Test the error code in the common header structure. See Broker Command and Information Services Error Codes.
If the receive buffer is not large enough to contain all available
information, the remaining information can be obtained with additional
RECEIVE functions in the same conversation.
WAIT=NO can be specified because
the data is there and only has to be collected. When no more data is available,
the RECEIVE returns an end of conversation
(EOC)
message.
If the selection is not unique - that is, more than one occurrence is possible - the information service returns a list (array) of information reply structures of the requested type. The common header structure informs the application of the total number of objects and the number of objects accompanying the reply data.
The protocol for an information service request is as follows:
CALL BROKER
FUNCTION=SEND // send data = information request
Service=USER-INFO
CID=NEW
WAIT=YES // receive data = information reply
/* work off retrieved data */
REPEAT
CALL BROKER // receive data=information reply
FUNCTION=RECEIVE
Service=USER-INFO
CID=n
WAIT=NO
IF End of Conversation
escape
END-IF
/* work off retrieved data */
LOOP
The initial
SEND
must be issued with the following:
WAIT=YES for blocking
send commands
CID=NEW because the information service is
implemented as a conversational service
For a command service request, the send buffer contains the command request structure. See Command Request Structure. When sending a command service request, note the possible combinations under Command Request Parameter Combinations.
The return data in the receive buffer includes the common header structure (see Common Header Structure for Response Data):
| Send Buffer | Command Request Structure |
|---|---|
| Receive Buffer | Common Header Structure for Response Data |
The error code in the common header structure must be tested by the application programmer. See Broker Command and Information Services Error Codes.
A typical command service request looks like this:
CALL BROKER FUNCTION=SEND // send data = command request Service=CMD CID=NONE WAIT=YES
Unlike information service requests, the command service is defined
as a non-conversational service that returns a single response. Therefore, the
initial SEND
must be issued with the following:
CID=NONE
WAIT=YES
For security purposes, the Command and Information services are treated exactly like any other service. Therefore, if you are using either EntireX Security or equivalent user-written exits, user access to operate these services can be protected through your security system. This allows you to grant access based upon user ID to only those users who are authorized, where this facility is provided by the platform security implementation for Broker kernel.
When using EntireX Security (or an equivalent), the full command service and the full information service are protected to avoid unauthorized access to information or potential disruption to systems. Therefore, you must grant appropriate access to the following resource profiles protecting the internal services:
Class: SAG Server: ETBCIS Service: CMD
Class: SAG Server: ETBCIS Service: INFO
The limited information service only returns information that belongs solely to the application making the request; it is not necessary to protect this service from unauthorized users. You can provide either limited or unlimited access to the resource profile used to protect the limited information service, as required:
Class: SAG Server: ETBCIS Service: USER-INFO
The full command service can be used to shut down individual servers and, therefore, terminate any Class/Server/Service registered to the server application. When using EntireX Security (or equivalent), the shut-server operation is protected to avoid unauthorized termination of applications. This security check honors the Class/Server/Service of the server application. Therefore, you must grant appropriate access to resource profiles protecting the server application, which gives authorized users permission to register. This is in addition to the authorization for the full command service:
Class: ACLASS Server: ASERVER Service: ASERVICE
The full command service can be used as a
PARTICIPANT-SHUTDOWN for individual participants
currently active in the memory of the Broker kernel. When using EntireX Security (or an equivalent), the stop-participant
operation is protected to
avoid unauthorized use and potential disruption of systems. Therefore, you must
grant appropriate access to the following resource profile:
Class: SAG Server: ETBCIS Service: PARTICIPANT-SHUTDOWN
The full command service can be used to administer EntireX Security. Currently the EntireX Security commands:
allow the EntireX Security trace level to be changed independently of the Broker trace level
allow all cached security information for a user to be cleared.
Therefore, you must grant appropriate access to the following resource profile:
Class: SAG Server: ETBCIS Service: SECURITY-CMD
The CIS commands SHUTDOWN CONVERSATION and SHUTDOWN SERVICE
require the authorization to use the specified Class/Server/Service triplet and to use CIS commands.
See Overview of EntireX Security and Writing Security Exits.
The Broker was restarted with the attribute
NEW-UOW-MESSAGES=NO.
This action will allow
only consumption of UOWs to occur after Broker restart. Therefore, after the
persistent store capacity has decreased to an acceptable level, the Broker
administrator can issue the CIS command to allow new UOW messages in the broker.
See ALLOW-NEWUOWMSGS.
The Broker has been executing for a period of time when the Broker
administrator notices that the persistent store is nearly at capacity. As a
preventive action, the Broker administrator can issue the CIS command to
forbid new UOW messages. See FORBID-NEWUOWMSGS.
This action will cause only consumption of UOWs to occur in the Broker.
Thereafter, when the persistent store capacity has been reduced to an
acceptable level, the Broker administrator can issue the CIS command to
allow new UOW messages in the Broker. See ALLOW-NEWUOWMSGS.