TibrvMsg::addField()

Method

Declaration

TibrvStatus addField(const TibrvMsgField& field)

Purpose

Add a field object to a message.

Remarks

This method copies the data into the new message field. All related convenience methods behave similarly.

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

Adding Fields to a Nested Message

Rendezvous programs must use this three-step process:

Procedure

Extract the nested submessage (see Get Nested Message).

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

Store the modified submessage back into the field of the parent message (see Update Nested Message).

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 Methods

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

•

Code readability.

•

Type checking.

•

Accept constants and literals directly.

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

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

•

Add Scalar.

•

Add Array.