tibrvMsg_GetFieldInstance()

Function

Declaration

tibrv_status tibrvMsg_GetFieldInstance(
    tibrvMsg            message,
    const char*         fieldName,
    tibrvMsgField*      fieldAddr,
    tibrv_u32           instance);

Purpose

Get a specified instance of a field from a message.

Remarks

When a message contains several field instances with the same field name, retrieve a specific instance by number (for example, get the ith field named foo). Programs can use this function in a loop that examines every field with a specified name.

The argument 1 denotes the first instance of the named field.

The function copies scalar data into the program’s field struct. Pointer data extracted from the field remain valid until the message is destroyed; that is, even removing the field or updating the field’s value does not invalidate pointer data.

When the instance argument is greater than the actual number of instances of the field in the message, this function returns the status code TIBRV_NOT_FOUND.

Release 5 Interaction

Rendezvous 5 (and earlier) did not support array datatypes. Some older programs circumvented this limitation by using several fields with the same name to simulate arrays. This work-around is no longer necessary, since release 6 (and later) supports array datatypes within message fields. The function tibrvMsg_GetFieldInstance() ensures backward compatibility, so new programs can still receive and manipulate messages sent from older programs. Nonetheless, we encourage programmers to use array types as appropriate, and we discourage storing several fields with the same name in a message.

Parameter	Description
message	Get the specified field instance of this message.
fieldName	Get an instance of the field with this name. NULL specifies the empty string as the field name.
fieldAddr	The program supplies a pointer to a tibrvMsgField struct; the function overwrites the contents of the struct, using information from the message field.
instance	Get this instance of the specified field name. The argument 1 denotes the first instance of the named field.

See Also

tibrvMsg_GetField()