Version 8.0	SEARCH   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT

Programs written for EntireX Broker contain instructions that specify to the Broker which functions to perform. The function's behavior is controlled by the option value and other ACI fields.

This document covers the following topics:

• Overview Table

• Function Descriptions

• Option Descriptions

• Function: ACI Field Reference Table

See also Broker ACI Fields

Overview Table

Key

Function Descriptions

CONTROL_PUBLICATION

This function is used to control a publication.

DEREGISTER

This function is used by a server application to deregister a service from EntireX Broker. Assigned resources are de-allocated. To remove multiple services, specify either SERVER-CLASS, SERVER-NAME and/or SERVICE.

EOC

This function is used by a client or server and applies to conversational mode only. It is used to terminate one or more conversations. EntireX Broker accepts no additional SEND s for the conversation(s). The partner can receive requests and messages that were sent before the EOC was issued.

Although conversations are normally terminated by the client, the EOC function can be issued by either partner in a conversation. If an active UOW has not yet been committed - i.e., its current status is received or delivered - the conversation will not be terminated until the UOW is either committed, backedout, cancelled, or timedout.

• To terminate all conversations initiated by the participant, use CONV-ID=ANY.

• To terminate all conversations for a particular service, use CONV-ID=ANY, SERVER-CLASS, SERVER-NAME and/or SERVICE.

KERNELVERS

This function is used by any participant to determine the highest API-VERSION that is supported by the requested Broker. The highest API-VERSION that the Broker supports is returned in the API-VERSION field (see: client and server / publish and subscribe). Platform and version information is returned in the error text.

The KERNELSECURITY field returns one of the following values to indicate whether the kernel is running with security. These values are returned only for API version 7 or above.

LOCTRANS

This function is used by a client application to determine the location of an available instance of a server application. It determines the location in terms of the BROKER-ID and the actual SERVER-CLASS, SERVER-NAME and SERVICE when provided with a logical service name. See also Location Transparency with EntireX.

• The Broker ACI Control Block fields for BROKER-ID, SERVER-CLASS, SERVER-NAME and/or SERVICE must be empty.

• The send buffer contains the specification of the logical service or logical Broker in one of the following forms. SetName is optional. The keywords LOGSERVICE= and LOGBROKER= indicate whether to use a logical service or a logical Broker. See also the System Management Hub documentation.

  • LOGSERVICE=logicalService

    In this case DefaultSet is used as the SetName.

  • LOGSERVICE=logicalService,SetName.

  • LOGBROKER=logicalBroker

    In this case DefaultSet is used as the SetName.

  • LOGBROKER=logicalBroker,SetName.

• The receive buffer and error text buffer can be omitted.

LOCTRANS resolves the logicalService specification by

• finding the logicalService;

• extracting the SERVER-CLASS, SERVER-NAME and SERVICE definition and a list of BROKER-ID s;

• searching (via KERNELVERS) the first active and reachable EntireX Broker, using the retrieved list of BROKER-ID s;

• API version 8 and above: If the CHECKSERVICE option is specified, the search is further refined to check whether the resolved SERVER-CLASS, SERVER-NAME and SERVICE are currently registered with EntireX Broker.

If the search is successful, the BROKER-ID and SERVER-CLASS, SERVER-NAME and SERVICE values are available for the application in the corresponding Broker ACI Control Block fields.

LOCTRANS resolves the logicalBroker specification by

• searching (via KERNELVERS) the first active and reachable EntireX Broker, using the retrieved list of BROKER-IDs.

If the search is successful, the Broker ID is available for the application in the corresponding Broker ACI Control Block field. The SERVER-CLASS, SERVER-NAME and SERVICE values have to be supplied in the corresponding Broker ACI Control Block fields.

If Location Transparency is being used, LOCTRANS must be the first Broker call. We recommend you use a KERNELVERS call immediately after LOCTRANS to determine the correct Broker ACI version.

Note:
If the application is using SSL communication and Location Transparency, SETSSLPARMS should be called immediately following a LOCTRANS call (and before KERNELVERS). However, it is also possible to specify SSL parameters, using the System Management Hub, in which case SSLPARMS is not required. See Location Transparency Administration using System Management Hub under Windows | UNIX.

LOGOFF

This function is used by all application components before termination when no further Broker functions are to be issued.

LOGOFF should be issued after the application's last SEND, SEND_PUBLICATION, RECEIVE, RECEIVE_PUBLICATION, DEREGISTER or UNSUBSCRIBE has been executed. It releases all resources used by the application immediately rather than waiting until they time out (see: client and server / publish and subscribe).

LOGON

This function is used by all application components so that the application can establish communication with a particular instance of the Broker kernel.

Allows the client or server application to logon to EntireX Broker, which allocates the necessary structures to handle the new participant. If EntireX Broker is running in a secure environment (with SECURITY=YES in the attribute file), LOGON performs the authentication process.

LOGON is normally the first function unless a LOCTRANS function is issued first to determine the BROKER-ID.

In addition to the USER-ID, the LOGON optionally transmits the PASSWORD, NEWPASSWORD and SECURITY-TOKEN to authenticate itself, provided Security=YES in the Broker attribute file.

RECEIVE

This function is used by clients to receive incoming messages and by servers to receive incoming requests.

• You can specify a WAIT time, causing the RECEIVE to wait for the request or message that satisfies the operation.

• The RECEIVE-LENGTH field is required. It specifies the maximum length of data the caller can receive. A receive buffer of at least this length must be provided. The actual length of the message received is returned in the RETURN-LENGTH field.

RECEIVE_PUBLICATION

This function is used by subscribers to receive publications. If PUBLICATION-ID=NEW is specified, Broker will deliver the next publication in accepted status to the subscriber, if a publication is in accepted status. In the case of subsequent RECEIVE_PUBLICATION commands, a valid PUBLICATION-ID is used to receive any messages from a multi-message publication. See function CONTROL_PUBLICATION,OPTION=COMMIT to acknowledge the publication.

REGISTER

This function is used by servers to inform EntireX Broker that a service is available. The Broker obtains information about the service from the Broker attribute file, creates the appropriate environment, and makes the participant available as the specified SERVER-CLASS, SERVER-NAME and SERVICE

If REGISTER is the first call by a server when both AUTOLOGON and SECURITY are set to YES in the Broker attribute file, USER-ID and PASSWORD are required in order to authenticate and authorize the server. This is because an implicit LOGON is being performed.

The services being registered must be defined in the Broker attribute file.

REPLY_ERROR

This function is used by clients or servers to send an error message to the partner of the conversation. The error number is specified in the error code field. The sent message is delivered as an error text; the specified error number is delivered as an error code.

• The user must be logged on.

• The error number is a numeric 8-byte value and must start with 8 - e.g., 80010001. A zero error number will be rejected. These errors are user-definable and therefore not documented.

• The error message is provided in the send buffer and is limited to 40 bytes.

• Use the SEND-LENGTH field to specify the length of the error message.

• REPLY_ERROR can be used with a valid CONVERSATION-ID only.

• Only WAIT=NO is allowed.

• The conversation is not allowed to contain units of work.

SEND

This function is used by clients to send requests and by servers to send replies (messages). If a corresponding RECEIVE function issued by a partner application is outstanding, EntireX Broker forwards the request or message to that partner application. If not, EntireX Broker queues the request or message until a suitable RECEIVE is issued by a partner application. If no suitable RECEIVE is issued by a partner application, the request will timeout within the specified timeout period.

• You can specify a SEND with either of the following:

  • WAIT=YES | Value

    This causes an implicit RECEIVE to be generated and the SEND to wait for a reply. If a reply is expected, the SEND must pass the length of the receive buffer, in bytes, as the value of the RECEIVE-LENGTH parameter. The actual - not the specified - length of the reply is returned to the sender as the RETURN-LENGTH value.

  • WAIT=NO

    Choose WAIT=NO if you are only forwarding a request or message.

• Use the SEND-LENGTH field to specify the length of the request or message being sent. The specified number of bytes is transferred, starting at the beginning of the send buffer.

• The client starts a new conversation, using CONV-ID=NEW.

• The client can specify non-conversational mode, using CONV-ID=NONE.

• Include the SERVER-CLASS, SERVER-NAME and SERVICE if this is a new conversation or a non-conversational request.

• If you add the ENVIRONMENT parameter, its value is passed to the translation routine for the service.

• To transmit conversation-related data to the sending application, use USER-DATA.

SEND_PUBLICATION

This function is used by publishers to create publications for a specified topic. PUBLICATION-ID=NEW is used to create a new publication. In the case of a subsequent SEND_PUBLICATION, a valid PUBLICATION-ID is used when sending a multi-message publication. The publisher completes the publication either by specifying SEND_PUBLICATION,OPTION=COMMIT or using the function CONTROL_PUBLICATION,OPTION=COMMIT. If SEND_PUBLICATION,OPTION=COMMIT is used, the option is specified on the final SEND_PUBLICATION in the sequence.

SETSSLPARMS

This function is used by clients and servers to set the SSL parameters. It can be called whenever the transport method SSL is available.

If the application is using SSL communication, SETSSLPARMS should be the called immediately following an LOCTRANS.

Note:
However, it is also possible to specify SSL parameters using the System Management Hub, in which case SSLPARMS is not required. See Location Transparency Administration using System Management Hub under UNIX | Windows.

The SSL parameters are specified in the send buffer, (second parameter of the Broker ACI call). These SSL parameters are used and communication is performed if the Secure Sockets Layer is configured. See: z /OS | Windows | UNIX.

SUBSCRIBE

This function is used to request EntireX Broker to subscribe to a specific topic. The Broker attribute file contains parameters which specify the behavior of the topic. If Broker runs with the setting SECURITY=YES in the Broker attribute file, the user must be be successfully authenticated by EntireX Broker and also authorized to subscribe to the specific topic.

It is not possible to use a TOPIC name unless it is defined in the Broker attribute file.

ALLOW-DURABLE=YES is a topic-specified attribute parameter that determines whether a subscriber is allowed to perform a durable subscription to a topic. If users are allowed to durably subscribe to any topic, you must specify a value for the SUBSCRIBER-STORE parameter.

SYNCPOINT

This function allows you to manage units of work (UOW), both persistent and non-persistent, that have been sent or received.

SYNCPOINT is used with the OPTION field. The UOW-ID parameter is required and normally limits the request to a specified UOW. For example:

SYNCPOINT OPTION=COMMIT,UOW-ID=n

SYNCPOINT OPTION=BACKOUT,UOW-ID=n

In cases where a server receives a UOW and sends a different UOW, you can ensure that the two UOWs will be processed together (i.e., if one is committed, both are committed) by specifying UOW-ID =BOTH. For example:

SYNCPOINT OPTION=COMMIT,UOW-ID=BOTH

UOW-ID =BOTH can also be used with OPTION=BACKOUT. This simply backs out both UOWs in a single call instead of two separate calls:

SYNCPOINT OPTION=BACKOUT,UOW-ID=BOTH

UNDO

This function is used to remove messages that have been sent but not received. It can only be used with an existing conversation. When a message is undone, the conversation continues.

Note:
UNDO is not used in conjunction with Units of Work.

UNSUBSCRIBE

This function is used to cancel the subscription to a specific topic. The fully specified topic name is required to execute the UNSUBSCRIBE request.

VERSION

This function is used to return the version of the stub implementation in the receive buffer. This version string is useful to the application in determining the maximum version supported by the stub and to Software AG's support staff if problems occur.

Returns the maximum API-VERSION of the Broker stub being used.

Option Descriptions

Function: ACI Field Reference Table

The following table identifies the ACI fields that apply to each of the Broker functions. For a given function, an ACI field value may be a request field (RQ), and/or a reply field (RT). Optional fields are marked (OP).