|
As defined in xcapi.h
| xerr xcAttachFieldSet( | xhandle object, |
| xuint32 slot, | |
| XC_FIELD_DESC *desc, | |
| xuint32 desc_count); |
Description:
Attaches an ad hoc "field set" to a slot in a container object in order to minimize the latency associated with accessing fields in the attached set. The ad hoc field set may include fields or field groups from the container itself, in addition to fields and groups from any event object associated with the container. (Note, however, that attaching event object fields for subscriptions from vectored-event feeds in not recommended.) After a field set is attached to a slot, relevant fields in the set are automatically populated prior to each callback invocation on the slot. In effect, data is "pre-fetched" for each callback and is already available when the client application receives the callback event notification.
The field set should be attached before making a subscription request on the slot. Only one field set may be attached to given slot at one time. If xcAttachFieldSet() is called on a slot that already has a field set attached, the previously attached field set is removed. Note that an attached field set remains attached to its slot unless (1) it is automatically removed when a different field set is attached to the slot; (2) the field set is explicitly detached by calling xcDetachFieldSet(); (3) the slot is cleared with xcClearSlots(); or (4) the object is destroyed with xcDestroyObject().
Note that the array of field descriptors passed in to xcAtta chFieldSet() must remain in persistent memory while the field set is attached to a given slot. Deleting or changing values in this array while the field set is attached could cause memory violations or other unintended results.
More on the descriptor array passed into the xcAttachFieldSet() call: One descriptor is passed in for each field or field group to be attached by the call. Each descriptor is a C structure consisting of five required input fields: a field/field group ID, an output buffer address, an output size, the maximum number of elements to return (greater than 1 if an array field is being read), and the size (in bytes) of the descriptor. There are also two output fields, representing the number of elements written to the output buffer and the status of the last event-related pre-population attempt. Note that the descriptor also includes several optional input fields to provide conversion instructions, if automatic conversion to string, binary float, or binary double output format is desired. If no conversion is desired, the values for the optional fields should be left at zero. As outlined below, three of the optional fields are for string conversion; one is for the binary-to-binary conversions. Note that the latter (conversion to the binary formats) is not available for field groups.
A note on automatic pre-fetching by the API: When an event is delivered on a slot that has an attached field set, note that all fields in the attached field set may not be prefetched. In general, only fields derived from the container slot and fields derived from the event object that actually fired are prefetched. (In other words, if a quote event is delivered, any fields from a quote event object or from the relevant container object slot are prefetched and populated in the attached field set. But fields derived from another event object, such as from a refresh event, will not be prefetched and populated.) To ensure that your application is only referring to fields that have been updated for a given callback, it is recommended that you check the status (xfd_status) and output count (xfd_out_count) on every field descriptor in your attached field set prior to using the associated data. The status and output count for each descriptor are updated by each callback.
| Field | Data Type | Description |
|---|---|---|
| xfd_id | xuint64 | [INPUT] Targeted field ID or field group ID. |
| xfd_buffer_address | xuint64 | [INPUT] Address of output buffer for the field for field group. |
| xfd_elmsiz | xuint32 | [INPUT] Size, in bytes, of the entity to be written. If xfd_in_count is greater than 1, this is the size of each element in the field or field group array. If the targeted entity is a non-array field group, this is the size of the entire field group. Note that the size may be larger than that of the actual field, elements, or group being retrieved (bytes beyond the end of retrieved data are not modified). |
| xfd_in_count | xuint32 | [INPUT] Maximum number of elements to return for each field (must be 1 for non-array fields and non-array field groups). |
| xfd_out_count | xuint32 | [OUTPUT] Number of elements written to the output buffer. |
| xfd_status | xuint32 | [OUTPUT] Status of the field/group extraction. |
| xfd_desc_size | xuint8 | [INPUT] Size of the XC_FIELD_DESC (in bytes). |
| xfds_string_type | XM_DATA_TYPE | [INPUT] Optional field for string conversion. Indicates the type of string to convert the output to, as follows: XTYP_STRING_FIXED_LENGTH XTYP_STRING_NUL_TERM If the "NUL terminated" string type is used, then xfd_in_count must be 1. Note that the xfd_elmsiz must also be set appropriately for string conversion, as follows: (1) if the "fixed length" string type is used, xfd_elmsiz is set to the length each output string will be; or (2) if the "NUL terminated" string type is used, xfd_elmsiz is set to the buffer size (in bytes) of the string, including the terminating NUL. If no conversion to string is desired, the field value should be zero. |
| xfds_field_width | xuint16 | [INPUT] Optional field for string conversion. Indicates the width of the field being converted. If no conversion to string is desired, the field value should be zero. |
| xfds_options | xuint32 | [INPUT] Optional field for string conversion. Indicates the formatting options to be applied to the string output. Available options are: XFSTR_UPCASE - all characters upper case XFSTR_DOWNCASE - all characters lower case XFSTR_VERBATIM - ouput non-printables without interpretation XFSTR_TRUNCATE - Truncate the string to make it fit the specified field width If no special formatting options are desired, the field value should be zero. |
| xfdb_convert_type | XM_DATA_TYPE | [INPUT] Optional field for binary-to-binary conversion to a float or double. If conversion is desired, the field is set to: XTYP_float (convert to single-precision float) XTYP_double (convert to double-precision float) If no binary-to-binary conversion is desired, the field value should be zero. Note that this conversion is not available for field groups. |
Three macros are available to facilitate construction of XC_FIELD_DESC entries:
(1) To construct an XC_FIELD_DESC which doesn't include any conversion action:
#define XCAPI_FIELD_DESC(_id, _bufadr, _elmsiz, _incnt)
(2) To construct an XC_FIELD_DESC which includes conversion to string:
#define XCAPI_FIELD_DESC_CSTRING(_id, _bufadr, _elmsiz, _fw, _options)
(3) To construct an XC_FIELD_DESC which includes conversion to a double:
#define XCAPI_FIELD_DESC_DOUBLE(_id, _bufadr, _elmsiz, _incnt)
The input parameters for the three macros refer to XC_FIELD_DESC fields, as listed below. Please see the preceding table for a detailed description of each field.
| Parameter | XC_FIELD_DESC field |
|---|---|
| _bufadr | xfd_buffer_address (output buffer address) |
| _elmsiz | xfd_elmsiz (size, in bytes, of entity to be written) |
| _fw | xfds_field_width (width of field being converted) |
| _id | xfd_id (field or group ID) |
| _incnt | xfd_in_count (number of elements to retrieve) |
| _options | xfds_options (formatting options to apply, if any) |
Restrictions:
Parameters:
Returns:
An xerr type indicating the status of the operation.
Common error codes:
XSUCCESS Operation completed successfully; all supplied fields are valid.
XINVAL An invalid parameter was supplied.
XBADFIELD One or more of the specified field IDs or field group IDs was invalid.
XBADSLOT Invalid slot number.
XMODIFIED Same as XSUCCESS, but indicates that a previously attached field set has been replaced.
XBADHANDLE Invalid handle.
XBADSIZE Input buffer smaller than size of field.