Index Index for
Section 3
Index Alphabetical
listing for D
Bottom of page Bottom of
page		 

DL_DataGetNext(3)


NAME

  DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record (CDSA)


SYNOPSIS

  # include <cdsa/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 (libcssm.so)


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_intro(3).

       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_intro(3))

  Reference Pages

  Functions for the CSSM API:

  CSSM_DL_DataGetFirst(3), CSSM_DL_DataAbortQuery(3)

  Functions for the DL SPI:

  DL_DataGetFirst(3), DL_DataAbortQuery(3)

Index Index for
Section 3
Index Alphabetical
listing for D
Top of page Top of
page