Field definitions

Record fields are identified in DataSource packets and RTTP messages by numeric identifiers, but for convenience in log files and development, record fields are identified by name.

The page describes how field IDs are mapped to field names.

Mapping field IDs to field names

A record field is uniquely identified by a numeric id, but for convenience the numeric id is normally mapped to a name. Naming fields makes it easier to refer to them programmatically and to identify them in log files and other debugging facilities.

Record field names and ids are mapped by add-field configuration items in each DataSource’s fields file (fields.conf).

It is important that all peers in a deployment use the same field codes and that they map to the same field names. The Deployment Framework makes updating fields.conf easier: all the fields.conf files in a deployment are automatically collated and loaded by components on start up. As a result, if a developer adds a new field mapping to an adapter’s fields.conf file, you don’t need to manually update the fields.conf files of all the other components in the deployment.

We recommend using generic objects instead of type 1 records. In contrast to records, generic objects include field names in DataSource and RTTP messages, and so do not require an external field definitions file.

Prior to Platform 8, in a deployment that doesn’t use the Deployment Framework, all fields.conf files must be updated manually. Platform 8 introduces a new feature, Dynamic Fields, that

StreamLink clients of Liberator automatically receive a mapping of field codes to field names. When a web client application logs in to Liberator, the Liberator sends the field names and associated numbers in its fields file to the client (StreamLink JS layer). The client can subsequently use the field names internally, while the StreamLink layer can communicate more efficiently with the Liberator by just sending and receiving field numbers in the RTTP messages.

Dynamic Fields

Dynamic Fields is a new feature in Platform 8 that automatically shares field definitions in the DataSource 8 connection handshake.

In recent years, Caplin has recommended the use of generic objects over type 1 records, however there are many adapters that still use type 1 records.

Type 1 records require both the Liberator and the adapter to have a common map of field numbers to field names. By convention this mapping has been defined in files called fields.conf.

Using the Deployment Framework, these fields.conf files are shared so that both Liberator and the adapter can read them. For a production system with a known set of data flowing through it, the static nature of fields.conf is not necessarily a problem.

However, during development and for Liberators managed by a separate team, restarting the system to add a single field is not a particularly smooth workflow.

In Platform 8, peers share their respective field mappings in the DataSource 8 handshake. This ensures that all components within the system have an up-to-date view of all the fields that are required. This is especially useful for peers that are not deployed in the same Caplin Deployment Framework, and so have no other way of sharing fields.conf configuration automatically.

Compatibility

Dynamic Fields requires that both peers are DataSource 8 applications.

Dynamic Fields includes extra data in the DataSource handshake that is not compatible with DSDK < 7.1.31, Liberator < 7.1.31, and Transformer < 7.1.19. To avoid this incompatibility, either upgrade older DataSource 7 applications, or disable Dynamic Fields in Platform 8 applications using one of the methods below:

  • Disable Dynamic Fields for all peer connections:

  • Disable Dynamic Fields for specific peer connections:

    add-peer
      local-flags nofields
      ...
    end-peer

See also: