Field Names and Field Identifiers
Rendezvous programs can specify fields in two ways:
| • | A field name is a character string. Each field can have at most one name. Several fields can have the same name. |
| • | A field identifier is a 16-bit unsigned integer, which must be unique within the message. That is, two fields in the same message cannot have the same identifier. However, a nested submessage is considered a separate identifier space from its enclosing parent message and any sibling submessages. |
Message methods specify fields using a combination of a field name and a unique field identifier. When absent, the default field identifier is zero.
To compare the speed and space characteristics of these two options, see Search Characteristics.
Rules and Restrictions
NULL is a legal field name only when the identifier is zero. It is illegal for a field to have both a non-zero identifier and a NULL field name.
However, NULL is not the same as "" (the empty string). It is legal for a field to have a non-zero identifier and the empty string as its field name.
Field Search Algorithm
The methods that get message fields (including methods that update or remove fields, since these methods call get internally) all use this algorithm to find a field within a message, as specified by a field identifier and a field name.
Procedure
| 1. | If the program supplied a non-zero field identifier, then search for the field with that identifier. On failure, continue to step 2. (If the identifier is zero, skip to step 3.) |
| 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. On failure, or 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- |
| 3. | Begin here when the program supplied zero as the identifier (or omitted a field identifier). |
Search for a field with the specified name—even if that name is NULL. On failure, return the status code TIBRV_NOT_FOUND.
If a message contains several fields with the same name, searching by name finds the first instance of the field with that name.
Adding a New Field
When a program adds a new field to a message, it can attach a field name, a field identifier, or both. If the program supplies an identifier, Rendezvous software checks that it is unique within the message; if the identifier is already in use, the operation fails with the status code TIBRV_ID_IN_USE.
Search Characteristics
In general, an identifier search completes in constant time. In contrast, a name search completes in linear time proportional to the number of fields in the message. Name search is quite fast for messages with 16 fields or fewer; for messages with more than 16 fields, identifier search is faster.
Space Characteristics
The smallest field name is a one-character string, which occupies three bytes in Rendezvous wire format. That one ASCII character yields a name space of 127 possible field names; a larger range requires additional characters.
Field identifiers are 16 bits, which also occupy three bytes in Rendezvous wire format. However, those 16 bits yield a space of 65535 possible field identifiers; that range is fixed, and cannot be extended.
Finding a Field Instance
When a message contains several field instances with the same field name, these methods find a specific instance by name and number (they do not use field identifiers):
| • | TibrvMsg::getFieldInstance(). |
| • | TibrvMsg::removeFieldInstance(). |