;

                      VFILER, Version 4.1

                       A - Overview 
              B - Installation and Customization 


F - Operations on Files             M - Invoking User Macros              
G - Movement Commands               N - Creating User Macros (VFILER.CMD) 
H - Miscellaneous Commands          O - ZEX and VFILER                    

I - VFILER Options                  P - Macro Parameter Summary           

:A


Program:  VFILER

Syntax:

       VFILER               (show all files in default directory)
       VFILER DIR: or DU:   (show all files in designated DIR:/DU:)
       VFILER AFN           (show all files in default DU that match AFN)
       VFILER DIR:AFN       (show all files in DIR: that match AFN)

Function:

  VFILER (for Video FILER) is a screen-oriented ZCPR3 shell used to work in
  various ways with individual files or groups of files.  VFILER presents a
  full-screen alphabetized display of the files in a specified directory that
  match a specified file mask.  A pointer "-->" designates the current file.
  A number of commands are available to allow the user to move the pointer
  so that it is pointing to a file of interest.  Once pointing to such a
  file, the user may perform any of a number of operations on it, such as
  copying, deleting, or viewing.  One of the operations is to tag the file.
  Group operations can then be performed on all tagged files at one time.


Options:

  There are no options to be chosen while invoking VFILER other than the
  selection of a directory, using either the DIR or DU form, and a file
  mask using any ambiguous file specification, such as "*.COM".  See the
  Options section of this help file for the VFILER options that can be
  changed from within VFILER.

Special Features:

  The VFILER user is given added flexibility in his command possibilities
  by the availability of user-definable macros.  These macros are like alias
  scripts that form command lines based on the currently selected file.  The
  macro definitions are contained in file VFILER.CMD, which is described in
  a special section of this help file.

Error Messages:

  Self-explanatory.




Examples of Use:

  VFILER is used for various file maintenance tasks, such as cleaning disks of
  unwanted files, copying groups of files to other diskettes, or performing
  automatic archival backup of modified files.  One common pattern of use is
  to examine the display of files and to tag the files to be operated on.
  Then the desired operation is performed quickly on the full set of tagged
  files.  Because of the convenient and powerful macro facility, very general
  operations, such as editing or assembling, can be performed on the file that
  is pointed to.

:B

Installing VFILER

  This version of VFILER will automatically install itself on any ZCPR3
  system unless that system uses a very unusual configuration, in which
  case Z3INS is used as with other ZCPR3 programs.

Configuration

  There are three features of VFILER that some users might want to tailor to
  their own preferences using a debugger or file patching utility.

  1. Macro scripts can be initiated using a lead-in key, whose default is the
  escape key (ESC).  If a different key is desired, change the byte in the
  first page of the file immediately after the string "CONFIG".

  2. When the macro help screen is displayed and the user selects an undefined
  macro, an error message is displayed and, after a delay, the file display
  is restored.  This delay time is set by the byte following the lead-in
  character; the value represents the number of tenths of a second delay.
  Caution: use only values from 1 to 255.  A value of 0 will give a delay of
  nearly two hours!  The default value is 10 for a one second delay.




  3. The next byte is a flag that allows VFILER to recognize macros "0" to "9"
  without requiring the lead-in character.  As distributed, VFILER has this
  option turned off.  Patch a byte of 0FFH to turn it on.



Command Table Addresses


  For those who might wish to make changes to the command dispatch tables by
  patching rather than reassembling, the addresses of the three command tables
  are stored for reference just before the "CONFIG" marker.  The first table
  is for commands that can be used only when files are displayed, the second
  is for commands that can always be used (even when the ring is empty), and
  the third is for group commands.
:F

Operations on Files


The following are the built-in operations that can be performed on files.
All of them, except for "A", can be performed on individual files.  Those
that have "(Group)" following the name of the operation can be performed on
groups of files.  The Group counterpart of an operation is invoked by
preceding the command by the group command "G".


A - ARCHIVE  (Group Only)
Archive files to another DIR area.  If the archive attribute of a tagged
file is not set, then the file is copied to the designated DIR and, if the
copy was successful, the archive attribute of the file is set.  Tagged files
whose attribute bit was already set are not copied.


C  - COPY  (Group)
Copy file(s) to another DIR area.  A colon after the DU or DIR specification
is optional.  The disk system is reset so that disks can be changed freely.


D - DELETE  (Group)
Delete file(s) from disk (prompts for verification).


F  - FILE  SIZE  (Group)
File size(s) in kilobytes,  rounded up to next disk allocation block.


P - PRINT  (Group)
Print file(s) to CP/M list device (printer).  Any keypress cancels.


Q - UNSQUEEZE  (Group)
Unsqueeze file(s).  User is prompted for directory in which to place
unsqueezed file.


R - RENAME
Rename file in current directory.  Only CP/M convention names permitted.
Wild cards are not permitted.  User is prompted for new file name.



T - TAG  (Group)
Tag file name(s) to be operated on by a group command.  A file remains
tagged  until either a disk log-in is selected, a group operation is
performed, or the file is untagged by the user.  A "#" marker is placed
after a tagged file name as a reminder that it is tagged.  A "'" (single
quote) marker is placed by a file name that had been tagged before a group
operation was performed on it.  The "Y" command (below) can be used to retag
those previously tagged files.  The group tag command, "GT", tags all files
selected by the current VFILER mask.  See the "W" command for a way to tag a
specified group of files.


U  - UNTAG  (Group)
Untag file name (opposite of tag command).



V  - VIEW  (Group)
View file(s) on console, with pagination or single-line turn-up.  <CTRL-C>
cancels function.  <SPACE> advances to next line, and any other character
advances one screen.  In group-view mode, <CTRL-X> skips to the next file.
Only ASCII characters are processed.   Squeezed files are unsqueezed for
viewing.


W - WILD TAG
Wildcard tag or untag of files.


Y - RETAG
Retag files that were untagged as the result of a group operation being
performed on them (those with "'" next to their names).
:G


Movement Commands


There are a number commands used to move the pointer to a file of interest.
If cursor control keys are defined in the TCAP, they will work in VFILER.
The TCAP definitions of control characters will, in all cases, override the
definitions given to control characters by VFILER.


The following are the WORDSTAR cursor control characters.  They will work
in VFILER if they are not overridden by TCAP definitions.



                             ^E
                              ^
                         ^S <-+-> ^D
                              v
                             ^X

<SP>, <CR>  - NEXT FILE
Advance to next file name.  Wraparound from last to first may occur.
^D also performs this function if not overridden by TCAP definitions.

<BS>  -  PREV FILE
Back  up to previous file name.  Wraparound from first to last may occur.
^S also performs this function if not overridden by TCAP definitions.

J - JUMP
Jump to a file.  Used to jump quickly to a specific file name.  User is
prompted for a file spec, which may include wildcards (? and *).  Moreover,
a wildcard "*" is automatically placed at the end of both the file name and
type.  Thus "A" is equivalent to "A*.*" and ".B" to "*.B*".  User is
positioned at first file that matches the file spec or at first file in ring
if not found.

+  - NEXT SCREEN
Jump to Next Screen (if any).  If there is more than one screen of file
names, the user is advanced to the next screen.  If at the last screen,
wraparound occurs to the first.  ^F also performs this function if not
overridden by TCAP definitions.  ">" and "." also perform this function.


- - PREV SCREEN
Jump to Previous Screen (if any).  Similar to "+" but in the opposite
direction.  Wraparound to last screen may occur.  ^A also performs
this function if not overridden by arrow keys.  "<" and "," do also.


^R - TOP OF SCREEN
Jumps to first file name in the current screen.


^C - END OF SCREEN
Jumps to last file name in the current screen.


^T - FIRST FILE
Jumps to first file name, regardless of current screen.


^B - LAST FILE
Jumps to last file name, regardless of current screen.
:H

Miscellaneous Commands

A - ALPHA SORT
This command reverses the sense of the sort of the current directory,
reloads the directory, and refreshes the screen, having sorted it in the
new sense.  Sorting is done by file name and type or by file type and
name.  See the "O" command for another way to do this.

E - REFRESH SCREEN
Cleans up the screen.

H  - HELP VFILER
Invokes external HELP Information.  VFILER will chain to HELP and display the
information in VFILER.HLP.  VFILER checks to see if HELP can be found along
path and does not attempt to chain if HELP.COM cannot be found.

L - LOGIN [DU/DIR][:MASK]
Log in new directory area and/or new file mask.  A DU or DIR specification
alone (no colon) changes the directory only and leaves the file mask the
same.  A colon followed by a mask spec ("*.*" if colon only) changes only
the file mask and not the directory.



O - OPTIONS
Allow the user to view and selectively change the options.  For further
information on available options see Options subsection of this help file.

S  - DISK STATUS
Status of requested drive (shows remaining disk storage in kilobytes).

Z - ZCPR3 COMMAND
Run any ZCPR3 Command Line.  User will be prompted for command line.  Note that
the command will execute in the original DU area as indicated by the prompt.

X - EXIT VFILER
Removes VFILER from the shell stack so that the user returns to the
operating system or to the previous shell on the stack.

/  or  ?  - PRINT COMMAND SUMMARY  (Short Help Info)
After viewing the summary, "/" will cause VFILER to redisplay the files.
:I
Options

  There are a number of options that can be set from within VFILER.  These
options remain in force until the user exits VFILER with the "X" command.
The options are changed using the "O" command.

  The user may create a new version of VFILER with the curent options as the
default options using the ZCPR3 "SAVE" command.  This can be done from within
VFILER by using the "Z" command.  The number of pages to save must have been
determined in advance (version 4.1 is 55 pages as released).

The results of having the options set to "Y" (yes) are as follows:

1 -  SINGLE REPLACE QUERY
If a file to be copied or created by unsqueezing already exists in the
destination directory, the user is asked whether he wants to delete it.
If the user chooses not to, then the operation is cancelled.

2 - GROUP REPLACE QUERY
For each file that already exists in the destination directory, the user
is asked whether he wants to delete it.  If the user chooses not to, then
the next tagged file is processed.

3 - ARCHIVE REPLACE QUERY
For each file that is to be archived, if it exists in the destination
directory, then the user is asked whether he wants to delete it.  If the
user chooses not to, then the next tagged file is processed.

4 - VERIFY QUERY
Before any operation is performed involving copying or unsqueezing files, the
user is asked whether he wants to employ CRC verification during the copy.

5 - VERIFY DEFAULT
If "verify query" is "N", then all copy/unsqueeze operations will employ CRC
verification or not depending on this option.  If "verify query" is "Y", then
this default answer will be used if the user responds with an answer other
than "Y" or "N" when prompted about verification.

6 - SUPPRESS SYS FILES
VFILER does not display files with the SYS attribute set.

7 -  SORT BY FILE NAME
Displayed files are sorted by filename and type.  (If the option is set
to "N" (no), then the files are sorted by type and filename.
:M



Invoking User Macros


  The VFILER command set is augmented by a set of user-definable macros
contained in file VFILER.CMD.  VFILER performs parameter substitutions to
build command lines.


  Each defined macro has a unique identifier.  The identifier can be any
printable character except a space.  There are two ways to invoke a macro,
directly or indirectly, as explained on the next screen.


Direct Invocation

  To invoke a macro directly press the lead-in character (default is ESC)
followed by the macro identifier character.  As a special case, macros with
digit identifiers (0..9) can be invoked without pressing the lead-in key.

Indirect Invocation

  A macro is invoked indirectly by striking "#" and waiting for the HELP
Block of VFILER.CMD to be displayed.  The user then invokes the desired macro
by pressing the identifier key.


Search Path

  When a macro is invoked, VFILER searches along the path for VFILER.CMD,
extracts the macro and expands it before it is executed.  Since VFILER
searches for VFILER.CMD along the path, several VFILER.CMD files may be
available for the user.
:N


Structure of VFILER.CMD


  The structure of VFILER.CMD is quite simple.  It can be created by any
text editor, and it consists of the following types of lines:

  1) a command line macro, which begins with a macro identifier that can be
  any printable character except a space and which contains the text of the
  macro to be expanded and executed.

  2) a help block, which is printed whenever the user types a pound
  sign (#); this block is denoted by a line which begins with a pound sign,
  and it extends from there to the end of the file

  3) a comment line, which is used to embed explanatory comments or a title;
  a comment line is a command line which begins with a space.



Command line macros

  The command line macro consists of the macro identifier , zero or more
spaces (which are ignored), and the text of the macro with embedded prompts
for user input.

  Prompts are enclosed in single- or double-quotes ('  or  ").  When  VFILER
executes these command lines, it prints the prompts contained within the quotes
as they are encountered and waits for the user to input a line of text
(terminated by a RETURN), at which point the text is substituted in the
command line where the prompt is.  If a prompt extends to the end of a command
line, it need not be terminated.  Spaces within the prompt are significant.

Example: 1 copy 'Source File? ' 'Destination Dir? '

When macro 1 is invoked, the user is prompted with "Source File?  ", he
enters his text, it is substituted in the command line, he is prompted for
"Destination Dir? ", he again enters a response, it is substituted,
and the resulting command line is executed.



There are a number of parameters that VFILER will expand before placing the
command line in the command buffer.  The values of the parameters are as
follows:

          Symbol      Parameter
            %D        Current Disk Letter
            %U        Current User Number (1 or 2 digits)
            %C        Current Named Directory (or "noname")
            %F        Current File Name and Type (pointed to by arrow)
	    %N        Current File, Name only
            %T        Current File, Type only
            %$ or %P  Current File, Complete Spec DU:FILENAME
            %H        Logged in DU:
            %R        Logged in DIR:
            %<char>   Inserts <char> in command line, where <char> is any
			character other than those above (e.g., %% or %")


See the next screen for some examples.



Examples: (A0:BASE logged in, A15:ROOT displayed, and pointing to MYFILE.TXT)


macro:      Disk is %d, User is %u, File is %f
expansion:  Disk is A, User is 15, File is MYFILE.TXT

macro:      Name is %"%N%", Type is %"%T%", Logged-in DIR is %"%R%"
expansion:  Name is "MYFILE", Type is "TXT", Logged-in DIR is "BASE"



  A "!" placed at the beginning of a macro will set the shell wait message
so that you will get the "strike any key" message when VFILER is reloaded.



Help Block

  The Help Block in the VFILER.CMD file is simply a block of text which
extends from the pound sign (#) in the file to the end of the file.

^A will turn on highlighting (if defined in TCAP) and ^B will turn it off.

This help information is displayed to the user as one screen, and it is
the responsibility of the person who writes the VFILER.CMD file to insure that
this body of text (including the line the pound sign is on) does not exceed
22 lines.

Example:

#  Help for Word Processing

     1 - Run WordStar
     2 - Run WordMaster
     3 - Run ROFF4



Comment Line


  A comment line is any line in the command section of VFILER.CMD which
begins with a space. The text of that line is the comment.  It is not
displayed to the VFILER user and is used only for reference by the person
who wrote the VFILER.CMD file.

Example:

    Edit Macro
W %d%u:;ws %f;%h:
    Assemble Macro
A !%d%u:;zas %n;%h:
:O



Running Zex from VFILER


  Like all standard ZCPR3 Shells, VFILER is able to support the
execution of the the ZEX command file processor on top of itself.  If ZEX
is running, VFILER will simply prompt ZEX for input rather than entering
its normal screen- oriented display mode.  In this way, a command executed
from the VFILER.CMD file may invoke ZEX, and all of the ZEX command
file processing will be performed before VFILER is reentered.
:P


Macro Parameter Summary


          Symbol      Parameter

            %D        Current Disk Letter
            %U        Current User Number (1 or 2 digits)
            %C        Current Named Directory (or "noname")
            %F        Current File Name and Type (pointed to by arrow)
	    %N        Current File, Name only
            %T        Current File, Type only
            %$ or %P  Current File, Complete Spec DU:FILENAME
            %H        Logged in DU:
            %R        Logged in DIR:
            %<char>   Inserts <char> in command line, where <char> is any
			character other than those above (e.g., %% or %")

                                                              Variables
                          Dis