1 Synopsis

advscan [-c, --cfg CONFIG] [-r, --rom] [-s, --sample]
    [-k, --disk] [-a, --add-zip] [-b, --add-bin]
    [-d, --del-zip] [-u, --del-unknown]
    [-g, --del-garbage] [-t,--del-text]
    [-n, --print-only] [-p, --report]
    [-f, --filter FILTER]
    [-v, --verbose] < info.xml

advscan [-R, --rom-std] [-S, --sample-std]
    [-K, --disk-std]< info.xml

advscan [-i, --ident] files... < info.xml

advscan [-l, --bbs] < info.xml

advscan [-e, --equal] < info.xml

advscan [-h, --help] [-V, --version]

2 Description

Differential merging means that any game has its zip archive, which contains all the rom files, which are not already in the parent zip archive (if exists).

advscan has these features:

• Directly read, writes zip archives without decompressing and recompressing them for best performance.
• Add, copy, move and rename files in the zip archives. Any rom that you have is placed automatically in the correct zip.
• Recognizes the text files added by rom sites and deletes them.
• Recognizes the text files added by the rom dumpers and keeps or deletes them as your choice.
• It's safe. In all the zip operations any file removed or overwritten is saved in the `rom_unknown' and `sample_unknown' directories and keep for future uses. This will prevent any unwanted remove operation.

but also has these misfeatures:

• Supports only roms and samples zipped.
• Supports only roms organized with differential merging.
• Doesn't support .chd files in subdirectories.

3 Getting Started

Let's start your preferred text editor and create the configuration file advscan.rc with these options:

rom DIR_OF_YOUR_ROMS rom_new DIR_OF_YOUR_ROMS rom_unknown DIR_OF_REJECTED_ROMS rom_import DIR_OF_ROMS_TO_IMPORT

The most important configuration option is the directory where your roms are stored. This directory must be specified in the 'rom' and 'rom_new' options. The 'rom_unknown' option is used to select the directory where store the unused roms. AdvanceSCAN never deletes roms for safety, so you need to specify this 'basket' directory. With the 'rom_import' option you can specify the directory where the roms to import resides. For example the update packs you want to integrate in your roms. If you don't have any, omit this option.

To analyze the roms, AdvanceSCAN needs also the roms information file from the emulator. This file can be created with the command:

mame -listxml > info.xml

Finally, you can now run AdvanceSCAN to fix your roms with the command:

advscan -R < info.xml

You can also generate a report of the state of your roms running the command:

advscan -r -p < info.xml > report.txt

4 Options

5 Information Options

6 Identification

Sample files are identified only by their names. This limits the possible operations. Essentially advscan can report only missing samples.

Garbage files are identified by their size and crc.

All the others files are identified with this algorithm:

• If the name is like *.sam, *.wav it's considered an unknown binary file.
• If the name is like *.doc, *.txt, *.nfo, *.diz, readme.* it's considered a text file.
• If the size is a power of 2 it's considered an unknown binary file.
• Otherwise it's considered a text file.

7 Configuration

The rom information file is the file that contains the information of all the roms used by the emulator. It can be made with the command:

mame -listxml > info.xml

This file is expected as input of advscan. So, you can use this command:

advscan [options] < info.xml

Or combine the two commands together:

mame -listxml | advscan [options]

The configuration file is a text file that describes your directories structure. You can use absolute path or relative path. Relative path is relative to the current directory from where you run advscan.

In Unix the PATH separator is `:'. In DOS and Windows the PATH separator is `;'. The following options are expressed with the Unix format.

rom PATH:PATH...

List of paths where the roms are placed. These are the zip archives, which are modified and fixed.

rom_new PATH

Single directory where the new created zip archives are placed. It's STRONGLY suggested to put this path ALSO in the `rom' specification. Otherwise at the next run the zip archives are recreated.

rom_import PATH:PATH...

List of directory trees where other roms files are placed. These are used for importing rom file missing in rompath. These files are only read and never modified in any way. It's very useful to insert here any rom directories of any other arcade emulators. When a new game will be supported the rom archive will be made automatically.

rom_unknown PATH

Single directory where unknown rom zip archives will be moved. In this directory is inserted any rom file removed from the rom zip archives. However, any rom file is automatically deleted by advscan if it's duplicated in an archive listed on the `rom' or `rom_import' options.

sample PATH:PATH...

List of paths where the samples are placed. These are the zip archives, which are modified and fixed.

sample_unknown PATH

Single path where unknown sample zip archives will be moved. In this directory is inserted any sample file removed from the sample zip archives.

disk PATH:PATH...

List of paths where the disks are placed. These are the chd archives.

disk_unknown PATH

Single path where unknown disk chd archives will be moved.

If the -c option is not specified the configuration file is read from ./advscan.rc.

The files advscan.rc.linux and advscan.rc.dos are two examples of configuration files.

8 Damaged Files

If the rename operation isn't possible the program aborts.

Please note that the program doesn't execute an extensive test to detect damaged files.

9 Filters

The filters available are:

	working	Use only working roms. A working rom is a rom reported working or a rom needed by another working rom. A rom is reported working if it isn't marked with the "preliminary" flag in the driver, video or sound. This should be the preferred filter which only store playable games.
	preliminary	Use only roms which are not in the "working" subset.
	working_parent	Use only working parent roms from the "working" subset excluding clones. If a parent rom is not working but it has a working clone, both the parent and the clone are used. This is the preferred filter if you want only one working game for any parent/clones group.
	working_clone	Use only roms which are in the "working" subset but not in the "working_parent" subset.

For example, if you want to keep preliminary and working roms in different directories, you can setup two different advscan.rc files with different directories but sharing the `rom_unknown' dir to allow automatic rom moving between the two sets. If this is your configuration, to update your romset, you need to run advscan three times:

	on working set	To export preliminary roms in the rom_unknown dir.
	on preliminary set	To import preliminary roms and export working roms in the rom_unknown dir.
	on working set	To import working rom from the rom_unknown dir.

For example:

advscan -R -c advscan-wrk.rc -f working < advmame.xml > rom_wrk.log advscan -R -c advscan-pre.rc -f preliminary < advmame.xml > rom_pre.log advscan -R -c advscan-wrk.rc -f working < advmame.xml > rom_wrk.log

10 Report Format

11 Examples

advscan -R < info.xml

This command will fix your rom collection (without removing the precious text files).

To check in advance all the operations that will be done you can use the command:

advscan -R -n < info.xml

which only show the operations.

To only generate an extensive report of your rom set you can use the command:

advscan -r -p < info.xml > report.txt

To increase the verbosity of the printed information you can add the -v switch.

12 Copyright

13 See Also