================================================================================
XEX2CAS 2.4
================================================================================

Overview
========
XEX2CAS 2.4 is a standalone command line utility that converts files to
standard tape records.

XEX2CAS 2.4 performs the following functions:
- Conversion of Atari DOS 2 binary files to standard tape records
- Conversion of tokenized Atari BASIC files to a form bootable from tape  
- Conversion of plain files to standard tape records

Conversion of Atari DOS 2 binary files to standard tape records
---------------------------------------------------------------
The conversion is performed as follows:
- A binary loader is converted to a tape boot file
- Binary file is converted to standard tape records

The structure of the converted binary file is checked. If the binary file
does not have a proper structure, a warning message is displayed. The
conversion continues because many binary files can be successfully loaded
despite their bad structure.

XEX2CAS 2.4 has ability to elongate IRGs after records that hold INIT
segments. This can help when transferring data using a cassette adapter or
a similar device that ignores the MOTOR CTRL signal.

You can choose a binary loader. Refer to Binary loaders section
for more information about capabilities and limitations of the loaders.

Conversion of tokenized Atari BASIC files to a form bootable from tape
-----------------------------------------------------------------------
The conversion works as follows:
- An Atari BASIC initializer is converted to a tape boot file
- Tokenized Atari BASIC file is converted to standard tape records

Conversion of plain files to standard tape records
--------------------------------------------------
The plain file is converted to standard tape records. 

Command line arguments
======================

Be advised that command line arguments differ from command line arguments of
both original XEX2CAS utility and XEX2CAS 2.0.

Usage
-----
xex2cas [mode] [option1] [option 2] ... infile.ext [outfile.cas]

Modes:
-binary     BINARY mode. Conversion of Atari DOS 2 binary file (default).
-bootbasic  BOOTBASIC mode. Conversion of a tokenized ATARI BASIC to a form
            bootable from tape.
-plain      PLAIN mode. Conversion of a plain file.

If the mode is not specified, the BINARY mode is assumed.

Options valid for all modes:

-r          Overwrite output file

-s          Use a shorter leader (12 s) 
            Specify this option to reduce loading time

-f          Faster transfer speed (720 bd) 
            Specify this option to reduce loading time

-e          Generate empty FUJI tape image chunk

-h,-help,-? Display usage instructions

Options valid for the BINARY mode:

-l<n>       Binary loader selection
            n=0 No binary loader 
            n=1 STDBLOAD 2a (default, displays program name)
            n=2 Exclamation mark (!) loader updated for XL/XE computers
            n=3 Exclamation mark (!) loader
            n=4 Binary loader from L.K. Avalon
            n=5 Fancy loader (XL/XE only, displays program and company name)
            n=6 SIECOD loader (Verbose loader, no support for INIT segments)
            
-i<n>       Elongate IRGs after INIT segments to n seconds (0 to 99) 
            Specify this option when you are using a cassette adapter instead of
            a compact cassette to prevent skipping of records.
            
-np'<name>' Set program name displayed by the binary loader (STDBLOAD 2a and
            Fancy loader only)
            If this option is not specified, the name of the input file is used.
            Maximum length is 34 characters. The Fancy loader will use only
            first 20 characters.

-nc'<name>' Set company name displayed by the binary loader (Fancy loader only)
            Maximum length is 20 characters.           
            
-g          Generate slightly longer (350 ms) IRGs

Options valid for the BOOTBASIC mode:

-bi<n>      BASIC initializer selection:
            n=0 LAUNCHBAS (default). This initializer has been written from
            scratch. This initializer does not use any undocumented entry
            points or routines and automatically attaches BASIC ROM on XL/XE
            machines. On pre-XL/XE machines, BASIC must be attached.

            n=1 BAS2CAS Initializer. Initializer from the BAS2CAS utility.
            
Options valid for the PLAIN mode:

-gl        Use long (3000 ms) IRGs. Use when converting Atari BASIC source files
           saved using the LIST"C:" command.

-et<n>     Trick with last record: 
           n=0 Use no trick (default)
           n=1 Use the "Data in EOF record trick"
           n=2 Use the "Last full record trick"           
         

Examples
--------
BINARY mode
xex2cas -r -i2 "-np'RIVER RAID'" -f -s rraid.xex rraid.cas
xex2cas -s -l3 rraid.xex
xex2cas -f  -np'SNOOKER' snooker.xex snooker-tape.cas

BOOTBASIC mode
xex2cas -bootbasic -r program.bas program.cas

PLAIN mode
xex2cas -plain -s -f -et1 loader.bot loader.cas

Usage notes
------------
- If you do not specify an output file, then infile.cas is implied. This allows
  you to convert binary files by dragging and dropping them on the
  xex2cas.exe icon, or a shortcut with your favorite options.

- There is no support for wildcarding

- Note that command line arguments that contain spaces must be enclosed
  in double quotes

Generating WAVE files
=====================
To generate WAVE files from tape images, use the following software:

A8CAS
Software for reading/writing Atari 8-bit cassettes
http://a8cas.sourceforge.net/ 

Alternatively, you can also use TURGEN SYSTEM (http://turgen.sf.net/), or
MagoTrans (download from the "Utils" section of http://atarionline.pl). 

Binary loaders
==============
This program allows you to select a binary loader:

STDBLOAD 2a. The loader has been written from scratch and placed in the Public
Domain. It can display a program name up to 34 characters long. It works
both with pre-XL/XE computers and XL/XE ones.

Exclamation mark (!) loader. This is a very popular loader created by
Nudmehi Software for their Boot Cassette Maker. It was written for
pre-XL/XE machines. With XEX2CAS 2.4, you can use its original version or a
version updated for XL/XE machines.

Binary loader from L.K. Avalon. This loader is very small (2 blocks). It is 
known to be used for certain L.K. Avalon games released on tapes.

Fancy loader. This loader displays program name and company name.
The loader comes from the XEX2CAS 1.5 utility. Note that this loader uses its
own custom display list, therefore do not use this loader with programs that
expect to be started in plain text mode (GRAPHICS 0). Also note that this
loader does not work with faster transfer speed.

SIECOD loader. This loader is a verbose loader. It has a rich display that
shows loaded bytes and blocks as well as a dump of the record being loaded.
Note that this loader does not support binary files with INIT segments,
therefore do not use this loader with programs that contain INIT segments.
A warning message is displayed when the binary file contains an INIT segment.

Tricks with last records
========================

Data in EOF record trick
------------------------
Under normal circumstances, the EOF record is only an End-of-file marker
that holds no data (in fact, all zeros). However, the data bytes of the
EOF record are still placed to the cassette buffer at address 1024 (0x0400).
Any data in the EOF record will appear in the cassette buffer. This trick
is sometimes used to make tape boot files one record shorter.

Last full record trick
----------------------
The last record of a file is not an EOF record, but a full record. This trick
is sometimes used to make tape boot files one record shorter.

Copying
=======
I have placed this work in the Public Domain, thereby relinquishing
all copyrights. Everyone is free to use, modify, republish, sell or give away
this work without prior consent from anybody.


Michael Kalouš (BAKTRA Software)
zylon@post.cz