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 zero^th 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.