Broker 10.5 | webMethods Broker Documentation | webMethods Broker Client C API Programmer's Guide | Creating and Initializing Events | Envelope Fields
 
Envelope Fields
 
Read-only Envelope Fields
Many of the event envelope fields are managed for you by the webMethods Broker library functions. Some event fields can be set by your application and others contain values set by the Broker.You cannot set the envelope fields that are set by the Broker, but you can retrieve their values.
Note:
Attempting to retrieve an envelope field that has not been set will return a BrokerError with a major code set to AW_ERROR_FIELD_NOT_FOUND.
Envelope Field
Event Editor Type
Description
age
long
The time in seconds since the event was received by the Broker.
appLastSeqn
int
The sequence number of the last event in the sequence. Your application defines how this field is used. The conventional way to use this field is to set it to 0 if you do not know the last sequence number. By specifying the last in the sequence, the recipient knows how many events to expect.
appPassword
unicode_string
Represents a user's password.
appSeqn
int
The sequence number, set by the event's publisher. Your application defines how this field is used. The conventional way to use this field is to count upward from 1.
appUsername
unicode_string
Represents a user's name.
controlLabel
short[]
Represents the access label that a receiving client must have to receive the event. See awSetClientAutomaticControlLabel for more information.
errorsTo
unicode_string
The client ID to which the event should be forwarded if any errors are generated when this event should be sent, instead of sending to the originator of the request.
errorRequestsTo
unicode_string
The client ID to which a request event will be forwarded if any errors generated processing the request. If field is not set, any request event that generates an error will be discarded.
maxResults
int
The maximum number of reply events a requestor would like to receive. A value of 0 indicates that no reply or acknowledgment should be sent for this event.
replyTo
unicode_string
The client ID to which the replies to this event should be sent, instead of sending to the originator of the request.
signature
byte[]
A byte sequence that holds a digital signature.
signatureType
unicode_string
Describes the type of digital signature being used.
startResult
int
A value >= 0 that specifies the starting number of the event to receive. Often used in conjunction with maxResults.
tag
int
Used in the request-reply model, described in Using Request-Reply, to match a request event with its corresponding reply event.
trackId
unicode_string
This field's value can be set by a publishing client application to a unique identifier for tracking purposes. This allows an event that is republished to be tracked. It also allows multiple events associated with a single logical transaction to be tracked. If not set, this field should be treated as if it contained the same value as the pubId field.
transactionId
unicode_string
This field's value can be set by a publishing client application to indicate that an event is part of a transaction. See Transactional Client Processing with Adapters for more information.
transformState
unicode_string
This field allows clients that transform data to mark an event's current state. An event could be published with a transformState value of USEnglish. A receiving client could translate the event into French and publish it with a transformState value of French.
The appSeqn and applastSeqn can be used by your publisher and subscriber applications for whatever purpose they require. One possibility is to track a sequence of events which represent a response to a single request event. Your publisher could start appSeqn at 1 and set appLastSeqn to the sequence number of the last event in the sequence. If your publisher does not know the length of the sequence when it starts publishing, then appLastSeqn need not be set. When your publisher is about to publish the last event of the sequence, appLastSeqn could be set to equal appSeqn. Setting both appSeqn and appLastSeqn are set to -1 indicates the event is empty.
If you want your publisher to have a continuous stream of sequence numbers, then you should use awSetEventPublishSequenceNumber.
Note:
The awSetPublishSequenceNumber function does not actually set the pubSeqn envelope field. Instead, it specifies the sequence number that the Broker is to use when the event is published by your Broker client.