XEXCAT(1)

NAME
xexcat - Concatenate Atari 8-bit executables (XEX) into a single XEX file.

SYNOPSIS

xexcat [-hvc] [-f 1 | 2] [-l address [-r address] [-i address] [-o outfile.xex] [infile.xex] [infile.xex ...]

DESCRIPTION

xexcat reads one or more Atari executables (XEX/BIN/COM/etc), or dasm(1) -f1, -f2 files; it writes a single Atari executable containing all the segments from all the input files to outfile.

To read from standard input, infile may be omitted, or given as -. To write to standard output, -o outfile may be omitted, or given as -o-.

The output file is a valid Atari executable, including the required $FFFF header for the first segment. If there are multiple segments, the second and subsequent segments will not have the optional $FFFF header.

OPTIONS

-c  Check only; no output file is written. Equivalent to -v -o /dev/null.

-o outfile
    Write output xex file to outfile. Default is to write to standard output.

-l address
    Force the output file's load address to address. This only affects the first segment of the output file.

-i address
    Force the output file's first init address (if present) to address. This only affects the first init address segment of the output file. Further init address segments in the input will be left unmodified. If address is 0, the first init segment will be removed (0 means "none", not "init at address 0"). This option does nothing if none of the input files contain init address segments.

-r address
    Force the output file's run address to address. If address is not 0, all run address segments from all input files will be ignored, and a new run address segment will be constructed with the given address and appended to the output. If address is 0, all run addresses from all input files are ignored, and the output file will not contain a run address segment at all. Such a file can still be loaded from DOS, but it will not execute (user will be returned to the DOS menu).

-a  "Automatic" run address: Force the output file's run address to the load address of the first segment.

-f 1 | 2
    Input file(s) are dasm(1) object files created by -f1 or -f2 options, rather than .xex files. -f1 files can't contain run or init addresses, so you'll probably want to use -r, -a, and/or -i with these. -f2 files can contain run or init addresses. The output file is still a .xex file. Note that this flag affects all input files: if you're trying to join a dasm file with a .xex file, it must be done in two steps: convert the dasm file to a .xex, then combine the two .xex files with a second run of xexcat.

-1  Output file will be an Atari DOS 1.0 executable. If there are any init addresses in the input, you will be warned about them, since DOS 1.0 doesn't support the init mechanism.

-h  Print a short help message and exit.

-v  Verbose operation. Each segment's information is printed to standard error, including start/end address and length.

NOTES

It is possible to join multiple Atari executables together with the standard cat(1) command. However, xexcat is always guaranteed to produce a valid Atari binary load file (or an empty file, if all input files are invalid), which is not the case for cat.

When writing to standard output, xexcat will refuse to write binary data to the user's terminal.

The Atari binary load format requires the $FFFF header only for the first segment in a file. The second and subsequent segments may also have a $FFFF header, but it's optional. xexcat's output file will always have the $FFFF header for the first segment, and no $FFFF header for further segments, regardless of whether the segments in the input files had it or not (in fact, xexcat can handle an invalid XEX file which is missing the initial $FFFF header for the first segment).

Some Atari executables contain raw blocks of data, which are meant to be read into memory by the init routine. These blocks do not have start/end address headers, so xexcat is unable to handle them. Raw data blocks usually occur in files created with "packer" or "compressor" programs, or occasionally in other large programs (Turbo BASIC is an example). Raw data blocks are generally found just after an init address segment. If you have an executable that loads just fine on a real Atari or emulator, but fails with xexcat, a raw data block is usually the reason why.

The terms "Atari executable", "binary load file", and "XEX file" all refer to the same thing. Also, there is no difference between Atari executables named with "XEX", "COM", "BIN", "EXE", etc. The Atari and its DOS don't care about the names, only the contents.

The dasm -f1 file format is also the native binary format for the Commodore 8-bit machines (PET, 64, etc), so you can use xexcat to load Commodore code & data into an Atari... though of course the code won't run correctly on the Atari.

EXIT STATUS

Exit status is zero for success, non-zero for failure.

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.