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

 SYNOPSIS
   # include <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
   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 in which to insert the new data record.

   RecordType (input)
           Indicates the type of data record being added to the data
           store

   Attributes (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.) 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.

   Data (input/optional)
           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.

   UniqueId (output)
           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
   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
   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.

        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
   Books

   Intel CDSA Application Developer's Guide (see CDSA)

   Other Help Topics

   Functions for the CSSM API:

       CSSM_DL_DataDelete

   Functions for the DL SPI:

       DL_DataDelete