DL_DataGetFirst

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_DataDelete

DL_DataGetFromUniqueRecordId

DL_DataGetFirst

Library
Description
Errors

Parameters
Return Value
See Also

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 storagelibrary module to be used to perform this function and the opendata 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 informationabout the search fields and the relational and conjunctive operatorsforming the selection predicate. The comparison values to be usedin the search are specified in the Attributes field of this Querystructure. If a search attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRINGand the search value specified for that string includes a null-terminator,then the length count for that string should include the terminatingcharacter. (If null-terminators are used they should be used consistently, storingthe terminator as part of the string in the data store, otherwiseselection predicates will not locate expected matches.) The Querystructure attributes also identify the particular attributes tobe searched by this query. If no query is specified, the DL module canreturn the first record in the data store, performing sequentialretrieval, or return an error. If no selection predicates are specified,the DL module can return the first record in the data store, performingsequential retrieval, or return an error (CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS).When selection predicates are specified, the `NumberOfValues` ofthe `Attribute` of each selection predicate mustbe 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 subsequentrecords that satisfied this query.
`Attributes` (optional-input/output)
		If the `Attributes` structure pointeris NULL, no values are returned. Otherwise, the `DataRecordType`, `NumberOfAttributes` and `AttributeData` fieldsare read. `AttributeData` must be an array of `NumberOfAttributes` CSSM_DB_RECORD_ATTRIBUTEelements. Only the `Info` field of each elementis used on input. The `AttributeFormat` field ofthe `Info` field is ignored on input. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containinga list of all or the requested attribute values (subset) from theretrieved record. The `SemanticInformation` fieldis set. For each CSSM_DB_ATTRIBUTE_DATA contained in the `AttributeData` array,the `NumberOfValues` field is set to reflect thesize of the `Value` array which is allocated bythe DL using the application specified allocators. Each CSSM_DATAin the `Value` array will have it's `Data` fieldas a pointer to data allocated using the application specified allocatorscontaining the attributes value, and have it's `Length` setto 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_DATAare left unchanged except for the `AttributeFormat` field, whichis set to reflect the schema.
`Data` (optional-input/output)
		Data values contained in the referenced memory areignored during processing and are overwritten with the retrievedopaque object. On output, a CSSM_DATA structure containing the opaqueobject stored in the retrieved record.
`UniqueId` (output)
		If successful and (at least) a record satisfyingthe query has been found, then this parameter returns a pointerto a CSSM_UNIQUE_RECORD_PTR structure containing a unique identifierassociated with the retrieved record. This unique identifier structurecan be used in future references to this record using this `DLDBHandle` pairing.It may not be valid for other `DLHandles` targetedto this DL module or to other `DBHandles` targetedto 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 terminationcondition has occurred. The `CSSM_DL_FreeUniqueRecord()` must be used to deallocate this structure.

DESCRIPTION

This function retrieves the first data record in the datastore that matches the selection criteria. The selection criteria(including selection predicate and comparison values) is specifiedin the Query structure. If the Query specifies an attribute thatis not defined in the database's meta-information, an error conditionis returned. The DL module can use internally-managed indexing structuresto enhance the performance of the retrieval operation. This functionselects the first record satisfying the query based on the listof Attributes and the opaque Data object. The output buffers forthe retrieved record are allocated by this function using the memorymanagement functions provided during the module attach operation.This function also returns a results handle to be used when retrievingsubsequent records satisfying the query.

Additional matching records are iteratively retrieved usingthe CSSM_DL_DataGetNext() function . The data storage module supports one of tworetrieval models:

Transactional - all query resultsare determined at initial query evaluation. Results do not changeduring an incremental retrieval process.

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

The caller can determine which retrieval model is supportedby examining the encapsulated product description for this datastorage module.

If the query selection criteria also specifies time for spacelimits for executing the query, those limits also apply ro retrievalof the additional selected data records retrieved using the CSSM_DL_DataGetNext() function. Finally, this function returns a unique recordidentifier associated with the retrieved record. This structurecan be used in future references to the retrieved data record. Oncea user has finished using a certain query, it must call CSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfyingthe query have been retrieved, then query is automatically terminated.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particularerror condition. The value CSSM_OK indicates success. All othervalues represent an error condition.

ERRORS

Errors are described in the CDSA Technical Standard.

CSSMERR_DL_ENDOFDATACSSMERR_DL_FIELD_SPECIFIED_MULTIPLECSSMERR_DL_INCOMPATIBLE_FIELD_FORMATCSSMERR_DL_INVALID_DB_HANDLECSSMERR_DL_INVALID_FIELD_NAMECSSMERR_DL_INVALID_PARSING_MODULECSSMERR_DL_INVALID_QUERYCSSMERR_DL_INVALID_RECORDTYPECSSMERR_DL_INVALID_RECORD_UIDCSSMERR_DL_UNSUPPORTED_FIELD_FORMATCSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDSCSSMERR_DL_UNSUPPORTED_OPERATORCSSMERR_DL_UNSUPPORTED_QUERYCSSMERR_DL_UNSUPPORTED_QUERY_LIMITS