NAME

CSSM_DL_DataGetFirst

SYNOPSIS

CSSM_DB_UNIQUE_RECORD_PTR CSSMAPI CSSM_DL_DataGetFirst
    (CSSM_DL_DB_HANDLE DLDBHandle,
    const CSSM_QUERY_PTR Query,
    CSSM_HANDLE_PTR ResultsHandle,
    CSSM_BOOL *EndOfDataStore,
    CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
    CSSM_DATA_PTR Data)

DESCRIPTION

This function retrieves the first data record in the data store that matches the selection criteria. The selection criteria (including selection predicate and comparison values) is specified in the Query structure. The DL module can use internally-managed indexing structures to enhance the performance of the retrieval operation. This function selects the first record satisfying the query based on the list of Attributes and the opaque Data object. This function also returns a flag indicating whether additional records also satisfied the query and a results handle to be used when retrieving subsequent records satisfying the query. If the query selection criteria specifies time or space limits for executing the query, those limits also apply to retrieval of the additional selected data records retrieved using the CSSM_DL_DataGetNext function. Finally, this function returns a unique record identifier associated with the retrieved record. This structure can be used in future references to the retrieved data record.

PARAMETERS

DLDBHandle (input)

The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for records satisfying the query.

Query (input/optional)

The query structure specifying the selection predicate(s) used to query the data store. The structure contains meta information about the search fields and the relational and conjunctive operators forming the selection predicate. The comparison values to be used in the search are specified in the Attributes and Data parameter. The CSSM pre-defined attribute names "PrintName" and "Alias" are valid in any query, regardless of the stored value for those attributes. If no query is specified, the DL module can return the first record in the data store, performing sequential retrieval, or return an error.

ResultsHandle (output)

This handle should be used to retrieve subsequent records that satisfied this query.

EndOfDataStore (output)

A flag indicating whether a record satisfying this query was available to be retrieved in the current operation. If TRUE, then a record was available and was retrieved unless an error condition occurred. If FALSE, then all records satisfying the query have been previously retrieved, and no record has been returned by this operation.

Attributes (output)

A list of attribute values (and corresponding meta information) from the retrieved record.

Data (output)

The opaque object stored in the retrieved record.

RETURN VALUE

If successful and EndOfDataStore is FALSE, this function returns a pointer to a CSSM_UNIQUE_RECORD structure containing unique identifier associated with the retrieved record. This unique identifier structure can be used in future references to this record using this DLDBHandle pairing. It may not be valid for other DLHandles targeted to this DL module or to other DBHandles targeted to this data store. If the pointer is NULL and EndOfDataStore is TRUE, then a normal termination condition has occurred. If the pointer is NULL and EndOfDataStore is FALSE, then an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_DL_INVALID_DL_HANDLE

Invalid DL handle.

CSSM_DL_INVALID_DB_HANDLE

Invalid DB handle.

CSSM_DL_INVALID_SELECTION_PRED

Invalid selection predicate.

CSSM_DL_NO_DATA_FOUND

No data records match the selection predicate.

CSSM_DL_DATA_GETFIRST_FAIL

An exception occurred when processing the query.

CSSM_DL_MEMORY_ERROR

Error in allocating memory.

SEE ALSO

CSSM_DL_DataGetNext, CSSM_DL_DataAbortQuery