Search:

As defined in xcapi.h

Description:

Adds the item to the object's current list of content items and enables the flow of notification events for the item. The targeted slot must be EMPTY.

Note that the xcRequestItemByString() call returns an XSUCCESS status if the item is properly requested (meaning that all the parameters for the request are well formed, the targeted slot is empty, and the connection to the appliance is active). In addition, the call triggers the event notification mechanism, and an EventSubscribe object is created. The xerr status in the XFLD_EVT_STATUS field of that object indicates whether the requested item was successfully subscribed to.

In general, calls to xcRequestItemByString() are non-blocking. However, when the number of outstanding requests per application exceeds the permitted limit of 500, subsequent calls to the function will be blocked until the number of outstanding requests again falls below 500.

Restrictions:

• May not be called from within a callback function.
• Belongs to the Mutually Exclusive function set.
• Not valid for session or event objects (i.e., for container objects only).

Parameters:

• object [IN] Handle to the container object the data item is to be added to.
• key_string [IN] An Exegy key string identifying the data item to be subscribed to or retrieved by the container object. An Exegy instrument key string takes the form: countrycode:exchangeid:symbol where countrycode is the 2-character Exegy country identifier, exchangeid the 1- or 2 character Exegy exchange ID, and symbol a an Exegy symbol string or an alternate ID identifying a unique financial instrument on the exchange. Baskets, keylists, and keylist filters have key strings of the same form, in which the countrycode and exchangeid are fixed (XX:BX for baskets, XX:UX for keylists, XX:RX for keylist filters) and the symbol portion is a user-supplied name for the item. Note that a namespace element can be pre-pended to the symbol portion of the Exegy key string. (See "Namespaces" in the Reference Tables section of this Guide.) Finally, note that the API now includes a pending subscriptions feature, used to request new instruments prior to their release by an exchange.
• turnkey [IN] Opaque value that will be stored in the targeted container object and passed to callback function when the latter is triggered for this data item.
• slot [IN/OUT] Address of the variable that holds the slot number of the slot to receive this data item. An input slot number of XC_NEXT_AVAILABLE_SLOT indicates the item is to be added at the next free slot. Returns the number of the actual slot used for this item.

Returns:

An xerr type indicating the status of the operation.

Common error codes:

XSUCCESS The item request was successful.
XINVAL An invalid parameter was supplied.
XNOTCONNECTED Session not connected.
XSOCKET Socket error when sending request. Connection in an invalid state.
XTHREAD Called from an invalid thread.
XBUSY Specified slot already has an existing item.
XBADHANDLE Invalid handle.