Search:

As defined in xcapi.h

Description:

Adds the item(s) to the object's current list of content items and enables the flow of notification events for the item(s). The targeted slot(s) must be EMPTY. Note that the XC_SLOT_CONTEXT includes an XC_KEY. If the symbol portion of that key is a "long symbol" ( > 20 characters), the Exegy internal binary representation of the key must be used. To simplify requests for items with a long symbol, use xcRequestItemByString(). That call does not require an XC_KEY, so data items with a long symbol can be requested as a normal (ASCII) Exegy key. (No lookup of the Exegy internal binary representation of the key is necessary.)

Note that the xcRequestItems() call returns an XSUCCESS status if any item is properly requested (meaning that all the parameters for the request were well formed, the targeted slot or slots were empty, and the connection to the appliance was active). The event notification mechanism is subsequently invoked, and an EventSubscribe object is created for each requested item. Querying the EventSubscribe object(s) then reveals the status of the individual item requests (i.e., whether a data item was returned for each).

In general, calls to xcRequestItems() 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. Note that a call to xcRequestItems() can be for more than the permitted limit (e.g., it is permissible to request 1000 items in one call, but the call will then block until only 499 requests are outstanding).

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., valid for container objects only).

Parameters:

• object [IN] Handle to the container object.
• contexts [IN] The address of an array of request information identifying the desired items. The request information (type XC_SLOT_CONTEXT) includes an XC_KEY and a user-specified Exegy turnkey for each item. See the note above for important information about using XC_KEYs which include a long symbol.
• context_count [IN] The number of contexts (i.e., requested items).
• slot [IN/OUT] Address of variable that holds the slot number of the slot to be subscribed to the requested data item. (The specified slot must be EMPTY at the time of the call.) If more than one item is being requested, the slot number represents the first slot in a contiguous block of slots, all of which must be EMPTY to receive the named items. A slot number of XC_NEXT_AVAILABLE_SLOT indicates that the requested item(s) are to be added starting at the first free slot in the object. Returns the number of the (first) slot allocated.

Returns:

An xerr type indicating the status of the operation.

Common error codes:

XSUCCESS At least one item was successfully requested. (See "Checking the status of individual item requests", below, for more information.)
XINVAL An invalid parameter was supplied.
XBADSLOT Invalid slot number.
XNOTCONNECTED Session not connected.
XTHREAD Invalid field.
XBUSY At least one slot in given range already has an existing item.
XSOCKET Socket error when sending request. Connection in an invalid state.
XBADHANDLE Invalid handle.