-------------------------------------------------------------------------------
                         DatUtil v1.20 - 20/05/2002

                  Written by Logiqx (http://www.logiqx.com)
-------------------------------------------------------------------------------

Introduction
------------

DatUtil was created to aid in the creation of dat files for Rom Managers such
as ClrMamePro and RomCenter (Roman Scherzer / Eric Bole-Feysot). It can convert
between formats, compare dats, extract individual games (and optionally their
clones), cleanse dats etc. It handles a variety of formats:

MAME Listinfo/ClrMamePro
RomCenter 1
RomCenter 2
MESS Listinfo
RAINE Gameinfo
Nebula Driver
Calice Driver
Directory scan (subdirectories and ZIPs)
Title List (for listing game titles - used by CPS-2 readme and RAINE docs)
Mimic HWC
Shark Listinfo
Retrocade Romlist
Callus Gamelist
System16 GCS
JFF.TXT
Sparcade RAT
JAS Romlist

The only formats that are for ROM managers are the first few but the others can
be used to check for missing/extra ROMs in your newly created datfile.

Adding support for additional formats is really easy too. If you do add support
for a new format please let me know and send me a copy of the code!

This program was developed under the GNU licence and is completely free but
you use DatUtil at your own risk. I take no responsibility for any loss/damage
caused as a result of it's use. Having said that though, I would be very
surprised if your machine burst into flames as a result of using it.  ;-)


Distribution
------------

The home page for DatUtil is http://www.logiqx.com/

Links can also be found at the following two sites:

ClrMamePro Home Page                    RomCenter Home Page        
http://www.mameworld.net/clrmame        http://www.romcenter.com/


The Executables
---------------

datutil.exe - supports standard 8.3 ROM names (no longer distributed)
datutilx.exe - supports 80 character ROM names (requires more memory)


Converting Dats
---------------

It is possible to convert dats between ClrMamePro and RomCenter with ease. The
most simple way to convert from one format to the other is like this:

datutil <datfile>

This will convert a ClrMamePro dat (listinfo) to a RomCenter datafile or
a RomCenter datafile to a ClrMamePro dat. The new dat is called 'datutil.dat'.
If you want to specify a different output filename, use the '-o' option.

e.g. datutil -o clrmame.dat romcenter.dat

This would convert romcenter.dat, saving the new file as clrmame.dat.
There is also a '-a' option to append to an existing file. This is especially
useful when converting/extracting individual games (explained later).

If you wish to specify the output format directly (for example, if you want
DatUtil to clean up the dat and resave in the same format) you can use the '-f'
option. Valid formats are 'listinfo', 'romcenter', 'romcenter2' or 'titlelist'.

e.g. datutil -f romcenter clrmame.dat

If you just wish to convert/extract an individual game of the original dat
you can use the -g option (and optionally -c for it's clones as well).

e.g. datutil -g sf2 -c romcenter.dat

This would extract sf2 and all of it's clones from romcenter.dat, saving them
under the name datutil.dat (of course, the '-o', '-a' and '-f' options could
be used in addition). This feature is useful for creating dats for an emulator
that uses ROM sets like those in MAME (extract from the output of listinfo).
When specifying individual games, datutil saves the new file in the same format
as the original (as opposed to doing a conversion between formats).

If you wish to exclude clones from the newly saved dat, you can use the '-r'
(remove clones) option.

People converting dats for home computers will often wonder what the 'funny
size' warnings are. This is intended for arcade dat creators so you can switch
off the size checking using the '-z' option.

To convert all game names, ROM names and ROM CRCs to lower case, use the '-l'
option.

The option to improve merging information ('-m') will ensure that CRCs match in
the parent and it's clones where they were previously a mixture of 00000000s or
complimented CRCs. After the CRCs have been unified it will then specify that
the ROMs can be merged.

The final option is '-s' for sorting the games before saving. This is essential
when saving RomCenter 1 and Title List dats so it is automatically switched on
for these formats.


Additional notes on conversion
------------------------------

When DatUtil saves a MAME datfile in RomCenter 1 format it will remove the 3
Neo-Geo ROMs from all Neo-Geo games and include the 'neogeo' resource as a game
(just as RomCenter does already).

The RomCenter 1 format doesn't support all of the potential information that is
in the MAME listinfo output. DatUtil will warn you if any information is lost
during conversion process though (e.g. samples, 'merge' details that specify a
different name and games with differing 'romof/cloneof' details).

When editing dats I find it easiest to work on a ClrMame dat (it's easier to
read) then convert it to RomCenter afterwards. DatUtil will create a RomCenter
dat just as good as you could have done by hand but less prone to errors.  ;-)

You will have noticed that ROMCenter dats and CMPro dats have a header section.
To specify values for the fields in the header, use the '-A', '-V', '-C', '-R'
and '-F' options (author, version, comment, refname, fullname/emu version).
Note that these options are all upper case (you must use the correct case).


Comparing Dats
---------------

To compare two dats (whatever their formats) you can use the basic command:

datutil retro.dat romlist.txt

This would compare the retro.dat against the romlist.txt file that came from
Retrocade. As the romlist file only contains names (no sizes or CRCs), this use
of DatUtil will just tell you if you have any extra/missing ROMs in your dat.
When doing a comparison of two 'real' datfiles it will compare all details that
are supported by both dat formats (size, CRCs, parent names etc.)

The results of the comparison are written to datutil.log by default but as with
conversion you can use the '-o' and '-a' options to specify the filename.

The only other options available when doing comparisons are the '-g' and '-c'
(to specify an individual game and it's clones).

Tip: When using System16 GCS, Sparcade RAT or Mimic HWC files, concatenate the
individual files together so that you can compare them against a dat in one go.


Dat features supported
----------------------

DatUtil has it's own internal representation for datfiles but in MAME Listinfo
terms it supports:

Games      game, resource, machine, name, description, cloneof, romof
           manufacturer, year
ROMs       name, merge, size, crc
Samples    sampleof, sample

On top of this, alternative ROM names and sizes are supported (used in Shark
listinfo.txt).

I forgot to mention earlier that I don't include samples in the comparison
facility (just conversion). Maybe I'll put them in at some time!

I also don't support the 'archive' information in Raine's gameinfo or
Shark's listinfo files (as no ROM manager supports this property).

When DatUtil does comparisons it will only compare features that are supported
by both formats. However, if certain features are used in one of the dats and
not supported by the other then DatUtil will warn you of this fact.


Adding support for new dat formats
----------------------------------

Take a look at readme.txt in the src directory. It is really easy to add
support for a new format but if you can't code, drop me an e-mail and I might
do it for you. Please do not send large files without asking first.


Other uses?
-----------

DatUtil can scan a directory and create a datfile for the ZIPs/subdirectories
within it. Simply specify the directory name to scan (instead of a datfile) and
DatUtil will generate the dat for you.

When a new release of MAME or MESS comes out you could use DatUtil to tell you
which games are new/changed. Actually, this also applies to the other supported
formats... RAINE, Retrocade, Callus, Shark, System16, Sparcade, JAS and JFF
etc (should they ever have new releases).

However, if you want to compare two versions of MAME, MESS or RAINE use my tool
MAMEDiff as it does a better job than DatUtil. Get it from my web site...


Thanks
------

Thanks go to the Eric Bole-Feysot and Roman Scherzer for mentioning DatUtil on
their web sites. Extra thanks also go to Eric Bole-Feysot and Pi for their time
testing DatUtil during it's life.


Bug Reports
-----------

If you find any bugs please let me know about them and provide details such as
OS version, command you are using, dat you are running it against etc.

Feel free to send me any suggestions that you have also.


History
-------

20/05/2002  *** v1.20 ***
            - New resource ROMs in MAME listinfo are automatically detected.
            - ClrMamePro log and Nebula driver loaders now use the STORE_ROM
              macro (this makes -g work correctly, amongst other things).
            - Improved -m (fix merging) behaviour for resource ROMs.
            - Nebula drivers now output the correct 'romof' for Neo-Geo clones.

22/04/2002  *** v1.19 ***
            - Added support for the PGM resource.

20/04/2002  *** v1.18 ***
            - Increased maximum number of samples to 10,000 (for PinMAME).
            - Exceeding the sample limit now results in a graceful exit.

04/04/2002  *** v1.17 ***
            - Made 'fix-merging' option check the CRC as well as the name.
            - Fix merging option warns of CRC conflicts it finds. Useful test!
            - Strips trailing spaces from Nebula ROM names (for convenience).
            - Executable is called 'datutil.exe' again.

28/03/2002  *** v1.16 ***
            - Added Nebula driver support (useful for data file validation).
            - Supports the new '0x' syntax of CMPro logs.
            - ZIP scanner now removes '.Zip' from filenames (case sensitive).
            - Increased maximum line length to 16384 bytes (for MAME history).
            - Increased maximum number of ROMs to 75000.
            - Exceeding the game or ROM limits now results in a graceful exit.

10/02/2002  *** v1.15 ***
            - Enhanced Calice support to cope with Neo-Geo sound ROMs.
            - Modified source to compile easily with CygWin (and FreeBSD?).

11/11/2001  *** v1.14 ***
            - Added knowledge of ng-lo.rom.

27/09/2001  *** v1.13 ***
            - Supports CPSE driver file.
            - Added 'ignore funny size' option (-z) for non-arcade dats.
            - Added 'make lower case' option (-l). Affects names and CRCs.
            - Puts "s around empty CMPro header items.
            - Fixed directory/zip scanner for ROM names containing spaces.
            - Fixed zip scanner to strip uppercase '.ZIP' from game names.
            - Improved the 'funny size' warning relating to RomCenter 2 dats.

28/08/2001  *** v1.12 ***
            - Supports new ROM loading introduced in Calice v0.3.8 to v0.4.4

28/06/2001  *** v1.11 ***
            - Added some warnings for bad quality RomCenter dats (wrong version
              number in header and missing ROM sizes)

23/06/2001  *** v1.10 ***
            - Fixed detection of RAINE32 dat format.
            - Improved ZIP scanner (not case sensitive when searching for zips).

08/06/2001  *** v1.9 ***
            - Added directory scanning feature (reads ZIPs and subdirectories).
            - Calice loader now uses the main driver code, not 'verifyroms'.
            - RomCenter 2 loader fixes missing 'romof' details automatically.

18/05/2001  *** v1.8 ***
            - Fixed a minor bug in the '-m' feature (bug introduced in v1.7).
            - Now compiled with MinGW (no long filename problems on NT now).

26/04/2001  *** v1.7 ***
            - Added handling of decocass resource in MAME dats.
            - Added load/save support for CMPro element 'clrmamepro' and
              ROMCenter headers.
            - Added preliminary support for Calice Driver files.
            - Added load support for ClrMamePro log files (i.e. to convert into
              a dat format).
            - Further improved the '-m' feature ('fix merging' option).
            - RomCenter2 save routine strips redundant 'merge' information from
              non-clones.
            - DJGPP compilation now uses -Wall option.
            - Can now be compiled with Microsoft Visual C++.

21/02/2001  *** v1.6 ***
            - Added option to improve MAME's merging information ('-m').

06/02/2001  *** v1.5 ***
            - Some handling of the playch10 and cvs resources in MAME dats.
            - RomCenter 2 is now the default save format when converting CMPro
              dats.

18/12/2000  *** v1.4 ***
            - Mimic HWC support.
            - New format to list game titles ('-f titlelist').
            - Year/Manufacturer support for formats that can include them.
            - Can specify values for ROMCenter/ROMCenter2 headers.
            - Remove clones factility ('-r').
            - GWC loader now understands '.speech' tags (System16 Beta).
            - Callus95 Patch renamed 'directory' to 'parent'. Now supported.
            - Auto sorts when converting to RomCenter format or a Title List.
            - Improved sorting (ensures each parent precedes it's clones).
            - RAINE and MESS files are converted to CMPro format by default.
            - Fixed a problem with the '-g' option and RAINE gameinfo files.
            - Increased maximum ROM size to 9 characters (~1GB) for U64Emu.
            - Increased number of lines scanned when identifying CMPro dats.
            - Source: Added a makefile and included a SAVE_ONLY_FORMAT.
            - Source: Changed parameter passing (uses a structure now).
            - Preliminary: 'Verify Merging' facility (currently disabled).

19/05/2000  *** v1.3 ***
            - RomCenter 2 support ('-f romcenter2').
            - New method of sorting (useful for RomCenter).
            - Two EXEs. This is because the long ROM name version eats memory
              and is slow on machines without much physical memory.
            - Improved handling of invalid parents.
            - Warns of funny ROM sizes.
            - Generates log of warnings during conversion.

28/04/2000  *** v1.2 ***
            - Increased game/rom name length to 80 characters.
              (DatUtil now requires even more memory for the dats!)
            - Minor string handling improvements. yawn...

08/04/2000  *** v1.1 ***
            - Added support for JFF.TXT, Sparcade RAT and JAS Romlist.
            - Increased maximum number of games from 4096 to 5000.
            - Increased game/rom name length to 50 characters.
              (DatUtil now requires a HUGE block of memory to hold the data)
            - Improved listinfo parser so that it can handle odd formatting.
            - Other minor modifications.

31/03/2000  *** v1.0 ***
