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=" 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=" 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)