VMS Help DCE_SECURITY, API Routines, sec_rgy_attr_test_and_update  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   sec_rgy_attr_test_and_update - Updates specified attribute instances
                                  for a specified object only if a set
                                  of control attribute instances match
                                  the object's existing attribute instances

 SYNOPSIS

   #include <dce/sec_rgy_attr.h>

   void sec_rgy_attr_test_and_update (
           sec_rgy_handle_t context,
           sec_rgy_domain_t name_domain,
           sec_rgy_name_t name,
           unsigned32 num_to_test,
           sec_attr_t test_attrs[],
           unsigned32 num_to_write,
           sec_attr_t update_attrs[],
           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_test
          An unsigned 32-bit integer that specifies the number of elements
          in the test_attrs[] array.  This integer must be greater than 0.

   test_attrs[]
          An array of values of type sec_attr_t that specifies the control
          attributes.  The update takes place only if the types and values
          of the control attributes exactly match those of the attribute
          instances on the named registry object. The size of the array is
          determined by num_to_test.

   num_to_write
          A 32-bit integer that specifies the number of attribute
          instances returned in the update_attrs[] array.

   update_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

   failure_index
          In the event of an error, failure_index is a pointer to the
          element in the update_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_test_and_update() routine updates an attribute only
   if the set of control attributes specified in the test_attrs[] match
   attributes that already exist for the object.

   This update is an atomic operation:  if any of the control attributes
   do not match existing attributes, none of the updates are performed,
   and if an update should be performed, but the write cannot occur for
   whatever reason to any member of the update_attrs[] array, 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.

   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.

   If you specify an attribute set for updating, the update applies to the
   set instance, the set itself, not the members of the set.  To update a
   member of an attribute set, supply the UUID of the set member.

   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_test_and_update() routine routine requires the test
   permission and the update permission set set for each attribute type
   identified in the test_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

   control attribute has changed

   unauthorized

   database read only

   server unavailable

   invalid/unsupported attribute type

   invalid encoding type

   value not unique

   trigger server unavailable

   site read only

   error_status_ok

 RELATED INFORMATION

   Functions: sec_intro
              sec_rgy_attr_update
              sec_rgy_attr_delete