Broker 10.5 | webMethods Broker Documentation | webMethods Broker Client C API Programmer's Guide | API Reference | awGet | awGet<type>SeqField
 
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);
event
The event whose field is to be returned.
field_name
The name of the sequence field to be returned from the event.
offset
The number of elements to skip from the beginning of the sequence.
max_n
The number of elements requested. If set to -1, all elements are requested.
n
The number of elements actually returned. This is an output value set by the function.
value_array
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
awGetBooleanSeqField
BrokerBoolean **
awGetByteSeqField
char **
awGetCharSeqField
char **
awGetDateSeqField
BrokerDate **
awGetDoubleSeqField
double **
awGetFloatSeqField
float **
awGetIntegerSeqField
int **
awGetLongSeqField
BrokerLong **
awGetShortSeqField
short **
awGetStringSeqField
char ***
awGetUCCharSeqField
charUC **
awGetUCStringSeqField
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.
Note:
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
Meaning
AW_ERROR_FIELD_NOT_FOUND
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.
AW_ERROR_FIELD_TYPE_MISMATCH
The field's type does not match the type of value_array or the field_name incorrectly accesses a type.
AW_ERROR_INVALID_EVENT
The event is invalid.
AW_ERROR_INVALID_FIELD_NAME
The field_name is invalid.
AW_ERROR_NULL_PARAM
The parameter field_name, n, or value is NULL.
AW_ERROR_OUT_OF_RANGE
The offset is less than zero or greater than the sequence size. Also returned if max_n is less than zero.
See also: