Open topic with navigation

TIBCO Rendezvous® 8.7.0

# tibrvMsg_AddField()

Function

## Declaration

    tibrv_status tibrvMsg_AddField(
        tibrvMsg            message,
        tibrvMsgField*      field);

## Purpose

Add a field to a message.

## Remarks

This function copies the data into the new message field. All related convenience functions behave similarly.

Parameter | Description
`message` | Add the new field to this message.
`field` | Add this field to the message.

## Adding Fields to a Nested Message

Earlier releases of Rendezvous software allowed programs to append fields to a nested submessage under certain conditions. Starting with release 6, Rendezvous software no longer supports this special case convenience. Instead, programs must use this three-step process:

Procedure

| 1. | Extract the nested submessage, using `tibrvMsg_getMsg()`.

| 2. | Add the new fields to the extracted submessage, using type-specific convenience functions or this function. The field is added to a snapshot copy of the submessage, and modifies the copy rather than the original parent message.

| 3. | Store the modified submessage back into the field of the parent message, using `TibrvMsg_UpdateMsg()`.

## Avoiding Common Mistakes

Whenever possible, we recommend storing arrays in message fields using one of the Rendezvous array types. This strategy makes the most efficient use of storage space, processor time, and network bandwidth.

If you must store array elements as individual fields, be careful mapping array indices to field identifiers. Zero-based arrays are common in C programs, but zero has a special meaning as a field identifier—it represents the absence of an identifier. Do not map the zeroth element of an array (`myArray[0]`) to a field with identifier zero; it is impossible to retrieve such a field by its identifier (because it does not have one).

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

## 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` (127) 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 adding fields:

| • | Code readability.

| • | Type checking.

| • | Accept constants and literals directly.

(Type-specific functions yield even further advantages when extracting or updating fields.)

These categories of type-specific convenience functions add a new field:

| • | Add Scalar.

| • | Add Array.

| • | Add Nested Message.

| • | Add String.

| • | Add Opaque Byte Sequence.

| • | Add XML Byte Sequence.

| • | Add DateTime.

## Extended Functions

Each convenience function has two forms.

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

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

For example, the function `tibrvMsg_AddI32()` is paired with the extended form `tibrvMsg_AddI32Ex()`.

Field identifiers have 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 more information, see Adding a New Field.

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.