TibrvMsg::getField()

Method

Declaration

TibrvStatus getField(
    const char*       fieldName,
    TibrvMsgField&    field,
    tibrv_u16         fieldId=0);

Purpose

Get a specified field from a message.

Remarks

Programs specify the field to retrieve using the fieldName and fieldId parameters. For details, see Field Names and Field Identifiers.

The method takes a snapshot of the field, and stores that information in the field argument, overwriting the field object supplied as an argument.

The method copies scalar data into the program’s field object. Pointer data (such as strings, arrays, submessages, XML data, or opaque byte sequences) 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.

Programs can use a related method to loop through all the fields of a message. To retrieve each field by its integer index number, see TibrvMsg::getFieldByIndex().

Parameter	Description
`fieldName`	Get a field with this name.
`field`	The program supplies a TibrvMsgField object; the method overwrites the contents of the object with a snapshot of the information from the message field.
`fieldId`	Get the field with this identifier. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.

Field Search Algorithm

This method, and related methods that get message fields, all use this algorithm to find a field within a message, as specified by a field identifier and a field name.

Procedure

If the identifier is zero, skip to step 3.

If the program supplied a non-zero field identifier, then search for the field with that identifier.

If the search succeeds, return the field.

On failure, continue to step 2.

2. If the identifier search (in step 1) fails, and the program supplied a non-NULL field name, then search for a field with that name.

If the name search succeeds, and the identifier in the field is NULL, return the field.

If the name search succeeds, but the actual identifier in the field is non-NULL (so it does not match the identifier supplied) then return the status code TIBRV_ID_CONFLICT.

If the name search fails, or if the program supplied NULL as the field name, return the status code TIBRV_NOT_FOUND.

3. When the program supplied zero as the identifier, search for a field with the specified name—even if that name is NULL.

If the search succeeds, return the field.

On failure, return the status code TIBRV_NOT_FOUND.

If a message contains several fields with the same name, searching by name finds the first instance of the field with that name.

Extracting Fields from a Nested Message

Rendezvous programs must separately extract the nested submessage using TibrvMsg::getMsg(), and then get the desired fields from the submessage.

Convenience Methods

In most situations, we recommend using type-specific convenience methods instead of this general method. Type-specific methods yield these advantages when extracting fields:

•

Code readability.

•

Type checking.

•

Automatic type conversion.

However, we do recommend the general method in two specific situations:

•

No convenience method exists.

•

The program must extract the data exactly as it appears in the message, without automatic type conversion. (Convenience methods always convert extracted data to a specific type.)

These categories of type-specific convenience methods find a field and get its data:

•

•

•

•

•

Get Opaque Byte Sequence.

•