Search:

As defined in xcapi.h

Description:

Reads one or more contiguous array-field-element values from an object. Indexing notation may be appended to the field ID if the initial element to extract is not the zeroeth. (See the fieldID parameter, below, for a description of the indexing notation.) This function should not be called for non-array-type field if anything other than the zeroeth element is to be retrieved.

Note that the API includes a set of built-in conversion routines, as documented in this Reference Guide.

Parameters:

• object [IN] The handle to the object.
• slot [IN] Slot number (or slot constant) identifying the targeted field's data item. A slot constant is used in two situations: (1) If an event or session object field is targeted, the slot constant "XC_EVENT" (for an event object), or "XC_SESSION" (for a session object) must be used. (These objects always have a single slot; therefore, numerical slot identification is never required for them.). (2) If an object-Level (as opposed to item-Level) container field is targeted, the slot constant "XC_CONTAINER" is used.
• fieldID [IN] ID of the array field + the index number for the initial element to extract: thus "fieldID+n", where n is the index number of the initial element to be extracted. The default, if no index notation is appended, is assumed to be "+0", i.e., the zeroeth element. (The number of contiguous elements to be extracted is set as the elmcnt parameter.)
• obuf [IN] Address of output buffer.
• elmsiz [IN] Size of each element to be retrieved (in bytes). Note that the size passed in must be large enough to contain each of the requested element values, but may also be larger. Bytes beyond those required by the field itself will not be written to by this function.
• elmcnt [IN/OUT] Maximum number of elements to retrieve (output is actual number retrieved).

Returns:

An xerr type indicating the status of the operation.

Common error codes:

XSUCCESS The operation completed successfully.
XINVAL An invalid parameter was supplied.
XBADSLOT Invalid slot number.
XBADFIELD Invalid field. (For example, variable length fields are invalid for array retrieval. This status is also returned if xcGetFieldArray() is called for an element other than the zeroeth in a non-array-type field.)
XOVERFLOW Result would overflow supplied buffer.
XPENDING Object has not received data yet.
XNODATA Could not find requested data.
XUNINIT Slot has not been subscribed to data.
XNOTCONNECTED Session not connected.
XBADSTATE Slot is empty.
XBADHANDLE Invalid handle.