NAME
   sec_rgy_pgo_get_by_id - Returns the name and data for a PGO item
                           identified by its UUID

 SYNOPSIS

 #include <dce/pgo.h>

 void sec_rgy_pgo_get_by_id(
         sec_rgy_handle_t context,
         sec_rgy_domain_t name_domain,
         sec_rgy_name_t scope,
         uuid_t *item_id,
         boolean32 allow_aliases,
         sec_rgy_cursor_t *item_cursor,
         sec_rgy_pgo_item_t *pgo_item,
         sec_rgy_name_t name,
         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
        This variable identifies the type of the principal, group, or
        organization (PGO) item identified by the given name.  The
        valid values are as follows:

        sec_rgy_domain_person
                    The UUID identifies a principal.

        sec_rgy_domain_group
                    The UUID identifies a group.

        sec_rgy_domain_org
                    The UUID identifies an organization.

 scope  A character string (type sec_rgy_name_t) containing the scope
        of the desired search. The registry database is designed to
        accommodate a tree-structured name hierarchy. The scope of a
        search is the name of the branch under which the search takes
        place. For example, all names in a registry might start with
        /alpha, and be divided further into /beta or /gamma. To search
        only the part of the database under /beta, the scope of the
        search would be /alpha/beta, and any resulting PGO items would
        have names beginning with this string. Note that these naming
        conventions need not have anything to do with group or
        organization PGO item membership lists.

 item_id
        A pointer to the uuid_t variable containing the UUID (Unique
        Universal Identifier) of the desired PGO item.

 allow_aliases
        A boolean32 value indicating whether to search for a primary
        PGO item, or whether the search can be satisfied with an alias.
        If TRUE, the routine returns the next entry found for the PGO
        item. If FALSE, the routine returns only the primary entry.

 Input/Output

 item_cursor
        An opaque pointer indicating a specific PGO item entry in the
        registry database. The sec_rgy_pgo_get_by_id() routine returns
        the PGO item indicated by item_cursor, and advances the cursor
        to point to the next item in the database.  When the end of the
        list of entries is reached, the routine returns
        sec_rgy_no_more_entries in the status parameter.  Use
        sec_rgy_cursor_reset() to reset the cursor.

 Output

 pgo_item
        A pointer to a sec_rgy_pgo_item_t structure to receive the data
        for the returned PGO item. The data in this structure includes
        the PGO item's name, UUID, UNIX number (if any), and
        administrative data, such as whether the item, if a principal,
        may have a concurrent group set.

 name   A pointer to a sec_rgy_name_t character string containing the
        returned name for the PGO item.

 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_pgo_get_by_id() routine returns the name and data for
 a PGO item. The desired item is identified by its type (domain) and
 its UUID.

 The item_cursor parameter specifies the starting point for the search
 through the registry database.  It provides an automatic place holder
 in the database.  The routine automatically updates this variable to
 point to the next PGO item after the returned item.  The returned
 cursor location can be supplied on a subsequent database access call
 that also uses a PGO item cursor.

 Permissions Required

 The sec_rgy_pgo_get_by_id() routine requires the r (read) permission
 on the PGO item to be viewed.

 CAUTIONS

 There are several different types of cursors used in the registry
 Application Programmer Interface (API). Some cursors point to PGO
 items, others point to members in a membership list, and others point
 to account data. Do not use a cursor for one sort of object in a call
 expecting another sort of object. For example, you cannot use the
 same cursor on a call to sec_rgy_acct_get_projlist() and
 sec_rgy_pgo_get_next().  The behavior in this case is undefined.

 Furthermore, cursors are specific to a server. A cursor pointing
 into one replica of the registry database is useless as a pointer
 into another replica.

 Use sec_rgy_cursor_reset() to renew a cursor for use with another
 call or for another server.

 FILES

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

 ERRORS

 sec_rgy_no_more_entries
              The cursor is at the end of the list of PGO items.

 sec_rgy_object_not_found
              The specified PGO item was not found.

 sec_rgy_server_unavailable
              The DCE Registry Server is unavailable.

 error_status_ok
              The call was successful.

 RELATED INFORMATION

 Functions: sec_intro
            sec_rgy_pgo_add
            sec_rgy_pgo_get_by_name
            sec_rgy_pgo_get_by_unix_num
            sec_rgy_pgo_get_next
            sec_rgy_pgo_id_to_name
            sec_rgy_pgo_id_to_unix_num
            sec_rgy_pgo_name_to_id
            sec_rgy_pgo_unix_num_to_id
            sec_rgy_cursor_reset