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:

• Overview Table

• Function Descriptions

• Option Descriptions

• ACI Field/Function Reference Table

• Unique Message ID

See also Broker ACI Fields.

---

Overview Table

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

Key

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

Function Descriptions

DEREGISTER

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

EOC

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

GET-MESSAGE-ID

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.

KERNELVERS

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).
U	User-written security (SECURITY=YES in the Broker attribute file).
N	SECURITY=NO in the Broker attribute file.

LOGOFF

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

LOGON

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.

LOGON is normally the first function.

In addition to the USER-ID, the LOGON optionally transmits the PASSWORD, NEWPASSWORD and SECURITY-TOKEN to authenticate itself, provided SECURITY=YES is set in the broker attribute file.

RECEIVE

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.

REGISTER

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.

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.

REPLY_ERROR

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.

SEND

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.

  • WAIT=NO

    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.

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.

SETSSLPARMS

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

1. See Using the Broker ACI with SSL/TLS (Assembler | C | COBOL | Java | PL/I).

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

   • Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE

   • Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

SYNCPOINT

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: SYNCPOINT OPTION=LAST SYNCPOINT OPTION=CANCEL SYNCPOINT OPTION=DELETE
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.

UNDO

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.

Option	Description
HOLD	To undo messages in HOLD status, use UNDO with HOLD.

VERSION

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

Option Descriptions

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. For a UOW being sent, it means that the UOW is complete and can now be delivered to the intended receiver. For a UOW being received, it means that the UOW is complete and no further processing of the UOW is allowed.
		SEND	Commit the active UOW.
11	BACKOUT	SYNCPOINT	For receiver of a UOW: Return the UOW to its undelivered state. The UOW can be processed again, in its entirety, by subsequent RECEIVE operations. For sender of a UOW: Delete the UOW. No further processing of the UOW is allowed.
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.

ACI Field/Function Reference Table

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
MESSAGE-ID	O	O												Rt
NEWPASSWORD	O				O			O
OPTION	O	O	O	O	O	O			O	O	O		O
PASSWORD	O				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

Unique Message ID

This section covers the following topics:

• Introduction

• Simple Client/Server Scenario

• Default Scenario (ACI and RPC)

• Generating a Message ID before Message is Sent

Introduction

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.

Simple Client/Server Scenario

	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.

Default Scenario (ACI and RPC)

	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.

Generating a Message ID before Message is Sent

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.