Previous section.

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group




    const CSSM_QUERY_PTR Query,
    CSSM_HANDLE_PTR  ResultsHandle,
    CSSM_BOOL  *EndOfDataStore,
    CSSM_DATA_PTR  Data)


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. The DL module can use internally managed indexing structures to enhance the performance of the retrieval operation. This function returns the first record satisfying the query in the list of Attributes and the opaque Data object. This function also returns a flag indicating whether any records satisfied the query and, if so, a results handle to be used when retrieving subsequent records satisfying the query. If the query selection criteria specifies time or space limits for executing the query, those limits also apply to 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.


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 and Data parameter. The CSSM pre-defined attribute names "PrintName" and "Alias" are valid in any query, regardless of the stored value for those attributes. If no query is specified, the DL module can return the first record in the data store (that is, perform sequential retrieval) or return an error.

ResultsHandle (output)

This handle should be used to retrieve subsequent records that satisfied this query.

EndOfDataStore (output)

A flag indicating whether additional unretrieved records satisfied the query. If TRUE, then additional records satisfying the query can be retrieved using CSSM_DL_DataGetNext. If FALSE, then all records satisfying the query have been retrieved.

Attributes (input/output)

The calling application specifies the names of the attributes to be retrieved. The DL module fills in these attributes' values for the retrieved record. If the Attributes pointer is NULL, the DL module should not return the record's attributes.

Data (output)

The opaque object stored in the retrieved record. If the Data pointer is NULL, the DL module should not return the record's data.


If successful and EndOfDataStore is FALSE, this function returns a pointer to a CSSM_UNIQUE_RECORD 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 the pointer is NULL and EndOfDataStore is TRUE, then a normal termination condition has occurred. If the pointer is NULL and EndOfDataStore is FALSE, then an error has occurred. Use CSSM_GetError to obtain the error code.



Invalid DL handle.


Invalid DB handle.


Invalid selection predicate.


No data records match the selection predicate.


An exception occurred when processing the query.


Error in allocating memory.


DL_DataGetNext, DL_DataAbortQuery

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents Next section Index