!
! UAC V2.0 by FJN on 16-Mar-1984
!
1 UAC
 UAC stands for User Access/Authorization Checker.  UAC is a program
 to maintain a file of usernames and hashed passwords to restrict
 access to turnkey accounts (creating a semi-turnkey environment to
 divide a single VMS account into subaccounts).  UAC is defined as a
 foreign DCL symbol via:

	$ UAC :== $FERMI$UTIL:UAC

 UAC is invoked via a command line of the format:

	$ UAC  action  [parameters...]

 The various action keywords are CHANGE, CHECK and EDIT.  See those
 subtopics for further details.  UAC is meant to be (except for EDIT
 mode) called from inside the turnkey command procedure.

2 CHANGE
 Format of UAC command:

	$ UAC CHANGE  user

 where user is the username whose password is to be changed interactively.
 CHANGE mode permits a user logged into the turnkey account to (if
 permitted by the turnkey command procedure) change his password in the
 same manner as the SET PASSWORD DCL command.  The user will be prompted
 for his current and new passwords and asked to verify the new password
 before the change is made.

2 CHECK
 Format of UAC command:

	$ UAC CHECK  usersym  [label]

 where usersym is the name of a local DCL symbol in which the username
 is returned to the turnkey command procedure.  The user is prompted to
 enter his username and password in the same manner as the VMS login.
 If the user is validated for access, then the username is stored into
 the DCL symbol and UAC exits (with success).  If the user is not
 authorized (incorrect password or unknown username), then UAC will
 exit with error status if there is no label parameter.  If the label
 parameter is specified, then a DCL GOTO will be executed to that label
 on an authorization failure.

2 EDIT
 Format of UAC command:

	$ UAC EDIT

 EDIT mode is used by the turnkey account manager to setup and maintain 
 the access file.  Upon entering EDIT mode, UAC will prompt for commands
 to be entered from SYS$INPUT:.  The EDIT-mode commands are discussed in
 the following subtopics.

 A single EDIT-mode command may be executed by a UAC command of the
 form:

	$ UAC EDIT command

3 CREATE
 Format of command:

	UAC-EDIT> CREATE[qualifiers]  [file]

 The CREATE command creates a new, empty access file.  The key length
 and minimum password length may be specified at this time and cannot
 be changed for the life of the access file.
/KEY_LENGTH=n
 Used on the EDIT-mode CREATE command to specify the length of the
 username key.  The allowed range is 1-32 characters.  The default
 is 12 characters.  Note that the key is always padded with blanks.
/LOWERCASE
  /LOWERCASE
  /NOLOWERCASE (D)

 Used on the EDIT-mode CREATE command to permit the passwords to
 include lowercase letters.  Without /LOWERCASE, the passwords are
 converted to uppercase.
/MINIMUM_PASSWORD_LENGTH=n
 Used on the EDIT-mode CREATE command to specify the minimum length of
 a password for CHANGE mode.  The allowed range is 0-255 characters.
 The default is 8 characters.
/TEXT_LENGTH=n
 Used on the EDIT-mode CREATE command to specify the length of the
 extra text portion of the access file records.  The extra text field
 is application specific to the user of UAC.  The allowed range is
 0-80 characters.  The default is 0 characters.
3 ADD
 Format of command:

	UAC-EDIT> ADD  username[qualifiers]

 Add a new username to the access file.  If the username already exists,
 a warning will be printed but no other action will be taken.
/PASSWORD[=text]
 If not specified, a blank password is defined for the user.  If the
 password contains spaces, special characters or lowercase characters,
 it must be enclosed in quotes (").  If no text is given, a blank
 password is created.
/TEXT[=text]
 Specifies the contents of the extra text (ignored if the length
 of the extra text is 0) of the access file record.  The text
 will be padded on the right with blanks or truncated (from the right)
 to fit in the record's field.  If the textcontains spaces, special
 characters or lowercase characters, it must be enclosed in quotes (").
 If not specified and extra text field length is non-zero, then
 a field of all blanks is setup for the user record.
3 COPY
 Format of command:

	UAC-EDIT> COPY[/INPUT=file]  users

 Copy one (specified user name give) or all ("*" for parameter) user
 records from one access file to another.  Appropriate transformations
 in user name length and extra text are performed automatically
 (short fields are padded with blanks, long fields are truncated on the
 right).

 If a single user record is copied, it will replace an existing record
 in the access file.  If multiple user records are being copied ("*"),
 records for existing users are not copied but result in error messages.
/INPUT=file
 Specifies the secondary access file from which records are copied.  If
 not specified, then "UACFILE;-1" (with the defaults "SYS$DISK:[].DAT")
 is used to work from the next-older version of the current file.
3 DELETE
 Format of command:

	UAC-EDIT> DELETE  username

 Delete a username from the access file.
3 EXIT
 Format of command:

	UAC-EDIT> EXIT

 Exit UAC back to DCL.
3 HELP
 Format of command:

	UAC-EDIT> HELP [topic]

 Access this information.
3 MODIFY
 Format of command:

	UAC-EDIT> MODIFY  username[qualifiers]

 Change the password associated with an existing username.  If the
 username is not found in the access file,  a warning will be printed
 but no other action will be taken.
/PASSWORD[=text]
 If not specified, the user's password is left unchanged.  If the
 password contains spaces, special characters or lowercase characters,
 it must be enclosed in quotes (").  If the qualifier is given without
 a value, a blank password is set for the user.
/RESET_ACCESS_COUNT
 Resets the access count maintained for this user to zero.
/TEXT[=text]
 Specifies the contents of the extra text (ignored if the length
 of the extra text is 0) of the access file record.  The text
 will be padded on the right with blanks or truncated (from the right)
 to fit in the record's field.  If the textcontains spaces, special
 characters or lowercase characters, it must be enclosed in quotes (").
 If not the extra text field is left unchanged.  A /TEXT qualifier
 without a value results in a blank extra text field.
3 REMOVE
 Format of command:

	UAC-EDIT> REMOVE  username

 Same as the DELETE command.
3 SHOW
 Format of command:

	UAC-EDIT> SHOW[qualifiers]

 Lists the usernames and access counts (number of times user has been
 successfully validated).
/BRIEF
 Provide a minimal listing of the access file.  Only the user records
 are listed with just the user name and extra text.
/FULL (D)
 Provide a full listing of the access file, including information on the
 file itself.  For each record include the number of times the user has
 performed an access check (via CHECK-mode).
2 GETTEXT
 Format of UAC command:

	$ UAC GETTEXT  user  textsym

 where user is the username for which the user-defined text is to be
 extracted from the access file record.  The text is returned as-is
 (including padding blanks) to the local DCL symbol specified by the
 textsym parameter.

2 Logical_names
 By default UAC expects to find the access file in the current disk area
 as UACFILE.DAT.  This can be overridden by defining the UACFILE logical
 name (the default file specification of "SYS$DISK:[].DAT" is still used).
 
 The logical name UAC_HELPLIB must be defined for the EDIT mode HELP
 command to function.  This logical name should point to the HELP library
 which contains the UAC topic.  At Fermilab Accelerator Division, this
 definition is:

	$ DEFINE  UAC_HELPLIB  SYS$HELP:FERMIHELP.HLB
 
 If the logical name UAC_PROMPT is defined, its equivalence string is used
 as the username prompt in CHECK mode.  The default prompt used if the
 logical name is not defined is the string "Username: ".

2 Usernames
 The username is used as the keyword into the access file.  It is always
 padded with spaces and letters are converted to uppercase when accessing
 the file.  Only alphanumeric, "$" and "_" (symbol definition) characters
 are permitted in the username.  The length of the username key is
 selectable by the /KEY_LENGTH qualifier of the EDIT-mode CREATE command.
 By default, usernames are 12 characters long (same as VMS usernames).
 The maximum size is 32 characters.
2 Passwords
 The password text is always prompted for inside UAC with terminal echoing
 turned off.  Trailing blanks are ignored, but any other printable ASCII
 characters are acceptable; lowercase letters are changed to uppercase
 unless the /LOWERCASE option had been selected when the access file was
 created.  The maximum length of the password text is 255 characters.
 A minimum length for the password may be selected when the access file
 is CREATE'd (by default, this is set to 8 characters).  This minimum
 length is only enforced in CHANGE mode.
