                          CartList v3.0 by SunTzu7
                  The Authoritative ROM Cataloging Utility
                  ----------------------------------------

PREFACE
-------

This project began for a specific reason: I didn't have a utility
that would extract game information from more than one ROM image
at a time.  The previous version of CartList did just that, but
was a little buggy.  I was going to leave it as it was until I
discovered that a number of people were very much interested in
it.  Therefore, being the narcissist that I am, I decided to make
a utility that would encapsulate the concept of ROM image cataloging.
What started off as one program branched into four.  The result
is what I believe to be the most comprehensive collection of tools
to manage your ever-growing lists of ROM images. 

SO HOW DOES IT WORK?
--------------------

Well, I'd like to think that it's self-explanatory from the
help screens that are invoked with the "-?" or "-h" options.
However, there are some noteworthy items that need addressing.
Instead of writing a full-blown document that explicitly describes
every detail of CartList's functionality, I'll explain via
example. 


cartlist -h
cartlist -?

	Prints out a help screen that explains what the various command
	line options to CartList are.
	
cartlist -snes

	Prints a help screen that explains the format of the output
	CartList generates for a Super Nintendo image.
	
cartlist -sega

	Prints a help screen that explains the format of the output
	CartList generates for a Sega Genesis image.

cartlist -gb

	Prints a help screen that explains the format of the output
	CartList generates for a Gameboy image.

cartlist -n64

	Prints a help screen that explains the format of the output
	CartList generates for a Nintendo 64 image.

cartlist

	Examines all the files in the current directory and prints
	out one line of game information for every file.  (If a
	file is not a recognized game type, it prints out blank 
	information.)
	
cartlist -i

	Examines all the files in the current directory but only prints
	out information on images that it recognizes.
	
cartlist -l

	Prints out a two line summary of image information rather than
	the default of one.

cartlist *.1 *.smd *.md

	Examines only the files with extensions of .1, .smd, and .md.
	Obviously, you can specify any pattern you wish.
	
cartlist -x=*.txt -x=*.diz -x=*.doc	sf*.*

	Examines all the files like "SF*.*" but excludes any files with
	extensions of .TXT, .DIZ, and .DOC.  (eg, SF16025A.078 would be
	examined, but SF16025A.DIZ would be ignored.)
	
cartlist -zip

	In addition to examining the other files in the current directory,
	CartList will also search through all the ZIP archives for ROM
	images.  If a "-temp=<dir>" option is not specified, CartList will
	attempt to extract the ZIP files to the "C:\TEMP" directory.
	The -arj, -lha, -lzh, and -rar options work expectably similarly.
	For these options to work properly, the files "PKUNZIP.EXE", 
	"ARJ.EXE", "LHA.EXE", and "UNRAR.EXE" must be located somewhere
	in your PATH.  

cartlist -zip -lzh -lha -arj -rar
cartlist -allarc

	Those two statements are logically equivalent.  If you want to
	search through all the archive files, you can specify -allarc
	instead of "-zip -lzh -lha -arj -rar".
		
cartlist -zip -temp=d:\temp

	Searches through your ZIP files but extracts the ZIP files using
	the temporary directory of "D:\TEMP".

cartlist > cartlist.txt

	Redirects any output generated by CartList into the file
	"cartlist.txt".  Note that *all* output is redirected...including
	the output from the unarchiving programs.
	
cartlist -out=cartlist.txt -zip

	This will write all of the output from CartList into the file
	"cartlist.txt"  You can specify any filename you wish in place
	of "cartlist.txt".  This is useful when you are searching through
	archive files and only want the output generated by CartList to
	appear in your output file.
	
cartlist -dir=c:\roms
cartlist -dir=c:\roms *.*
cartlist c:\roms\*.*

	CartList will search through all the files located in the
	directory "C:\ROMS"  All three lines are equivalent.

cartlist -r

	CartList will examine all files in the current directory
	as well as the files in all the subdirectories of the current
	directory.  
	
cartlist -l -r e:\ *.smd -allarc

	CartList will scan through your entire E drive and list 2 line
	game information for all .SMD files (even the ones located in
	archives).  
	
cartlist -ns

	CartList will suppress the summary information displayed at the
	end of its run.
	
cartlist -f

	This option will force the generation of checksums on every file
	being examined.  A checksum is simply a way to generate a unique
	number for every file.  This makes it easy to see if you have
	duplicates.  CartList is different from other file checksum
	generators such that it specializes in calculating checksums for 
	ROM images.  It intelligently examines only the code of the ROM
	images and ignores things like headers, game names, etc.  This
	way, even if someone changes the internal game name, you can
	still uniquely identify a ROM image from its checksum value.
	Also, CartList will automatically convert between MGD/SWC/FIG 
	formats (SNES) *and* MGD/SMD/BIN/MD formats (SGEN) on-the-fly 
	to generate the same checksum no matter *what* format your ROM 
	image is!  

cartlist -db=roms.dat 
cartlist -f -db=roms.dat

	Those two lines are equivalent (ie, the -db option automatically
	enables the calculation of checksums).  The -db option specifies
	a database data file from which to search for game name information.
	When the checksum is generated for a file, it will look it up in
	the database file (roms.dat in this example).  If a match is found,
	it prints out the name of the game specified in roms.dat.  The
	ROMS.DAT file included with the CartList archive contains game
	names for the following console systems:
	
		Atari 2600 			- 536  games
		Atari 5200 			- 74   games
		Colecovision 		- 152  games
		GameGear 			- 135  games
		Lynx 				- 108  games
		Sega Master System 	- 135  games
		NES 				- 677  games
		PC-Engine 			- 250  games
		Gameboy 			- 935  games
		Nintendo 64 		- 45   games
		Super Nintendo 		- 2569 games
		Sega Genesis 		- 903  games

cartlist -out=cartlist.txt -compfile=cartlist.dat

	This generates two files: CARTLIST.TXT contains the textual output
	from cartlist ; CARTLIST.DAT contains binary data of the checksums
	of the files listed in CARTLIST.TXT.  CARTLIST.DAT can then
	be used with CartComp and another CartList comparison file to
	identify the differences between the two lists.  This is explained
	further in the CartComp section.
	
The CARTLIST environment variable:

	You also have the option of setting an environment variable 
	called CARTLIST to some options that you use all the time.
	For example, 
	
		set CARTLIST=-temp=d:\temp -r -l -f
		
	Now if you were to invoke CartList alone:
	
		cartlist
		
	It would be just as if you had typed:
	
		cartlist -temp=d:\temp -r -l -f
		
	The environment variable options can be overridden at the
	command line, however.  So with the environment variable 
	specified above, if you typed:
	
		cartlist -temp=e:\temp
		
	The temporary directory used would be E:\TEMP instead of D:\TEMP.
	
	After some more testing, I've found that you cannot use an "="
	sign in the data of the CARTLIST environment variable in
	DOS/Win31.  You might be able to in Win95, and you definitely
	can do so in WinNT.	
	            
	            
CartSort
--------

This program will allow you to sort your CartList output files by
game type and game name.

cartsort cartlist.txt

	This will sort cartlist.txt by the game names and output the
	sorted list to the screen.
	
cartsort cartlist.txt cartsort.txt

	This will sort cartlist.txt by the game names and output the
	sorted list to cartsort.txt

cartsort -2 cartlist.txt cartsort.txt

	This will sort cartlist.txt by the game type and the game
	name specified on the second line of the output in a 
	CartList output file generated with the "-l" option.
	
cartsort -join cartlis1.txt cartlist2.txt cartall.txt

	This will join the two files cartlis1.txt and cartlis2.txt 
	and write the output to cartall.txt.  Note that cartlis1.txt
	and cartlis2.txt must already be sorted for this to work 
	properly!  This option is useful for very large lists that 
	cannot be sorted all at once.  For example, let's say you
	generated a CartList output file of over 500000 bytes.  CartSort
	probably will not be able to sort all of that information.
	So use a text editor and cut the output file into two equal 
	pieces (cl1.txt and cl2.txt).  Now run CartSort separately on
	each file to generate two sorted listings for them.
	
		cartsort cl1.txt cl1sort.txt
		cartsort cl2.txt cl2sort.txt
		
	Now you can join the files together:
	
		cartsort -join cl1sort.txt cl2sort.txt cl_all.txt
		
	The resulting file, CL_ALL.TXT will be the sorted version of
	your original 500000 byte output file.
	
cartsort cartlist.txt cartsort.txt -dups=cartdups.txt

	This will create the sorted list CARTSORT.TXT and will also
	create the file CARTDUPS.TXT which contains all the duplicates
	found in CARTLIST.TXT.  Please be aware that when it is sorting
	via the game name on the first line (default) it only compares the
	first 10 characters.  The reason for this was to cut down on
	the overhead while keeping the sorted listing in memory.  This
	allows CartSort to sort larger lists than otherwise.  If you
	want a surefire way to identify duplicates, then do the following:
	
		cartlist -f -l -out=cartlist.txt
		cartsort -2 cartlist.txt -dups=cartdup.txt
		
	The first step creates a CartList listing with checksums.
	The second step sorts this listing by the second game name
	(where the checksum is located) and writes the duplicates to
	CARTDUP.TXT.  Since the entire checksum is checked, you ensure
	that CARTDUP.TXT contains all the duplicates in CARTLIST.TXT


	
CARTCOMP
--------

This program will allow you to compare two lists generated by 
CartList to see the differences between the two.  This is probably
the most useful tool included in the CartList package.  With it,
you can generate a listing of all your games, and then give that
listing to a friend who can run CartComp against your list and his
list to see what each of you are missing from your respective 
collections.  This makes trading *much* easier.

cartlist -l -f -out=cartlis1.txt -compfile=cartlis1.dat c:\mysnes\*.*
cartlist -l -f -out=cartlis2.txt -compfile=cartlis2.dat c:\yoursnes\*.*
cartcomp cartlis1.dat cartlis2.dat diffs.txt

	Compares the CartList comparison files (generated with the
	"-compfile=<filename>" option) and writes the differences
	to DIFFS.TXT.  Please note that the files specified by
	-compfile and -out *must not* be changed in any way before
	you run CartComp.  If you text edit the CARTLIST.TXT file before
	you run CartComp, you will get unpredictable results.  You also
	must not rename the TXT file because it is used in the DAT file.
	
cartlist -l -f -out=cartlist.txt -compfile=cartlist.dat c:\mysnes\*.*
cartcomp -dbfile=snesroms.dat cartlist.dat

	This will first create a comparison file CARTLIST.DAT.
	The second command will list all of the games found in the
	SNESROMS.DAT database file that are not in your CARTLIST.DAT file.
	This allows you to see which games you are missing.  Please note
	that the ROMS.DAT database file does *not* contain a comprehensive
	listing of all the game titles for the various console systems,
	but it does cover a very large portion of them.  If you have a
	game which is not listed in the ROMS.DAT database, then please
	e-mail me your game name, console type and checksum information
	so I can add it to the list.  (My email address can be found at
	the end of this document.)


CARTDB
------

This program manages your CartList database files.  The one database
file included in the CartList package is ROMS.DAT and contains	
game name information for over 6500 games.  It can create database
files from the output generated by CartList, join two database
file together into one, dump the contents of a database file, and
split a database file apart by the game types.

cartlist -l -f -out=cartlist.txt
cartdb cartlist.txt myroms.db

	The first step creates a long listing with checksum information.
	You need to create the checksums in order to create a database file.
	The second step parses the output from CartList and creates the
	database file MYROMS.DB using the game name found on the first
	line of output and the checksum found on the second line of
	output in the CARTLIST.TXT file.
	
cartdb -join myroms1.db myroms2.db allroms.db

	This will join two database files together into one.  This is
	useful when you want to create a database file from a large
	CartList output listing.  If it is too large for CartDB to
	handle at once, then split the CartList output listing into
	two files (cl1.txt and cl2.txt) and then do the following:
	
		cartdb cl1.txt cl1.db
		cartdb cl2.txt cl2.db
		cartdb -join cl1.db cl2.db allcl.db
		
	The resulting file ALLCL.DB will contain the entire database
	information for the original output file.
	
cartdb -show=# ROMS.DAT

	This will show you the game name and checksums for a given
	game type.  Output is written to the screen.
	"#" can be any of the following:
	
		 0 = ALL
		 1 = Atari 2600       2 = Atari 5200
		 3 = Coleco           4 = Gamegear
		 5 = Lynx             6 = Sega Master System
		 7 = NES              8 = PC-Engine
		 9 = Gameboy         10 = Nintendo 64
		11 = Sega Genesis    12 = Super Nintendo
		
cartdb -show=# ROMS.DAT -outdb=newdb.dat

	This will create a new database file NEWDB.DAT that contains
	only game name information for the specified game type.
	For example:
	
		cartdb -show=12 ROMS.DAT -outdb=snesroms.dat
		
	will create a new database file called SNESROMS.DAT that 
	contains only SNES game name information.  It will also
	dump the SNES game info in ROMS.DAT to the screen.
	
		cartdb -show=12 ROMS.DAT -outdb=snesroms.dat snes.txt
		
	will dump the SNES game info to SNES.TXT
	
		cartdb -show=12 ROMS.DAT -outdb=snesroms.dat > NUL
		
	will dump the SNES game info to the bit bucket
	
	
FINAL WORDS
-----------

If you find any bugs or have any suggestions for improvement, contact
me on EFNet IRC (SunTzu7).  I'm usually idling in #emu or #emuroms.
Or you can e-mail me at "sven@sven.publicnet.com"  Criticisms of the
constructive or intelligent varieties are also welcome.  

If CartList displays a company name which looks arcane or is "unknown"
or has a code listed instead of a name, then please inform me of the
company_code <---> company_name association.

If you run across a ROM image that does not have a match in the ROMS.DAT
file included in the CartList package, then please send me an email
containing the game name, game type, and checksum value so I can keep
the ROM database as comprehensive as possible.  

I could have included database support for C64, Amiga, MSX, Apple II,
Atari 800, Atari ST, BBC, Amstrad, Coco, Oric, Vectrex, Vic20,
Spectrum, TI99, C16, TRS80, etc, etc, etc, etc but these do not seem
to be particularly popular, so I felt I would be wasting my time.  If
I get enough requests for another system, I'll add it.

This program is freely distributable under the condition that it and the
archive in which it came should be unmodified.  Also, in the unlikely
event that you'll be putting this on a commercial CD (as opposed to
a pirate CD), you must obtain my permission first.  


Lastly, 
            **************************************
            *    DO NOT EMAIL ME ROM REQUESTS    *
            **************************************


Hope this util is useful.

 -SunTzu7 (sven@sven.publicnet.com)

