
				       XD
				 eXtended Dump

			   Copyright Jason Hood 2003

			     Freeware. Version 1.00


    ===========
    Description
    ===========

    XD is a utility to help make sense of a binary file. Not  only  does  it
    have  the usual hexadecimal and/or character display, but also a config-
    urable record display.  With records it is possible to see the structure
    of	a  file  (particularly	useful with high-score tables).  XD can also
    write the text dump back to the binary file.


    =====
    Usage
    =====

    xd [options] [files] [options]

    where "xd" is any of the .exes:

	xd:	32-bit DOS (requires 386; also see "cwsdpmi.txt")
	xd16:	16-bit DOS (should work anywhere)
	xd32:	32-bit Windows console

    Options and files can be freely intermixed, as all options will apply to
    all files.	If no file is given, standard input will be used; no options
    will perform a hex and character dump, 16 bytes per line.

    Briefly, the options are:

	-x		Hex dump
	-c		Character dump (ASCII characters)
	-a		Character dump will use alphanumeric characters
	-A		Character dump will use all (printable) characters
	-<num>		Bytes per line
	-r<record>	Record format
	-~		Reverse the byte order of records
	-f		"Formatted" record file
	-w		Write a binary file from a text file
	-o		Offset display
	+<offset>	File position
	=<count>	Number of bytes or records to display

    Options beginning with "-" can be combined. Numbers can begin with  "0x"
    for  hex  or  "0" for octal ("-20", "-0x14" and "-024" all mean 20 bytes
    per line).


    x - Hex dump

    Only display the hexadecimal numbers, without the character equivalents.


    c - Character dump

    Only display the characters, without the hexadecimal equivalents.


    a - Alphanumeric
    A - All

    The default character dump will only display the printable	ASCII  char-
    acters, using a "." for the other characters. "-a" will only display the
    alphanumeric characters; "-A" will  display  all  printable  characters.


    <num> - Bytes per line

    Display this many bytes per line. Note that using  a  hexadecimal  value
    and combining it with "c" will require the "c" to go first (eg: "-0x40c"
    will display a hex and character dump of 1036 bytes,  not  a  character-
    only  dump	of  64	bytes;	use "-c0x40" instead). Likewise when using a
    formatted record file.


    r - Record

    Instead of simply processing the file as bytes, this option  will  allow
    it	to  be	processed  as  a  series of types, providing a more readable
    output. Please see the help screen for the types available. Each  record
    is	displayed  on one line; if more than one record is specified a blank
    line will be displayed after all the  records.  If	a  record  can't  be
    displayed  (end-of-file  occurred  or  an invalid string), a normal dump
    will be displayed instead (up to the location of the error). A backspace
    character is written to separate the dump from the records.

    Here's a couple of simple examples.  Let's say  you  have  a  high-score
    table that looks like this:

	1ST	10000
	2ND	 5000
	3RD	 2500

    The dump might look like this:

    000000  31 53 54 00 10 27 00 00 32 4e 44 00 88 13 00 00  1ST..'..2ND....
    000010  33 52 44 00 c4 09 00 00			     3RD....

    From this you could deduce that the  name  is  a  three-character  zero-
    terminated	string	(type  "z")  and the score is four bytes (type "l").
    This could be displayed as a record by using "-r3zl"  -  read  a  three-
    character  zero-terminated	string	followed  by  a long, and keep going
    until the end of the file.

    Some high-score tables, though, place all  the  names  first,  then  the
    scores. In that case, the dump would look like this:

    000000  31 53 54 00 32 4e 44 00 33 52 44 00 10 27 00 00  1ST.2ND.3RD..'..
    000010  88 13 00 00 c4 09 00 00			     ......

    This can be displayed as a record by using "-r3z*3 -rl*3"  -  read three
    three-character  strings,  then  three longs ("-r3l" could also be used,
    but that would display the scores on one line).


    ~ - Reverse byte order

    By default, records are little-endian (the	least  significant  byte  is
    first,  like  on  Intel machines). This option will effectively make all
    records big-endian (the most significant byte is first, like on Motorola
    machines).	Note  that  it	must come before the "-r" to take effect. If
    used again, the order will be restored.


    f - Format

    This option is used to facilitate  the  process  of  modifying  a  file.
    Instead  of  displaying  each file, it will create a new file, replacing
    the extension with ".xdt". It also adds a one-line header to  the  file,
    so	it  is	not necessary to repeat the record format when updating. See
    below for an example.


    w - Write

    This option will turn a text file into its binary equivalent. It can  be
    used  in  conjunction with "-f", where the record format will be read as
    part of the file. If neither "-f" nor any records  are  given,  it  will
    read  two-character  hex  digits  (this  is  important, as it means, for
    example, "123" will be treated as "12 03").  Not  specifying  "-f"  will
    create a new file, replacing the extension with ".xdb".

    An example is in order. Let's say you play a game quite  frequently,  so
    occassionally you'd like to reset the high scores (to values higher than
    the normal default). This could be done by:

	xd hiscores -fr3zl

    This will generate "hiscores.xdt", containing the current  scores.  Edit
    this  file	to  have  the  names/scores  you  desire  and  rename  it to
    "loscores.xdt". Then every time you want to reset the scores:

	xd <hiscores -r3zl >>hiscores.txt
	xd loscores.xdt -fw

    This will append the current high scores to "hiscores.txt", then replace
    them with the "low" scores.


    o - Offset display

    Normally the dump displays the file offset, but the records do not. This
    option will reverse that behavior.


    <offset> - Offset position

    This option specifies the start and/or end offsets, allowing  a  portion
    of the file to be dumped.  The end offset is ignored for records.


    <count> - Count

    Limit the number of bytes or records to display, rather than  using  the
    entire file.


    ===========
    Limitations
    ===========

    The source should compile on a big-endian  machine,  but  the  resulting
    executable will probably not work.

    Control and Unicode characters are converted to "." in the  dump.  There
    is	currently  no way to translate them back for "-w". Similarly, spaces
    will be ignored for the character type (thus using the  first  character
    of the next type) and quotes will cause problems for the string types.

    The line number for record write errors is only  a	guess,	based  on  a
    normally formatted record file (the file can actually be free-form).

    Creating an ".xd[bt]" file will not  prompt  to  overwrite  an  existing
    file, if the base name is the same, but the extension is different.

    Updating a file requires being in the same directory  where  the  record
    file was created (otherwise a new file is created).


    =======
    Contact
    =======

    mailto:jadoxa@yahoo.com.au
    http://xd.adoxa.cjb.net/

    Jason Hood
    11 Buckle Street
    North Rockhampton
    Qld 4701
    Australia


    ============
    Distribution
    ============

    The original zipfile can be freely distributed, by any means. However, I
    would  like  to  be  informed if it is placed on a CD-ROM (other than an
    archive compilation).  Modified versions may be distributed, as long  as
    the original zipfile is included (I would prefer to be contacted).


    ============================
    Jason Hood, 7 October, 2003.
