;
                          Video Library Utility

      A-  Overview                   D-  Option Menu                  
      B-  Help Display               E-  Cursor Motion                
      C-  Invoking VLU               F-  Jump Command                 

            Disk Operations                   Library Operations
      G-  Changing directories       O-  Changing libraries           
      H-  Tagging files              P-  Extracting and Uncompressing 
      I-  Crunching disk files       Q-  Building libraries           
      J-  File size report           R-  Adding Files to a library         
      K-  Deleting disk files                            
      L-  Renaming disk files                 Miscellaneous               
      M-  Group Operations           S-  Configuration                
      N-  Viewing disk files         T-  Security                     
           (and lbr members)         U-  Contributors/Programmer Note 
:A
 VLU107                                                                       
 Copyright 1987, 1988 Esoteric Software                   Michal Carson 11/88 

A ZSIG release.


VLU is a ZCPR3-specific library utility with crunch,  uncrunch,  and unsqueeze
capabilities.  It will allow the user to view,  uncompress, or extract library 
members or  to view,  uncompress (unsqueeze or uncrunch,  VLU will decide), or 
crunch disk files.   VLU will build libraries  from disk files,  crunching the 
files as they are added.  Date and time stamping is supported.

The utility will  display  a list  of disk files on  the screen  along with  a 
cursor and other information.   Placing the cursor next  to the name of a file 
with the extension .LBR and pressing 'O' for Open will display the contents of 
the library and shift the cursor into that directory.
:B
 The Help display 


Pressing "/" or "?" will evoke a display summarizing the commands available to
the user.   These commands  change  according  to  Wheel status  and directory
choice (e.g., Delete is not available in the library and is never available to
non-wheels).   Pressing either  of these  keys  a second time  will  clear the
display.

:C
 Invoking VLU 


Use VLU as an extension to a ZCPR3 shell,  such as ZFiler,  invoked  through a 
macro.  To install it,  one need  only open  the ZFILER.CMD file  with  a word 
processor and  enter  a line  of the  form "1 vlu".   Thereafter,  positioning 
ZFiler's cursor beside  a library file  and pressing "1" (possibly preceded by 
[esc]) will bring  up VLU with  the library already open.  A better thought is
to assign this macro to  the "O" key--"O $d1$u1:;vlu"  in ZFILER.CMD--so  that
[esc]"O" will open the indicated library.

Some aspects of VLU  were designed  to make  it  an  extension of  tools  like 
ZFiler.   Most of these tools  use the ZCPR system  files to store the name of 
the  current file  (the file the cursor was pointing to on exit).   VLU checks 
these filenames and interprets the current file (sys file 2) as a library.  On
starting up,  VLU will try to open  a library file of this name in the current 
directory.  

This  allows the user to invoke VLU from the "Z" prompt of ZFiler or through a 
macro, pass no parameters,  yet open the  current file if it  is a library (or 
shares the same  name as  a library though it may have a different extension).
If a different library is opened  before returning to ZFiler,  VLU will modify 
the  filename  in system  file 2  (and thus  cause  ZFiler to  believe it  was 
pointing to this library when it exited).

As  a command file,  VLU can,  of course,  be invoked  from the system command 
prompt.  If a library name is entered on the command line, that name will take
priority over any  name currently in system file 2  and  the library  will  be 
opened if it exists.   Even from  ZFiler's "Z" prompt,  with  the  pointer  on 
ABC.LBR,  entering the command "VLU DEF" will open DEF.LBR and place that name 
into system file 2.

If the invocation is followed by  a DU: specification or by the name of a ZCPR
named directory (DIR:),  VLU  will display  the filenames  in  that  directory
instead of  the  default  directory.  That is,  "VLU TOOLS:" will  display the
contents of the TOOLS: directory.

VLU can be re-entered with the GO command.
:O
 Changing libraries 


When  a library  is opened,  when VLU  is invoked  with  a library name in the 
command line,  or when  a new directory is logged in with a library open,  the 
VLU cursor will point into the library directory.  Pressing the [esc] key will 
shift the cursor back into the disk directory.  Opening a different library is
as simple as positioning the cursor in front of the name and pressing "O".  

:E
 Cursor motion 


Moving  the  cursor (pointer) in VLU  is effected  using  the  WordStar cursor 
motion controls.   Ctrl-E moves the cursor up one line,  ctrl-X moves it down.
Ctrl-S moves the cursor left one file, ctrl-D moves it right.  Ctrl-F brings a
new directory onscreen  if there  are  more files in the directory  (as if the 
display were  moving  right  by  a  directory),  ctrl-A moves  back toward the 
beginning of the file list.   Ctrl-F will wrap around from the final directory
to the original.

The arrow keys  will also function  if they  are properly defined in the users 
Environment descriptor.   The symbols "+" and "-"  (and "=",  the  usual  non-
shifted counterpart of "+")  have the same effect on the directories as ctrl-F
and ctrl-A, respectively.

The [esc] key shifts directories:  from the library to the disk, from the disk
to library.  In most instances the cursor will "remember" where it was when it
last pointed into that directory.

:F
 Jump command 


Typing a "J" will bring  a prompt for a filename to which the cursor will jump
when the user hits return.  The name need not be exact (entering "v" will jump
to the first filename which begins with "v") and it need not be on the current
display.   It is  only necessary that the targeted  file  come  alphabetically 
after the current file.

:P
 Extracting and Uncompressing library members 


Positioning  the cursor beside the name of a member file within  a library and
pressing "E"  for Extract will cause the file to be copied from the library to 
the disk with no change in form.   If  it  is crunched  or squeezed within the 
library, it will be crunched or squeezed on the disk.  

Pressing "U" for Uncompress will cause a crunched  file to  be uncrunched onto
the disk,  a squeezed file  to be unsqueezed onto the disk, or an uncompressed
file to be extracted sic.  

:G
 Changing directories 


Library members may be extracted to a disk and/or user area other than the one
which contains  the library.   Open  the library  first,  then  use  the Login 
command  to move to the destination  directory  and perform  the extraction or 
decompression.   The  move is  accomplished  by pressing "L"  (cursor position 
makes no difference with this command)  and answering  the prompt "Directory".  
The user may enter a DU: specification  (e.g., A0:, B14:, F:) or the name of a
ZCPR3  named  directory to  be found in  the  current  system  (e.g.,  MODEM:, 
DUNGEON:).  The colon is not necessary in any case and an invalid directory or
denied access will relog the current area.   No entry  at all  will also relog 
the current area to facilitate disk changes.

:H
 Tagging files 


The "T" command will tag an untagged file and the "Y" command  will remove the 
tag from  a tagged file.   The tag appears as a hash (#) immediately following 
the filename.   After a group operation (actually, during the group operation) 
hard tags represented by the hash are replaced by soft tags which appear as an
apostrophe (').  Soft tags may be transformed back into hard tags by the retag
command: "*".

Wildcard tagging is accomplished by pressing "W" and providing a wildcard file
specification in response to the prompt.  All files in the directory, starting
from the beginning, which match the file spec will be tagged.

Group Tag ("GT") is equivalent to a *.* wildcard tag.

It may be convenient at times to untag all files.  This can be accomplished by
relogging the directory with the Login command.  Certain file operations which
affect the disk directory  (anything that adds or deletes files) will also end 
by  relogging  the directory and  any  remaining  tags will  be erased.  Group 
operations obviously prevent this relogging until all files have been operated
upon.

:M
 Group operations 


"G" will  evoke  the  Group prompt.  From  this prompt,  several  commands are 
available to  wheels.  Only the View command is available to non-wheels and it
will be executed immediately.   If the wheel byte is not zero, the prompt will
indicate  by the  first letter of  each command that  View,  Tag,  Uncompress, 
crunch,  and either Extract or Delete and Build are available.   Any selection
is carried out on all tagged files.   The Group manager will  check for ctrl-C 
between each file and abort if it is seen.

:N
 Viewing files and library members 


Crunched,  squeezed,  and uncompressed files  may be viewed by pressing "V" at 
the VLU prompt.  The screen will clear, the file's name will appear at the top
of the  screen.  Just below the filename, the  file's datestamps,  if present, 
will be shown.  These will be taken from the disk in the case of ordinary text
files,  from  the library  directory  if the  file is  a  member,  or from the 
internal  datestamp of  a compressed file.   The  display will stop  with  the 
prompt  "[strike any key]" after,  in general,  22 lines.  The number of lines 
(the size of a screen page) is taken  from  the  ZCPR3 Environment descriptor.  
The number provided there,  by convention,  is two lines less  than the screen 
height.   This should give the viewer two lines of overlap with each page.  If 
this is unsatisfactory, the user's Environment descriptor can be adjusted.

At  any time during  the  viewing,  pressing  ctrl-S  will  pause the display.  
Pressing ctrl-C  will  abort the operation.   Under Group control, ctrl-C will 
abort the entire operation and  no more files will be presented; the user will 
be  returned  to  the file directory display.   Unscreened  files  will remain 
tagged.  Ctrl-X may be used to skip to the next file under Group execution; it
has the same effect  as ctrl-C  if only one  file is  being viewed, id est, we 
abort.

Ctrl-Z will suppress the "[strike any key]" prompt and the file will scroll by
continuously.   The viewer is  then left  with ctrl-S to stop the display (and 
any  key except  ctrl-X  and  ctrl-C  will restart it).   Another  Ctrl-Z will 
restore the paging mode  and  stop the  screen immediately.  This is handy for 
long files when the interesting text is near the end.

Certain file extensions are  proscripted (e.g.,  COM, LBR, ARK, SYS, RCP, REL, 
PRL, etc.) and VLU will  give the message "may not type" followed  by the file 
name.   Crunched files of proscripted types  may have a "stamp" of interest to 
the user.   If a proscripted file has a "Z" in the extension  (e.g., CZM, RZL, 
etc.) VLU will give the  filename  as it appears  and attempt  to  extract the 
original filename and  any stamp contained  in the  first record of  the file.
Thus,  the datestamps of  COM and  REL files  may  be inspected using the VIEW
command.

:I
 Crunching disk files 


The crunching faculty  of VLU is incidental.  Because of the Group operations,
it is quite useful but, ab ovo,  crunching files on disk has been secondary to 
the project of crunching files into libraries.   Selecting  "K" at the command 
prompt will cause VLU to crunch the file pointed to by its cursor.

VLU  will first prompt for a "stamp."  By convention,  this is a message of up 
to 40 characters enclosed in square brackets.   The message is imbedded in the 
first record  of the  crunched file  to be  displayed when  the file is either 
uncrunched or viewed.   Often,  the message reports the date of the crunching, 
the author or origin of the file, or its expanded size.

VLU will allow the entry of up to 38 characters.   Two characters are reserved 
so that VLU can insert the square brackets if the user omits one or both.  VLU
will remove  any trailing  spaces  from  the message;  if the user  wishes the 
spaces to appear, the user must enter at least the final closing bracket.

VLU will also imbed the current datestamp of the file, if present, in the form
established  by CRUNCH23D.  To use  the datestamp in  place  of  a text  stamp 
simply type a return at the "Enter stamp" prompt.

The crunching operation will  be aborted  if the file  is  already  compressed 
(either crunched or squeezed) or  is  of a proscripted filetype.   Proscripted 
filetypes are LBR, ARC, ARK, BAD,  and, if the target is a library,  FOR, INF, 
and CIM (vide infra).

VLU will allow the  user to crunch  a member out of a library  onto  the disk.  
There seems no harm in such an operation (and as little use).

:J
 File size report 


The size of  a file in  kilobytes  and sectors (records) is reported  when the 
user presses either "F" or carriage return.   If the file is a library member,
size is reported to the nearest higher 1k.   If the file is  on disk,  size is
reported according to the blocking factor of the disk.

:L
 Renaming disk files 


To rename a  library member or disk file,  position the cursor beside the file
and press "R".  Enter the new name at the prompt.
:K
 Deleting files 


To delete a library member or a disk file, position the cursor beside the file
and press "D".   The user  will be prompted  to confirm that the file is to be 
deleted.   Under Group Delete,  the first prompt  applies to all tagged files.
Answering Yes  to this prompt will delete  all files with  no further prompts.
Answering No will abort the operation entirely (no files deleted).   Answering
Verify will cause a prompt to appear for each file in the group.
:Q
 Building libraries 


In order for VLU to build a library, all files to be  included must be located 
in the same directory.  The library may,  if necessary,  be built in a foreign 
directory.

As  distributed,  VLU will crunch  all files  as they are added to the library 
(unless  the  extension  is  unacceptable  as  previously  stated).   See  the 
configuration section for possible attenuation of this practice.

VLU does have limits  governing the  maximum size library it may build or deal
with.   Those limits will vary with the  size of the current TPA.   Most users
will never approach VLU's limits,  but for curiosity's  sake,  a TPA of 58k is
sufficient to manipulate a library of over 1200 members.

To initiate the construction,  tag the files which are to be included and then 
type "GB" for Group and Build.   VLU will prompt for the name and directory of 
the  "new library" and  the number of entries  to allow.  A carriage return at 
the "entries"  prompt will build  a library with  the minimum  directory size, 
only large enough  to accomodate the  currently tagged files.   If you specify 
the number of members (say, 40), VLU will build a library large enough to hold
at least  this many  members and will  report  the actual  number  of possible 
entries ("Initializing 43 entries").

Rather than count the number of members you have tagged and add to that number
of members you expect to add in the future, you may simply enter "+40" to have
VLU make the calculation.   VLU will build  a library large enough to hold the
presently  tagged files  and 40 more.   If no files are currently tagged,  VLU 
will build an empty library large enough to hold at least 40 members.

VLU will  then initialize  the  library  directory  area.   The directory list 
(onscreen)  will be reset the first screen;  the cursor will move to the first
tagged file and  a message  will display that  the file  is  being crunched or 
added  as appropriate.   If any files  are to be crunched,  the "stamp" prompt 
will appear and  the  stamp thus  entered  will  be  in  effect  for all files 
crunched into the library.

Under this operation,  as under the Wildcard,  and other Group operations, the 
directory list onscreen will shift through all files searching for tags.  This 
will  be  more  noticeable in larger directories  (which require more than one
display) and during the Building  of libraries  (because of the pause to close 
the library).

:R
Adding Files to a Library


Adding files to  an existing library is  as simple as constructing the library
in  the first  place and  the files  will be compressed according  to the same
rules.  Date/time  stamps will  be preserved.   The current  date/time will be
written   into  the  library   directory  to   indicate  the  library's   last 
modification.

Files may be added individually or tagged and added in a Group operation.  The 
library to  which they  will  be  added  must  be  open and  must  have unused 
directory entries (deleted entries will not be overwritten). 
:S
 Configuration 


Several configuration bytes are located in the first sector of the VLU command
file where they may be easily patched.   For the  exact  location and function
of these bytes, see the accompanying file, VLUxxxC.Z80.
:D
Option menu


The Option menu,  accessed by typing "M"  at the  command prompt,  will toggle
many of  the configuration bytes.  This  allows  temporary  assignment  of the
options.
:T
Security


The Login command of  VLU will  use the Z33 parser when it is available,  thus
behaving exactly  as  the  operating  system would  in allowing  admittance to
directory areas.  When Z33 is  not available,  VLU  allows immediate  entry to
any du: or dir: within the MAXDSK and MAXUSR limits of the environment.   Dir:
forms outside these  limits  are  also accepted;  passwords,  if present,  are
enforced.

Commands Delete  and Rename  and any commands that  would create new files are
available only while the wheel byte is set.
:U
 Contributors 


VLU directly incorporates the work of many  "better makers."  My thanks to all 
of them as much and more for the opportunity to read and learn from their code
as well as for their library releases.  Among them, the following:

Richard Conn,  Howard Goldstein,  Jay Sage, et al. for SYSLIB, Z3LIB, Z33LIB04 
and VLIB--and ZCPR, itself.

C.B. Falconer and Steven Greenberg for USQREL, UNCREL, CRN, and BUFFERS.

Steven Cohen for M24.   Carson Wilson for DATEHL and Z80DOS.  Bridger Mitchell 
for FRESET and CRUNCH23D.

Martin Murray for NULU, the standard for these efforts.   And Gary Novosielski 
for the library format.

 Note from the programmer 


VLU,  its source code,  and its  documentation  are  copyright  1987, 1988  by
Esoteric Software.   VLU is  distributed  for  non-commericial use  only;  any
commerical use  or  any  re-distribution  in  association  with  a commericial
product or package requires the prior written permission of the author.

I may be reached on Z-nodes 2  and 3--Al Hawley's Ladera and Jay Sage's Newton 
Centre;  both  are   available  via   PC-Pursuit.   I  log  into  these  nodes 
approximately  weekly.   If it is important to reach me sooner, my home Z-node 
is #58, operated by Kent Mason in Oklahoma City (405/943-8638).  
