:VLU101							07/01-12/15/87
Copyright 1987, Esoteric Software			Michal Carson


This program is distributed through ZSIG.




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 
(uncrunch or unsqueeze, VLU will decide), or crunch disk files.  
VLU will build libraries from disk files, crunching the files as 
they are added.

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.


What is a Library?


The Library file format was developed to overcome two persistent 
limitations of CP/M disk storage capacity: limited directory 
entries and large blocking.

Although CP/M writes files in units of 128 bytes (sectors), most 
manufacturers have used larger blocks for storage on disk.  On a 
Kaypro with double-sided disks, for instance, all files are stored 
in 2K blocks; even a file one sector in length will occupy 2K on 
the disk.  Because the Kaypro disk format allows only 64 directory 
entries (files) on one disk, 64 of these 1-sector files (8K) will 
fill a 390K disk.

In a library, a one sector file occupies one sector (plus 32 bytes 
for internal directory information).  The library itself occupies 
only one directory entry on the disk.  If 64 one-sector files are 
placed into a library, the library will occupy 10K.

This is obviously an extreme example but illustrates the 
usefulness of libraries.  Other reasons exist; for instance, 
libraries keep related files together.  VLU will make files within 
libraries more accessible.


In this Library


Two executable versions are distributed:  VLUxxx-R.COM is for 
machines using reverse video as highlighting.  VLUxxx-D.COM is for 
machines using dim video as highlighting.  VLU.FOR is a short 
description of the utility; VLU.HLP is full documentation 
compatible with the ZCPR3 HELP text display utility.


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.


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.

VLU can be re-entered with the GO command.


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".


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.


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.


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.


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.


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.


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 and the file will 
be presented.  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.

At the "[strike any key]" prompt, pressing the period will bring 
one more logical line to the screen.

Ctrl-Z will suppress the "[strike any key]" prompt and the file 
will scroll 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.


Crunching disk files


The crunching faculty of VLU is incidental.  Because of the Group 
operations, it may be quite useful and may become addictive, but 
crunching files on disk is 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.

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 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).


File size report


The size of a file in kilobytes is reported when the user presses 
either "F" or carriage return.  If the file is a library member, 
the size will also be reported in records.


Renaming disk files


VLU will not rename a library member.  To rename a disk file, 
position the cursor beside the file and press "R".  Enter the new 
name at the prompt.


Deleting disk files


VLU will not delete a library member.  To delete 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 execution, if the user selects Delete, the prompt will 
appear for each file.  Currently, there is no provision to avoid 
this prompt.


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.

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.  The largest library 
that may be built with VLU is 255 entries.

VLU will then initialize the library directory area.  The 
directory list (onscreen)  will be reset to 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).


Configuration


There are five configuration bytes.  The first, at 10Ch, controls 
the display of files whose system bit is set.  Zero value in this 
location will display such files, any other value will suppress 
their display.  Default as distributed is "not displayed."

The second byte was added in order to accomodate LDR v1.6.  This 
version of LDR allows all ZCPR3 system segments to be packed into 
a single library, saving disk and directory space.  If the byte at 
10Dh is of zero value, all system segments will be crunched 
according to the rules governing other files.  If the user wishes 
to be prompted when a system segment is detected--given the option 
of crunching or not--the byte at 10Dh should be not zero.  Default 
as distributed is "prompt."

The third byte (10Eh) controls a prompt in the library building 
routines.  If this byte is not zero, the user will always be 
prompted before a file is crunched.  This gives the opportunity to 
load uncompressed files to the library.  The fourth byte (10Fh) is 
dependent on the third.  If the third byte is zero, there will be 
no prompt and all files will be loaded to the library on direction 
of the fourth byte.  If the fourth byte is zero, all files will be 
loaded sic; if not zero, files which have passed VLU's other 
criteria will be crunched.  The fourth byte has no effect if the 
third byte is not zero.  Default as distributed is "no prompt, 
crunch when possible."

The fifth byte (110h) is a bit map of fixed media.  The most 
significant bit represents the A: drive; the least significant, 
the H: drive.  If the bit is set (1), the drive will not be reset 
on logging to a new directory.  If the bit is reset (0) a disk 
reset (BDOS function 37) will be performed each time the Login 
command is used.  This takes some time; users with Hard Disks and 
RAM disks are encouraged to configure this byte to match their 
system.  Users with only floppy disk drives should leave the byte 
in its default as distributed: "no fixed media" (00h).

The value needed in this byte to indicate that the A: drive is not 
to be reset is 80h.  The value for A: and B: is C0h.

Following the five configuration bytes, the user will note the two 
file extents FOR and CIM.  This location contains a list of 
filetypes which the user does not wish to be crunched in building 
a library.  More filetypes may be patched into this list; the list 
must be terminated by a null.


Option menu


The Option menu, accessed by typing "M" at the command prompt, 
will toggle any of the first four configuration bytes.  This 
allows temporary assignment of the options to display/suppress 
system files, prompt before crunching system segments, and prompt 
before crunching files into libraries.


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 admitance 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.


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, Al Dunsmuir 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.

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


Note from the programmer


Please notice that VLU is not a shell.  If there are good 
arguments for making it a shell, please forward them to me.  Other 
functions are planned; next upon the board is output to printer.  
If you have requests or ideas, contact me.

VLU, its source code, and its documentation are copyright 1987 by 
Esoteric Software.  VLU is distributed for non-commercial use 
only; any commercial use or any re-distribution in association 
with a commercial 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).  You should check into this node 
anyway; there aren't many Kaypros online with 1Meg of memory.