DOC 1.1 file -- Goodies Disk #9 root directory file documentation

NOTE!  This is a plain ASCII text file containing multiple
documents. You may find it most convenient to view or print this file
by running the DOC.EXE program (supplied on this disk) on your PC.
This is the first Goodies Disk to do it this way.  Hope you like it.

:GD9
:Goodies Disk 9
:-jkh-
@@Read Me First!
             ͸
              HORN9 disk of HP 48 software 
                     January 4, 1994       
             ;
Collected & annotated by Joseph K. Horn, also known as
"-jkh-".

Please read all of this little document before bombarding
me with questions answered here. Thank you.

This is Joe Horn's personal collection of favorite HP 48
goodies, disk #9. It contains many excellent programs by
many excellent programmers. Most of these files were
downloaded from HP's Corvallis bulletin board system.

                      ͸
                       DOC & LIST 
                      ;
This is the first Goodies Disk to use the DOC program for
viewing and printing the files' documentation.  Just type
DOC at the DOS prompt on your PC.  See the DOC document
below for further information about it.  Note: You may
also use the LIST program (also included here) to view
and/or print any file on the disk.

                    ͸
                     S? SX? G? GX? 
                    ;
Whether a program will run on the HP48 S/SX and/or the
G/GX is indicated in the DOC program's "Select Document"
column; "SG" means it'll run on the S(X) and G(X); "S-"
means S(X) only; "-G" means G(X) only.  Notation to this
effect also appears within each document.  Running a
program on the wrong machine will almost certainly cause
a Memory Clear, but will probably not harm the calculator
hardware.  "PC" means that the program is not for the
HP48 at all, but is to be run on your IBM PC compatible
computer.  If that field is blank, then that document is
not for a program but is purely informational (like the
document you're reading now).

                    ͸
                     SUBDIRECTORIES 
                    ;
The files are contained in subject-oriented subdirector-
ies. List FILEINFO.SRC for a complete listing of all the
files and a brief description of each. 4DOS was used to
"attach" these descriptions onto every file and subdirec-
tory on the disk; if you use 4DOS, you will enjoy using
it with the Goodies Disks.  If you use 4DOS version 5.0
or above, you'll also see the authors' names.

ͻ
 Note: Everything on this disk is either freeware or   
 shareware. If you use the shareware, please register  
 as instructed. PLEASE DO give copies of this disk to  
 everybody! (But if you do, please don't change the    
 contents.)                                            
ͼ

Files with the same name before the extension are all
related. For example, FRED would be a downloadable
binary; FRED.SRC would be its source code (possibly
commented); etc. To copy a file into the HP 48, you MUST
specify the entire name; e.g. "FRED.LIB".

I have tried to provide documentation of some sort for
every file on this disk. If you know who wrote a file "by
?", please let me know so that proper credit may be
given.  Thanx.

Apologies to those whose files I accidentally mangled
while editing and reformatting for the DOC program. Warm
thanks to all authors whose works appear here. Good job!

These files are not guaranteed in any way; use at your
own risk.

For EduCALC Goodies Disk Customer Support, see
the SUPPORT document below.

- - -  Joseph K. Horn
Email: akcs.joehorn@hpcvbbs.cv.hp.com
Snail: 19292 El Toro Road / Silverado, CA 92676-9801 USA
Phone: None. Pretend I'm deaf. Write. See above.
@@About GD9
Poop Sheet about HORN9, the 9th EduCALC HP 48 Goodies
Disk.

 1. Official Name: "HP 48 Goodies Disk, Vol. 9".

 2. Diskette Volume Label: "HORN9"

 3. Ordering Information from EduCALC:

    Stock #GD9A (5.25-inch high-density mini-floppy),
    $4.95

    Stock #GD9B (3.5-inch high-density micro-floppy),
    $4.95

    (Note: This is EduCALC's cost; they make no money off
    these, nor does anybody else.)

    Shipping: $2.00 parcel post, or $5.00 U.P.S. (USA)

               EduCALC
               27953 Cabot Road
               Laguna Niguel, CA 92677 U.S.A.

 4. Copyright: See COPYRIGHTS for details about the
    files on this disk which HP wrote and copyrighted.
    The disk as a whole, however, may be freely copied if
    and only if (1) it is copied in its entirety without
    any modification to any of its contents whatsoever,
    and (2) you make no profit in doing so. You may, of
    course, recoup your copying costs. The idea here is
    not to make a profit from software which the authors
    specifically released for non-profit public benefit.

 5. Shareware: Some of these programs are called
    "shareware" by their authors. This means that they
    encourage you to "test drive" their programs first,
    and then if you like them and continue to use them,
    to send in the suggested "registration fee". Failure
    to do so will torture your conscience for the rest of
    your life.

 6. Diskette file recovery: This disk is doubly protected
    against accidental loss of contents. Several hidden
    files on the disk allow the full use of MS-DOS 5 &
    6's UNDELETE and UNFORMAT commands. For those
    without DOS 5 or 6, Norton's equivalent utilities are
    also supported (called QU and FR in the early
    versions, and UNERASE and UNFORMAT in later
    versions).

 7. Diskette optimization: The contents of this disk are
    100% unfragmented. Golden Bow Systems' VOPT and
    Norton's SD (SPEEDISK) were used to optimize the disk
    for speedy access. Use DISKCOPY to copy it, not
    XCOPY, to preserve this disk optimization.

 8. Viruses: This diskette was verified as virus-free by
    Microcom's Virex PC, and as HP-48 virus-free by Brian
    Maguire's VACCINE.1, and will remain virus-free as
    long as you keep it write-protected.

 9. Directories: DIR produces alphabetized file listings,
    even if you don't have 4DOS or DOS 5 or 6, since the
    directories are sorted using Golden Bow Systems' VDS
    and Norton's DS.

10. File Comments: Users of 4DOS or NDOS will notice that
    every file on this disk has a "description" attached
    which gets automatically displayed whenever DIR is
    used.

11. Documentation: This is the first Goodies Disk to use
    DOC.EXE for viewing the files' documentation.
@@Goodies Index
                         GD9.IDX
            THE HP48 GOODIES DISKS INDEX FILE
                       Disks 1 - 9
              by Stephen J Thomas & Joe Horn

GD9.IDX is an index to all the files included in Joe
Horn's HP 48 Goodies Disks 1 through 9, except for #4.
(Disk 4 is HP's System RPL disk, so it is not included in
this index).

See FETCH on this disk for an easy way to search through
this index file for key words. FETCH easily answers
questions like "What file had that reference to Ulam's
Conjecture, and what disk was it on, and what
subdirectory was it in?"  Just type 'FETCH Ulam'. Or,
"What are all the goodies from Bill Wickes?"  Type 'FETCH
Wickes'.

This index is sorted alphabetically by file name.
Generally, only one listing is included here WITHOUT file
name extensions, since files with the same root name are
related (if they're on the same disk, of course).

The disk number is followed, when necessary, by the first
two letters of the file's subdirectory. For example, if
a file is identified as "5PR", that means the file can be
found on Goodies Disk #5, in the PROGRAMR subdirectory.

Disks #1 and #3 only had one subdirectory (HORN1 and
HORN3, respectively) containing all the files on those
disks. The Index File therefore makes no reference to
the subdirectories on these disks. (They'd all be 1HO
and 3HO, respectively).

Disk #2 had two subdirectories:

   DNICKEL - Derek Nickel's VOYAGER and related files
   HORN2 - More random goodies

Therefore the files on Disk 2 are identified with "2DN"
or "2HO".

Beginning with Disk #5, the files have been organized
into subdirectories roughly by subject:

   AMIGA - Commodore Amiga Utilities
   ANIMS - Animated Video Programs (not games)
   DETLEF - Detlef Mueller's <-LIB-> & <-RPL-> Tools
   FRANCE - Goodies Received from Paris, France
   GAMES - Interactive Video Games
   GROBS - HP 48 Graphic Objects
   HACKER - Goodies for HP 48 Hackers (SRPL & ML)
   HP - Goodies From Hewlett Packard Company
   MATH - Mathematical Utilities
   POSTINGS - Text-Only Articles from HP's BBS
   PROGRAMR - Goodies for HP 48 Programmers
   TUNES - Quaint Melodies & Sound Effects
   UTILS - Heavy Utilities for HP 48 Power Users
   WORK - Real-World, Useful, Non-Silly Stuff

Steve Thomas organized this information as an index. The
actual files listed herein were written by their
respective authors and collected together by Joe Horn.
The descriptions and author listing are those Joe
provided on the Goodies Disks themselves in the FILEINFO
files.

The Goodies Disks' contents are available from various
BBSs which support the HP 48, and directly from EduCALC
on floppies; call 800-677-7001 or 714-582-2637, Mon-Fri
8am-5pm, California time.
@@Support
CUSTOMER SUPPORT POLICIES FOR EDUCALC PD GOODIES DISK #9

1.  The EduCALC Goodies Disks have been "successful"
    beyond my wildest dreams. We've given up trying to
    keep track of how many copies are out there; it's
    certainly more than 20,000. This is good news and bad
    news. It's good because it means that many people
    appreciate good PD software. The cross-pollenation
    of ideas will result in even better software. But
    it's bad because it means that there are thousands of
    people with thousands of new questions. And they
    expect me to answer them.
    
    I can't. I make no money off this project. It's my
    hobby. If you send me a stamped, self-addressed
    postcard and make it REAL EASY for me to answer, then
    I might be tempted to oblige. But if it costs me any
    money, or isn't fun, forget it.

2.  The files on this disk are not guaranteed in any way.
    Use at your own risk. EduCALC copies and sells these
    disks as a service, not as a product, and does not
    offer customer support for them in any way. All
    e-mail to me at the email address below will be
    answered. Do not ask me how to use these programs;
    read the .DOC files, and then you'll know more than I
    do.

Thank you for your HP 48 enthusiasm. Let's keep this PD
concept going!

- - -  Joseph K. Horn
Email: akcs.joehorn@hpcvbbs.cv.hp.com
Snail: 19292 El Toro Road / Silverado, CA 92676-9801 USA
@@Copyrights
       Ŀ
        Notice Of Copyright, Warranty And Rights 
       

This software is provided "as is" and is subject to
change without notice. Neither Hewlett-Packard Company,
EduCALC Mail Store, Joseph K. Horn, nor the authors of
other software contained on this disk makes any warranty
of any kind with regard to this software, including, but
not limited to, the implied warranties of merchantability
and fitness for a particular purpose; nor are they liable
for any errors herein or for incidental or consequential
damages in connection with the furnishing, performance,
or use of this software.

Some of the programs on this disk are Copyrighted by
Hewlett-Packard Company. All rights are reserved.
Hewlett-Packard Company grants you the right to use any
Hewlett-Packard copyrighted program contained in this
product in Hewlett-Packard calculators and to share them
with others as long as you receive no compensation for
doing so. If you share these HP copyrighted programs
with others, you must include this notice with the
program. HP copyrighted programs contain a copyright
notice at the beginning of the documentation file.

Some of the programs on this disk are shareware.
Shareware authors grant you permission to try their
programs on a limited-time basis. If you like the
program and intend to keep using it, then you are
required to send the author a shareware registration fee
as detailed in the program's documentation. You are also
granted permission to share the program with others as
long as you include its full, unmodified documentation,
and receive no compensation.

Some programs lie between shareware and freeware, and are
called "giftware". You are free to use and copy these
programs. The author asks only that you send a token of
your appreciation. Such authors have written the very
best software, and I highly encourage you to "make their
day" by sending them something they'll remember you by.
Anything from a picture post-card to a title deed of a
French Riviera chateau would be appreciated.

All other programs and files on this disk are in the
public domain. Enjoy!
@@- Root Dir -
Goodies Disk #9 contains 4 utilities in the root
directory for use from the DOS prompt:

DOC   : Documentation viewer & printer
FETCH : Goodies Disk Index Searcher
SEND  : Easy-to-use Goodies Disk PC-to-HP sender
GDOK  : Checks file integrity of entire Goodies Disk

BRIK, GREP, and LIST are utilities used by the above.

See the documentation for each of these below.
@@DOC        PC
Documentation viewer and printer            version 1.1


Purpose

DOC is a simple on-disk documentation viewer to present
the documents for the programs on this disk. It displays
a list of available documents down the left side of the
screen and shows the text of the currently selected
document on the right. DOC has a simple printing ability
which will produce a neat printout of a document so that
you can have a manual at hand while working with a
program. You can also print to a file, in case you wish
to create a single document file.

Running DOC

To start DOC, enter the command DOC. If you're looking
for a particular program's document, you may also give it
at the command line. For example:

    DOC IceCube

starts DOC and searches for the document for the IceCube
program. It may take some time to find it, however, since
it has to search through the entire disk.

You can speed up the search by specifying the document
file. For example:

    DOC FRANCE IceCube

is very fast because it loads just the FRANCE.TXT
document file and jumps to the IceCube document in it.

You don't need to type the entire name of the document or
document file, however; just enough to specify them. For
example:

    DOC F I

has the same result as the previous example, since there
is only one document file that starts with "F" and only
one document in it that starts with "I".

If presented with a list of document files, pick one by
using the arrow keys or by pressing its first letter, and
then press ENTER.

Select individual documents within the document file with
the up and down arrow keys to move through the list on
the left. Typing the initial letters of a document name
will jump directly to the next matching document. (Type
them in quick succession, or DOC will jump to different
lines with each letter pressed). Once you've found the
document you want, press TAB, or ENTER (RETURN), or the
right arrow key to move to the text of the document on
the right. The cursor keys (Home, End, Up, Down, PgUp,
PgDn) will now move through the text. Press the left
arrow or TAB or ENTER key again to go back to select
other documents.

Press ALT-Q or ESC Q to quit.

The DOC menu

To call up DOC's menu, press your favorite menu-launching
key (ESC, /, Insert, or F10). DOC presents various
options which you can select with the cursor and ENTER
keys or by pressing one of the highlighted letters. The
options will vary depending on your PC's configuration
and the document files available.

Pressing ESC a second time cancels the menu.

Quitting DOC

Choose the Quit option from the menu to leave the DOC
program and return to DOS. ALT-Q is a shortcut.

Color Display Off

Choose Color display off from the menu to ask DOC to work
in black-and-white. You may wish to do this if you're
using a laptop with an LCD screen that doesn't show
colors well or with some greyscale or CGA composite video
monitors.

If you need to do this, you might also enter the DOS
command MODE BW80 before running DOC. This makes DOC and
many other programs start up in black-and-white. Adding
/M (or just /) to the DOC command at the DOS prompt also
forces monochrome operation.

This menu option does not appear on PCs that do not have
color capability.

Extended screen on

Choosing this menu option switches the display to 43 or
50 lines so that you can see more text without scrolling.
You can go back to the normal display by choosing
Extended screen off subsequently.

If you have a Super VGA display card and a program to set
extended text modes, such as 60 lines deep, you might
like to try setting an appropriate mode before starting
DOC. DOC will usually operate with the non-standard
format.

This menu option is only available on EGA or VGA equipped
PCs.

Fast screen on

This menu option only appears on PCs fitted with CGA
standard or equivalent displays. Normally the DOC program
deliberately slows down on this type of display to
prevent the screen flicker or 'snow' that genuine IBM CGA
displays (and some compatible makes) can suffer from. If
your system does not suffer from snow, choose 'Fast
screen on' for a faster screen display. There's no harm
in trying this option either way on your PC... snow does
no harm and you might prefer to have a fast display that
flickers to a slow one that doesn't.

Print Document

Choose this menu option (or use the ALT P shortcut key)
to print the currently selected document. A menu appears
from where you can make four print settings, choose Go to
start printing, or Cancel (or press ESC) to return to
viewing documents. You may need to alter the settings to
suit your system before choosing Go as follows:

1. Output port

   This is the printer interface that DOC should print
   the document to. By pressing O you can step through
   the ports fitted to your computer. The default LPT1,
   the first parallel printer port, is correct for most
   PCs. DOC can work with a serial printer (COM1 or COM2)
   if you have one but you must make sure that the port
   is correctly set up (e.g. with a command such as MODE
   COM1:9600,n,8,1,p) BEFORE running DOC. X-On/X-Off
   handshaking is automatically provided for serial
   printers.

   You can set the output port to "FILE". In this case,
   DOC will ask for the name of a disk file when you
   start printing and will then print to disk rather than
   to a printer. If the file you name already exists, DOC
   will append pages to it.

   Note that DOC will not print on PostScript printers.
   If you have one of these, you might like to use the
   print to FILE option and then use a PostScript
   conversion program or word processor to print the
   resulting file.

2. Lines per page

   This is the number of printable lines on each page on
   your printer. DOC will print even if this is set
   incorrectly, but then it will not put the page breaks
   and headers in the right place. The default is 66
   lines for standard fan-fold paper. Other common values
   are 60, 62, 64 and 70. (LaserJet default is 60)

   If you have difficulty with this setting, a workaround
   is to set the form-length correctly on your printer,
   enter a small number of lines per page (e.g. 60) and
   then select the "Use form-feeds" option.

3. Use form-feeds

   Set this option to Yes if you're using a LaserJet-
   style printer or any printer with the form-length set
   correctly. DOC will work with this option set to No by
   counting output lines, but this is slower.

4. Pause between pages

   Set this option to Yes if you're feeding single-
   sheets to the printer... DOC will pause for you to get
   the next sheet ready between each page.

Working with document files

Document files should be kept in the same directory as
the  DOC.EXE program. Under DOS 3.0 or later, DOC will
find the files when it starts no matter which drive or
directory is current (with older versions of DOS, you
should change to the relevant drive and directory before
starting DOC).

Multiple document files

You can, if you like, place more than one document file
in the DOC.EXE directory. DOC will display a menu of
available files when first started and offer a 'Select
document file' option on its menu to let you switch
between documents. This menu is automatically skipped if
there is only one document file.

Document file format


You can use DOC.EXE in your own applications by creating
your own document files. This can be done with any text
editor or word processor.

Document files must have filename extensions of TXT, and:

(1) The very first line of the file must begin with:

DOC 1.1

which can be followed by any amount of text, none of
which will be displayed by DOC, such as the date, author,
purpose, etc. of the file.

(2) The text following the first colon found (:) is shown
at the left side of the screen title line, and at the
beginning of the document selection line for that
document; the text following the second colon is shown at
the center of the screen title line, and at the end of
the document selection line; and the text following the
third colon is shown at the right side of the title line,
and nowhere else.

(3) Two consecutive "@" symbols consititutes a manual
title marker; the following 13 characters will be shown
in the document title column, and the subsequent lines
will appear in the text area when that document title is
selected.

(4) Text lines ought to be kept to a maximum length of 57
characters, because lines longer than 58 characters will
be truncated when displayed, forcing the user to scroll
the screen with the arrow keys.
@@FETCH      PC
FETCH, a Goodies Disk Index Hunter, by Joe Horn
Searches through the Goodies Disk Index for any word(s).

Ŀ
 Mini-instructions: At DOS prompt, type FETCH 
 and then whatever you want to hunt for.      


The search text is not case-sensitive; it doesn't matter
whether it's in capital letters or lowercase letters.

Uses LIST, either the one on this disk, or the one built
into 4DOS.

FETCH is great for answering questions like "What Disk is
HYDE.LIB on?" or "Is there anything on the Goodies Disks
about Ulam's Conjecture?" FETCH HYDE and FETCH ULAM is
all it takes!

As written, FETCH assumes that the index file is called
GD9.IDX and is in the current directory. It would be
better to move the index file and FETCH onto your hard
disk (in a subdirectory in your PATH), and to edit FETCH
to reflect the location of the index file. That way, you
can FETCH things any time, no matter what directory you
happen to be in; and it runs MUCH faster.

Suggestions for improvements to FETCH (especially if you
also tell me how to implement your suggestions!) are
requested:

    Joseph K. Horn
    19292 EL TORO ROAD
    SILVERADO, CA 92676-9801
@@SEND       PC
SEND, a handy-dandy auto-kermit utility for 4DOS users.

By Joseph Horn (a True Believer in 4DOS).

This little program needs 4DOS to work correctly.
*AND SO DO YOU*

Ŀ
 MINI-INSTRUCTIONS: Point and shoot at the desired   
 directory, then at the desired file, and it will be 
 sent to the HP48 in SERVER mode.                    


4DOS users can send any HP48 file from this disk to their
calculators easily: type SEND and then "point and shoot".
It's not as versatile as Norton Commander, but it's less
expensive!

(NOTE: It is assumed that you have KERMIT.EXE renamed as
K.EXE on your hard disk and in your system path. If you
call it KERMIT.EXE, change the "k" in SEND.BTM to
"kermit" and then SEND will work just fine. Or do what I
did: include k*ermit=kermit.exe in your alias file.)

Ŀ
 FULL INSTRUCTIONS: 


First, put your HP 48 in SERVER mode (S/SX: press
blue-shift PRG; G/GX: press green-shift SWAP).

Type SEND on your PC. A menu of the disk's
subdirectories will be displayed. Use the arrow keys to
highlight the desired subdirectory, and press ENTER to
select it.

Then a menu of that subdirectory's downloadable files
will be displayed, complete with a brief description of
each. Use the arrow keys to highlight the desired file,
and press ENTER to send the file to the HP48. (Note:
Pressing the space bar instead of ENTER allows you to
mark multiple files, which are then sent in a batch when
you press ENTER).

When transmission is complete, the HP48 will exit server
mode automatically.

If you decide to abort SEND by pressing ESC on your PC,
you may have to also press E on your PC to exit kermit.

Note: SEND is ObviousWare, no rights reserved.

-jkh-
@@GDOK       PC
GDOK (Goodies Disk Okay?) File Integrity Verifier

Uses BRIK.EXE; make sure it is in your PATH.

Instructions: Just type GDOK at the DOS prompt, and wait
a few minutes. A list of all the files which are not
identical to the original Goodies Disk files will be
displayed.  If none are displayed, all are okay.

GDOK runs a lot faster on a hard disk, and if it finds
any bad files, you can recover by copying the files from
the original Goodies Disk onto your hard drive. If you
run GDOK directly from the floppy, and it finds bad
files, you're out of luck.

GDOK was originally written to prevent pranksters at my
school from altering the Goodies Disks' contents on the
IBM's in the computer lab. GDOK was included here at the
request of several other educators, but can be useful to
anybody who suspects that a file got mangled somehow.

-jkh-
@@GREP       PC
GREP: A UNIX-like text-search utility; better than "FIND"
in MS-DOS.

Ŀ
 Mini-instructions: Type "GREP ?" at the 
 DOS prompt for the grep help screen.    


Used by the Goodies Disk FETCH batch file. I suggest
putting it in your DOS directory and using grep instead
of DOS's "FIND" command.

Complete documentation for GREP.COM can be found on
Goodies Disk #8.
@@BRIK       PC
                        Brik  1.0
                  A free CRC-32 program
                            by
                       Rahul Dhesi

[Note: BRIK is used by GDOK.BAT; I suggest that you copy
BRIK.EXE to your C:\DOS directory, or any directory
that's in your PATH. -jkh-]

Brik 1.0 generates and verifies 32-bit CRC values
(checksums). It is designed to generate CRCs for text
files that are the same on all computer systems that use
the ASCII character set, provided each text file is in
the usual text file format for each system. Brik 1.0
will also optionally use binary CRCs calculated using
every byte in a file. Such binary CRCs are portable
across systems for binary files that are moved from
system to system without any newline conversion.

The general usage format is:

     brik -gcGCbfvsWT [file] ...

The brackets mean that "file", which is the name of a
file, is optional. The three dots indicate that more
than one filenames may be typed (separated by blanks).
Exactly one of the options -c, -C, -g, -G, or -h is
required. The -h option gives a help screen.

In addition to -h, the brik options available (as they
appear on the help screen) are:

  -g   look for Checksum: header, generate CRC for rest
          of file

  -c   get CRC from header, verify CRC of rest of file

  -G   generate CRC for entire file (add -b for binary
          files)

  -C   verify all file CRCs from output of -G (-f is not
          needed)

  -b   use binary mode--read file byte by byte, not line
          by line

  -f   read filenames (wildcards ok) from specified files

  -v   be verbose, report all results (else only errors
          are reported)

  -s   be silent, say nothing, just return status code

  -W   after generating CRC with -g, write it to original
          header

  -T   include trailing empty lines, normally ignored
          (text mode only)

VERIFYING CRC HEADERS

The primary intended use of brik is to verify Checksum:
headers in Usenet postings and in C and Pascal source
files. A Checksum: header looks like this:

  Checksum: 9485762645   (verify or update this with
     "brik")

The word "Checksum:" must occur at the beginning of a
line. It is followed by a colon, an optional blank, a
ten-digit CRC-32 value, and any arbitrary optional string
such as the comment shown above. When brik is invoked
with the syntax

  brik -c file ...

it will search for the Checksum: header in each specified
file, read the CRC value from that header, calculate the
CRC-32 for all lines in the file that occur *after* the
header line, and report an error if the two values do not
match. Brik ignores any trailing empty lines.


CALCULATING CRC HEADERS

The command

  brik -g file ...

tells brik to look for the Checksum: header in each
specified file, calculate the CRC of the lines in the
file following the header, and print the CRC and filename
without changing the file in any way. You can also ask
brik to update the Checksum: header with the following
command:

  brik -gW file ...

This causes brik to fill in the newly-calculated CRC in
the Checksum: header. If there is not enough space for
the CRC value in the existing header, brik reports an
error and does not change the existing header. To
initially add a Checksum: header to a file, insert a line
of the following form into the file with a text editor:

  Checksum: XXXXXXXXXX  -- this is an optional comment

The word "Checksum" must be at the beginning of a line.
The ten 'X' characters shown can be any ten characters.
They will be later replaced by the calculated CRC value.
They do not need to be 'X'. The comment following them
is optional and can be any arbitrary string of characters
after the CRC field, separated from it by a blank. As an
example, in a C source file called "main.c", you might
have:

  /*
  Checksum: XXXXXXXXXX (verify or update this with brik)
  */

Once a header like this exists in the file, invoke brik
as follows:

  brik -gW main.c

This will cause the ten 'X' characters to be replaced
with the calculated checksum, giving something like this:

  /*
  Checksum: 1922837484 (verify or update this with brik)
  */

Later you can use the command

     brik -c main.c

to verify that the contents of the file following the
header have the same CRC as the stored value.

If brik is invoked with the -c or -g options and it
cannot find a Checksum: header in a file, it prints a row
of question marks. If it is invoked with the -gW option
and it does not find enough character positions after the
"Checksum:" string to hold the CRC, it does not fill in
the CRC and prints an error message.

When calculating the CRC to fill in with the -gW option,
brik ignores any trailing empty lines in the file.


WHOLE-FILE CRCS

A "whole-file" CRC calculation is done for the entire
contents of a file, without looking for a Checksum:
header. The command

     brik -G file ...

asks brik to do this calculation for all specified files.
The output from this command is a list of files and their
whole-file CRCs. It is sent to the standard output
stream, which in most cases is your screen. The output
should be saved in a file by redirecting it. For
example, the command "brik -G *.h *.c > crc.lst" on an
MS-DOS system might yield the following in the output
file "crc.lst":

  # Whole file CRCs generated by Brik v1.0.
  # Use "brik -C" to verify them.

  # CRC-32        filename
  # ------        --------

  2566277976      getopt.c
   100594287      brik.c
  1151475469      vms.c
  3929503738      turboc.c
  2424271922      addbfcrc.c
  1943472856      assert.h
  2601923477      brik.h

The output of the -G option is in free format. The
output file may be edited by hand. Empty lines and lines
beginning with '#' will be ignored by brik when it is
later asked to read this file.

This list of filenames and whole-file CRCs may be
verified by a command like this:

  brik -C crc.lst

This makes brik read the file "crc.lst", get the CRCs and
filenames from it, do the CRC calculation again for each
file, and report an error if it does not match the CRC
recorded inside "crc.lst".

UNIX and MS-DOS users (and others who can pipe the output
of one command into another) could use a command like the
following to see if brik's -G and -C options are working:

     brik -G file ... | brik -C

This invokes "brik -G" on some files, sending the output
to a pipe where it becomes the input of "brik -C". If no
filename is specified, brik reads from standard input, so
"brik -C" will read from the pipe and concurrently verify
all the CRCs that are being generated by "brik -G".

Whole-file CRCs are normally generated in text mode, in
which a file is treated as lines of text. In this mode
brik ignores any trailing empty lines in a file. You can
also generate whole-file CRCs in binary mode. See below.


BINARY VERSUS TEXT MODE 

Brik can work in two different modes. The most common
mode, used by the -g, -c, and -G options, is text mode.
In this mode brik ignores all trailing empty lines in
files. (See more about this below.)

In text mode, brik reads all files line by line, and
forces lines to be terminated by a newline character of
constant value before doing a CRC calculation. Thus, no
matter what newline character is used by your system, the
CRC calculation will be unaffected. This means that
whether your operating system uses linefeeds to terminate
lines (e.g. UNIX), or a carriage return and a linefeed
(e.g. MS-DOS) or a carriage return only (e.g. Macintosh)
or nothing but a record length field (e.g. VAX/VMS), the
CRC calculation in text mode gives the same results.

If a file is not intended to be a text file, the text
mode CRC calculated by brik may not be reliable or the
same on all systems for the same file. Brik can be asked
to operate in binary mode by adding a -b option to the
option. Binary mode is applicable only to the -G option,
which acts on whole files. Thus while "brik -G file..."
finds whole-file CRCs of all specified files in text
mode, "brik -Gb file ..." does the same in binary mode.
In binary mode brik attempts no newline compensation, but
simply reads and calculates the CRC for all bytes in a
file. Provided a file is moved from one system to
another without any changes, brik should calculate the
same CRC for it on both systems.

The output from "brik -Gb" includes a trailing 'b'
character in each CRC, so "brik -C" will correctly use
text or binary mode as needed, and -Cb is equivalent to
just -C.


TRAILING EMPTY LINES

The normal behavior of brik in text mode is to ignore any
trailing empty lines in a file when checking or updating
the CRC in a Checksum: header. An empty line is a line
that contains nothing, not even blanks or tabs. (Just
hitting a carriage return when you are editing a text
file usually produces an empty line.)   If manipulating a
text file causes trailing empty lines to be added or
deleted, the CRC calculated by brik will be unaffected.

You can override this if necessary with the -T option,
which makes brik include trailing empty lines in the CRC
calculation. For example, "brik -gWT" will update the
Checksum: header with a CRC value that includes all lines
in a text file. Similarly "brik -GT" will find
whole-file CRCs that include all lines in a text file.

When brik is given the -T option, it adds a 'T' suffix to
each generated CRC value. Then, when the CRC is verified
with "brik -c" or "brik -C", brik will correctly include
trailing empty lines without having to be explicitly told
to do so.

In binary mode brik always reads all bytes in a file, so
it does not ignore trailing empty lines, and the -T
switch is not needed.

The -T and -b options are mutually exclusive, since the
first is used only for text mode and the second is used
only for binary mode. If both are given, whichever is
used later overrides the first. This "-bT" is equivalent
to "-T" and "-Tb" is equivalent to "-T".


FILENAME CONVENTIONS

Under MS-DOS and VAX/VMS, wildcards are allowed on the
command line and will be expanded by brik. Under UNIX,
wildcards are expected to be expanded by the shell and
are not expanded by brik.

If no filename is given, brik reads its standard input.
By default this is keyboard input, but it is expected
that input will usually be redirected to come from a file
or a pipe. Also, if a filename is explicitly specified
as a dash ("-"), it stands for standard input.

Thus the following five commands (valid under the UNIX
operating system)

  brik -c myfile
  # verify "myfile"

  brik -c < myfile
  # verify stdin, which is "myfile"

  cat myfile | brik -c
  # verify stdin, which is a pipe

  brik -c - < myfile
  # verify "-", which is stdin, which is "myfile"

  cat myfile | brik -c -
  # verify "-", which is stdin, which is a pipe

all have the effect of verifying the Checksum: header in
the file "myfile".

Standard input can also be read by "brik -C". For
example, suppose we have already given the command

  brik -G *.c *.h > crc.lst

to create a file called "crc.lst" that contains a list of
whole-file CRCs. We can now verify the integrity of
these files with any of the following commands:

  brik -C crc.lst
  # read "crc.lst"

  brik -C < crc.lst
  # read stdin, which is "crc.lst"

  brik -C - < crc.lst
  # read "-", which is stdin, which is "crc.lst"

  cat crc.lst | brik -C
  # read stdin, which is a pipe

  cat crc.lst | brik -C -
  # read "-" which is stdin which is a pipe


INDIRECT FILE NAMING

The -f option allows you to have filenames in a list
rather than on the command line. For example, suppose
you want to generate whole-file CRCs of files whose names
are selected by some other program. You could use "find"
(under UNIX) or "stuff" (under MS-DOS) to generate a list
of filenames. When the -f option is given, brik reads
filenames, one per line, from the file(s) specified.
Thus you could do the following:

  find . -mtime +3 -print > flist
  brik -Gf flist > crc.lst

The first command asks "find" to generate a list of names
of all files that were modified more than 3 days ago, and
sends the output to the file "flist". The contents of
"flist" might now look like this, as an example:

  ./sez.doc
  ./brik.doc
  ./stuff.doc
  ./looz.doc
  ./fiz.man

The second command above asks brik to read the file
called "flist", get a list of filenames from it, one per
line, and generate the whole-file CRC of each of these
files. We additionally redirect the output of "brik -Gf"
to the file called "crc.lst". Given the above contents
of "flist", the following two commands are exactly
equivalent:

  brik -Gf flist > crc.lst

  brik -G ./sez.doc ./brik.doc ./stuff.doc ./looz.doc
       ./fiz.man > crc.lst

The advantage of the -f option is that once you have
filenames in a file, you need not type them again at the
command line. The -f option also allows you to feed brik
filenames generated by another program through a pipe.
Consider this command:

  find . -mtime +3 -print | brik -Gf - > crc.lst

Under UNIX this concurrently invokes both "find" and
brik. As find generates a filename and sends it to its
standard output (a pipe), brik reads the filename from
its standard input and generates its whole-file CRC. The
following pipeline

  find . -mtime +3 -print | brik -Gf - | brik -C -

invokes "find" to generate filenames, brik to print the
whole-file CRCs of those files, and brik again to
immediately verify them.

Under MS-DOS and VAX/VMS (and any other operating system
under which brik has been installed to expand wildcards
itself), a file specified by the -f option can itself
contain wildcards in the filenames. For example, suppose
the file "wildfile" contains the following lines:

  /bin/*.exe
  /bin/*.com
  /doc/*.doc

Now if we invoke brik with the command

  brik -Gf wildfile

it will read filespecs from "wildfile", expand wildcards
in each filespec, and generate whole-file CRCs for all
matching files.

If you are checking whole-file CRCs with the -C option,
you do *not* normally need to use the -f option, as the
-f option introduces an additional level of file naming
indirection. For example, the command

  brik -C crc.lst

takes a list of CRCs and filenames from "crc.lst" and
verifies them. However, the command

  brik -Cf master.lst

does not do the same thing. Instead, it takes a list of
files from "master.lst", looks inside each of *those*
files for a list of CRCs and filenames, and verifies
them.

As an example of the use of -Cf, consider this sequence:

  brik -Gb /bin/*.exe > exelist
  brik -Gb /bin/*.com > comlist
  brik -GT /doc/*.doc > doclist
  brik -G  /doc/*.man > manlist

Now we have four files called "exelist", "comlist",
"doclist", and "manlist" containing whole-file CRCs of
various types. We can test the integrity of files listed
in these in four separate commands like this:

  brik -C exelist
  brik -C comlist
  brik -C doclist
  brik -C manlist

But we could also do this in a single step by first
creating a file called "biglist" that contains the names
of these four files:

  exelist
  comlist
  doclist
  manlist

and then use -Cf thus:

  brik -Cf biglist

This causes brik to read filenames from "biglist", look
inside each of those files ("exelist", "comlist",
"doclist", and "manlist") and check the CRCs found there.
A UNIX example to do the same thing in a more compact way
might be:

  cat exelist comlist doclist manlist | brik -Cf -


SILENT VERSUS VERBOSE

Brik accepts options -s and -v that cause it to be more
silent or more verbose than usual.

Normally brik prints a message only if it detects an
error. For example, if you give the command "brik -c *.c
*.h" and brik finds that all Checksum: headers contain
CRCs that match the calculated value, it prints nothing.

The -v switch makes brik print a message for each file
tested that contains the word "ok" if stored and
calculated CRCs matched and "BAD" if they did not.

In all messages reporting file CRCs, brik prints the
actual CRC it calculated, or a row of question marks if
it could not calculate one. Brik fails to calculate a
CRC if it is trying to calculate a header-based CRC
(commands -c and -g) but does not find a Checksum: header
in a file.

The -s switch tells brik to be silent. This will cause
nothing to be printed if brik does not find a Checksum
header or if CRCs don't match. However, the status code
on exit is still set. The -s option is useful for
invoking brik from within a shell script (UNIX) or a
batch file (MS-DOS) and later testing the error code it
returned when it exited.

The -s switch does not suppress the error message printed
if brik is given a filename and the file cannot be found.
For example, if the command "brik -cs myfile" is given
but "myfile" does not exist, brik will print an error
message even though the -s option was given.


PROGRAM LIMITATIONS

Brik 1.0 is designed to work with computer systems that
use the 7-bit ASCII character set and 8-bit bytes with
the eighth (parity) bit set to zero.

Brik 1.0 has not been tested with computer systems that
use ASCII characters with the eighth bit set or those
that use EBCDIC characters. Although it will calculate a
CRC on such machines, the probability of this CRC being
the same as the one calculated on machines that use 7-bit
ASCII is approximately 0.00000000023.

                                    -- Rahul Dhesi
                                       1989/03/13
@@LIST       PC
LIST.COM, by Vern Buerg, a file viewer with scroll,
search, print, and many other nifty features.

Press F1 (when LIST is running) for a complete help
screen.  Note: It's shareware.  Please register.

Included here solely for those poor souls who don't have
4DOS and its built-in LIST command.

-jkh-
