DL_DataModify

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_DataInsert

DL_DbClose

DL_DataModify

Library
Description
Errors

Parameters
Return Value
See Also

NAME

DL_DataModify: CSSM_DL_DataModify - Modify persistent data record (CDSA)

SYNOPSIS

# include <cssm.h>

API:
CSSM_RETURN CSSMAPI CSSM_DL_DataModify
(CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier,
const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified,
const CSSM_DATA *DataToBeModified,
CSSM_DB_MODIFY_MODE ModifyMode)
SPI:
CSSM_RETURN CSSMDLI DL_DataModify
(CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier,
const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified,
const CSSM_DATA *DataToBeModified,
CSSM_DB_MODIFY_MODE ModifyMode)

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 to search for records satisfying the query.
`RecordType` (input)
		Indicates the type of data record being modified.
`UniqueRecordIdentifier` (input/output)
		A pointer to a CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with the record to modify. If the modification succeeds, the `UniqueRecordIdentifier` points to a CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with the updated record. If the modification fails, the `UniqueRecordIdentifier` is not modified.
`AttributesToBeModified` (input/optional)
		A list of structures containing the attribute values to be stored in that attribute and the meta information (schema) describing those attributes. The list contains at most one entry per attribute in the specified record type. The specified `AttributeFormat` for each attribute must match that of the database schema, otherwise the error CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string includes a null-terminator, then the length count in the CSSM_DATA structure containing the input string should include the terminating character. (If null-terminators are used, they should be used consistently when storing, searching, and retrieving the string value, otherwise selection predicates will not locate expected matches.) Each attribute specified is modified according to the value of `ModifyMode` (see table in the `DESCRIPTION` section of this definition). Those attributes that are not specified as part of this parameter remain unchanged. If the `AttributesToBeModified` parameter is NULL, no attribute modification occurs.
`DataToBeModified` (input/optional)
		A pointer to the CSSM_DATA structure which contains the opaque data object to be stored in the data record. If this parameter is NULL, no Data modification occurs.
`ModifyMode` (input)
		A CSSM_DB_MODIFY_MODE value indicating the type of modification to be performed on the record attributes identified by `AttributesToBeModified`. If no attributes are specified, then this value must be CSSM_DB_MODIFY_ATTRIBUTE_NONE.

DESCRIPTION

This function modifies the persistent data record identified by the UniqueRecordIdentifier. The modifications are specified by the Attributes and Data parameters. The ModifyMode indicates how the attributes are to be updated. The ModifyMode has no affect on updating the data blob contained in the record. If the data blob is the only record attribute being updated by this function call, then the modification mode must be 0. The current modification modes behave as follows:

ModifyMode Value
Function Behavior

CSSM_DB_MODIFY_ATTRIBUTE_NONE
No Attributes are being updated.

CSSM_DB_MODIFY_ATTRIBUTE_ADD
The specified values are added to the set of current values for each attribute. If 0 values are specified then the error CSSMERR_DL_INVALID_MODIFY_MODE is returned. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.

CSSM_DB_MODIFY_ATTRIBUTE_DELETE
The specified values are removed from the set of current values for each attribute. If 0 values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.

CSSM_DB_MODIFY_ATTRIBUTE_REPLACE
The values for each attribute are replaced with the specified set of values for each attribute. If no values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned when more than 1 value is specified.

If the attribute lists specifies an attribute that is not defined in the database's meta-information, an error condition is returned. For each attribute-value pair, the value replaces the corresponding attribute value in the record. If a data value is specified, the record's data value is replaced with the specified value. A record's data value or attribute values can be set to NULL or zero to represent deletion or the lack of a known value.

If the record referenced by UniqueRecordIdentifier has been modified since the last time it was updated, the error CSSMERR_DL_STALE_UNIQUE_RECORD is returned and no modification takes place.

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_FIELD_SPECIFIED_MULTIPLE
CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
CSSMERR_DL_INVALID_DB_HANDLE
CSSMERR_DL_INVALID_FIELD_NAME
CSSMERR_DL_INVALID_MODIFY_MODE
CSSMERR_DL_INVALID_RECORDTYPE
CSSMERR_DL_INVALID_RECORD_UID
CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
CSSMERR_DL_INVALID_VALUE
CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED
CSSMERR_DL_STALE_UNIQUE_RECORD

`ModifyMode Value`	`Function Behavior`
CSSM_DB_MODIFY_ATTRIBUTE_NONE	No Attributes are being updated.
CSSM_DB_MODIFY_ATTRIBUTE_ADD	The specified values are added to the set of current values for each attribute. If 0 values are specified then the error CSSMERR_DL_INVALID_MODIFY_MODE is returned. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.
CSSM_DB_MODIFY_ATTRIBUTE_DELETE	The specified values are removed from the set of current values for each attribute. If 0 values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned.
CSSM_DB_MODIFY_ATTRIBUTE_REPLACE	The values for each attribute are replaced with the specified set of values for each attribute. If no values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned when more than 1 value is specified.