Quick Reference |
This document covers the following topics:
See also Broker ACI Functions and EntireX Broker ACI for Assembler | C | COBOL | Natural | PL/I | RPG.
The ACI field formats are alphanumeric, binary, or integer and include the number of bytes. For example:
Format | Description |
---|---|
A8, A16, A32 | Alphanumeric (A-Z, 0-9, underscore, hyphen). Other characters are currently possible, but we cannot guarantee that these will work consistently across all platforms in future versions. Do not use dollar, percent, period or comma. |
B16, B32 | Binary |
Integer (unsigned) |
The terms "null value" or "nothing specified" used for a field mean blank for alphanumeric formats and zero for integer formats.
The ACI fields are described below in alphabetical order.
ACI Field | Format | Possible Values |
API Vers |
I/O | Description | ||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ADAPTER‑ERROR |
A8 | 2 | O | Filled by Broker with the transport error as supplemental diagnostic data. | |||||||||||||||||||||||||||||||||||||||||||||||||
ADCOUNT |
I4 | 2 | O | A count of the number of times an attempt was made to deliver a UOW. The count is incremented if a UOW is backed out or timed out. | |||||||||||||||||||||||||||||||||||||||||||||||||
API‑TYPE |
B1 | bits | 1 | I | Required for all ACI functions. See API-TYPE and API-VERSION .
|
||||||||||||||||||||||||||||||||||||||||||||||||
API‑VERSION |
I1 | 1-13 | 1 | I | Required for all ACI functions. | ||||||||||||||||||||||||||||||||||||||||||||||||
BROKER‑ID |
A32 | string | 1 | I | ID of the broker instance. Required for all ACI
functions except VERSION .
The Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
CLIENT‑ID |
I4 | 1-2147483647 | 9 | O | Returns to a server application the unique instance number of a client application. | ||||||||||||||||||||||||||||||||||||||||||||||||
CLIENT‑UID |
A32 | string | 2 | O | Applies only to client/server communication
model.
When a server issues a
See Authentication (z/OS only). Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
COMMITTIME |
A17 | YYYY MMDD HHMM SSms (millisecs.) |
7 | O | Time when UOW was committed. | ||||||||||||||||||||||||||||||||||||||||||||||||
COMPRESSLEVEL |
A1 | 0-9 or Y | N | 7 | I | Compression level. See Data Compression. The following values are possible:
|
||||||||||||||||||||||||||||||||||||||||||||||||
CONV‑ID |
A16 | string | 1 | I/O | A unique ID assigned to each
conversation by EntireX Broker. Client and server must include the
CONV-ID in their
communications. Client and server can also specify the indicated textual values
(capitals) in order to indicate to Broker the expected status of the
conversation. Messages for the conversation are taken from the queue on a
first-in, first-out basis. See Conversational and Non-conversational Mode.
|
||||||||||||||||||||||||||||||||||||||||||||||||
CONV‑STAT |
I1 | 1 | 2 | 3 | 2 | O | Conversation Status. See Managing Conversation Contexts.
|
||||||||||||||||||||||||||||||||||||||||||||||||
CORRELATION‑ID |
A64 | string; padded with hex zero | 11 | O | Output value for function SEND if a message has been received.
The CORRELATION-ID is the MESSAGE‑ID that was used for the sent message. See Unique Message ID under Broker ACI Functions.
|
||||||||||||||||||||||||||||||||||||||||||||||||
CREDENTIALS‑TYPE |
I1 | 0 | 9 | O | Determines the credentials type to be used to authenticate a user.
|
||||||||||||||||||||||||||||||||||||||||||||||||
DATA‑ARCH |
I1 | 4 | I | Architecture code. For future use. | |||||||||||||||||||||||||||||||||||||||||||||||||
ENVIRONMENT |
A32 | string | 1 | I |
Using the character conversion approach Translation User Exit, an ACI programmer can provide additional information to their translation exit through the The field cannot be used for any other character conversion approaches and must be empty if a method other than translation user exit is used. |
||||||||||||||||||||||||||||||||||||||||||||||||
ERROR‑CODE |
A8 | 1 | O | Returns an error code to the caller. The application should check the contents of this field at the completion of every Broker function. See Error Handling. The first four digits represent the error class; the next four digits represent the error number; see also Error Messages and Codes. | |||||||||||||||||||||||||||||||||||||||||||||||||
ERRTEXT‑LENGTH |
I4 | 0-40 | 0-255 | 1 | 9 | I | Length of the error text buffer in bytes. See Call Format for
Assembler |
C |
COBOL |
Natural |
PL/I |
RPG.
If there are fewer than 40 bytes, the error text may be truncated. A value of 0 (zero) means no error text. Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
FORCE‑LOGON |
A1 | Y | N | 6 | I | Override the AUTOLOGON feature of the Broker. See AUTOLOGON .
|
||||||||||||||||||||||||||||||||||||||||||||||||
FUNCTION |
I1 | 1-22 | 1 | I |
|
||||||||||||||||||||||||||||||||||||||||||||||||
KERNELSECURITY |
A1 | Y | N | U | 7 | I/O |
Notes
|
||||||||||||||||||||||||||||||||||||||||||||||||
LOCALE‑STRING |
A40 | string | 4 | I | The optional locale string contains a codepage name and tells the broker the encoding of the data.
The application must ensure the encoding of the data matches the locale string.
The broker stub itself does not convert your application data.
The application's data is shipped and received as given.
Under the Windows operating system:
Under all other operating systems:
Enable character conversion in the broker by setting the service-specific attribute |
||||||||||||||||||||||||||||||||||||||||||||||||
LOG‑COMMAND |
I1 | 0 | 1 | 9 | I |
Components that communicate with Broker can trigger command logging
by setting this field. By default, command logging is based on the command log
filters set in the kernel. You may override these kernel settings
programmatically by setting this Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
LONG‑BROKER‑ID‑LENGTH |
I4 | 0-2147483647 | 10 |
Length of long-broker-id value.
If the value is non-zero, specify the value of long-broker-id
directly after the ACI control block. The long-broker-id value
overrides any entry for ACI field BROKER-ID .
With the long-broker-id you can now specify numeric IPv6 addresses. Some sample values:
The IP address is enclosed in square brackets or parentheses. |
|||||||||||||||||||||||||||||||||||||||||||||||||
LONG‑NEWPASSWORD‑LENGTH |
I4 | 0-65535 | 12 | I | Length of long-newpassword value.
If the value is non-zero, specify the value of long-newpassword directly after the ACI control block after second optional value long-password. The long-newpassword value is the third optional value after the ACI control block. With this value you can specify long new passwordsup to 64 KB in length. The value of ACI field The current long password can be changed only when the client or server authenticates itself, see Changing your Password under Writing Applications using EntireX Security.
This occurs on the first Broker ACI function (can be |
||||||||||||||||||||||||||||||||||||||||||||||||
LONG‑PASSWORD‑LENGTH |
I4 | 0-65535 | 12 | I | Length of long-password value.
If the value is non-zero, specify the value of long-password directly after the ACI control block after first optional value long-broker-id.
The value of long-password is transmitted to the Broker to check the authentication of the application.
See Authentication and The long-password value is the second optional value after the ACI control block. With the long-password you can specify long passwords up to 64 KB in length. The value of ACI field |
||||||||||||||||||||||||||||||||||||||||||||||||
MESSAGE‑ID |
A64 | string; padded with hex zero | 11 | I/O | Input value for function SEND if USE‑SPECIFIED‑MESSAGE‑ID is 1.
The supplied MESSAGE-ID is used as unique identification for the message in the send buffer.
Output value of function If a message has been received, this field returns the corresponding This See Unique Message ID under Broker ACI Functions. |
||||||||||||||||||||||||||||||||||||||||||||||||
NEWPASSWORD |
B32 | Can contain binary data. | 2 | I | The current password can be changed only when the client or server authenticates itself. See Changing your Password under Writing Applications using EntireX Security.
This occurs on the first Broker ACI function (can be LOGON ) and requires the application to assign to the Broker ACI fields
PASSWORD and NEWPASSWORD .
Use of control block field |
||||||||||||||||||||||||||||||||||||||||||||||||
OPTION |
I1 | 0-21 | 1 | I | Provides additional information that modifies the behavior of the Broker ACI Functions.
|
||||||||||||||||||||||||||||||||||||||||||||||||
PASSWORD |
A32 | Can contain binary data. | 1 | I | Specifies a password to be transmitted to the Broker to check the
authentication of the application. See Authentication and FORCE-LOGON under Writing Applications using EntireX Security.
Use of control block field |
||||||||||||||||||||||||||||||||||||||||||||||||
PTIME |
A8 | 2 | I | Not used by EntireX Broker. | |||||||||||||||||||||||||||||||||||||||||||||||||
RECEIVE‑LENGTH |
I4 | Binary. | 1 | I/O | Specifies the length of receive buffer, in bytes. The maximum
length depends on the transport method:
Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
RETURN‑LENGTH |
I4 | 1 | O | Length, in bytes, of the data returned. | |||||||||||||||||||||||||||||||||||||||||||||||||
SECURITY‑TOKEN |
B32 | binary | 1 | I/O | The contents of this field depend heavily on the implementation
of the security exits.
This field is utilized by EntireX Security. The application must
maintain If EntireX Security is not implemented, and you choose to write your
own security exits, you can transmit an initial value to your security exit as
a credential that is used to calculate the actual security token. After an
application's authenticity has been verified by the security exits, the
|
||||||||||||||||||||||||||||||||||||||||||||||||
SEND‑LENGTH |
I4 | binary | 1 | I/O | Specifies the length of data being sent, in bytes. The maximum
length depends on the transport method:
Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
SERVER‑CLASS SERVER‑NAME SERVICE |
A32 each | string, case-sensitive | 1 | I/O | A client uses these fields to identify the service that it
requires. A server uses this field to offer a service.
Using all three fields allows you to organize servers, making them easier to identify, monitor, and maintain. Servers can be organized into server-classes, with each server providing a number of different services. Each service must be defined in the attribute file (see Service-specific Attributes). The service fields are required with
Note: |
||||||||||||||||||||||||||||||||||||||||||||||||
STATUS |
I1 | 2 | I/O | Not used by EntireX Broker. | |||||||||||||||||||||||||||||||||||||||||||||||||
STORE |
I1 | 0 | 1 | 2 | 2 | I/O | Persistence or non-persistence of a UOW. Used with the first SEND function for a UOW to specify whether the UOW is persistent or not.
Once established, the persistence of a UOW cannot be altered.
|
||||||||||||||||||||||||||||||||||||||||||||||||
TOKEN |
A32 | string, case-sensitive | 1 | I | Optionally identifies the caller and, when used, is required for all Broker ACI functions except VERSION . See USER-ID and TOKEN .
|
||||||||||||||||||||||||||||||||||||||||||||||||
UOW‑STATUS‑PERSIST |
0 - 255 | 3 | I | The value of the
UOW-STATUS-PERSIST field is used as a multiplier to calculate the lifetime for
the persistent status of a UOW. The value is multiplied by the value of the broker attribute
UWTIME . The value 255 can be specified to indicate no persistent status.
|
|||||||||||||||||||||||||||||||||||||||||||||||||
UOWID |
A16 | 3 | I/O | A unique identifier for a UOW. The value is returned on the first SEND or RECEIVE command within a
UOW; the value must be provided on all subsequent SEND , RECEIVE and
SYNCPOINT commands related to the same UOW. Client and server can also specify the
indicated textual value (capitals) in order to indicate to Broker the following:
|
|||||||||||||||||||||||||||||||||||||||||||||||||
UOWSTATUS |
I1 | 3 | O | Contains the status of a UOW. EntireX Broker returns the UOWSTATUS field to the calling application in order to provide information about the condition of the specified UOW.
With the exception of
|
|||||||||||||||||||||||||||||||||||||||||||||||||
USE‑SPECIFIED‑CORRELATION-ID |
I1 | 0 | 1 | 11 | I | Only used for function SEND .
|
||||||||||||||||||||||||||||||||||||||||||||||||
USE‑SPECIFIED‑MESSAGE‑ID |
I1 | 0 | 1 | 11 | I | Only used for function SEND .
|
||||||||||||||||||||||||||||||||||||||||||||||||
USER‑DATA |
B16 | binary | 2 | I/O | Conversation User Data. See Managing Conversation Contexts. | ||||||||||||||||||||||||||||||||||||||||||||||||
USER‑ID |
A32 | string, case-sensitive | 1 | I | Identifies the caller and is required for all Broker ACI functions except VERSION . See USER-ID and TOKEN .
|
||||||||||||||||||||||||||||||||||||||||||||||||
USTATUS |
A32 | string | 3 | I/O | User-defined information about a unit of work (UOW). It can be
transmitted on a SEND or SYNCPOINT function and is returned to
applications that query the status of the UOW or issue function RECEIVE .
To update the USTATUS field, use function SYNCPOINT OPTION=SETUSTATUS .
|
||||||||||||||||||||||||||||||||||||||||||||||||
UWSTAT‑LIFETIME |
A8 | nS | nM | nH | nD | 8 | I | Add value for persistent status lifetime in the client and server communication model. See Writing Client and Server Applications.
This field is used to calculate the lifetime of the
UOW status. The value of this field determines how long the UOW status is
to be retained in the persistent store after the UOW is processed or timed out
if it is not processed. This is an alternative to specifying
|
||||||||||||||||||||||||||||||||||||||||||||||||
UWTIME |
A8 | nS | nM | nH | nD | 3 | I | The lifetime of a UOW. The UOW exists until its lifetime expires or it is explicitly cancelled or backed out with SYNCPOINT OPTION=CANCEL or SYNCPOINT OPTION=BACKOUT .
If the UOW is not committed, backed out, or cancelled before its
|
||||||||||||||||||||||||||||||||||||||||||||||||
VARLIST‑OFFSET |
I4 | 0-2147483647 | 10 | I | For Software AG internal use only. | ||||||||||||||||||||||||||||||||||||||||||||||||
WAIT |
A8 | NO | YES | nS | nM | nH | 1 | I | When a WAIT value (other than NO ) is specified on a SEND or RECEIVE function,
the caller will wait for a reply until the message is received or the specified time limit has been reached. See Blocked and Non-blocked Broker Calls.
|