NAME
   DL_DataGetFirst, CSSM_DL_DataGetFirst - Get first data record (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_DL_DataGetFirst
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_QUERY *Query,
        CSSM_HANDLE_PTR ResultsHandle,
        CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
        CSSM_DATA_PTR Data,
        CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)
    SPI:
        CSSM_RETURN CSSMDLI DL_DataGetFirst
        (CSSM_DL_DB_HANDLE DLDBHandle,
        const CSSM_QUERY *Query,
        CSSM_HANDLE_PTR ResultsHandle,
        CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
        CSSM_DATA_PTR Data,
        CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

 LIBRARY
   Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

 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 field of this Query structure. If a search
           attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the
           search value specified for that string includes a null-
           terminator, then the length count for that string should
           include the terminating character.     (If null-terminators
           are used they should be used consistently, storing the
           terminator as part of the string in the data store, otherwise
           selection predicates will not locate expected matches.) The
           Query structure attributes also identify the particular
           attributes to be searched by this query. If no query is
           specified, the DL module can return the first record in the
           data store, performing sequential retrieval, or return an
           error. If no selection predicates are specified, the DL
           module can return the first record in the data store,
           performing sequential retrieval, or return an error
           (CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS). When selection
           predicates are specified, the NumberOfValues of the Attribute
           of each selection predicate must be 1.  If any selection
           predicate does not satisfy this requirement, the error
           CSSMERR_DL_INVALID_QUERY is returned.

   ResultsHandle (output)
           This handle should be used to retrieve subsequent records
           that satisfied this query.

   Attributes (optional-input/output)
           If the Attributes structure pointer is NULL, no values are
           returned.

           Otherwise, the DataRecordType, NumberOfAttributes and
           AttributeData fields are read.  AttributeData must be an
           array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE
           elements. Only the Info field of each element is used on
           input. The AttributeFormat field of the Info field is
           ignored on input.

           On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing
           a list of all or the requested attribute values (subset) from
           the retrieved record.  The SemanticInformation field is set.
           For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData
           array, the NumberOfValues field is set to reflect the size of
           the Value array which is allocated by the DL using the
           application specified allocators.  Each CSSM_DATA in the Value
           array will have it's Data field as a pointer to data allocated
           using the application specified allocators containing the
           attributes value, and have it's Length set to the length of the
           value.

           All values for an attribute are returned (this could be 0).
           All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA
           are left unchanged except for the AttributeFormat field,
           which is set to reflect the schema.

   Data (optional-input/output)
           Data values contained in the referenced memory are ignored
           during processing and are overwritten with the retrieved
           opaque object. On output, a CSSM_DATA structure containing
           the opaque object stored in the retrieved record.

   UniqueId (output)
           If successful and (at least) a record satisfying the query has
           been found, then this parameter returns a pointer to a
           CSSM_UNIQUE_RECORD_PTR structure containing a 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 there are no records
           satisfying the query, then this pointer is NULL and
           CSSM_DL_DataGetFirst() must return CSSM_DL_ENDOFDATA; in this
           case a normal termination condition has occurred. The
           CSSM_DL_FreeUniqueRecord() must be used to de-allocate this
           structure.

 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. If the Query specifies an attribute that is not defined
   in the database's meta-information, an error condition is returned.
   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. The output buffers for the retrieved record
   are allocated by this function using the memory management functions
   provided during the module attach operation. This function also
   returns a results handle to be used when retrieving subsequent records
   satisfying the query.

   Additional matching records are iteratively retrieved using the
   CSSM_DL_DataGetNext() function . The data storage module supports
   one of two retrieval models:

     ·  Transactional - all query results are determined at initial
        query evaluation. Results do not change during an incremental
        retrieval process.

     ·  File System Scan - query results are selected during the
        incremental retrieval process. Records matching the query may
        be added to or deleted from the underlying data store during
        the iterative retrieval.  The caller may receive the new
        matching records and not received the deleted records.

   The caller can determine which retrieval model is supported by
   examining the encapsulated product description for this data
   storage module.

   If the query selection criteria also specifies time for space limits
   for executing the query, those limits also apply ro 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. Once a user has finished using a certain query, it must call
   CSSM_DataAbortQuery() for releasing resources that CSSM uses.  If all
   records satisfying the query have been retrieved, then query is
   automatically terminated.

 RETURN VALUE
   A CSSM_RETURN value indicating success or specifying a particular
   error condition. The value CSSM_OK indicates success. All other
   values represent an error condition.

 ERRORS
   Errors are described in the CDSA technical standard.  See CDSA.

        CSSMERR_DL_ENDOFDATA
        CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
        CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
        CSSMERR_DL_INVALID_DB_HANDLE
        CSSMERR_DL_INVALID_FIELD_NAME
        CSSMERR_DL_INVALID_PARSING_MODULE
        CSSMERR_DL_INVALID_QUERY
        CSSMERR_DL_INVALID_RECORDTYPE
        CSSMERR_DL_INVALID_RECORD_UID
        CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT
        CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS
        CSSMERR_DL_UNSUPPORTED_OPERATOR
        CSSMERR_DL_UNSUPPORTED_QUERY
        CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_DataGetNext
       CSSM_DL_DataAbortQuery

   Functions for the DL SPI:

       DL_DataGetNext
       DL_DataAbortQuery