@external-css=allegro.css
@document_title=dat

<center><h1><b>
The DAT archiver 
</b></h1></center>
<hr>

@heading
Commandline options

As an alternative to the graphical grabber program, you can use the command 
line dat utility. This accepts the following options:

   '-a &ltfiles&gt'

      Adds the named files to the datafile, for example:

<textblock>
	 dat myfile.dat -a title.pcx scream.wav
<endblock>

      If the objects are already present in the datafile, their current 
      contents will be replaced. Names for the new objects will be generated 
      from the input filenames, and the object type will be detected from 
      the file extensions. In some cases this is ambiguous, for example a 
      PCX file can be read as a bitmap, RLE sprite, compiled sprite, or font 
      object, so you may need to explicitly specify the object type with the 
      '-t' flag. For example, to insert alien.pcx as an RLE sprite, use the 
      command:

<textblock>
	 dat myfile.dat -a alien.pcx -t RLE
<endblock>

   '-bpp colordepth'
      Specifies which color format bitmap data should be grabbed in (valid 
      depths are 8, 15, 16, 24, and 32 bits per pixel).

   '-c0' - no compression

   '-c1' - compress objects individually

   '-c2' - global compression on the entire datafile

      Sets the compression mode (see below). These can be used on their own 
      to convert a datafile from one format to another, or in combination 
      with any other options.

   '-d &ltobjects&gt'

      Deletes the named objects from the datafile.

   '-dither'

      Dithers graphics when reducing color depths.

   '-e &ltobjects&gt'

      Extracts the named objects from the datafile. To extract everything, 
      use the wildcard * as the object name. To set the output filename or 
      directory, use the '-o filename' option. For example, to extract an 
      object called TITLE_SCREEN to the file title.pcx, use the command:

<textblock>
	 dat myfile.dat -e title_screen -o title.pcx
<endblock>

      To extract the entire contents of the datafile to the directory 
      c:\output, use:

<textblock>
	 dat myfile.dat -e * -o c:\output\
<endblock>

   '-f'

      Stores the references to original files as relative filenames instead of
      absolute filenames. This greatly increases the portability of complete
      source trees containing the source data.

   '-g x y w h'

      Grabs bitmap data from a specific grid location.

   '-h outputfile.h'

      Sets the output header file, for exporting object index definitions. 
      This may be used on its own to produce a header file from an existing 
      datafile, or in combination with any other commands. You can also use 
      the '-p prefixstring' option to set a prefix string for the object 
      definitions.

   '-k'

      Keep original names while grabbing objects. Without this switch, a 
      file called image.pcx will be imported as an object called IMAGE_PCX, 
      to ensure that all the object names are valid symbols for the output 
      header defines.

   '-l'

      Lists the contents of the datafile. This can be combined with the '-v' 
      option to list object properties along with the names, and you can 
      specify particular objects to produce a partial listing.

   '-m dependencyfile'

      Writes a set of makefile dependencies into the specified file, which 
      can be used to automatically update the file whenever any of the 
      source data changes.

   '-n0' - no sort: list the objects in the order they were added

   '-n1' - sort the objects of the datafile alphabetically by name

      Sets the sort mode (see below). These can be used on their own to 
      sort the objects of the datafile, or in combination with any other 
      options.

   '-o output'

      Sets the output file or directory when extracting data.

   '-p prefixstring'

      Sets the prefix for the output header file.

   '-pal objectname'

      Specifies which palette to use.

   '-r'

      Recursively adds directories as nested datafiles. This makes it possible
      to maintain the data hierarchy within the datafile.

   '-s0' - no strip: save everything

   '-s1' - strip grabber specific information from the file

   '-s2' - strip all object properties and names from the file

   '-s-PROP' do not strip object property PROP from the file

      Sets the strip mode (see below). These can be used on their own to 
      strip properties from the datafile, or in combination with any other 
      options.

   '-t type'

      Sets the object type when adding files.

   '-transparency'

      Preserves transparency when converting between color depths.

   '-u'

      Updates the contents of the datafile. See below.

   '-v'

      Selects verbose mode. This can be used in combination with any other 
      options to produce more detailed output.

   '-w'

      Always updates the entire contents of the datafile.

   '-x &ltobjects&gt'

      Alias for '-e &ltobjects&gt'.

   '-007 password'

      Sets the file encryption key.

   '&ltobjects&gt PROP=value'

      Sets properties for the specified objects. This works like environment 
      variables, in that setting a property to an empty string removes it. 
      Because object names are stored as NAME properties, you can use this 
      command to rename objects. For example, to rename MY_OBJECT to 
      WHAT_A_SILLY_NAME, use the command:

<textblock>
	 dat myfile.dat my_object NAME=what_a_silly_name
<endblock>

      You can use the wildcard * to apply the property to everything in the 
      file, so to remove the ORIG property from the entire datafile, you 
      could execute:

<textblock>
	 dat myfile.dat * ORIG=
<endblock>

You can create hierarchical nested datafiles by inserting one datafile into 
another with the '-a' command. Objects in the nested datafile can then be 
referred to by as "parentname/objectname". For example if the datafile 
myfile.dat contains a nested datafile called nestedfile, which contains a 
bitmap called thepicture, you could export the bitmap with the command:

<textblock>
	 dat myfile.dat -e nestedfile/thepicture -o output.pcx
<endblock>