Open topic with navigation

TIBCO Rendezvous® 8.7.0

# tibrvMsg_UpdateField()

Function

## Declaration

    tibrv_status tibrvMsg_UpdateField(
        tibrvMsg            message,
        tibrvMsgField*      field);

## Purpose

Update a field within a message.

For most programs, we recommend type-specific convenience functions instead of this generic function. However, translation engine programs can require generic tibrvMsg_UpdateField(), and would use it in conjunction with generic tibrvMsg_GetField(). In this paradigm, modify the field returned from tibrvMsg_GetField() by replacing its `field->value`, and supply it as the `field` argument to tibrvMsg_UpdateField().

## Remarks

This function locates a field within the message by matching the name and identifier of `field`. Then it updates the message field using the `field` argument. (Notice that the program may not supply a field object with a different field name, field identifier, or datatype.)

If no existing field matches the specifications in the `field` argument, then this function adds the field to the message. Update convenience functions also add the field if it is not present.

The type of the existing field (within the message) and the type of the updating `field` argument must be identical; otherwise, the function returns the error status code TIBRV_INVALID_TYPE. However, when updating array or vector fields, the count (number of elements) can change.

Pointer data (such as strings, arrays, submessages, opaque byte sequences or XML data) previously extracted from the field remain valid and unchanged until the message is destroyed; that is, even updating the field’s value does not invalidate pointer data.

Parameter | Description
`message` | Update this message.
`field` | Update the existing message field using this field.

## Field Search Algorithm

This function, and related functions that update message fields, all use this algorithm to find and update 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, then update that 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 program supplied `NULL` as the field name, return the status code `TIBRV_NOT_FOUND.`

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 search fails, add the field as specified (with name and identifier).

| 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 fails, add the field as specified (with name and identifier).

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

## Reserved Field Name

Warning | The field name `_data_` is reserved. Programs may not add fields with this name. (More generally, all fields that begin with the underbar character are reserved.)

## Field Name Length

The constant `TIBRVMSG_FIELDNAME_MAX` determines the longest possible field name.

## Convenience Functions

When the datatype of a field is determined during execution, use this general function. When you can determine the datatype of a field before compile-time, we recommend using type-specific convenience functions instead of this general function. Type-specific functions yield these advantages when updating fields:

| • | Code readability.

| • | Type checking.

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

| • | Update Scalar.

| • | Update Array.

| • | Update Nested Message.

| • | Update String.

| • | Update Opaque Byte Sequence

| • | Update XML Byte Sequence

| • | Update DateTime

## Extended Functions

Each convenience function has two forms.

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

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

For example, the function `tibrvMsg_UpdateI32()` is paired with the extended form `tibrvMsg_UpdateI32Ex()`.

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.

It is illegal to add a field that has both a `NULL` field name, and a non-zero field identifier.

For details, see Field Names and Field Identifiers.

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.