________________________________________________________
      |                                                        |
      |           [ XTRAX v2.0 / XTRAX Builder 2.0 ]           |
      |                                                        |
      | Program and Documentation Copyright 1989 Jerry Kindall |
      |________________________________________________________|
      |                                                        |
      |          Ma Bell:        614/871-4399                  |
      |          SnailMail:      2612 Queensway Drive          |
      |                          Grove City, OH  43123         |
      |          Internet:       JerryK@cup.portal.com         |
      |          GEnie:          A2.JERRY                      |
      |          AppleLink PE:   A2 Jerry                      |
      |                                                        |
      |          Last revision:  July 17, 1989                 |
      |________________________________________________________|




What Is XTRAX?
______________

XTRAX (pronounced "extracts") is a self-extracting archive format.  This means
that no unpacker is needed to unpack XTRAX files; they can be unpacked by simply
EXECing them from the ProDOS BASIC prompt.  There's nothing new about the idea
of EXECable archives; they were invented in the early days of Apple
telecommunications to transfer Apple files to and from non-Apple systems.  In
those days, before the Binary II standard was a standard, and when the only
protocol available for transferring data files from one computer to another was
plain ASCII text, EXECable files were the ONLY way to transfer Apple files while
retaining the filetype information.

Today, Gary Little's Binary II file format (along with binary transfer protocols
such as Xmodem, Ymodem, and Zmodem) takes care of keeping a file's directory
attributes intact when sending files to a non-Apple system.  The EXEC file is no
longer in the mainstream of Apple II telecommunications.  Even so, the "EXEC
method" is still used under two very specific sets of circumstances.

1: Sending files by Unix mail (and newsgroups).

The Internet is a large "network" of independently operated Unix systems.  All
of these systems can exchange mail, and there are several newsgroups which
anyone who has access to can post messages on.  There's a comp.sys.apple
(infoapple) newsgroup for Apple II discussions; there's a comp.binaries.apple2
group for Apple II programs.  Because only text can be transferred via mail and
on the newsgroups, any files posted on the Internet must be converted to a text
format.  In the past, the most popular way of doing this was to create an
EXECable text file.  Popular utilities for creating EXEC files include The
Executive and The Executioner.  Recently, the use of EXEC files has been
superseded by David Whitney's introduction of BinSCII, a standalone program
which has a number of advantages over EXEC file methods.

2: Overcoming the "new user paradox", or, "How do I unpack my packer?".

Most online services require that all files uploaded be compressed before being
uploaded.  The files must then be decompressed after being downloaded so that
they can be used.  In the past, BLU was the standard packer; now Andy Nicholas's
ShrinkIT is becoming a new standard. A new user obviously doesn't have an
unpacker, which means that unpackers must be made available in an unpacked or a
self-unpacking form.  EXEC files were usually used for this purpose.

XTRAX is specifically designed to address this second application of EXECable
archives.  A good question to ask at this point is: why not simply continue to
use "normal" EXEC files, such as those created by The Executioner and The
Executive?  What does XTRAX provide that makes it superior to older EXEC file
formats?


EXEC File Drawbacks
___________________

1: EXEC files are big.

Typically, when you convert a file to text format, the file becomes anywhere
from 1.5 to 3 times as large as the original. This is because the bits in each
byte of the original file must be split up to be represented as text.  The
Executive, which simply converted files to a series of Monitor commands, turned
each byte in the original file into three bytes in the EXEC file.  The
Executioner, which does things much more intelligently, has a 6-bit packing
option which will make the file a little more than 1.5 times as large as the
original.  Either way, it's a serious drawback, because larger files mean more
time (and money) to transfer via modem.

2: The Executioner doesn't work with large files.

This became a problem when it was discovered that Executioner couldn't handle
ShrinkIT because it was too large.  If ShrinkIT was to become the new standard
packer, an EXECable version must be available for new users to download.  The
Executive worked fine, but created a monstrous (over 200 block) text file.  This
put ShrinkIT out of the reach of users with only 5.25" floppy drives, since the
EXEC file and the unpacked file wouldn't fit on the same disk.

3: Only one file can be placed into an normal EXECable archive file.

This meant that related files had to be placed in separate files in the library.
 It would be more convenient to have related files in the same archive.  This
could be done by using BLU or ShrinkIT on a group of files and then converting
the resulting file to an EXEC file, but then the user would still need an
unpacker to use the file.

XTRAX solves all of the above problems.  First, it creates compact files
compared to The Executioner and The Executive; XTRAX files are only about 1K (2
ProDOS blocks) longer than the original file.  Second, the XTRAX format can
handle files up to 6 megabytes in length.  And third, XTRAX archives can contain
up to 255 files.  (Each file in an XTRAX archive requires a mere 31 bytes of
overhead.)


Making XTRAX Archives
_____________________

The XTRAX Builder, a simple but useful utility, is provided to create XTRAX
archives.  It's a BASIC program, a little less than 6K long -- obviously it
doesn't have any pull-down menus.  It's spartan, but it does work.  Here's how
to use it.  You'll need a IIe, IIc, or IIgs.  Sorry, II+'s are not supported by
the XTRAX Builder; XTRAX archives WILL unpack fine on II+'s though.  Two disk
drives will add to your joy; if you have only one drive, the source and target
prefixes must both be set to a pathname on the same volume, because the XTRAX
Builder does not prompt you to switch disks.

Simply RUN XTRAX.BUILDER.  The main menu will appear on the screen.  The first
two options allow you to specify the Source and Target directories: the Source
directory is where the XTRAX Builder gets files to put into an archive, the
Target directory is where it builds archives.  To change these directories,
press S or T as appropriate.  You can specify a maximum of 48 characters for
these pathnames, since the XTRAX Builder must be able to append up to fifteen
characters worth of filename to it when accessing files.  You will probably want
to start each pathname with a slash; if you don't, the current prefix will be
added when accessing the files.  Both pathnames default to the current prefix
when the program is run.

Press C for a catalog listing of either the Source or Target directories.  The
XTRAX Builder will ask you which directory you want to view a listing of and
display the contents of that directory a page at a time.  At the end, the disk
usage information will be displayed.

Press N to create a new XTRAX archive in the Target directory.  You will be
asked to name the file and to specify two lines of text to be displayed on the
screen when the archive is extracted.  If the file exists, you will be asked if
you want to overwrite it.  I would suggest using the suffix ".XTX" to
distinguish XTRAX files on online services.

Press A to add a file (from the Source directory) to an XTRAX archive (in the
Target directory).  You will be asked for the archive name, but the XTRAX
Builder will default to the last archive accessed.  Then you will be prompted
for the name of the file to be added; type it in and the XTRAX Builder will do
its thing.

In case it's not completely obvious, to create an XTRAX archive you first make a
New archive, then Add all the desired files one at a time.  There's no rule that
says you have to add all the files from the same Source directory, either.

The I command displays some Info about the program.  The Q command Quits.


Unpacking XTRAX Archives
________________________

Extracting files from an XTRAX archive is cake.  XTRAX archives will extract
themselves on any ProDOS-compatible II+ or better.  The easiest way for new
users to handle it is to copy the files PRODOS and BASIC.SYSTEM to a new, blank
disk.  (If a IIgs is being used, the file P8 should be copied to the disk
instead of PRODOS, and then renamed to PRODOS.)  Then download the XTRAX archive
file onto that disk.  The user can then boot that disk and type EXEC
archive.name to extract files from the archive. The ProDOS "smart run" (dash)
command can also be used.

The XTRAX archive will display a screen containing the XTRAX title and copyright
message, the two-line message specified when the archive was created, the number
of files in the archive, and the name of each file as it is extracted, followed
by either DONE or ERROR.

If an error occurs during extraction, the ProDOS MLI error number is displayed
and extraction will be aborted.  The user can also abort the extraction by
pressing ESC or Control-C; XTRAX will finish extracting the current file and
then abort.

If there are no files in an XTRAX archive, the screen will display "0 FILE(S)"
and the program will terminate normally.

XTRAX archives can be extracted to a different directory from the one in which
the archive resides by simply setting the prefix to the target directory with
the PREFIX command, then issuing an EXEC command specifying the complete
pathname of the XTRAX archive.


XTRAX Limitations
_________________ 

1: XTRAX archives can contain be a maximum of 16 megabytes long.

2: Files contained within an XTRAX archive can be a maximum of 6 MB long.

This limitation is imposed by the algorithm used in the extractor: each file is
considered to be a series of up to 255 24K "chunks" followed by an "excess" of
less than 24K.

3: GS/OS extended files cannot be included in an XTRAX archive.

This is because XTRAX is a ProDOS 8 program, and ProDOS 8 cannot access files
which have resource forks.

4: Sparse files cannot be included in an XTRAX archive.

Well, they CAN, but they will lose their sparseness and may require more disk
storage.  This will not be a problem with files that have been "sparsified" by
the ProDOS 8 FST under GS/OS; the files will simply turn out a bit "bigger".

5: XTRAX files cannot be transferred with ASCII sends.

Even though XTRAX archives LOOK like text files to the user and to the operating
system, they're binary files internally.  Therefore, Xmodem or another binary
transfer protocol must be used when transferring XTRAX files.  This means that
XTRAX archives cannot be transferred via Unix mail.  However, BinSCII is an
excellent solution to that particular problem.

6: No subdirectories can be included in an XTRAX archive.

7: A maximum of 255 files may be contained in an XTRAX archive.

As you consider these "limitations", remember the problem that XTRAX is meant to
solve: the "new user paradox".  In that context, the above limitations are not
major limitations at all (and in fact, all but #5 are shared by older EXEC file
formats).


How It Works
____________

Above I mentioned that although XTRAX files are text files on disk, they're
binary files internally.  ProDOS allows you to store any kind of data you like
within any kind of file; filetypes are merely for the convenience of users.
XTRAX takes advantage of this fact by simply storing the archived files directly
inside the text file, one after another, with a 31-byte header on each to keep
track of the file attributes.  No data compression is used, which makes
extracting the files quite simple.

To allow the user to EXEC the file from BASIC, all XTRAX files contain a special
executable header.  The first 256 bytes of the header are an EXECable collection
of ASCII characters, which put the computer into a standard configuration and
type in and execute a short machine-language program.  This machine-language
program is known as the XTRAX Booter.  Its sole purpose is to load in and
execute the real XTRAX Extractor, which is stored in binary form (to make it
more compact) in the next 768 bytes of the file.  This area also contains
information about the entire archive, including the two-line description entered
by the creator of the archive, and the number of files in the archive.  The
XTRAX Extractor then takes over and extracts each file in the archive.

Since XTRAX archives are binary files internally, you must use a binary transfer
protocol such as Xmodem, Ymodem, or Zmodem to transfer XTRAX archives. Every BBS
and online service that I've ever encountered supports Xmodem, at the very
least, so this will be no problem.  Just remember that you can't transfer them
using an ASCII send or receive even though they appear to be type TXT on your
disk.  Use BinSCII when you must convert files to true text files.


The Files
_________

There are a number of XTRAX-associated files in this ShrinkIT archive.  (Sure
would have been nice symmetry to distribute XTRAX in an XTRAX archive, but
ShrinkIT is much more efficient at packing.)  The files are:

The useful:  XTRAX.BUILDER   (the XTRAX Builder program)
             XTRAX.DOCS      (this doc file)

The arcane:  XTRAX.BOOT.S    (source code for XTRAX Booter)
             XTRAX.BOOT.T    (EXECable version of XTRAX Booter)
             XTRAX.EXTRACT.S (source code for XTRAX Extractor)

The assembler files are all created using the Merlin 8 assembler, with the
Archimedes 8 utility (by TC Wilson and myself) added on.  So you'll need
Archimedes 8 to assemble the source files, but they're mainly for looking at,
anyway.  The only Archimedes opcodes I used were MLI, which assembles a ProDOS
MLI call, and RRF, which reads a file and inserts it verbatim into the object
code.  Archimedes also allowed me to assemble the object code into a text file.

The XTRAX.BUILDER file is actually a sandwich file.  In the first 256 bytes of
the file is a short BASIC program which makes sure the program is running at the
proper address and then jumps to the other BASIC part.  The next 1K of the file
contains the XTRAX Extractor -- I did this so that I wouldn't have to BLOAD the
file when creating a new archive.  The XTRAX Builder itself starts in earnest
one and a quarter K past the beginning of the file.  If you want to get a
listing of that part of the program, just run the program and press
Control-Reset when the menu appears.


XTRAX Memory Maps
_________________

All memory not shown in the maps below is either unused, or reserved by the
operating system.

When running the XTRAX Builder:

        $0800 - $08FF:  "Front end" BASIC code
        $0900 - $0CFF:  XTRAX Extractor code
        $0D00 - $1FFF:  XTRAX Builder BASIC code
        $2000 - $7FFF:  Buffer for copying chunks of files
        $8000 - $9600:  BASIC variable space

When extracting files from an XTRAX archive:

        $0300 - $03CF:  XTRAX Booter (Extractor front end)
        $0880 - $088F:  XTRAX Extractor work space
        $0900 - $0BFF:  XTRAX Extractor
        $1000 - $13FF:  Disk I/O buffer for writing to files
        $2000 - $7FFF:  Buffer for copying chunks of files


XTRAX Revision History
______________________

1.0 - XTRAX 1.0 was never released to the public.  It was relatively primitive,
and simply read one byte at a time from the source file and then wrote it to the
target file, until the end of the source file was reached, causing the disk
access arm to thrash back and forth a lot.  Also, when files were transferred
via Xmodem, they sometimes ended up slightly longer than they were originally,
which meant that the extracted file would be slightly longer; this caused
problems with ShrinkIT which checked its file length as part of its virus
protection.  XTRAX 1.0 was "handmade"; there was no utility for creating XTRAX
archives.

1.1 - Fixed the bug with the file length.  An XTRAX 1.1 version of ShrinkIT was
made available in GEnie's A2 RoundTable library.  Files were now extracted in
16K "chunks", causing less disk thrashing.

2.0 - The first "generic" version of XTRAX.  An XTRAX Builder is provided to
create XTRAX archives.  All file attributes are saved and restored (the older
XTRAX formats only saved the filetype).  Support for multiple files was added. 
The "chunk" buffer was increased to 24K.  Error handling code was included, as
was code to reset the computer's status to normal. A user-definable 2-line
archive description (which is printed on the screen during extraction) was
added.


Copyright & Other Stuff
_______________________

The XTRAX Builder, the XTRAX Extractor (which is contained within each XTRAX
archive), all related source code, and this documentation are Copyright (C) 1989
by Jerry Kindall.  The XTRAX software and documentation may be distributed
freely for non-commercial purposes as long as no modifications are made to the
program or documentation.  The sysops of online services including (but not
limited to) GEnie and CompuServe are also granted permission to use the XTRAX
software to create self-extracting archives for their software libraries, again
as long as the software and documentation are not modified in any way.  I
reserve all other rights to the XTRAX software.  It is important to note that
the files contained in an XTRAX archive may be subject to other copyrights;
thus, the fact that the XTRAX software may be distributed freely does NOT
necessarily mean that software contained in XTRAX archives may be distributed
freely.

The XTRAX software has been tested extensively, but please let me know if you
find any bugs -- GEnie email will get to me the quickest.  In no event will I be
liable for any damages, incidental or consqeuental, caused by this program. It's
free, and you get what you pay for: TANSTAAFL.  (Grin)

Special thanks to the staff of GEnie's A2 and A2Pro RoundTables for their
support.


A Blatant GEnie Ad
__________________

GEnie's A2 and A2Pro RoundTables stand ready to assist you in getting more out
of your Apple II.  Managed by Tom Weishaar of A2-Central (formerly Open-Apple)
fame, A2 and A2Pro continue the tradition of providing 100% Grade A Apple II
Information with no additives or preservatives.

A2 features weekly conferences with industry leaders (as well as informal
conferences); an informative message base; online support from several software
and hardware companies; a large software library; the A2-Central Font
Clearinghouse; and the A2 University.  A team of knowledgable sysops works day
and night to make A2 a valuable resource for Apple II users.  A2Pro features
messages, files, and conferences of a more technical nature, covering everything
from beginning BASIC programming to advanced topics on the IIgs.

Here's how to sign up for GEnie:

        1: Have a major credit card or checking account number handy.
        2: Set your communications software to 1200 baud, 8N1, local
           echo (half duplex).
        3: With your modem, dial 1-800-638-8369.
        4: When you connect, type HHH and press Return.
        5: When GEnie responds with U#=, type XJM11706,GENIE and
           press Return.
        6: Answer the questions GEnie asks you, and you will be able
           to use GEnie the next business day.

Once you're on GEnie, you can get to A2 simply by typing "A2" at the main GEnie
menu.  Stop by and say hi; we'll be looking for you!