| ## sec_rgy_pgo_get_next(3sec) Returns the next PGO item in the registry database Synopsis #include <dce/pgo.h> void sec_rgy_pgo_get_next( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t scope, 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 Returns the next principal item. sec_rgy_domain_group Returns the next group item. sec_rgy_domain_org Returns the next organization item. 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. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_next( ) 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 the value 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 name of the returned 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_next( ) routine returns the data and name for the PGO in the registry database indicated by item_cursor. It also advances the cursor to point to the next PGO item in the database. Successive calls to this routine return all the PGO items in the database of the specified type (given by name_domain), in storage order. The PGO data consists of the following: · The Universal Unique Identifier (UUID) of the PGO item. · The UNIX number for the PGO item. · The quota for subaccounts. · The full name of the PGO item. · Flags indicating whether - A principal item is an alias. - The PGO item can be deleted. - A principal item can have a concurrent group set. - A group item can appear on a concurrent group set. Permissions Required The sec_rgy_pgo_get_next( ) 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. Return Values The routine returns the data for the returned PGO item in pgo_item and the name in name. Files /usr/include/dce/pgo.idl The idl file from which dce/pgo.h was derived. Errors The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. sec_rgy_no_more_entries The cursor is at the end of the list of PGO items. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. Related Information Functions: sec_intro(3sec) sec_rgy_pgo_add(3sec) sec_rgy_cursor_reset(3sec) sec_rgy_pgo_get_by_id(3sec) sec_rgy_pgo_get_by_name(3sec) sec_rgy_pgo_get_by_unix_num(3sec) sec_rgy_pgo_id_to_unix_num(3sec) sec_rgy_pgo_unix_num_to_id(3sec) ##