NAME
   DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record (CDSA)

 SYNOPSIS
   # include <cssm.h>

    API:
        CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_HANDLE ResultsHandle,
        CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
        CSSM_DATA_PTR Data,
        CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)
    SPI:
        CSSM_RETURN CSSMDLI DL_DataGetNext
        (CSSM_DL_DB_HANDLE DLDBHandle,
        CSSM_HANDLE 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 from which records were selected by
           the initiating query.

   ResultsHandle (input)
           The handle identifying a set of records retrieved by a query
           executed by the CSSM_DL_DataGetFirst() function.

   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. If the
           pointer is data structure pointer is NULL, the opaque object
           is not returned.

   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 more
           records satisfying the query, then this pointer is NULL and
           CSSM_DL_DataGetNext() 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 returns the next data record referenced by the
   ResultsHandle.  The ResultsHandle references a set of records
   selected by an invocation of the DataGetFirst function. The
   Attributes parameter can specify a subset of the attributes to be
   returned. If Attributes specifies an attribute that is not defined
   in the database's meta-information, an error condition is returned.
   The record values are returned in the Attributes and Data parameters.
   The output buffers for the retrieved record are allocated by this
   function using the memory management functions provided during the
   module attach operation. The function also returns a unique record
   identifier for the return record.

   The data storage module supports one of two retrieval models:
   transactional or file system scan. The transactional model freezes
   the set of records to be retrieved at query initiation. The file
   system scan model selects from a potentially changing set of records
   during the retrieval process. The EndOfDataStore() function indicates
   when all matching records have been retrieved. The caller can
   determine which retrieval model is supported by examining the
   encapsulated product description for this data storage module.  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_RECORDTYPE
        CSSMERR_DL_INVALID_RECORD_UID
        CSSMERR_DL_INVALID_RESULTS_HANDLE

 SEE ALSO
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_DataGetFirst
       CSSM_DL_DataAbortQuery

   Functions for the DL SPI:

       DL_DataGetFirst
       DL_DataAbortQuery