Index Index for
Section 3
Index Alphabetical
listing for D
Bottom of page Bottom of
page		 

DL_DataModify(3)


NAME

  DL_DataModify, CSSM_DL_DataModify - Modify persistent data record (CDSA)


SYNOPSIS

  # include <cdsa/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 (libcssm.so)


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
				     No Attributes are being updated.

  CSSM_DB_MODIFY_ATTRIBUTE_NONE

  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.	See CDSA_intro(3).

       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


SEE ALSO

  Books

  Intel CDSA Application Developer's Guide (see CDSA_intro(3))

  Reference Pages

  Functions for the CSSM API:

  CSSM_DL_DataInsert(3), CSSM_DL_DataDelete(3)

  Functions for the DL SPI:

  DL_DataInsert(3), DL_DataDelete(3)

Index Index for
Section 3
Index Alphabetical
listing for D
Top of page Top of
page