WHICHBAS(1)

NAME
whichbas - Determine BASIC variant of a tokenized Atari 8-bit program

SYNOPSIS

whichbas [-v] input-file [input-file ...]

DESCRIPTION

whichbas reads tokenized Atari 8-bit BASIC, Turbo BASIC, BASIC XL, BASIC XE, BASIC/A+, or Atari Microsoft BASIC programs and attempts to discover which BASIC is required to run each one.

input-files must be actual files. whichbas can't read from standard input, because it seeks in the input file.

With multiple input-files, the output is one line per file, with the filename, a tab, and the detected BASIC. With only one input-file, the filename and tab are not printed.

OPTIONS

Note: none of the options -s -k -v are allowed when checking multiple files; they only work if there's just one input-file argument.

  Detection Options

-s  Script (or silent) mode. Instead of printing a human-readable name like "Turbo BASIC XL" or "OSS BASIC XE" to stdout, whichbas will print nothing on standard output, but will exit with a status indicating what it detected. The caller can check the return status (e.g. the $? variable in Bourne/POSIX shells, or ERRORLEVEL in MS-DOS or Windows). See EXIT STATUS, below.

-k  Keep going. The default is to stop looking at the program if the BASIC type gets narrowed down to either Turbo BASIC or BASIC XE. This option also enables -v (verbose). It's really only useful for testing, if you're hacking on whichbas itself.

  General Options

--help
    Print usage message and exit.

--version
    Print version number and exit.

-v  Verbose operation. When displaying a number in verbose mode, it will be prefixed with $ if it's in hex, or no prefix for decimal.

NOTES

Atari BASIC programs are detected almost 100% reliably. See BUGS, below, for the gory details.

Turbo BASIC, BASIC XL, and BASIC XE are all supersets of Atari BASIC. If you wrote a program using one of them, but didn't use any of the extra commands or functions, the result is still an Atari BASIC program. Likewise, if you wrote a program using BASIC XE, but only used the commands/functions it has in common with BASIC XL, it would be detected as BASIC XL.

There are two types of BASIC XE programs: regular and EXTENDed. The extended type is detected 100% reliably, because the first byte of the file changes from $00 to $DD. Non-extended programs are only identified as BASIC XE if they use any of the extra commands BASIC XE adds to those found in BASIC XL.

Detection of Turbo vs. BXL/BXE isn't 100% reliable, and probably never will be. There's too much overlap between the sets of extra tokens added by each. Programs that don't use very many of the extra functions provided by Turbo/BXL/BXE may show up as "Either Turbo BASIC XL or OSS BASIC XL".

Atari Microsoft BASIC is detected by checking that:

•   the first byte of the file is $00.

•   the next 2 bytes (LSB/MSB) are the same as the actual file length minus 3.

•   the last 3 bytes of the file are zero.

    This may result in false positives (files that aren't BASIC programs at all might show up as Microsoft). Also, no distinction is made between Atari MS BASIC 1.0 and 2.0.

    OSS BASIC/A+ is an extended form of Atari BASIC. It's source compatible with Atari BASIC, but not token-compatible because it uses different token numbers for the regular BASIC commands and operators. Example: SAVE is token $19 in Atari BASIC (also Turbo/BXL/BXE), but in A+ it's token $1D. Detection should be 100% reliable, but since there aren't many BASIC/A+ programs in the wild, it hasn't been thoroughly tested.

    Various non-BASIC files are detected (including Mac/65 source, ELF binaries, etc) as a convenience, but I wouldn't rely on whichbas's non-BASIC file type detection if I were you. If you need the file(1) command, use it.

    whichbas knows nothing about other BASICs such as Frost BASIC or Altirra BASIC.

    When using multiple input-file arguments, a separate instance of whichbas is spawned for each file. This isn't the most efficient approach, but it shouldn't cause problems on reasonably modern systems.

BUGS

  Misdetection

It's possible to get a BASIC XL/XE program to misdetect as Atari BASIC by writing a program that does these things:

•   Dimension a string array with a number of elements that isn't just a numeric constant or numeric variable (e.g. DIM A$(2+2,10) or DIM A$(I*2,10)). The code that detects a string array DIM command can only handle simple cases like DIM A$(10,10) or DIM A$(I,10). It doesn't actually matter if the 2nd argument is a fancy expression, though.

•   Does not actually use the string array variable by assigning to it or reading a value from it. String array accesses in BASIC XL/XE are reliably detected because they require a semicolon after the first number, even if there isn't a 2nd number. Example: ? A$(2;) prints the 2nd element of the A$ string array. If it were written as ? A$(2), but A$ is a string array (not a regular string), BASIC XL/XE would give an Error 40 (string type mismatch) at runtime.

    The good news is, such a program will still work fine in Atari BASIC. Atari BASIC will dimension it as a regular string variable and ignore the 2nd dimension. Since it's not actually used elsewhere in the program, it doesn't hurt anything.

EXIT STATUS

Without the -s option, exit status is 0 for success, non-zero for failure.

With the -s option, the exit status is:

0   Not used with -s.

1 or 2
    Error reading file. Error message will be printed on standard error.

3   Atari BASIC detected.

4   Turbo BASIC detected.

5   OSS BASIC XL detected.

6   Non-EXTENDed OSS BASIC XE detected.

7   Turbo BASIC or BASIC XL (undecided which).

8   Turbo BASIC or non-EXTENDed BASIC XE (undecided which).

9   Turbo BASIC, BASIC XL, or non-EXTENDed BASIC XE (undecided which).

10  Unknown Atari BASIC derivative (not Atari BASIC, but not Turbo/BXL/BXE/A+ either).

11  Atari Microsoft BASIC detected.

12  EXTENDed OSS BASIC XE detected.

13  Compiled Turbo BASIC detected.

14  OSS BASIC/A+ detected.

64  None of the above; not BASIC.

    In the future, more exit codes may be defined (in the range 15 to 63), but the existing ones will not change.

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.