DL_DataGetNext

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP Open Source Security for OpenVMS Volume 1:...

API Functions

DL_DataGetFromUniqueRecordId

DL_DataInsert

DL_DataGetNext

Library
Description
Errors

Parameters
Return Value
See Also

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 deallocate 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.

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