1 MAINT
! MAINT.HLP
! Written by:	Leonard J. Peirce	08/12/87
!

MAINT is a full-screen File Maintenance utility that can be used to
maintain directories/files.  Directories are presented to the user in a
series of one or more screens and allows the user the opportunity to work
with entire directories at one time instead of working with a few files
and having to do a DIRECT to see the current state of the directory.

With the entire directory accessible it is possible to perform commands
on files.  This means that the command for the file or directory is
specified but the action is not actually performed until the user
"executes" the commands in the directory.  This gives the user ample
opportunity to change his/her mind.

The following functions are available in MAINT:

   1) delete files/directories
   2) copy files
   3) rename files/directories
   4) protect files/directories
   5) edit an ACL for a file/directory
   6) list a file's contents to the screen
   7) change to a subdirectory
   8) get full directory information on a file
   9) search for a specific file in a directory
  10) suspend MAINT and return to DCL level, either indefinitely or just
      to execute one command
  11) create extended textual descriptors for files and directories
  12) access on-line help

MAINT works within the directory structure provided by VMS, that of a tree.
This being the case, the first directory that the program sees is considered
the 'root' of the session and is the highest-level directory that is access-
ible for the duration of the session.

There is no limitation on the number of files in a directory that MAINT can
handle other than the amount of memory that it can request from the operating
system.

To invoke MAINT, the syntax for the command is:

   $ MAINT/qualifier(s) [start-spec]

   where

      [start-spec]        optional starting root directory and optional
                          starting file specification; if not specified,
                          the current default directory will be used
                          and all files in the directory will be included.
                          A file specification will only be in force for
                          the first level of the session; if a subdirectory
                          is selected, all files in the subdirectory will
                          be included.
2 Qualifiers
/CONFIRM

  Confirm that the commands for the current directory are to be done when
  an eXecute command is issued.

/DATE
  
  Include the creation date for all files.

/FULL

  /FULL

  Equivalent to /DATE/SIZE/PROTECTION.

/HELP

  Invoke the VMS Help utility for MAINT.  

/PROTECTION

  Include the protection string for each file

/SIZE

  Include the file size of each file in number of blocks used.

/SORT

  /SORT=[option]

  The files can be sorted by a number of different field.  The default is
  FILENAME.  Other options that can be specified include:  SIZE (size of the
  files in blocks) and FILENAME (default).

  The /SORT option can impact the performance of MAINT, especially for large
  directories.

/TEXT

  Use extended textual descriptors if the file MAINT.TDF
  exists in the selected directory.

/WIDE

  /WIDE

  Use 132-column mode (if available for terminal), allowing more information
  to be included for each screen of the directory listing.
2 Display_information
Filenames on the Main Display have maximum field widths for the filename
part, the filetype, and the version number.  This is done to make it easier
to format the screen.

The maximum field widths for the three parts of the file name are

   filename	maximum of 10 characters
   filetype	maximum of 3 characters
   version	maximum of 5 digits

In most cases, filenames will fit in the above fields.  In the cases where a
filename overflows one or more of the fields, an asterisk ('*') will appear
to the right of the filename to indicate that the full filename cannot be
displayed.  It is possible, however, to see the full filename by using the
Expand command.

The protection string for a file is not enclosed in parentheses as it is
for the DCL DIRECT command.  This is done to save space on the screen.

When a file has one or more file commands associated with it, it will appear
in bold on the screen (for terminals that have this capability).

There is a limit on the number of characters that may be displayed for the
current default directory at the top of the screen.  It depends on the mode
of the terminal at the time (80- or 132-column).  MAINT will truncate any
default directory string that is too long to fit.
2 Single_file_commands
The following commands operate on the file pointed to by the cursor.  Re-
member that none of the commands will be attempted until the X (eXecute)
command is issued.  The normal keyboard keys, as well as VT200 keys and
other alternatives keys, are listed for the commands.

   Command          Keystroke         Description
   -------          ---------         -----------
   Acl              A or a            Edit the ACL for the file.  You will
                                      be placed in the VAX/VMS ACL editor
                                      and returned to MAINT when you exit.

   Delete           D or d            Mark the file for deletion
                    Remove

   Rename           R or r            Rename the file.  You will be promp-
                                      ted for the new file name.

   Protect          P or p            Protect the file.  You will be promp-
                                      ted for the new protection.  It should
                                      be input in exactly the same format as
                                      it would be at DCL.

   Copy             K or k            Kopy the file to another.  You will
                                      be prompted for the new file name.

   Cancel           C or c            Cancel all file commands for file.

   Select           S or s            If the file is a subdirectory, tra-
                                      verse into that directory (saving the
                                      state of the current directory) and
                                      begin working with that directory.
                                      Otherwise, attempt to display the file
                                      to the screen.

   Expand           E or e            Expand on file; give information
                                      similar to DIRECT/FULL, along with
                                      any file commands associated with the
                                      file.

   Text             T or t            If the MAINT.TDF file already exists
                                      for the current directory, create/
                                      modify the text descriptor for the
                                      file.  If no MAINT.TDF file exists,
                                      ask if one should be created and
                                      prompt for the text descriptor for
                                      the directory itself.


2 Screen_cursor_commands
The following commands are used for position the cursor on the screen
and for changing screens.  The normal keyboard keys, as well as VT200
keys and other alternative keys, are listed for the commands.

   Command          Keystroke         Description
   -------          ---------         -----------
   Next screen      +, =              Go to next screen in directory
                    Next Screen
                    Control-F

   Previous screen  -, _              Go to previous screen in directory
                    Prev Screen
                    Control-B

   Right-arrow      Right-arrow       Move cursor right one column
                    Space
                    Tab
                    Greater than >
                    Control-L

   Left-arrow       Left-arrow        Move cursor left one column
                    Less than <
                    Control-H

   Up-arrow         Up-arrow          Move cursor up one row
                    Caret ^
                    Control-K

   Down-arrow       Down-arrow        Move cursor down one row
                    Control-J

   Goto screen      G or g            Go to a specific screen (useful for
                                      multiple-screen directories).  This
                                      option does not appear on the options
                                      line because there is not enough room.
2 General_commands
The following commands are used for general commands that not specific
to any one file.  The normal keyboard keys, as well as VT200 keys and
other alternatives keys, are listed for the commands.

   Command          Keystroke         Description
   -------          ---------         -----------
   DCL escape       $                 Escape to DCL and execute a single
                    !                 command.  You will be prompted for
                                      the command to be executed.  If a
                                      carriage-return is specified,
                                      you will be returned to DCL level
                                      exactly as if a ^Push command had
                                      been entered.  After the specified
                                      command is executed, MAINT will
                                      ask for a carriage-return before
                                      continuing.

   Execute          X or x            Execute all file commands for the
                    Do                current directory

   Finish           F or f            Finished with current directory;
                                      go back to most recent previous
                                      directory without executing commands

   Help             Help              Access HELP for MAINT.  You will be
                    H or h            prompted for a topic for help.  If
                                      no topic is given, HELP will be
                                      entered at the beginning.

   Locate           L or l            Search for a file in the current 
                    Find              directory.  Prefix searching is
                                      done so only enough of the filename
                                      to make it unique is necessary.  You
                                      will be prompted for the search
                                      string.

   ^Push            Control-P         Temporarily suspend MAINT and go to
                    Insert Here       DCL.  The DCL prompt will be "Maint> "
                                      to indicate that you are running a
                                      subprocess of MAINT.  This is diff-
                                      erent from the DCL Escape command in
                                      that Push means return to DCL while
                                      DCL Escape command means execute a
                                      single DCL command and return to
                                      MAINT.

   Quit             Q or q            Quit MAINT and return to DCL imme-
                    Control-Z         diately

   Refresh          Control-W         Refresh the screen.

   Version          V or v            Display current version of MAINT
2 Text_descriptors
MAINT has the ability to maintain extended textual descriptors for files
within a given directory.  What text descriptors do is allow you to asso-
ciate up to a 40-character description with any file in a directory, along
with having up to a 60-character description of the directory itself.  This
is particularly useful when MAINTaining directories with a large number of
files.  To use the extended file descriptor facility, do the following:

   1.  Run MAINT.

   2.  Type a T (Text) command.

   3.  MAINT will ask
       Text descriptor file MAINT.TDF does not exist.  Create it [y]?

   4.  Respond with something other than N or n for the file to be created.

   5.  MAINT will then ask
       Text descriptor for directory:

   6.  Enter a text descriptor (up to 60 characters) for the DIRECTORY.
       This will serve as a descriptor of the group of files in the
       DIRECTORY and will appear at the top of the screen.

   7.  MAINT will then ask
       Commands will be wiped out.  eXecute them? [y]

   8.  Enter something other than N or n to have the all of the current file
       commands eXecuted when the text descriptor file MAINT.TDF is created.
       If you answer n, MAINT will discard all of the file command made up
       until this point.  The default is to execute the commands.

   9.  MAINT will rebuild the directory information and rebuild the screen,
       including the text descriptors for the directory and text descriptor
       file itself, provided they will fit on the screen.  Even if they
       can't fit on the screen, they are still available for each file via
       the E (Expand) command.

The text descriptor file has now been created.  To add or modify a text
descriptor for a file, move to a the file and type a T (Text) command.  You
will be prompted for the text descriptor for the file.  It will be updated
when you Xecute the commands for the directory.

On subsequent uses of MAINT, text mode may be entered by one of two methods:

   1.  Use the /TEXT qualifier on the MAINT command.  This will cause MAINT
       to use text mode if the file MAINT.TDF exists.

   2.  Use the T (Text) command.  Again, if MAINT.TDF exists, MAINT will
       enter text mode.

Either way, once in text mode, the T (Text) command may be used to add or
change the text descriptor for a file.
2 Other_features
If you are running MAINT and you receive new mail, you will be notified by
a message appearing in the bottom-right corner of your screen.  Similarly,
if you are being PHONEd, a message will appear in the bottom right corner
and MAINT will continue to beep as long as you are being PHONEd.  If you
wish to read your new mail or answer the phone, just push (see Push command
above) out of MAINT and do so.
2 Caveats       
Some things to remember when running MAINT:

   1) A file cannot be reprotected if you don't have WRITE access to it.

   2) Protecting a file with a protection string of S:,O:,G:,W: (no access
      for all four classes) will leave the protection unchanged.  Both
      this and #1 will be fixed in the future; they require talking right
      to the XQP, which is something I haven't figured out yet.
        
   3) Select will try to display any file, even if it is a .EXE, .OBJ, or
      .MAI file.  MAINT might complain after it tries to display it, though.

   4) You cannot move backwards through a file using Select.  Use the editor
      if you want this functionality.

   5) Files with escape sequences in them can be selected but the escape
      sequences will not be interpreted.  The escape character will appear
      as ^[.  The inability to interpret escape sequences is an SMG limi-
      tation and one that probably cannot be fixed.

   6) There is no way to edit a file from MAINT.  If you want to edit a
      file, ^Push out of MAINT and edit it.  When you push out, you will be
      in the same directory you were in while in MAINT.  Edit the file and
      when you are finished, type "log" to return to MAINT.

   7) Highly volatile directories might not always be up to date in MAINT.

				- Author
