DL_DataGetFromUniqueRecordId

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_DataGetFirst

DL_DataGetNext

DL_DataGetFromUniqueRecordId

Library
Description
Errors

Parameters
Return Value
See Also

NAME

DL_DataGetFromUniqueRecordId: CSSM_DL_DataGetFromUniqueRecordId - Get data record (CDSA)

SYNOPSIS

# include <cssm.h>

API:CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId(CSSM_DL_DB_HANDLE DLDBHandle,const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,CSSM_DATA_PTR Data)SPI:CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId(CSSM_DL_DB_HANDLE DLDBHandle,const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord,CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,CSSM_DATA_PTR Data)

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 the data record.
`UniqueRecord` (input)
		The pointer to a unique record structure returnedfrom a `DL_DataInsert`, `DL_DataGetFirst`,or `DL_DataGetNext` operation.
`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. If the pointer is data structure pointeris NULL, the opaque object is not returned.

DESCRIPTION

This function retrieves the data record and attributes associatedwith this unique record identifier. The Attributes parametercan specify a subset of the attributes to be returned. If Attributes specifiesan attribute that is not defined in the database's meta-information,an error condition is returned. The output buffers for the retrievedrecord are allocated by this function using the memory managementfunctions provided during the module attach operation. The DL modulecan use an indexing structure identified in the UniqueRecordId toenhance the performance of the retrieval operation.

The DL should assume that the value of CSSM_QUERY_FLAGS iswhen performing this operation. In particular this means that ifthe data of a key record is being retrieved, the DL will returna CSSM_KEY structure with a key reference.

If the record referenced by UniqueRecordIdentifier hasbeen modified since the last time it was retrieved, the error (warning)CSSMERR_DL_RECORD_MODIFIED is returned but the requested attributesand data of the new record is returned. The caller should be advisedthat other attributes (or the data) might have changed that werenot fetched from the DL with this call.

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_FIELD_SPECIFIED_MULTIPLECSSMERR_DL_INCOMPATIBLE_FIELD_FORMATCSSMERR_DL_INVALID_DB_HANDLECSSMERR_DL_INVALID_FIELD_NAMECSSMERR_DL_INVALID_RECORDTYPECSSMERR_DL_INVALID_RECORD_UID