NAME    [Toc]    [Back]

       DL_DataInsert,  CSSM_DL_DataInsert - Create new persistent
       data record (CDSA)

SYNOPSIS    [Toc]    [Back]

       # include <cdsa/cssm.h>

       API:      CSSM_RETURN      CSSMAPI      CSSM_DL_DataInsert
       (CSSM_DL_DB_HANDLE  DLDBHandle, CSSM_DB_RECORDTYPE RecordType,
  const  CSSM_DB_RECORD_ATTRIBUTE_DATA   *Attributes,
       const     CSSM_DATA    *Data,    CSSM_DB_UNIQUE_RECORD_PTR
       *UniqueId)   SPI:   CSSM_RETURN   CSSMDLI    DL_DataInsert
       (CSSM_DL_DB_HANDLE  DLDBHandle, CSSM_DB_RECORDTYPE RecordType,
  const  CSSM_DB_RECORD_ATTRIBUTE_DATA   *Attributes,
       const     CSSM_DATA    *Data,    CSSM_DB_UNIQUE_RECORD_PTR
       *UniqueId)

LIBRARY    [Toc]    [Back]

       Common Security Services Manager library (libcssm.so)

PARAMETERS    [Toc]    [Back]

       The handle pair that describes  the  add-in  data  storage
       library module to be used to perform this function and the
       open data store in which to insert the  new  data  record.
       Indicates  the type of data record being added to the data
       store 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  nullterminator,
  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.)  For   those
       attributes that are not assigned values by the caller, the
       DL module may assume the values to be the  empty  set,  or
       assume  default  values, or return an error. If the specified
 record type does not  contain  any  attributes,  this
       parameter must be NULL.  A pointer to the CSSM_DATA structure
 which contains the opaque data object to be stored in
       the new data record. If the specified record type does not
       contain an opaque data  object,  this  parameter  must  be
       NULL.  A pointer to a CSSM_DB_UNIQUE_RECORD_PTR containing
       a unique identifier associated with the new  record.  This
       unique  identifier  structure can be used in future references
 to this record during the  current  open  data  base
       session.  The  pointer will be set to NULL if the function
       fails. The  CSSM_DL_FreeUniqueRecord()  function  must  be
       used to deallocate this structure.

DESCRIPTION    [Toc]    [Back]

       This  function creates a new persistent data record of the
       specified type by inserting it  into  the  specified  data
       store.  The  values  contained  in the new data record are
       specified by the Attributes and the  Data.  The  attribute
       value  list  contains  zero  or more attribute values. The
       Attributes parameter also specifies a  record  type.  This
       type must be the same as the type specified by the RecordType
 input parameter. The DL module  may  require  initial
       values  for the CSSM pre-defined attributes. The DL module
       can assume default values for  any  unspecified  attribute
       values  or can return an error condition when DLM-required
       attribute values are not specified by the caller. The Data
       is an opaque object to be stored in the new data record.

       If  a  primary key (concatination of all unique indexes in
       the     relation)     exists,     the      error      CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA
  is returned. The client
       should   call    CSSM_DL_DataGetFirst(),    followed    by
       CSSM_DL_DataModify() to change an existing record.

RETURN VALUE    [Toc]    [Back]

       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    [Toc]    [Back]

       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_FIELD_NAME
    CSSMERR_DL_INVALID_DB_HANDLE
       CSSMERR_DL_INVALID_PARSING_MODULE                     CSSMERR_DL_INVALID_RECORDTYPE
   CSSMERR_DL_INVALID_RECORD_UID
       CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA                  CSSMERR_DL_INVALID_VALUE
 CSSMERR_DL_MISSING_VALUE

SEE ALSO    [Toc]    [Back]

       Books

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

       Reference Pages    [Toc]    [Back]

       Functions for the CSSM API:

       CSSM_DL_DataDelete(3)

       Functions for the DL SPI:

       DL_DataDelete(3)



                                                 DL_DataInsert(3)