CHKSAP(1)

NAME
chksap.pl - check, fix or calculate statistics for *.sap files

SYNOPSIS
  chksap.pl option... file...

DESCRIPTION
chksap processes SAP (Slight Atari Player) files. It can operate in one of three modes: check file format conformance, fix errors automatically, compute statistics.

You must select a mode using one of the options described below and pass names of files or directories to be processed. Directories are processed recursively, but only "*.sap" files are analyzed.

OPTIONS
Exactly one of the following options should be used to select the operation:

-c, --check
    Display the errors found for each file. Does not display anything for correct files.

-f, --fix
    Try to automatically fix errors. Shows descriptions for the fixed errors and the errors that cannot be fixed automatically.

    Warning: files are modified in-place and no backup copies are made. Make backups yourself before using this option!

-s, --statistics
    Compute and display statistics.

The following options are available in any mode:

-p, --progress
    Print name of the currently processed file.

In the fix mode the following options are available:

-t, --time
    For files that have no TIME tag detects playback time using an external program "asapscan" and stores it in TIME tags.

-T, --overwrite-time
    Detects playback time using an external program "asapscan" and stores it in TIME tags, possibly overwriting the current values.

In the statistics mode the following options are available:

-u, --features
    Lists files with rarely used POKEY and 6502 features.

The following options display some text and terminate the program without file operations:

-h, --help
    Display usage summary.

-v, --version
    Display program version.

ERRORS FIXED AUTOMATICALLY

line terminators within header are not CRLF
    The lines of the header should be separated with CR/LF pairs and not just LF or CR characters.

header not terminated with CRLF
    The last line of the header is not terminated with CR/LF.

extra whitespace within header
    There should be exactly one space between the tag name and its argument. There should be no spaces after the argument.

missing AUTHOR, NAME or DATE tag
    Although AUTHOR, NAME and DATE have no meaning to SAP players, they should always appear in the file. If the value is unknown, "<"<?"">> should be used.

blank AUTHOR, NAME or DATE argument
    If the value is unknown, it should not be empty or consist of only question marks - use "<"<?"">> instead.

NTSC tag with no FASTPLAY
    For compatiblity with players that don't understand the NTSC tag, it should be accompanied by "FASTPLAY 262".

SONGS 1 is superfluous
    "SONGS" tag with the argument of 1 is meaningless because the number of songs defaults to 1.

DEFSONG 0 is superfluous
    "DEFSONG" tag with the argument of 0 is meaningless because the default song defaults to 0.

hexadecimal values should be 4-digit
    The arguments of INIT, PLAYER, MUSIC and COVOX should specify all 4 digits.

hexadecimal values should be uppercase
    The arguments of INIT, PLAYER, MUSIC and COVOX should use "A-F" letters rather than "a-f".

more TIME tags than songs
    There are more TIME tags than specified in the SONGS tag.

non-standard order of tags
    The order of tags is of little importance, but making some assumptions about it makes it easier to create new tools that process SAP files. The canonical order is: first SAP, then AUTHOR, then NAME, then DATE. After DATE, the following tags should be used in any order: SONGS, TYPE, FASTPLAY, STEREO and NTSC. DEFSONG must appear after SONGS. The tags that should appear last are: INIT, PLAYER, MUSIC and COVOX, in any order.

FFFF inside binary part
    Two 0xFF bytes start the binary part but are redundant inside it.

garbage bytes at the end
    There are extra bytes after the last binary block, but less than 4 necessary to form a new block header.

truncated binary block
    There are not enough bytes in the file to fill the last binary block.

ERRORS THAT CANNOT BE FIXED AUTOMATICALLY

filename too long
    For portability, filenames should be limited to 26 characters (plus ".sap").

illegal characters in filename
    Filenames should consist of letters ("A-Z" and "a-z"), digits ("0-9") and underscore characters ("_").

file too long
    File should not exceed 63 KB (64512 bytes). This is because only 62 KB base RAM is available for use in Atari XL/XE machines (2 KB is reserved for I/O area) and the SAP header should be no longer than 1 KB.

missing SAP header
    The file does not begin with "SAP".

missing binary part
    Two 0xFF bytes were not found in the file.

unknown header line: ...
    A line of the header does not start with an uppercase tag name.

unexpected argument of SAP, STEREO or NTSC
    SAP, STEREO and NTSC tags should have no argument.

invalid argument of AUTHOR, NAME or DATE
    The arguments of these tags should be wrapped in double quotes and should consist of ASCII characters between space and lowercase 'z', except for the double quote and backtick (0x60) characters. Moreover, no argument should be longer than 122 characters (including quotes).

invalid argument of SONGS
    The argument of SONGS must be an integer within the range 2-255.

invalid argument of DEFSONG
    The argument of DEFSONG must be an integer greater than zero and less than the argument of SONGS.

missing TYPE tag
    This tag is mandatory.

invalid argument of TYPE
    The currently defined types are: B, C, D, S.

invalid argument of FASTPLAY
    The argument of FASTPLAY must be an integer within the range 1-32767.

INIT is meaningless with TYPE C
    "TYPE C" uses PLAYER and MUSIC tags, but not INIT.

MUSIC is meaningful only with TYPE C
    The MUSIC tag should be used only with "TYPE C".

missing PLAYER tag
    The PLAYER tag is mandatory for "TYPE B" and "TYPE C".

invalid argument of INIT, PLAYER, MUSIC or COVOX
    The argument of these tags must be 4-digit hexadecimal number.

duplicate tag: ...
    The same tag appears several times within the header.

unknown tag: ...
    Known tags are: SAP, AUTHOR, NAME, DATE, SONGS, DEFSONG, TYPE, FASTPLAY, STEREO, NTSC, INIT, PLAYER, MUSIC, COVOX.

duplicate FFFF in the binary part
    A binary block starts with four 0xFF bytes.

block end address less than start address
    Each binary block begins with a header that specifies the addresses of the first and the last byte in the block. The end address must not be less than the start address.

missing TIME tags
    The SAP file contains no TIME tags or less TIME tags than songs.

BUGS
The checks are more strict than necessary, which is a good thing.

AUTHOR
Piotr Fusik "fox@scene.pl".

SEE ALSO
asap-mplayer(1), asap-sdl(1), asapconv(1), sap2ntsc(1), sap2txt(1)