1 GETUAF_
 The function of this program is to fetch information from the System
 User Authorization File.  The access key may be either a username or a
 UIC (if multiple defined UIC's only first is returned).   If no access
 key is specified then the information on the current process is 
 obtained.

 Calling Procedure:

    $ GETUAF := $SYS$COM:GETUAF
    $ GETUAF [access_key]

 This program requires suitable privilege to access the system User
 Authorization File.

2 Parameter
 access_key - This is the 'username' or the '[uic]' of the UAF record
    that is desired.  If it is the '[uic]' it must be enclosed in []
    to distinguesh it from a 'username'.

    If no access_key is specified then the UAF information on the 
    current process is returned.

    If the '[uic]' specified has more that one record associated
    with it only the information on the first found is returned.

2 Qualifiers
/ALL=state (D=NEXT)
 This qualifier is used when it is desired to fetch all, or a range,
 of the entries from the UAF.  This is done by first initializing
 GETUAF and then calling repeadly for the next member of the UAF. 
 The values that 'state' may take are as follows: 

    INITIALIZE - is specified on the first call to GETUAF.  GETUAF
        will return the information on the specified 'access_key' or
        if no entry exists for that 'access_key' then the first
        record with a key that is greater than the specified
        'access_key' will be returned. 

    NEXT - is specified on all the calls which follow the INITIALIZE
        call and will return the next sequential entry from the UAF
        until no more entries are found.  The 'access_key' must be
        omitted on calls which specify /ALL=NEXT since the access
        key information comes from logical names created by the
        /ALL=INITIALIZE and updated by the /ALL=NEXT calls.  These
        logical names are GETUAF_USERNAME, GETUAF_UIC, &
        GETUAF_KEYID. 

/ACCOUNT=symbol
 will return the account number from the record, selected by the
 access_key, in the local 'symbol' supplied.

/DEVICE=symbol
 will return the default disk device from the record, selected by
 the access_key, in the local 'symbol' supplied.

/DIRECTORY=symbol
 will return the default directory from the record, selected by the
 access_key, in the local 'symbol' supplied.

/EXACT (D)
/NOEXACT
 This qualifier specifies whether the username access_key specified 
 is to match the name of a user in the User Authorization File 
 exactly or if only the leading characters specified need match.

 If /NOEXACT is specified then the access_key need only match the 
 leading characters of the record key.  This is useful in 
 determining if a potential username to be added to the UAF will 
 generate a directory name which matches an existing directory on 
 the system.  The /NOEXACT will only return the first match.

 The default is /EXACT.

/NEXT_UIC_MEMBER=symbol
 will return the next available (un-used) member number (in octal).
 The group and the lower limit for the search are specified by the
 access_key which must be a UIC specification when this qualifier is
 specified.

 An error will be generated if /USERNAME, /UIC, /ACCOUNT, /DEVICE,
 /DIRECTORY, or /OWNER are specified along with this qualifier.

/NEW_MAIL=symbol
 will return the number of new mail messages for the specified user
 and return the count in the local 'symbol' supplied.  If the user
 has no new mail a value of 0 is returned.

/OWNER=symbol
 will return the owner name from the record, selected by the
 access_key, in the local 'symbol' supplied.

/UAF=file_spec (D=SYS$SYSTEM:'f$logical("SYSUAF")')
 This qualifier will specify then name of an alternate User 
 Authorization File.

 By default the program will translate the logical name SYSUAF and
 append the translated value to SYS$SYSTEM: to find the User
 Authorization File. 

/UIC=symbol
 will return the UIC from the record, selected by the access_key, in
 the local 'symbol' supplied.

/USERNAME=symbol
 will return the username from the record, selected by the
 access_key, in the local 'symbol' supplied.
