Broker ACI Fields

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/OSD and z/VSE).

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.

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 the ENVIRONMENT Field with the Translation User Exit for client and server | publish and subscribe.

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.

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

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.

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.

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.

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 for client and server | publish and subscribe.

See Using Send and Receive Buffers for client and server | publish and subscribe.

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

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 for client and server | publish and subscribe.

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 under Broker 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.

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 under Broker Attributes.