Open topic with navigation

TIBCO Rendezvous® 8.7.0

# tibrvMsg_GetField()

Function

## Declaration

    tibrv_status tibrvMsg_GetField(
        tibrvMsg          message,
        const char*       fieldName,
        tibrvMsgField*    field);
    tibrv_status tibrvMsg_GetFieldEx(
        tibrvMsg         message,
        const char*      fieldName,
        tibrvMsgField*   field,
        tibrv_u16        fieldId);

## 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 function takes a snapshot of the field, and stores that information in the `field` argument, overwriting the struct supplied as an argument.

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

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

Parameter | Description
`message` | Get the specified field of this message.
`fieldName` | Get a field with this name.
`field` | The program supplies a pointer to a tibrvMsgField struct; the function overwrites the contents of the struct 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 function, and related functions 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

| 1. | Extended functions begin here. Regular functions begin at step 3.

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. | Regular functions begin here. Extended functions also begin here when the program supplied zero as the identifier (supplying zero is equivalent to not supplying a field identifier, so the behavior is equivalent to the corresponding regular function).

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

| Earlier releases of Rendezvous software allowed programs to get fields from a nested submessage by concatenating field names. Starting with release 6, Rendezvous software no longer supports this special case convenience. Instead, programs must separately extract the nested submessage using `tibrvMsg_GetMsg()`, and then get the desired fields from the submessage.

## Convenience Functions

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

| • | Code readability.

| • | Type checking.

| • | Automatic type conversion.

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

| • | No convenience function exists.

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

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

| • | Get Scalar.

| • | Get Array.

| • | Get Nested Message.

| • | Get String.

| • | Get Opaque Byte Sequence.

| • | Get XML Byte Sequence.

| • | Get DateTime.

## Extended Functions

Each convenience function has two forms.

| • | The usual form specifies the field to get using a field name.

| • | The extended form specifies the field to get using a field name and a field identifier.

For example, the function `tibrvMsg_GetI32()` is paired with the extended form `tibrvMsg_GetI32Ex()`.

The field identifier has type tibrv_u16. Zero is a special value that signifies no field identifier. All non-zero field identifiers must be unique within each message.

For details, see Field Names and Field Identifiers.

## See Also

Field Names and Field Identifiers

Get Scalar

tibrvMsgField

Subtopics

Did you find this helpful?

Yes No
Great!
Thanks for taking the time to give us some feedback.
Sorry about that

Why wasn't this helpful? (check all that apply)

Could not find what I was looking for
Instructions confusing or unclear
Instructions did not work

Want to tell us more?

Please select at least one option or provide details about the issue!!

Error occurred while submitting feedback.

Error2 occurred while submitting feedback.

TIBCO Rendezvous®

Copyright © 1997-2023. Cloud Software Group, Inc. All Rights Reserved.