Quick Reference

Broker ACI Fields

This document covers the following topics:

See also Broker ACI Functions and EntireX Broker ACI for Assembler | C | COBOL | Natural | PL/I | RPG.

Field Formats

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.

Field Descriptions

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-12 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 BROKER-ID may be specified in URL Style or Transport-method Style. In order to communicate, applications must specify the same BROKER-ID.

Note:
URL style does not apply to mainframe platforms (z/OS, BS2000 and z/VSE).

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 RECEIVE function, the user ID of the client is returned to the server in the CLIENT-UID field. If EntireX Security is installed, it is valid for the server application to rely on this user ID when making decisions concerning access to information.

See Authentication (z/OS only).

Note:
There is an uppercase translation when the USER-ID field is propagated to the CLIENT-UID field under EntireX Security when Broker kernel is running under z/OS.

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:
0 - 9 0 = no compression, 9 = maximum compression/decompression
N No compression
Y Compression level 6
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.
NEW On a SEND function, initiates a new conversation. On a RECEIVE function, signals readiness to receive requests for new conversations only. A CONV-ID value is assigned to the conversation, and the value is returned to the caller.
OLD Applies to RECEIVE function only. Only messages for existing conversations are returned.
ANY On a RECEIVE function, requests or messages are returned on a first-in, first-out basis for any conversation. On an EOC function, any conversations belonging to the caller are terminated.
NONE On a SEND function, the message is non-conversational.
conv-id Indicates a specific conversation.

The CONV-ID value is an internally generated identifier (containing numeric characters only or alphanumeric characters) for the conversation. Application programmers are advised to make no assumptions about the contents, layout, or meaning of any part of the CONV-ID field.

If the client has specified API-VERSION 3 or above, the CONV-ID contains both alphanumeric and numeric characters.

If the Broker does not support UOW processing (the Broker attribute MAX-UOWS=0) or the client has specified API-VERSION or 2, the CONV-ID contains numeric characters.

CONV-STAT I1 1 | 2 | 3 2 O
Conversation Status. See Managing Conversation Contexts.
1 NEW - The message is the first in a new conversation.
2 OLD - The message is part of an existing conversation.
3 NONE - The message is non-conversational.
CORRELATION-ID A64 string 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.
0 Default. Use user ID and password.
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 ENVIRONMENT field, allowing flexible character conversion behavior in accordance with application requirements such as EBCDIC-ASCII conversion, byte swapping, and mixed data types. The ENVIRONMENT field can be used to pass this information from the application to the translation exit in Broker kernel.

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:
In previous ACI versions, Broker kernel always returned 40 bytes of error text that were space-padded if necessary. With ACI version 9 and above, variable-length error texts can be returned to improve logging and tracing.

FORCE-LOGON A1 Y | N 6 I
Override the AUTOLOGON feature of the Broker. See AUTOLOGON.
Y The attribute AUTOLOGON=YES in the Broker attribute file is overridden. See FORCE-LOGON under Writing Applications using EntireX Security.
N Default. Use the value of the Broker attribute file for AUTOLOGON.
FUNCTION I1 1-22 1 I
1 SEND 9 LOGON
2 RECEIVE 10 LOGOFF
4 UNDO 13 SYNCPOINT
5 EOC 14 KERNELVERS
6 REGISTER 16 SETSSLPARMS
7 DEREGISTER 22 REPLY_ERROR
8 VERSION 26 GET-MESSAGE-ID
KERNELSECURITY A1 Y | N | U 7 I/O
This field is used by the application to indicate programmatically its intention to communicate with a secure/non-secure Broker. The field also indicates to the application how security has been configured for a particular Broker kernel. See Broker attribute SECURITY.

When used as an input field, this field is used by programmer to indicate the desired security behavior of the application. If no option is specified, defaults to administrator's configuration setup.

Y EntireX Security
N No security
U User-written security (deprecated). Existing user-written security exits created for earlier versions of EntireX will continue to be supported.
Notes

  • Output
    In version 7 or above, this field returns the output value when executing the KERNELVERSION command.

  • Input
    In version 8 or above, the application can programmatically specify the desired security behavior for all commands other than KERNELVERSION.

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:

  • The broker stub assumes by default the data is given in the encoding of the Windows ANSI codepage configured for your system. If you are using at least API-VERSION 8, a codepage identifier of this Windows ANSI codepage is automatically transferred to tell the broker how the data is encoded, even if no codepage name in the locale string is given.

  • If you want to adapt the Windows ANSI codepage, see the Regional Settings in the Windows Control Panel and your Windows documentation.

  • If you want to encode the data different to your Windows ANSI codepage, convert the data in the application and provide the codepage name in the locale string. During receive, decode the data accordingly.

Under all other operating systems:

  • The broker stub does not automatically send a codepage identifier to the broker.

  • It is assumed the broker's locale string defaults match. See Locale String Mapping. If they do not match, provide the correct codepage name in the locale string here.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTCHA". See also Configuring ICU Conversion under z/OS | UNIX | Windows | BS2000 | z/VSE. More information can be found under Internationalization with EntireX.

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 LOG-COMMAND field. If this field is set, all associated commands will be logged.

Note:
If command logging is not enabled for your kernel, you must first contact your administrator.

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:

tcpip://[2001:0db8:85a3:08d3:1319:8a2e:​0370:​7347]:​3930

[2001:0db8:85a3:08d3:1319:​8a2e:​0370:​7347]:​3930:​TCP

(2001:0db8:85a3:08d3:1319:​8a2e:​0370:​7347):​3930:​TCP

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 NEWPASSWORD is ignored if the value of LONG-NEWPASSWORD-LENGTH is non-zero.

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 LOGON) and requires the application to set long-password and long-newpassword and to assign LONG-PASSWORD-LENGTH and LONG-NEWPASSWORD-LENGTH.

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 FORCE-LOGON under Writing Applications using EntireX Security.

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 PASSWORD is ignored if the value of LONG-PASSWORD-LENGTH is non-zero.

MESSAGE-ID A64 string 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 GET-MESSAGE-ID.

If a message has been received, this field returns the corresponding MESSAGE-ID. Note that the sender must use API version 11 or above to receive a MESSAGE-ID.

This MESSAGE-ID is a unique indicator for the corresponding message.

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 LONG-NEWPASSWORD-LENGTH and optional long password is recommended with ACI version 12 and above. However, NEWPASSWORD is still supported for compatibility reasons. If your passwords do not exceed 32 bytes and if password phrases are not applicable, the NEWPASSWORD field can be used without any functional constraints.

OPTION I1 0-21 1 I
Provides additional information that modifies the behavior of the Broker ACI functions.
0 no option 8 NEXT 16 QUERY
1 MSG 9 PREVIEW 17 SETUSTATUS
2 HOLD 10 COMMIT 18 ANY
3 IMMED 11 BACKOUT 19 reserved for future use
4 QUIESCE 12 SYNC 20 DURABLE (deprecated)
5 EOC 13 ATTACH 21 CHECKSERVICE
6 CANCEL 14 DELETE    
7 LAST 15 EOCCANCEL    
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 LONG-PASSWORD-LENGTH and optional long password is recommended with ACI version 12 and above. However, PASSWORD is still supported for compatibility reasons. If your passwords do not exceed 32 bytes and if password phrases are not applicable, the PASSWORD field can be used without any functional constraints.

PTIME A8   2 I Not used by EntireX Broker.
RECEIVE-LENGTH B32 Binary. 1 I/O Specifies the length of receive buffer, in bytes. The maximum length depends on the transport method:
NET 30,545
TCP 2,147,483,647
SSL 2,147,483,647

Note:
Under z/OS with Adabas version 8, the value for NET is the same as for TCP.

See Using Send and Receive Buffers.

RETURN-LENGTH I4   1 O Length, in bytes, of the data returned.

See Using Send and Receive Buffers.

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 SECURITY-TOKEN between commands and not change this value. We recommend that the application allocate a separate ACI control block for each user if it issues commands on behalf of more than one user. For objects executing inside Web servers, assigning a unique value, such as 'session ID', to the ACI TOKEN field is highly recommended to ensure uniqueness of user at same physical location. See Ignore Security Token.

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 SECURITY-TOKEN can be used to avoid additional authentication checks.

SEND-LENGTH B32 binary 1 I/O Specifies the length of data being sent, in bytes. The maximum length depends on the transport method:
NET 30,545
TCP 2,147,483,647
SSL 2,147,483,647

Note:
Under z/OS with Adabas version 8, the value for NET is the same as for TCP.

See Using Send and Receive Buffers.

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 SEND, RECEIVE, and EOC functions when CONV-ID is set to NEW, OLD, or ANY. When a CONV-ID is supplied, the service fields are ignored.

SERVICE=* or SERVER-NAME=* can be used on a RECEIVE function to indicate all services within a specified server or all servers within a specified server class.

Note:
Server classes "SAG", "Entire", "Adabas", "Natural", "ETB", "RPC" and Broker are reserved for Software AG. Do not use them in your applications.

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.
0 none - Defaults to the value specified for the service.
1 OFF - The UOW is not persistent.
2 BROKER - The UOW is persistent.
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.
Warning:
USER-ID and TOKEN must be specified by all applications that use UOWs held in the persistent store.
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.
0 Means that the multiplier will have the same value as the UWSTATP Broker attribute.
255 Means that there will be no persistent status for UOWs.
1-254 Any number in this range is a valid multiplier.
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:
BOTH Since a server receives a UOW and replies with a different UOW, both UOWs can be committed or backed out by specifying UOWID=BOTH for the SYNCPOINT command.
uowid The uowid must be supplied in subsequent SEND, RECEIVE and SYNCPOINT commands related to the same UOW.
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.
1 RECEIVED - One or more messages have been sent as part of a UOW but the UOW has not yet been committed.
2 ACCEPTED - The UOW has been committed by the sender.
3 DELIVERED - The UOW is currently being received.
4 BACKEDOUT - The UOW has been backed out by the sender.
5 PROCESSED - The UOW has been received and the receiver has committed it.
6 CANCELLED - The UOW has been cancelled by the receiver.
7 TIMEOUT - The UOW was not processed within the time allowed.
8 DISCARDED - The UOW was not persistent and its data was discarded as the result of a restart.

With the exception of DELIVERED, all UOWSTATUS values are persistent. Persistent values are kept until they are explicitly deleted by the user or the time limit is exceeded. The lifetime of the UOWSTATUS value is determined by the broker attribute UWSTATP.

UOWSTATUS values in the following table are returned on a RECEIVE function to indicate whether the message being transferred is part of a UOW and, if so, its sequence within the UOW:

0 NONE - The message is not part of a UOW.
9 FIRST - The message is the first message in a UOW.
10 MIDDLE - The message is neither the first nor the last in the UOW.
11 LAST - The message is the last message in the UOW.
12 ONLY - The message is the only message in the UOW.
USE-SPECIFIED-CORRELATION-ID I1 0 | 1 11 I
Only used for function SEND.
0 Default. No CORRELATION-ID is sent to the broker.
1 The value in field CORRELATION-ID is sent with this request.
See Unique Message ID under Broker ACI Functions.
USE-SPECIFIED-MESSAGE-ID I1 0 | 1 11 I
Only used for function SEND.
0 Default. A MESSAGE-ID must be generated for the message that is sent with this request.
1 The existing value in field MESSAGE-ID must be used for the message that is sent with this request.
See Unique Message ID under Broker ACI Functions.
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 client and server communication model.

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 UOW-STATUS-PERSIST.

nS The number of additional seconds the UOW status will exist.
nM The number of additional minutes the UOW status will exist.
nH The number of additional hours the UOW status will exist.
nD The number of additional days the UOW status will exist.
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 UWTIME expires, the UOW is discarded and its status becomes TIMEOUT.

UWTIME is specified on the first SEND function for a UOW; it is not allowed on a RECEIVE function.

nS The number of seconds the UOW can exist.
nM The number of minutes the UOW can exist.
nH The number of hours the UOW can exist.
nD The number of days the UOW can exist.
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.
NO Default. No wait. Control is returned to the caller.
nS The number of seconds the caller will wait for a reply.
nM The number of minutes the caller will wait for a reply.
nH The number of hours the caller will wait for a reply.
YES Depending on the role of the user (client or server), the respective attribute is used (CLIENT-NONACT | SERVER-NONACT). If a server registers multiple services, the highest value of all the services registered is taken as wait time for the server. However, if the user is both client and server, CLIENT-NONACT is also used for calculating the wait time.

All different roles provide non-activity attributes. The maximum value is taken for the wait time.