TURGEN Files

================================================================================
XEX2CAS 2.6.3
================================================================================

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

XEX2CAS 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 has the 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. IRGs after blocks
that hold INIT segments are elongated to at least 2400 ms.
Use the -i option to set custom elongation.

You can choose a binary loader. Refer to Binary loaders section
for more information about the 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] [option2] ... 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. This option is mutually exclusive
            with the -a option.

-a          Append to output file. This option is mutually exclusive
            with the -r option.

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

-spd:<n>    Set transfer speed (480 - 1200). The default is 600. Specify
            this option to set the baud rate for the baud tape image chunks.

-efuji      Generate empty FUJI tape image chunk

-nofuji     Do not generate 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 TSCBL (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)
            
-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.
            
-lfn'<name>' Set program name displayed by the binary loader (TSCBL and
            Fancy loader only)
            If this option is not specified, the name of the input file is used.
            The maximum length is 34 characters. The Fancy loader will use only
            first 20 characters.

-lfc'<name>'Set company name displayed by the binary loader (Fancy loader only)
            The maximum length is 20 characters.           
            
-lfbg:<n>   Set background color for the loader (TSCBL only)
-lfsilent   Set silent I/O (TSCBL only)

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:

-long       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 "-lfn'RIVER RAID'" -spd:720 -s rraid.xex rraid.cas
xex2cas -s -l3 rraid.xex
xex2cas -spd:660  -lfn'SNOOKER' -lfbg:0 -lfsilent snooker.xex snooker-tape.cas

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

PLAIN mode
xex2cas -plain -s -spd:660 -et1 loader.bot loader.cas
xex2cas -plain -s -spd:630 -long myprog.lb myprog.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 wild carding

- 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/ 

TURGEN
Create your own tapes with software for Atari 8-bit computers
https://turgen.sourceforge.io/


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

TSCBL. This loader skeleton is a modern and open-source replacement of the 
Exclamation mark (!) loader. It can display a program name up to 34 characters
long. It works both with pre-XL/XE computers and XL/XE ones.
You can also set the background color or set silent I/O.
It is recommended to use this binary loader.

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

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.

Building from the source code under Windows
===========================================

In general, it is recommended to use the available binary packages.

If you need to build xex2cas from the source code, follow these steps:
- Install MSYS2, Software Distribution and Building Platform for Windows, 
  available at https://www.msys2.org 
- Using pacman, install the GCC C++ Compiler and the CMAKE tool 
- Run the mingw32 shell shipped with MSYS2
- Change working directory to the directory with xex2cas sources and invoke the 
  following commands:
  
  cmake -G "MSYS Makefiles" .
  make

  The xex2cas.exe will appear in the src subdirectory.

Building from the source code under Unix-like systems
=====================================================
If you need to build xex2cas from the source code, follow these steps:
- Install GCC C++ compiler and the CMAKE tool
- Run your shell
- Change working directory to the directory with xex2cas sources and invoke the
  following commands:
  cmake .
  make
  make install

  The xex2cas binary will be installed to the default bin directory.

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