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

 NAME
   sec_rgy_acct_lookup - Returns data for a specified account

 SYNOPSIS

   #include <dce/acct.h>

   void sec_rgy_acct_lookup(
           sec_rgy_handle_t context,
           sec_rgy_login_name_t *name_key,
           sec_rgy_cursor_t *account_cursor,
           sec_rgy_login_name_t *name_result,
           sec_rgy_sid_t *id_sid,
           sec_rgy_unix_sid_t *unix_sid,
           sec_rgy_acct_key_t *key_parts,
           sec_rgy_acct_user_t *user_part,
           sec_rgy_acct_admin_t *admin_part,
           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_key
          A pointer to the account login name.  A login name is composed
          of three character strings, containing the principal, group,
          and organization (PGO) names corresponding to the account.
          Blank strings serve as wildcards, matching any entry.

   Input/Output

   account_cursor
          An opaque pointer to a specific account in the registry database.
          If name_key is blank, sec_rgy_acct_lookup() returns information
          about the account to which the cursor is pointing. On return,
          the cursor points to the next account in the database after the
          returned account.  If name_key is blank and the account_cursor
          has been reset with sec_rgy_cursor_reset(),
          sec_rgy_acct_lookup() returns information about the first
          account in the database.  When the end of the list of accounts
          in the database is reached, the routine returns the value
          sec_rgy_no_more_entries in the status parameter.  Use
          sec_rgy_cursor_reset() to refresh the cursor.

   Output

   name_result
          A pointer to the full login name of the account (including all
          three names) for which the information is returned.  The
          remaining parameters contain the information belonging to the
          returned account.

   id_sid
          A structure containing the three UUIDs of the principal, group,
          and organization for the account.

   unix_sid
          A structure containing the three UNIX numbers of the principal,
          group, and organization for the account.

   key_parts
          A pointer to the minimum abbreviation allowed when logging in
          to the account. Abbreviations are not currently implemented
          and the only legal value is sec_rgy_acct_key_person.

   user_part
          A pointer to the sec_rgy_acct_user_t structure containing the
          user part of the account data. This represents such information
          as the account password, home directory, and default shell, all
          of which are accessible to, and may be modified by, the account
          owner.

   admin_part
          A pointer to the sec_rgy_acct_admin_t structure containing the
          administrative part of an account's data. This information
          includes the account creation and expiration dates and flags
          describing limits to the use of privilege attribute
          certificates, among other information, and can be modified
          only by an administrator.

   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_acct_lookup() routine returns all the information about
   an account in the registry database. The account can be specified
   either with name_key or account_cursor. If name_key is completely
   blank, the routine uses the account_cursor value instead.

   For name_key, a zero-length principal, group, or organization key
   serves as a wildcard.  For example, a login name key with the
   principal and organization fields blank returns the next (possibly
   first) account whose group matches the input group field.  The full
   login name of the returned account is passed back in name_result.

   The account_cursor provides an automatic place holder in the registry
   database.  The routine automatically updates this variable to point to
   the next account in the database, after the account for which the
   information was returned. If name_key is blank and the account_cursor
   has been reset with sec_rgy_cursor_reset()*O, sec_rgy_acct_lookup()
   returns information about the first account in the database.

   Permissions Required

   The sec_rgy_acct_lookup() routine requires the r (read) permission
   on the account principal 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]ACCT.IDL
                The idl file from which dce/acct.h was derived.

 ERRORS

   sec_rgy_no_more_entries
                The cursor is at the end of the accounts in the registry.

   sec_rgy_object_not_found
                The input account could not be found by the registry
                server.

   sec_rgy_server_unavailable
                The DCE Registry Server is unavailable.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_rgy_cursor_reset
              sec_rgy_acct_replace_all
              sec_rgy_acct_admin_replace
              sec_rgy_acct_user_replace