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

Quick Reference

— EntireX Developer's Kit —

Broker ACI Fields

This document covers the following topics:

Field Formats
Field Descriptions

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)
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
Version I/O Description

ADAPTER-ERROR A8 2 O Not used by EntireX Broker.

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 except VERSION. See API-TYPE and API-VERSION in Writing Applications: Client and Server or Publish and Subscribe.

API-VERSION I1 1-9 1 I Required for all ACI functions except VERSION.

BROKER-ID

A32

string

The BROKER-ID as defined in the Broker attribute file. 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.

CLIENT-ID I4 1-2147483647 9 O Returns to a server application the unique instance number of a client application.

CLIENT-UID

A32

string

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

Time when UOW was committed.
ms	= milliseconds in Possible Values field

COMPRESSLEVEL

0-9 or Y | N

Compression level. See Data Compression in Writing Applications: Client and Server or Publish and Subscribe. 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

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 in Writing Applications: Client and Server.
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 =1 or 2, the CONV-ID contains numeric characters.

CONV-STAT

1 | 2 | 3

Conversation Status, see Managing Conversation Contexts in Writing Applications: Client and Server.
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.

CREDENTIALS-TYPE

binary

Determines the credentials type to be used to authenticate a user.
`blank`	Default. Use user ID and password.
IAF	The token specified in the IAF token field is used.

DATA-ARCH

1-12

Value		Endian	Packed Decimal Format	Floating Point Format
Architecture code. Used only rarely - when the data being sent or received is to be converted by the Broker's conversion exit into a format different from what the stub can determine to be the architecture of the caller's local machine. Normally, the stub can determine enough architectural information about the caller's local machine to allow successful character conversion, which makes use of the data_arch field unnecessary.
1	ACODE_HIGH_ASCII_IBM	Big	IEEE	IBM
2	ACODE_LOW__ASCII_IBM	Little	IEEE	IBM
3	ACODE_HIGH_EBCDIC_IBM	Big	IBM	IBM
4	ACODE_LOW__EBCDIC_IBM	Little	IBM	IBM
5	ACODE_HIGH_ASCII_VAX	Big	IEEE	VAX
6	ACODE_LOW__ASCII_VAX	Little	IEEE	VAX
7	ACODE_HIGH_EBCDIC_VAX	Big	IBM	VAX
8	ACODE_LOW__EBCDIC_VAX	Little	IBM	VAX
9	ACODE_HIGH_ASCII_IEEE	Big	IEEE	IEEE
10	ACODE_LOW__ASCII_IEEE	Little	IEEE	IEEE
11	ACODE_HIGH_EBCDIC_IEEE	Big	IBM	IEEE
12	ACODE_LOW__EBCDIC_IEEE	Little	IBM	IEEE

ENCRYPTION-LEVEL I1 0|1|2 6 I Encryption level. See Using Encryption.

ENVIRONMENT

A32

string

Information for Translation User Exits.

The contents of the field are solely the responsibility of the application and its associated Translation User Exit. The field cannot be used for any other internationalization approaches and must be empty if a method other than Translation User Exit is used. See Using Internationalization in Writing Applications: Client and Server.

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 in Client and Server or in Publish and Subscribe. The first four digits represent the error class; the next four digits represent the error number; see also Messages and Codes.

ERRTEXT-LENGTH

0-40 | 0-255

1 | 9

Length of the error text buffer in bytes. See Call Format: Natural | C | COBOL | PL/I | RPG | Assembler.

If there are fewer than 40 bytes, the error text may be truncated. A value of 0 (zero) means no error text.

Note regarding ACI 9: In previous ACI versions, Broker kernel always returned 40 bytes of error text that were space-padded if necessary. With ACI version 9, variable-length error texts can be returned to improve logging and tracing.

FORCE-LOGON

Y | N

Override the `AUTOLOGON` feature of the Broker.
Y	The attribute `AUTOLOGON`=YES in the Broker attribute file is overridden. See Using FORCE-LOGON.
N	Default. Use the value of the Broker attribute file for `AUTOLOGON`.

FUNCTION

1-22

The EntireX Broker function to be performed. A function value is required and is modified by the ACI Field OPTION and the other ACI fields. See below for description of values.
1	SEND	9	LOGON	18	RECEIVE_PUBLICATION
2	RECEIVE	10	LOGOFF	19	SUBSCRIBE
4	UNDO	13	SYNCPOINT	20	UNSUBSCRIBE
5	EOC	14	KERNELVERS	21	CONTROL_PUBLICATION
6	REGISTER	15	LOCTRANS	22	REPLY_ERROR
7	DEREGISTER	16	SETSSLPARMS
8	VERSION	17	SEND_PUBLICATION

KERNELSECURITY

Y | U | N

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
U	User-Written Security
N	No security
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

It is assumed that you have read the introductory document Internationalization with EntireX and are familiar with the various internationalization approaches.

The locale string tells the broker the encoding of the data. No conversion is done within the broker's stub. The application must ensure the data provided matches the locale string. The locale string is case-insensitive, also dashes '-' and underscores '_' are ignored (dashes and underscore improve human readability). See Using Internationalization.

LOG-COMMAND

0 | 1

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.

MSG-ID B32 2 I/O Not used by EntireX Broker.

MSG-TYPE A16 2 I/O Not used by EntireX Broker.

NEWPASSWORD

B32

Can contain binary data.

Specifies a new password to be transmitted to the Broker kernel to check the authentication of the application. See Authentication.

The current password can be changed only when the client or server authenticates itself. 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.

OPTION

0-21

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
5	EOC	13	ATTACH	21	CHECKSERVICE
6	CANCEL	14	DELETE
7	LAST	15	EOCCANCEL

PARTNER-BROKER-ID A32 string 9 O ID of the partner broker. See Achieving High Availability of the Persistent Store.

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 Using FORCE-LOGON.

PTIME A8 2 I Not used by EntireX Broker.

PUBLICATION-ID

A16

string, case-sensitive.

I/O

Publication ID for publish-and-subscribe communication model. A unique ID assigned to each publication by EntireX Broker. Publisher and subscribers must include the publication ID and the conv-id in their communications. Publisher and subscriber can also specify the indicated textual value (capitals) in order to indicate to Broker the expected status of the publication. Messages for the publication are queued to the topic on a first-in, first-out basis.
NEW	On a SEND_PUBLICATION function, initiates a new publication. On a RECEIVE_PUBLICATION function, signals readiness to obtain next available publication. A publication id value is assigned to the publication, and the value is returned to the caller.
publication-id	Indicates a specific publication. The publication id value is an internally generated identifier (containing alphanumeric characters) for the publication. Application programmers are advised to make no assumptions about the content, layout or meaning of any part of the PUBLICATION-ID field.

RECEIVE-LENGTH

B32

Binary.

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 and SSL.

See Using Send and Receive Buffers in Client and Server or in Publish and Subscribe.

RETURN-LENGTH

Length, in bytes, of the data returned.

See Using Send and Receive Buffers in Client and Server or in Publish and Subscribe.

SECURITY-TOKEN

B32

binary

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 in the EntireX Security documentation.

If EntireX Security is not implemented, and you choose to write your own security exits your 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

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 and SSL.

See Using Send and Receive Buffers in Client and Server or in Publish and Subscribe.

SERVER-CLASS
SERVER-NAME
SERVICE

A32 each

string, case-sensitive

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

0 | 1 | 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.

Optionally identifies the caller and, when used, is required for all Broker ACI functions except VERSION. See USER-ID and TOKEN in Client and Server or in Publish and Subscribe.

Warning:
USER and TOKEN must be specified by all applications that use UOWs held in the persistent store, and by all publisher and subscriber applications where publication and subscription data is held in the persistent store.

TOPIC

A96

string,case-sensitive.

I/O

Topic name for publish and subscribe communication model.

A publisher uses this field to identify the topic name required. A subscriber uses this field to indicate the topic from which publications are to be obtained. Each topic must be defined in the attribute file. See Topic-specific Attributes.

UOW-ID

A16

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.
uow-id	The uow-id must be supplied in subsequent SEND, RECEIVE and SYNCPOINT commands related to the same UOW.

UOWSTATUS

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 UWSTATP Broker attribute. 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.

UOW-STATUS-PERSIST

0 - 255

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 UWTIME Broker attribute. The 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.

USER-DATA B16 binary 2 I/O Conversation User Data. See Managing Conversation Contexts.

USER-ID

A32

string, case-sensitive

Identifies the caller and is required for all Broker ACI functions except VERSION. See USER-ID and TOKEN in Client and Server or in Publish and Subscribe.

Warning:
USER and TOKEN must be specified by all publisher and subscriber applications where publication and subscription data is held in the persistent store.

USTATUS A32 string 3 I/O User-defined information about a unit of work (UOW). It can be transmitted on a SEND, RECEIVE, or SYNCPOINT function and is returned to applications that query the status of the UOW. To update the USTATUS field, use OPTION=SETUSTATUS.

UWSTAT-LIFETIME

nS | nM | nH | nD

Add value for persistent status lifetime in client and server communication model. This field is used to calculate the lifetime of the UWSTAT-LIFETIME. 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. UWSTAT-LIFETIME is specified on the first SEND_PUBLICATION function for a UOW; it is not allowed on a RECEIVE_PUBLICATION function.
`n`S	The number of additional seconds the UOW status will exist.
`n`M	The number of additional minutes the UOW status will exist.
`n`H	The number of additional hours the UOW status will exist.
`n`D	The number of additional days the UOW status will exist.

UWTIME

nS | nM | nH | nD

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.
`n`S	The number of seconds the UOW can exist.
`n`M	The number of minutes the UOW can exist.
`n`H	The number of hours the UOW can exist.
`n`D	The number of days the UOW can exist.

WAIT

NO | YES | nS | nM | nH

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 for client/server and publish-and-subscribe communication models.
NO	Default. No wait. Control is returned to the caller.
`n`S	The number of seconds the caller will wait for a reply.
`n`M	The number of minutes the caller will wait for a reply.
`n`H	The number of hours the caller will wait for a reply.
YES	The caller will wait an unlimited time for a reply.