TCL Routines to manipulate object schema and disk dumps
Dervish knows about the internal layout of C-level objects such as
REGIONS; this is manifested in two ways: the ability to return lists
of values of elements of structs along with their names and types
and to change values;
and the ability to write objects to disk and read them back. The latter
in not entirely trivial, as it involves understanding pointers, and
writing out all pointed-to objects.
This document is essentially for reference; fortunately more tutorial
introductions to
disk dumps
and
schema manipulation
have been written.
dumpOpen
dumpReopen
dumpClose
dumpPtrsResolve
dumpDateGet
dumpDateDel
dumpTypeGet
dumpHandleWrite
dumpValueWrite
dumpHandleRead
schemaGetFromType
schemaGet
schemaMemberGet
schemaKindGet
schemaKindGetFromType
There are also some utility routines, written in TCL:
dumpRead
dumpPrint
schemaHashPrintStat
schemaPrint
schemaPrintFromType
Also more information in available on how to access handle
TCL SYNTAX:
dumpOpen <file> <mode>
<file> name of dump file
<mode> mode to open file in. Mode may be r, w, or a for read, write,
or append. If you capitalise the mode, don't perform usual cleanup on close.
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred.
This is the same as dumpOpen, but doesn't initialise the internal data
structures used by the dump code.
TCL SYNTAX:
dumpReopen <file> <mode>
<file> name of dump file
<mode> mode to open file in
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred.
Close an open dump file. If there are any `anonymous' structures left at the
end of the file they are read, and then all remaining pointer id's are
mapped to pointers.
TCL SYNTAX:
dumpClose
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred (e.g. not all pointer id's could be mapped)
Attempt to convert pointer ids to pointers. This will fail if there are
pointer ids whose target has not yet been read, in which case dereferencing
some `pointers' will lead to trouble; binding these ids to handles will
also cause problems. Caveat Lector.
You don't usually need to use this verb explicitly, as it is executed
when a dump file is closed. An example of when you might want to use it
would be just after reading a list, to resolve the `first' and `last' pointers.
TCL SYNTAX:
dumpPtrsResolve
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Not all pointer id's were successfully resolved.
Return the data string from a dump file
TCL SYNTAX:
dumpDateGet
RETURNS:
TCL_OK Successful completion. The date string is returned
TCL_ERROR Error occurred.
Replace the data in a dump file with XXXs. This is occasionally useful for
comparing dump files. No dump file may be open when you use this verb
TCL SYNTAX:
dumpDateDel <file>
<file> The name of the dump file
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred.
Return a string giving the type of the next object in a dump file.
TCL SYNTAX:
dumpTypeGet
RETURNS:
TCL_OK Successful completion. Return the type, e.g. REGION
TCL_ERROR Error occurred.
Write an object described by <handle> to the current dump file.
TCL SYNTAX:
dumpHandleWrite <handle>
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred.
Write an object, given as a <value> and a <type> to the dump file. This
is only supposed to be used for primitive types, ints, longs, floats,
or strings
TCL SYNTAX:
dumpValueWrite <value> <type>
RETURNS:
TCL_OK Successful completion. Return the type, e.g. REGION
TCL_ERROR Error occurred.
Read the next object in a dump file. A handle is returned for your perusal.
TCL SYNTAX:
dumpHandleRead [shallow]
shallow Optional. If true only top-level data structures are
read; see shDumpRead.
RETURNS:
TCL_OK Successful completion. Returns a handle to the object read.
TCL_ERROR Error occurred.
Return a list of { type name } pairs for all members of the specified type;
such information is referred to as a type's schema.
TCL SYNTAX:
schemaGetFromType <type>
<type> The type under scrutiny. You can use either a symbolic name
such as REGION or a number such as 1008.
RETURNS:
TCL_OK Successful completion. Returns a list of {type name}s
TCL_ERROR Error occurred.
Like schemaGetFromType, but the type is taken to be that of the handle.
TCL SYNTAX:
schemaGet <handle>
<handle> The handle whose schema is desired.
RETURNS:
TCL_OK Successful completion. Returns a list of {type name}s
TCL_ERROR Error occurred.
Read an entire dump file from <file>, returning a list of handles.
The first element in the file name and dump time; successive elements
are handles to the contents of the file. This list can be inspected
by using dumpPrint. Currently, dumpRead
produces a spurious error message.
TCL SYNTAX:
dumpRead <file>
<handle> The file that we want read.
RETURNS:
TCL_OK Successful completion. Returns a list of handles
TCL_ERROR Error occurred.
Print the contents of a dump, by reading the <list> produced by
dumpRead.
TCL SYNTAX:
dumpPrint <list>
<list> A list produced by dumpRead
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred.
Print the hashing statistics of the schema table.
TCL SYNTAX:
schemaHashPrintStat
RETURNS:
TCL_OK Successful completion.
TCL_ERROR Error occurred.