NAME
   sec_rgy_attr_lookup_by_name - Read a single attribute instance for a
                                 specific object

 SYNOPSIS

 #include <dce/sec_rgy_attr.h>

 void sec_rgy_attr_lookup_by_name(
         sec_rgy_handle_t context,
         sec_rgy_domain_t name_domain,
         sec_rgy_name_t name,
         char *attr_name,
         sec_attr_t *attr,
         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 domain in
        which the named object resides.  The valid values are as follows:

        sec_rgy_domain_principal
                    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 pointer to a sec_rgy_name_t character string containing
        the name of the person, group, or organization to which the
        attribute is attached.

 attr_name
        An pointer to a character string that specifies the name of the
        attribute to be retrieved.

 Output

 attr   A pointer to a sec_attr_t that contains the first instance
        of the named attribute.

 status
        A pointer to the completion status.  The completion status can
        be one of the following:

         + error_status_ok if all instances of the value are returned
           with no errors.

         + more_available if a multi-valued attribute was specified
           as name and the routine completed successfully. For multi-
           valued attributes, this routine returns the first instance
           of the attribute.

         + attribute_set_instance  if an attribute set was specified
           as name and the routine completed successfully.

         + An error message is the routine did not complete
           successfully.

 DESCRIPTION

 The sec_rgy_attr_lookup_by_name() routine returns the named attribute
 for a named object. This routine is useful for an interactive editor.

 For multi-valued attributes, this routine returns the first instance
 of the attribute. To retrieve every instance of the attribute, use the
 sec_rgy_attr_lookup_by_id call, supplying the attribute UUID returned
 in the attr parameter.

 For attribute sets, the routine returns the attribute set instance,
 not the member instances. To retrieve all members of the set, use the
 sec_rgy_attr_lookup_by_id call, supplying the the attribute set UUID
 returned in the attr parameter.

 Warning

 This routine does not provide for input data to an attribute trigger
 query operation.  If the named attribute is associated with a query
 attribute trigger, the attribute trigger will be called with no input
 attribute value information.

 Permissions Required

 The sec_rgy_attr_lookup_by_name() routine requires the query permission
 set for the attribute type of the attribute instance identified by
 attr_name.  These permissions are defined as part of the ACL manager
 set in the schema entry of each attribute type

 ERRORS

 unauthorized

 registry server unavailable

 trigger server unavailable

 error_status_ok

 RELATED INFORMATION

 Functions: sec_intro
            sec_rgy_attr_lookup_by_id
            sec_rgy_attr_lookup_no_expand