NAME
   sec_rgy_attr_update - Creates and updates attribute instances for a
                         specified object

 SYNOPSIS

 #include <dce/sec_rgy_attr.h>

 void sec_rgy_attr_update (
         sec_rgy_handle_t context,
         sec_rgy_domain_t name_domain,
         sec_rgy_name_t name,
         unsigned32 num_to_write,
         unsigned32 space_avail,
         sec_attr_t in_attrs[],
         unsigned32 *num_returned,
         sec_attr_t out_attrs[],
         unsigned32 *num_left,
         signed32 *failure_index,
         error_status_t *status);

 PARAMETERS

 Input

 context
        An opaque handle bound to a registry server.  Use
        sec_rgy_site_open() to acquire a bound handle.

 name_domain
        A value of type sec_rgy_domain_t that identifies the registry
        domain in which the object specified by name resides.  The
        valid values are as follows:

        sec_rgy_domain_person
                    The name identifies a principal.

        sec_rgy_domain_group
                    The name identifies a group.

        sec_rgy_domain_org
                    The name identifies an organization.

 This parameter is ignored if name is policy or replist.

 name   A character string of type sec_rgy_name_t specifying the name
        of the person, group, or organization to which the attribute
        is attached.

 num_to_write
        A 32-bit unsigned integer that specifies the number of elements
        in the in_attrs array.  This integer must be greater than 0.

 space_avail
        A 32-bit unsigned integer that specifies the size of the
        out_attrs array. This integer must be greater than 0.

 in_attrs[]
        An array of values of type sec_attr_t that specifies the
        attribute instances to be updated.  The size of the array is
        determined by num_to_write.

 Output

 num_returned
        A pointer to an unsigned 32-bit integer that specifies the
        number of attribute instances returned in the out_attrs[] array.

 out_attrs
        An array of values of type sec_attr_t that specifies the updated
        attribute instances.  Not that only if these attributes were
        processed by an update attribute trigger server will they differ
        from the attributes in the in_attrs[] array.  The size of the
        array is determined by space_avail and the length by
        num_returned.

 num_left
        A pointer to an unsigned 32-bit integer that supplies the number
        of attributes that could not be returned because of space
        constraints in the out_attrs[] buffer.  To ensure that all the
        attributes will be returned, increase the size of the
        out_attrs[] array by increasing the size of space_avail and
        num_returned.

 failure_index
        In the event of an error, failure_index is a pointer to the
        element in the in_attrs[] array that caused the update to fail.
        If the failure cannot be attributed to a specific attribute,
        the value of failure_index is -1.

 status
        A pointer to the completion status.  On successful completion,
        the routine returns error_status_ok.  Otherwise, it returns an
        error.

 DESCRIPTION

 The sec_rgy_attr_update() routine creates new attribute instances and
 updates existing attribute instances attached to a object specified by
 name and Registry domain.  The instances to be created or updated are
 passed as an array of sec_attr_t data types.  This is an atomic
 operation:  if the creation of any attribute in the in_attrs[] array
 fails, all updates are aborted.  The attribute causing the update to
 fail is identified in failure_index. If the failure cannot be
 attributed to a given attribute, failure_index contains -1.

 The in_attrs array, which specifies the attributes to be created,
 contains values of type sec_attr_t.  These values are:

  +  attr_id, a UUID that identifies the attribute type

  +  attr_value, values of sec_attr_value_t that specify the attribute's
     encoding type and values.

 If an attribute instance already exists which is identical in both
 attr_id and attr_value to an attribute specified in in_attrs, the
 existing attribute information is overwritten by the new information.
 For multi-valued attributes, every instance with the same attr_id is
 overwritten with the supplied values.

 If an attribute instance does not exist, it is created.

 For multi-valued attributes, because every instance of the multi-valued
 attribute is identified by the same UUID, every instance is overwritten
 with the supplied value. To change only one of the values, you must
 supply the values that should be unchanged as well as the new value.

 To create instances of multi-valued attributes, create individual
 sec_attr_t data types to define each multi-valued attribute instance
 and then pass all of them in in the input array.

 If an input attribute is associated with an update attribute trigger
 server, the attribute trigger server is invoked (by the
 sec_attr_trig_update() function) and the in_attr[] array is supplied
 as input. The output attributes from the update attribute trigger server
 are stored in the registry database and returned in the out_attrs[]
 array. Note that the update attribute trigger server may modify the
 values before they are used to update the registry database.  This is
 the only circumstance under which the values in the out_attrs[] array
 differ from the values in the in_attrs[] array.

 Permissions Required

 The sec_rgy_attr_update() routine requires the update permission set
 for each attribute type identified in the in_attrs[] array. These
 permissions are defined as part of the ACL manager set in the schema
 entry of each attribute type.

 FILES

 SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL
              The idl file from which dce/sec_rgy_attr.h was derived.

 ERRORS

 unauthorized

 database read only

 server unavailable

 invalid/unsupported attribute type

 invalid encoding type

 value not unique

 attribute instance already exists

 trigger server unavailable

 site read only

 error_status_ok

 RELATED INFORMATION

 Functions: sec_intro
            sec_rgy_attr_delete
            sec_rgy_attr_test_and_update