Writing Applications: Command and Information Services

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:

Accessing the Services

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.

Basic Rules

Several basic rules for command as well as information services are described here.

Field Values

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

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:
  • BROKER
  • CLIENT
  • CMDLOG-FILTER
  • CONVERSATION
  • NET
  • PARTICIPANT
  • POOL-USAGE
  • PSF
  • PSFADA
  • PSFCTREE
  • PSFDIV
  • RESOURCE-USAGE
  • SECURITY
  • SERVER
  • SERVICE
  • SSL
  • STATISTICS
  • TCP
  • TRANSPORT
  • UOW-STATISTICS
  • USER
  • WORKER
  • WORKER-USAGE

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.

Accessing Information Services

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.

Examples of Selection Criteria

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 ]

Tips

  • 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

Accessing Command 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

Tips

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

Security with Command and Information Services

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.

Full Command and Information Services

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:

  • Full Command Service 
    Class: SAG Server: ETBCIS Service: CMD
  • Full Information Service 
    Class: SAG Server: ETBCIS Service: INFO

Limited Information Services

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:

  • Limited Information Service 
    Class: SAG Server: ETBCIS Service: USER-INFO

Protecting Specific Options

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:

  • Full Command Service (Shut Service option) 
    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:

  • Full Command Service (PARTICIPANT-SHUTDOWN option) 
    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:

  • Full Command Service (SECURITY-CMD option) 
    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.

Examples of Command Service

Example 1: ALLOW-NEWUOWMSGS

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.

Example 2: FORBID-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.