Quick Reference |
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:
See also Broker ACI Fields.
Function Name | Applicable Participant | Logon Required (1) | User ID Required (2) | Minimum API Version | |||
---|---|---|---|---|---|---|---|
Client | Server | Publisher | Subscriber | ||||
CONTROL_PUBLICATION
|
X | X | X | X | 8 | ||
DEREGISTER
|
X | X | 1 | ||||
EOC
|
X | X | X | 1 | |||
KERNELVERS
|
X | X | X | X | X | 4 | |
LOGOFF
|
X | X | X | X | X | X | 2 |
LOGON
|
X | X | X | X | X | 2 | |
RECEIVE
|
X | X | (3) | X | 1 | ||
RECEIVE_PUBLICATION
|
X | X | X | 8 | |||
REGISTER
|
X | X | 1 | ||||
REPLY_ERROR
|
X | X | X | 8 | |||
SEND
|
X | X | (3) | X | 1 | ||
SEND_PUBLICATION
|
X | X | X | 8 | |||
SETSSLPARMS
|
X | X | X | X | 6 | ||
SUBSCRIBE
|
X | X | X | 8 | |||
SYNCPOINT
|
X | X | X(3) | X | 3 | ||
UNDO
|
X | X | X | X | 2 | ||
UNSUBSCRIBE
|
X | X | X | 8 | |||
VERSION
|
X | X | X | X | 2 |
(1) | Logon is a prerequisite for
issuing this command. See LOGON .
|
(2) | User ID is a prerequisite for issuing this command. |
(3) | The following functions
require a logon when used with units of work:
RECEIVE , SEND ,
SYNCPOINT .
|
This function is used to control a publication.
Option | Description |
---|---|
BACKOUT
|
|
COMMIT
|
|
QUERY
|
Used by the publisher, it returns the status of the publication
specified by the
PUBLICATION-ID .
|
SETUSTATUS
|
Used by the publisher, it updates the optional application-specific user status of the specified publication that is in received status. |
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
.
Option | Description |
---|---|
IMMED |
To execute a immediate deregistration, use
IMMED .
The service is removed immediately; an error code informs partners in existing
conversations of this removal. Any active UOW is backedout.
|
QUIESCE |
To execute a non-immediate deregistration, use
QUIESCE .
All active conversations are allowed to continue until an EOC is issued or a
conversation timeout occurs. The application that issues the
DEREGISTER function must remain active until all
existing conversations are ended. No new conversations are accepted.
|
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 (that is, its current status is received or delivered) the conversation will not be terminated until the UOW is either committed, backedout, cancelled, or timedout. See Broker UOW Status Transition.
To terminate all conversations initiated by the participant, use
CONV-ID
.
To terminate all conversations for a particular service, use
CONV-ID
,
SERVER-CLASS
,
SERVER-NAME
and/or SERVICE
.
Option | Description |
---|---|
CANCEL |
To inform the partner that the EOC is due to an unexpected
event, use CANCEL .
|
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 API-TYPE
and API-VERSION
for client and server | publish and subscribe). Platform and version information is returned in the
error text.
Option | Description |
---|---|
CHECKSERVICE
|
If option is set to
CHECKSERVICE ,
the command will determine whether a specified
SERVICE
is currently registered to the Broker.
|
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.
Value | Description |
---|---|
Y | Software AG-supplied security (SECURITY=YES in the Broker attribute file).
|
U | User-written security (SECURITY=YES in the Broker attribute file).
|
N | SECURITY=NO in the Broker attribute file.
|
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 Timeout Parameters for client and server | publish and subscribe.
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 (deprecated) 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
is set in the broker attribute
file.
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.
Option | Description | Note |
---|---|---|
ANY |
Used with the RECEIVE function to indicate that the RECEIVE will
be satisfied by any message, whether part of a UOW or not.
|
|
LAST |
To retrieve the last (most recent) message in a conversation,
use LAST .
|
With this option,
WAIT must
be set to "NO" or not specified.
|
MSG |
To indicate that the RECEIVE will be satisfied only by a message
that is not part of a UOW, use MSG .
See also Broker UOW Status Transition.
|
|
NEXT |
To retrieve the next unprocessed request or message in a
conversation, use NEXT .
|
|
PREVIEW |
To retrieve the next unprocessed request or message in a
conversation without deleting the previous message or moving the READ pointer,
use PREVIEW , which
excludes using units of work.
|
|
SYNC |
To receive only messages that are part of a UOW,
use SYNC .
See also Broker UOW Status Transition.
|
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
to acknowledge the publication.
ACI Field | Description |
---|---|
RECEIVE-LENGTH
|
This field is required. |
WAIT
|
You can specify a WAIT time to wait for a new
publication.
|
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 Attributes,
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 attribute file.
Option | Description |
---|---|
ATTACH |
To register an attach service, use
ATTACH . An
attach service cannot be requested by a client. Its function is to make
available a service that cannot otherwise be scheduled.
|
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
CONV-ID
only.
Only
WAIT=NO
is
allowed.
The conversation is not allowed to contain units of work.
Option | Description |
---|---|
EOC |
To end the conversation after the REPLY_ERROR function, use
EOC .
|
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.
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
.
Option | Description | Note |
---|---|---|
COMMIT |
Use COMMIT to indicate
that the UOW being sent is complete and can now be delivered to the intended
receiver, which can be either client or server.
|
|
EOC |
To end the conversation after the SEND , use
EOC .
|
WAIT must
be "NO" or not specified.
|
HOLD |
To hold SEND data in a queue, use
HOLD . The
data is released by a SEND without a HOLD.
|
WAIT must
be "NO" or not specified.
|
SYNC |
Client and server can send a message as part of a unit of work
(UOW), using SYNC .
|
WAIT must
be "NO" or not specified.
|
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
.
If SEND_PUBLICATION,OPTION=COMMIT
is used, the option is specified on the final
SEND_PUBLICATION
in the sequence.
Option/ ACI Field | Description |
---|---|
OPTION=COMMIT
|
Required to complete a publication if the function
CONTROL_PUBLICATION is not
used.
|
PUBLICATION-ID=NEW
|
Required to start a new publication. |
SEND-LENGTH
|
Required. |
This function is used by clients and servers to set the SSL parameters. It can be called whenever the transport method SSL is available.
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 Running Broker with SSL or TLS Transport under z/OS | UNIX | Windows.
This function is used to request EntireX Broker to subscribe to a
specific topic. The
Topic-specific Attributes under Broker Attributes contains parameters that specify the behavior of the
topic. If Broker runs with the setting
SECURITY=YES
in the Broker attribute file, the user must be successfully authenticated by
EntireX Broker and also authorized to subscribe to the specific topic.
The TOPIC
name must be defined in the Broker attribute file.
Option | Description |
---|---|
DURABLE |
If durable is specified within the SUBSCRIBE command, users need
to subscribe only once to a topic. The subscription is retained after the user
issues a logoff command or if the subscriber has timed out. Similarly, the
subscription remains if Broker is restarted. All publications necessary to meet
subscription requirements are also retained. If a subscriber no longer wishes
to subscribe to a topic, it must issue an
UNSUBSCRIBE command;
otherwise the subscription remains valid until the subscription expiration time
has passed.
Durable subscription requires the administrator to configure the persistent store. See Concepts of Persistent Messaging. In addition, the topic must be specified as durable within the Topic-specific Attributes under Broker Attributes. |
ALLOW-DURABLE
is a topic-specific attribute 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
attribute.
This function allows you to manage units of work (UOWs), both persistent and non-persistent, that have been sent or received. See Using Persistence and Units of Work.
SYNCPOINT is used with the OPTION
field.
The UOWID
parameter is required and normally limits the request
to a specified UOW. For example:
SYNCPOINT OPTION=COMMIT,UOWID=n SYNCPOINT OPTION=BACKOUT,UOWID=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 (that is, if one is
committed, both are committed) by specifying
UOWID=BOTH
. For
example:
SYNCPOINT OPTION=COMMIT,UOWID=BOTH
UOWID=BOTH
can
also be used with BACKOUT
. This simply
backs out both UOWs in a single call instead of two separate calls:
SYNCPOINT OPTION=BACKOUT,UOWID=BOTH
Option | Description |
---|---|
BACKOUT |
Used by the sender, it causes the UOW
to be deleted, with a status of backedout. By the receiver, causes the UOW to be returned to its prior, unreceived state, with a status of accepted. The ADCOUNT
field is incremented. See also Broker UOW Status Transition.
|
CANCEL |
Used by the receiver, it causes the UOW
to be considered finished, with a status of cancelled. No further
processing of the UOW is possible. The sender can cancel the UOW if, and only
if, it is in accepted status. The following sequence of commands,
issued during recovery processing, allows the sender to remove any created but
undelivered UOWs:
|
COMMIT |
User by the sender, it indicates that the UOW has been completely built and can be made available for delivery, with a status of accepted. By the receiver, indicates that the UOW has been completely received, with a status of processed. No further processing of the UOW is possible. |
EOC |
With
UOWID=n ,
commits the UOW being created and ends the conversation.
|
EOCCANCEL |
With
UOWID=n ,
commits the UOW being created and cancels the conversation, that is, terminates
the conversation immediately.
|
DELETE |
With
UOWID=n ,
deletes the persistent status of the specified UOW. The UOW
must be logically complete (processed, cancelled,
timedout, backedout, discarded) and must have been
created by the caller.
|
LAST |
Returns the status of the last UOW sent by the caller. In addition,
SERVER-CLASS ,
SERVER-NAME
and SERVICE
details of the associated server are also returned. The
CONV-ID
can be included to qualify the request.
|
QUERY |
With
UOWID=n ,
returns the status of the specified UOW. In addition,
SERVER-CLASS ,
SERVER-NAME
and SERVICE
details of the associated server are also returned.
|
SETUSTATUS |
With
UOWID=n ,
updates the user status of the specified UOW.
|
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.
See Using Persistence and Units of Work.
Option | Description |
---|---|
HOLD |
To undo messages in HOLD status, use UNDO with
HOLD .
|
This function is used to cancel the subscription to a specific topic.
The fully specified topic name is required to execute the UNSUBSCRIBE
request.
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 API version supported by the stub and to Software AG support if problems occur.
The string was modified in version 8.2. Example:
EntireX Broker Stub XXXXXXXX Version=08.3.0.00, Highest API Supported=09
where | "XXXXXXXX" | is is the name of the stub, for example "CICSETB". |
Number | Option | Description |
---|---|---|
1 |
MSG
|
Used with a RECEIVE function to receive only a
message that is not part of a UOW.
|
2 |
HOLD
|
Used in conversational mode only. |
3 |
IMMED
|
Used with the DEREGISTER function to immediately
terminate all conversations for the specified server. All partners are informed
with an appropriate error code.
|
4 |
QUIESCE
|
Used with the DEREGISTER function to terminate a
server smoothly. Existing conversations are allowed to end normally; no new
conversations are accepted. The server is removed from the
"active" list. QUIESCE is the default option for the DEREGISTER
function.
|
5 |
EOC
|
Used with the SEND function to end the conversation
with the current message. It can be issued by either partner. The conversation
is not ended if an active UOW
has not yet been committed, that is, its status is received or
delivered. See Broker UOW Status Transition.
|
6 |
CANCEL
|
Used with the EOC
function to abort a conversation rather than terminate normally. The receiver
of a UOW can use
SYNCPOINT OPTION=CANCEL to interrupt processing and discard the UOW.
|
7 |
LAST
|
|
8 |
NEXT
|
Used with the RECEIVE function to retrieve the next
unprocessed request or message. The request or message is then considered
processed and can be accessed only with OPTION=LAST .
NEXT is the default
option for the RECEIVE function.
|
9 |
PREVIEW
|
Used with the RECEIVE function to retrieve the next
unprocessed request message without deleting the previous message or moving the
READ pointer. The previewed message will be retrieved again by the next RECEIVE
OPTION=NEXT .
|
10 |
COMMIT
|
|
11 |
BACKOUT
|
|
12 |
SYNC
|
On a SEND
function, indicates that the message is part of a UOW.
On a RECEIVE function,
indicates that the RECEIVE will be satisfied only by a message that is part of
a UOW.
|
13 |
ATTACH
|
Used with the REGISTER function to register an
attach server.
|
14 |
DELETE
|
Used with the SYNCPOINT function to delete the
persistent status information for the specified UOW.
|
15 |
EOCCANCEL
|
Used with the SYNCPOINT function to cancel the
conversation after committing a UOW.
|
16 |
QUERY
|
|
17 |
SETUSTATUS
|
|
18 |
ANY
|
Used with the RECEIVE function to indicate that the
RECEIVE will be satisfied by a message that is or is not part of a UOW.
|
19 | No longer used. | |
20 |
DURABLE
|
Used with the SUBSCRIBE function to establish a
durable subscription to a topic with attribute ALLOW-DURABLE=YES .
|
21 |
CHECKSERVICE
|
Use with the KERNELVERS function to check
if the specified service is active in EntireX Broker.
|
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 (O).
ACI Field | Function | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ADCOUNT
|
Rt | Rt | Rt | Rt | Rt | ||||||||||||||
API-TYPE
|
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq |
API-VERSION
|
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq Rt |
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq |
BROKER-ID
|
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | ||
CLIENT-UID
|
Rt | Rt | |||||||||||||||||
COMMITTIME
|
Rt | Rt | Rt | Rt | Rt | Rt | |||||||||||||
COMPRESSLEVEL
|
O Rt |
O Rt |
O Rt |
O Rt |
O | ||||||||||||||
CONV-ID
|
Rq | Rq | Rq | Rq | Rq Rt |
Rq | |||||||||||||
CONV-STAT
|
Rt | Rt | |||||||||||||||||
DATA-ARCH
|
O | O | O | O | O | ||||||||||||||
ENCRYPTION-LEVEL
|
O | O | O | O | |||||||||||||||
ENVIRONMENT
|
O | O | O | O | O | ||||||||||||||
ERROR-CODE
|
Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt |
ERRTEXT-LENGTH
|
O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O |
FORCE-LOGON
|
O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | ||||
FUNCTION
|
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq |
KERNELSECURITY
|
Rt | ||||||||||||||||||
LOG-COMMAND
|
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | |||
LOCALE-STRING
|
O | O | O | O | O | ||||||||||||||
MSG-ID
|
|||||||||||||||||||
NEWPASSWORD
|
O | O | O | ||||||||||||||||
PARTNER-BROKER-ID (deprecated)
|
O | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | Rt | |||
OPTION
|
O | O | O | O | O | O | O | O | O | O | O | O | O | Rq | O | ||||
PASSWORD
|
O | O | O | O | |||||||||||||||
PUBLICATION-ID
|
Rq Rt |
Rq | Rq Rt |
||||||||||||||||
RECEIVE-LENGTH
|
O | Rq | Rq | Rq | |||||||||||||||
RETURN-LENGTH
|
Rt | Rt | Rt | Rt | |||||||||||||||
SECURITY-TOKEN
|
O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | O | |||
SEND-LENGTH
|
Rq | Rq | Rq | Rq | Rq | ||||||||||||||
SERVER-CLASS
|
Rq | O | O | Rq | O | O Rt |
Rt | ||||||||||||
SERVER-NAME
|
Rq | O | O | Rq | O | O Rt |
Rt | ||||||||||||
SERVICE
|
Rq | O | O | Rq | O | O Rt |
Rt | ||||||||||||
STORE
|
O | Rt | Rt | Rt | |||||||||||||||
TOKEN
|
O | O | O | O | O | O | O | O | Rq | Rq | Rq | Rq | Rq | O | |||||
TOPIC
|
Rq | Rq | Rq | Rq | Rq | ||||||||||||||
UOWID
|
O Rt |
O Rt |
Rq | ||||||||||||||||
UOWSTATUS
|
Rt | Rt | Rt | Rt | Rt | Rt | |||||||||||||
UOW-STATUS-PERSIST
|
O | ||||||||||||||||||
USER-DATA
|
O | Rt | Rt | O | |||||||||||||||
USER-ID
|
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | ||||
USTATUS
|
O Rt |
O Rt |
O Rt |
O Rt |
O Rt |
O Rt |
O Rt |
||||||||||||
UWSTAT-LIFETIME
|
O | ||||||||||||||||||
UWTIME
|
O | ||||||||||||||||||
WAIT
|
O | O | O | O |