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 and EntireX Broker ACI for Assembler | C | COBOL | Natural | PL/I | RPG.
Function Name | Applicable Participant | Logon Required (1) | User ID Required (2) | Minimum API Version | |
---|---|---|---|---|---|
Client | Server | ||||
DEREGISTER |
X | X | 1 | ||
EOC
|
X | X | X | 1 | |
GET‑MESSAGE‑ID
|
X | X | X | 11 | |
KERNELVERS |
X | X | X | 4 | |
LOGOFF |
X | X | X | X | 2 |
LOGON
|
X | X | X | 2 | |
RECEIVE |
X | X | (3) | X | 1 |
REGISTER |
X | X | 1 | ||
REPLY_ERROR
|
X | X | X | 8 | |
SEND
|
X | X | (3) | X | 1 |
SETSSLPARMS
|
X | X | 6 | ||
SYNCPOINT |
X | X | X(3) | X | 3 |
UNDO
|
X | X | X | X | 2 |
VERSION |
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 by a server application to deregister a service
from EntireX Broker. Assigned resources are deallocated. To remove multiple
services, specify either
SERVER‑CLASS
,
SERVER‑NAME
and/or SERVICE
.
Option | Description |
---|---|
IMMED |
To execute an 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 clients and servers to generate a MESSAGE‑ID
for a subsequent SEND
.
GET-MESSAGE-ID
makes it possible to access the MESSAGE-ID
before sending it.
API function SEND
with field USE‑SPECIFIED‑MESSAGE‑ID
set to 1 is used to send the message with the previously generated MESSAGE-ID
.
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
). 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).
|
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
,
RECEIVE
or
DEREGISTER
has been
executed. It releases all resources used by the application immediately rather
than waiting until they time out (see Timeout Parameters).
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. See Authentication.
An Explicit Logon is normally the first function.
LOGON
is normally the first function.
In addition to the user ID, the LOGON
optionally transmits the password, new password and SECURITY‑TOKEN
to authenticate itself, provided SECURITY=YES
is set in the broker attribute file.
Starting with ACI version 12, long passwords are supported up to a maximum length of 65535 bytes, containing upper and lowercase characters, digits, or any special characters.
Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID
, PASSWORD
, LONG-PASSWORD-LENGTH
, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
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 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.
Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID
, PASSWORD
, LONG-PASSWORD-LENGTH
, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
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, for example 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
.
If SEND
is the first call by a client 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 client.
This is because an Implicit Logon is being performed.
Providing user ID and password in ACI-based Programming is described under Broker ACI fields USER‑ID
, PASSWORD
, LONG-PASSWORD-LENGTH
, and the COBOL Example using Long Password.
For user ID and password handling with RPC clients, refer the documentation of the wrapper in use; see EntireX Wrappers in the Designer documentation.
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 only available on platforms where the broker stub directly supports SSL/TLS transport. See Transport: Broker Stubs and APIs It is used by ACI clients and ACI servers to set the SSL parameters. ACI-based clients or servers are always SSL clients. 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 SSL/TLS and Certificates with EntireX.
To use SSL
See Using the Broker ACI with SSL/TLS (Assembler | C | COBOL | Java | Natural | PL/I).
Make sure the SSL server to which the ACI application (client or server) connects is prepared for SSL connections as well.
The SSL server can be EntireX Broker or Broker SSL Agent.
See:
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 committed UOW sent by the caller. In addition,
SERVER‑CLASS ,
SERVER‑NAME ,
SERVICE and
CONV‑ID are also returned.
|
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 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 | Used with Function | Description | Note |
---|---|---|---|---|
1 | MSG |
RECEIVE |
Receive only a message that is not part of a UOW. | |
2 | HOLD |
SEND |
Places the messages in a HOLD queue. Messages are released by a SEND without HOLD .
|
Used in conversational mode only. |
UNDO |
Releases all previously held messages. | |||
LOGOFF |
The conversation is not ended, even though the user is logged off. | |||
3 | IMMED |
DEREGISTER |
Immediately terminate all conversations for the specified server. All partners are informed with an appropriate error code. | |
4 | QUIESCE
|
DEREGISTER |
Terminate a server smoothly. Existing conversations are allowed to end normally; no new conversations are accepted. The server is removed from the "active" list. | Default option for this function. |
5 | EOC |
SEND |
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 |
EOC |
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 |
RECEIVE |
Used in conversational mode to retrieve the last (most recent) message. | |
SYNCPOINT |
Returns the status of the last committed UOW sent by the caller. | |||
8 | NEXT |
RECEIVE |
Retrieve the next
unprocessed request or message. The request or message is then considered
processed and can be accessed only with OPTION=LAST .
|
Default option for this function. |
9 | PREVIEW
|
RECEIVE |
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 |
SYNCPOINT |
Commit the
active UOW.
|
|
SEND |
Commit the active UOW. | |||
11 | BACKOUT
|
SYNCPOINT |
|
|
12 | SYNC |
SEND |
Indicates that the message is part of a UOW. | |
RECEIVE |
RECEIVE will be satisfied only by a message that is part of
a UOW.
|
|||
13 | ATTACH |
REGISTER |
Register an attach server. | |
14 | DELETE |
SYNCPOINT |
Delete the persistent status information for the specified UOW. | |
15 | EOCCANCEL
|
SYNCPOINT |
Cancel the conversation after committing a UOW. | |
16 | QUERY |
SYNCPOINT |
Query the status of a UOW. | |
17 | SETUSTATUS
|
SYNCPOINT |
Updates the user status of the specified UOW. | |
18 | ANY |
RECEIVE |
Indicate that the RECEIVE will be satisfied by a message that is or is not part of a UOW.
|
|
19 | No longer used. | |||
20 | No longer used. | |||
21 | CHECKSERVICE
|
KERNELVERS |
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 | ||||||||||||
API‑TYPE |
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 |
BROKER‑ID |
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | |
CLIENT‑UID |
Rt | |||||||||||||
COMMITTIME |
Rt | Rt | Rt | |||||||||||
COMPRESSLEVEL |
O Rt |
O Rt |
O | |||||||||||
CONV‑ID |
Rq | Rq | Rq | Rq | Rq Rt |
Rq | ||||||||
CONV‑STAT |
Rt | |||||||||||||
CORRELATION‑ID |
O | O | ||||||||||||
DATA‑ARCH |
O | O | O | |||||||||||
ENVIRONMENT |
O | O | O | |||||||||||
ERROR‑CODE |
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 |
FORCE‑LOGON |
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 |
KERNELSECURITY |
Rt | |||||||||||||
LOG‑COMMAND |
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | |||
LOCALE‑STRING |
O | O | O | |||||||||||
LONG-PASSWORD-LENGTH |
O | O | O | |||||||||||
LONG-NEWPASSWORD-LENGTH |
O | O | O | |||||||||||
MESSAGE‑ID |
O | O | Rt | |||||||||||
NEWPASSWORD |
O | O | O | |||||||||||
OPTION |
O | O | O | O | O | O | O | O | O | O | ||||
PASSWORD |
O | O | O | |||||||||||
RECEIVE‑LENGTH |
O | Rq | Rq | |||||||||||
RETURN‑LENGTH |
Rt | Rt | Rt | |||||||||||
SECURITY‑TOKEN |
O | O | O | O | O | O | O | O | O | O | O | |||
SEND‑LENGTH |
Rq | Rq | Rq | |||||||||||
SERVER‑CLASS |
Rq | O | O | Rq | O | O Rt |
||||||||
SERVER‑NAME |
Rq | O | O | Rq | O | O Rt |
||||||||
SERVICE |
Rq | O | O | Rq | O | O Rt |
||||||||
STORE |
O | Rt | ||||||||||||
TOKEN |
O | O | O | O | O | O | O | O | O | |||||
UOWID |
O Rt |
O Rt |
Rq | |||||||||||
UOWSTATUS |
Rt | Rt | Rt | Rt | ||||||||||
USE‑SPECIFIED‑CORRELATION‑ID |
O | |||||||||||||
USE‑SPECIFIED‑MESSAGE‑ID |
O | |||||||||||||
UOW‑STATUS‑PERSIST |
O | |||||||||||||
USER‑DATA |
O | Rt | Rt | O | ||||||||||
USER‑ID |
Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | Rq | |||
USTATUS |
O Rt |
O Rt |
O Rt |
O Rt |
||||||||||
UWSTAT‑LIFETIME |
O | |||||||||||||
UWTIME |
O | |||||||||||||
WAIT |
O | O | O |
This section covers the following topics:
With ACI version 11 and above, all messages sent to the broker are given a unique message ID. This message ID is useful for
tracking individual messages. PSTORE-VERSION
=5
is required to save and restore message IDs of persistent data.
Under UNIX and Windows, the message ID is a Universally Unique Identifier (UUID). On mainframe platforms, the value consists of CPU ID and clock (machine instructions STCK or STCKE).
ACI functions SEND
and GET‑MESSAGE‑ID
generate message IDs. ACI version 11 must be defined. No additional programming in the application is needed.
The broker stub generates message IDs and saves the values in the field MESSAGE‑ID
. The message ID is returned immediately with function GET‑MESSAGE‑ID
, or after processing of function SEND
(without wait).
If the application receives a message from the broker - either by function SEND
(with wait) or function RECEIVE
(with or without wait) - the field MESSAGE‑ID
contains the message ID of the received message.
If the application receives a message from the broker by function SEND
with wait, the message ID of the sent message is returned in field CORRELATION‑ID
.
If a server receives a message from a client by function RECEIVE
(with or without WAIT
) and sends back a message as response to the client, we recommend moving the message ID of the received message to field
CORRELATION-ID
and to set 1 into field USE-SPECIFIED-CORRELATION-ID
before sending the message. This correlates the response message to the received message.
If a client or a server has generated a message ID with ACI function GET-MESSAGE-ID
and wants to use this message ID for the function SEND
(with or waithout WAIT
), the field USE-SPECIFIED-MESSAGE-ID
must be set to 1.
The broker stub generates a new message ID if client or server uses function SEND
and did not issue function GET-MESSAGE-ID
before and set field USE-SPECIFIED-MESSAGE-ID
to 0.
See fields MESSAGE‑ID
, CORRELATION‑ID
and USE‑SPECIFIED‑MESSAGE‑ID
under Broker ACI Fields.
First broker call. | |
Second broker call. Unique message ID "e05d760c..." is generated automatically. No additional programming is required. | |
Server receives message with ID generated by second broker call. In this simple scenario, no correlation ID is set. |
First broker call. | |
Second broker call. Unique message ID "e05d760c..." is generated automatically. | |
Server receives message with ID generated by second broker call. A correlation ID is not yet set. The server sets USE-SPECIFIED-CORRELATION-ID to 1 and moves the received message ID to the field CORRELATION-ID .
|
|
Third broker call. Another unique message ID "88de67aa..." is generated. | |
Client receives message with ID generated by third broker call. The connection to the original message is established by means of the correlation ID provided by the broker. |
In this scenario a message is given a unique ID but is not sent immediately.
A sample scenario would be financial transactions where the message ID needs to be logged before the actual message is sent.
Function GET-MESSAGE-ID
generates a unique message ID. The application writes the message ID to the log file.
When the message is finally sent, the SEND
request requires the flag USE-SPECIFIED-MESSAGE-ID="1"
.
This ensures no new message ID is generated; instead the unique ID created by function GET-MESSAGE-ID
is used. This unique ID makes it easier to identify the message at a later date.
Function GET-MESSAGE-ID generates a unique message ID. The application may store this ID in a log file.
|
|
Broker call. A message is sent to the broker with the message ID specified earlier with the command GET-MESSAGE-ID. |