TibrvMsg::updateField()
Method
Declaration
TibrvStatusupdateField(
const TibrvMsgField& field);
Purpose
Update a field within a message.
For most programs, we recommend type-specific convenience methods instead of this generic method. 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 method 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 method adds the field to the message. Update convenience methods 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 method 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, XML data, or opaque byte sequences) 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 |
|
|
Update the existing message field using this field. |
Field Search Algorithm
This method, and related methods 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. | 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. | When the program supplied zero as the identifier, 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 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 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 updating fields:
| • | Code readability. |
| • | Type checking. |
| • | Automatic type conversion. |
These categories of type-specific convenience methods find a field and update its data:
| • | Update Scalar. |
| • | Update Array. |
| • | Update Nested Message. |
| • | Update String. |
| • | Update Opaque Byte Sequence |
| • | Update DateTime |
Nested Message
When the new value is a message object, this method uses only the data portion of the nested message (data); it does not include any address information or certified delivery information.