                               Command : XDUMP

NAME
   xdump - Extended dump of everything under the sun

Level: Expert

SYNTAX
   [##:##] Command : xdump <TYPE|NUMBER> <RECORDS>

SYNTAX
   [##:##] Command : xdump meta <TYPE|NUMBER>

The  xdump command displays information on game configuration and state in ma-
chine readable format.  It is intended for use by clients and tools.  This in-
fo  page  gives an overview; see doc/xdump in the source distribution for com-
plete documentation.

Game configuration and state consists of a number of tables or  files.   xdump
shows  only  things  that  are certainly visible to you: sectors you own, ship
types known, etc.

The output of xdump is a table consisting of a header line, the table body and
a footer line.

The  header line is of the form "XDUMP <TYPE> <TIMESTAMP>".  <TYPE> identifies
the dump.  The timestamp permits incremental dumps (see below).

The body consists of records; one record  per  line.   A  record  consists  of
fields  separated  by  a  space.   All records have the same number of fields.
Fields match records in the table's meta-table (see below).

A field is either in integer, floating-point number or string format.   In  no
case does it contain space or newline.  All fields in the same column have the
same format.

Integer fields are in decimal; they can be parsed by scanf %d.  Conversely, if
that succeeds and consumes the complete field, it's an integer field.

Floating-point fields can be parsed by scanf %g (or equivalents %e, %f).  Con-
versely, if that succeeds, it's a floating-point field.

String fields are in C syntax.  Funny characters including space, newline  and
double-quote  are  shown  as octal escape sequences.  Example: "gold\040mine".
If a field starts with a double-quote, it's a string field.

FUTURE DIRECTIONS:  We might decide to support more C  escape  sequences,  but
never \".

Some  fields  can  contain  null  strings.  A null string is the three letters
"nil".  If a field contains nil, it's a string field.

Each table has a meta-table, which defines format and meaning of  its  fields.
To show the meta-table for <TYPE>, use
   [##:##] Command : xdump meta <TYPE>

All  meta-tables  share the same meta-meta-table, which is its own meta-table.
The command to show it is
   [##:##] Command : xdump meta meta

Fields correspond to selectors used in Empire conditionals (see  "info  Selec-
tor"), and they use the same names.  Naturally, xdump shows fields correspond-
ing to deity-only selectors only to deities.

The command to display table <TYPE> is
   [##:##] Command : xdump <TYPE> <RECORDS>

Argument <RECORDS> selects which records to show, in common Empire syntax  for
the kind of things in that table.  "*" always shows the complete table.

To dump sector -22,2, for example, you can use:
   [##:##] Command : xdump sect -22,2

This dumps all ships with mobility in fleet a:
   [##:##] Command : xdump ship a ?mobil>0

This dumps all sectors changes after timestamp 1141068862:
   [##:##] Command : xdump sect * ?timestamp>1141068862

Use  this  with a value one less than the timestamp in the xdump header to get
everything that changed since that xdump (incremental dump).

FUTURE DIRECTIONS:  We may still extend the syntax  to  select  fields  to  be
shown.

The  table "table" is the table of (non-meta-)tables.  It contains table names
and numbers.  xdump accepts table numbers as well as names.  Table numbers may
differ between server versions.

BUGS:  Still  missing  are game state files power, map, bmap; the list of com-
mands; foreign levels, contact information, mortal access to  sector  selector
mines,  ship  selectors  xbuilt, ybuilt, trade selectors xloc, yloc, commodity
selectors xbuy, ybuy, xsell, ysell.  Some information is not yet available  in
human-readable  form:  the  lost  file,  sect-chr  selector nav, ship and land
plague status (deity only), plane theta (governs  satellite  movement),  trade
selectors  xloc,  yloc,  commodity  selectors  xbuy,  ybuy.   Incremental dump
doesn't work after importing news with the empdump utility.

FUTURE DIRECTIONS:  xdump evolves along with the server.  Clients should  cope
gracefully  with new tables and fields.  We try to avoid incompatible changes,
but they are occasionally necessary to make progress.

SEE ALSO
   dump, ldump, ndump, pdump, sdump, lost, show, version, Communication,  Lan-
dUnits, Planes, Sectors, Ships

