CP/M/CPM_CDROM.iso/cpm/utils/dirutl/dir1st31.lbr/DIRFIRST.DQC/DIRFIRST.DOC

Text File | 1986-04-18 | 9KB | 170 lines

DIRFIRST:                    (General description and operation.)
     Z-80 sorted directory showing of first line(s) of files.

This file documents version 3.1, written February 28, 1986.
Copyright 1986 by Bob Abrahams, released for non-commercial use
at no cost.  May not be sold.  All other rights reserved.
Messages for the author can be left on Kim Levitt's Micro-BBS
system in Hollywood, CA (213-653-6398) or on Abel Iwaz's
Literaria BBS in Glendale, CA (818-956-6164).

NOTE:  This version is written using Z-80 instructions, so it
should be run on Z-80 CPU systems only.

This program lists a sorted disk directory (with file sizes) that
also shows the first line(s) of each file (if printable).  This
feature can be used to provide additional information on files
beyond the name of the file alone.  This is intended primarily
for text files, but other file types can be displayed.  The user
must put the additional description or other information on the
first line(s) of the file, with less than 80 characters in each
line.  The display of each line will stop at any carriage return.
If file is to be used by WordStar, the line(s) can be set up as a
"comment" line by starting the line with two periods.  Any blank
lines are skipped, including lines with blanks and tabs only.

The contents of some files (those with certain extensions, such
as .COM and .OVR) will not be displayed (unless the $A option is
used).  In any case, in displaying the contents line of the file,
control characters are suppressed, and each line stops at the
first carriage return or at the end of the first console line* so
that "unprintable" files do not wreak havoc even if displayed.
  * In this version, console width is assumed to be 80 chars.

Squeezed files (with file type ?Q?) of the standard type squeezed
by the various public domain CP/M squeezing programs are
unsqueezed, unless the program is modified as listed below, or
unless the original file is of an "unprintable" type.  Whether or
not the unsqueezing is done, the squeezed and original file names
are still listed, even if of an "unprintable" type.  The check
for file type can be skipped by uising the appropriate options.

It is suggested that the user change the name of the program to
D1.COM for easier use.  D1 is called similar to DIR -- that is,
              D1 {<afn>} {$<options>}
As with DIR, the <afn> parameter can be any file specification,
ambiguous (containing wildcard characters * and/or ?) or
unambiguous, including an optional drive specification.  Only
standard CP/M drive specifications are permitted (e.g. B:).  This
version is NOT set up to use ZCPR-type drive/user specifications,
such as B1:<filename>.

Options are indicated with a dollar sign ($) followed by the
requested option code(s).  Spaces may not be embedded between the
dollar sign and the option codes.  As created, the defaults for
most options is OFF.  Default for options $L (Libraries) and $X
(eXclude types) is ON.  See below for information on patching for
other defaults.

In this version, the options are:

A:  display contents of All files.  (Otherwise supress the
     display of the contents of files with some types:  .COM,
     .OBJ, .SYS, .OVR, etc.)  When listed types are supressed, a
     squeezed file whose original name is on the "unprintable"
     list will not be unsqueezed and displayed.
S:  include SYS attribute files.  Normally these files are
     supressed from the listing.
X:  eXclude files on the "bad" type list altogether.  (Not even
     listed in the directory.)  This does not exclude squeezed
     files by their original name, though this can be done by
     including ?Q? to the type table (see patching procedure
     below), which will exclude all files with type ?Q?, whether
     truely squeezed or not.  Overrides the $A option.  Default
     for this option is ON.
L:  open Library files (type .LBR), list member names and sizes
     and display the contents of each member, following the
     same rules as under option A with regard to files not
     displayed.  (With no $L, option, files with type .LBR are
     not displayed, unless option A is used.)  Library members
     are shown in order in library directory (sorted only if
     created by library utility that sorts its directory.)
     Default for this option is ON.
K:  show file sizes in 1K increments.  Normally file sizes are
     shown in disk block increments.  (This has no real effect if
     the drive referenced has 1K blocks.)  Library member sizes
     are always shown in 1K increments.
N:  No paging.  Do not stop at the end of each screen.*  (May be
     used with CP/M ^P echo feature to print output on list
     device.)  Normally, the display stops at the end of each
     screen with the message "More...".  The program then waits
     for any key to be pressed.  At this point (or at almost any
     other point in the execution), pressing ^C will abort the
     program execution.
  * In this version, screen height is assumed to be 24 lines.
1-9: List this number of lines from each file.  Default is
     normally 1 line (thus DIRFIRST).  With 1 line requested, no
     page break will occur between the file or member name and
     the first line of that file.  With more than one line
     selected, a page break may occur in the middle of the file
     display.  (Obviously this does not apply if the $N option is
     ON and there is no paging.)  If more lines are requested
     than are in the file, an extra blank line may be shown at
     the end of the display for that file.

All options used are listed on the command line together
following a dollar sign.  For example, to list files on drive B:,
opening Libraries, displaying contents of All files, and
including SYS files, use the command  D1 B: $LAS.  Option codes
may be listed in any order.

Program operation may be aborted at any time by pressing ^C
(Control and C keys together.)  On some system, this entry is
blocked during disk reads.  Those with buffered keyboard entries
will not have this restriction.

-----------------------------------------------------

Making modifications to .COM file (patching):
(Use DDT, SID or other file patcher to make modifications.)

1) The list of files that cannot be displayed (except under A
option) is located near the beginning of the program, following
the sign-on message.  This is a table in which each entry has
three characters, each representing an unprintable file type.
The character following the last entry must be a 00 byte to
terminate the scan.  The ? character can be used to represent any
character (wildcard).  (The * wildcard cannot be used.)  An entry
starting with a period (.xx) may be used to hold a space to be
skipped, since there can never be a type starting with a period.

2) Library files (type .LBR) are checked against a string
following the above table.  This string is 4 bytes long,
consisting of the letters LBR and terminating with a 00 byte.
If .LBR files are not to be checked as Libraries, then patch out
the character L with a 00 byte to terminate the comparison.

3) Immediately following the 00 byte terminating the LBR string
above is a table used to check for and set options.  Each entry
in this table consists of the option letter and a byte used to
store the status of the option.  A value of zero sets the option
off.  The last entry is followed by a 00 byte terminator.  To set
the option default on, set the 0 byte for that option to non-
zero.  With the default set on, using the option letter in the
option group on the command line (following the $) then sets the
option off.  (Actually, each use of the option represents a
toggle.  Normally, using any option twice leaves the option off.)

4) Following the above table, is the character "#" followed by a
byte with the value 01.  This second byte is the default value of
the number of lines to be printed.  It can be set for any value
from 1 to 9.  DO NOT SET THIS VALUE TO 00.  (It is recommended
not to use a value over 9.)

5) The program includes an unsqueezing section which pushes the
total size of the .COM file over 2K.  If no unsqueezing is to be
done (perhaps because no squeezed files are included) and the
user wants the file to be within 2K, the unsqueezer can be
deactivated and removed.  To do this, use DDT or SID as follows:
load the program into memory using DDT or SID.  If using SID,
start with the CP/M command SID D1.  Then use the SID command
W<new>.COM,0100,08FF, then exit with the SID command G0.  If
using DDT (on CP/M 2.2), start with the CP/M command DDT D1.COM,
then immediately exit DDT with the G0 command, then use the CP/M
command SAVE 8 <new>.COM.  With CP/M 2.2, use SID or DDT to be
sure to SAVE an initialized version of the program.  With CP/M
3.0, only use SID, with its W command.  In both cases <new> is
the new temporary name of the program.  It may be renamed to
D1.COM after testing.  The file D1/NOUSQ.COM has been prepared in
this way.