Search:

As defined in xcapi.h

Description:

Reads an individual field value from an object slot. The output buffer size must be sufficient to hold the requested field value, but may also be larger, as described for the obufsiz parameter. If this function is called on an array field, the value of only one array-field element can be extracted, and the zeroeth element is extracted by default. (See the fieldID parameter for a description of the indexing notation available to extract an element other than the zeroeth.) To extract more than one element value from an array field, use xcGetFieldArray(). 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 field to be extracted. For array fields, index notation can be appended to the Field ID, as "fieldID+n", where n is the index number for the desired element in the field array. (The default, if no index notation is appended, is assumed to be "+0", i.e., the zeroeth element.).
• obuf [IN] Address of output buffer.
• obufsiz [IN] Size of output buffer (in bytes). Note that the specified output buffer size must be large enough to contain the requested field value, but may also be larger. Bytes beyond those required by the field itself will not be written to by this function.

Returns:

An xerr type indicating the status of the operation.

Common error codes:

XSUCCESS The operation completed successfully.
XMOREDATA Successful completion, but only partial data returned due to buffer size. (Applicable to variable-length fields only.)
XINVAL An invalid parameter was supplied.
XBADSLOT Invalid slot number.
XBADFIELD Invalid field.
XTIME Timer expired.
XOVERFLOW Result would overflow supplied buffer.
XNODATA Could not find requested data.
XUNINIT Slot has not been subscribed to data.
XPENDING Object has not received data yet.
XBADSTATE Slot is empty.
XBADHANDLE Invalid handle.