Open topic with navigation

TIBCO Rendezvous® 8.7.0

# Field Names and Field Identifiers

In Rendezvous 5 and earlier releases, programs would specify fields within a message using a field name. In Rendezvous 6 and later releases, 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.

Regular message functions specify fields using a field name. Extended functions specify fields using a combination of a field name and a unique field identifier.

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 functions that get message fields (including functions that update or remove fields, since these functions 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. | Extended functions begin here. Regular functions begin at step 3.

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-`NULL` (so it does not match the identifier supplied) then return the status code `TIBRV_ID_CONFLICT.``

| 3. | Regular functions begin here. Extended functions also begin here when the program supplied zero as the identifier (supplying zero is equivalent to not supplying a field identifier, so the behavior is equivalent to the corresponding regular function).

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 uses an extended function to add 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 and returns the status code `TIBRV_ID_IN_USE.`

## Passing Field Name and Identifiers

The program can pass the field name and identifier to functions in either of two ways:

| • | All extended functions accept two separate parameters, named `fieldName` and `fieldId`.

| • | tibrvMsg_AddField() and tibrvMsg_UpdateField() do not have extended functions. Instead, they accept a `field` parameter, which contains these two items as members within a tibrvMsgField struct. (The convenience functions that add and update fields do have extended functions.)

## 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 functions find a specific instance by name and number (they do not use field identifiers):

| • | tibrvMsg_RemoveFieldInstance().

| • | tibrvMsg_GetFieldInstance().

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.