Broker 10.5 | webMethods Broker Documentation | webMethods Broker Client C API Programmer's Guide | API Reference | awGet | awGet<type>SeqField
Functions such as awGetBooleanSeqField and awGetShortSeqField have the following general syntax:
BrokerError awGet<type>SeqField(
BrokerEvent event,
char *field_name,
int offset,
int max_n,
int *n,
<Field_Value_Type> value_array);
The event whose field is to be returned.
The name of the sequence field to be returned from the event.
The number of elements to skip from the beginning of the sequence.
The number of elements requested. If set to -1, all elements are requested.
The number of elements actually returned. This is an output value set by the function.
An array of values associated with the field that is output from this function.
The following functions are provided to return the values associated with a specific sequence field type.
Function Name
Field Value Type
BrokerBoolean **
char **
char **
BrokerDate **
double **
float **
int **
BrokerLong **
short **
char ***
charUC **
charUC ***
These functions return the values of sequence-type event fields, as listed above. Values of event fields can be requested in any order. If you get a sequence field whose value was not set by the event's publisher, a zero-length sequence will be returned.
To get a sequence of structures, use the awGetStructSeqFieldAsEvents function. To get values of non-sequence type event fields, use one of the awGet<type>Field.
A sequence is a series of values with the same type, similar in concept to an array. Sequence-type event fields are created using one of the awSet<type>SeqField functions. You can create sequences of more than one dimension by building sequences of sequences. To get all sequence values in one call, set max_n = -1 and offset = 0.
You may limit the number of sequence values returned by specifying a max_n \>0 and offset =0 on the first call. For subsequent calls, set offset to the number of elements already processed, so that the elements already retrieved may be skipped. For example, if there are 75 strings in a sequence, and you want to handle no more than 50 on each function call:
*On the first call to awGetStringSeqField, pass:
max_n=50, offset=0,n=50 (returned)
*On the second call to awGetStringSeqField, pass:
max_n=50, offset=50 (already processed),
n=25 (returned)
*On return, every function returns a pointer to an array; for example:
*The awGetCharSeqField function returns a pointer to an array of chars.
*The awGetStringSeqField function returns a pointer to an array of string pointers.
When awGetStringSequenceField is used to obtain the value of a sequence field whose type is FIELD_TYPE_UNICODE_STRING, the values returned will automatically be converted to ANSI strings.
The caller is responsible for calling free on value_array, which is allocated in one block of storage. See Specifying Field Names for complete information on specifying field_name.
Possible BrokerError major codes
The event is associated with a Broker client and field_name does not exist in the event or an attempt was made to obtain the value of an envelope field that has not been set.
The field's type does not match the type of value_array or the field_name incorrectly accesses a type.
The event is invalid.
The field_name is invalid.
The parameter field_name, n, or value is NULL.
The offset is less than zero or greater than the sequence size. Also returned if max_n is less than zero.
See also: