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

    dumpOpen

    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.

    dumpReopen

    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.

    dumpClose

    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)

    dumpPtrsResolve

    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.

    dumpDateGet

    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.

    dumpDateDel

    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.

    dumpTypeGet

    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.

    dumpHandleWrite

    Write an object described by <handle> to the current dump file. TCL SYNTAX: dumpHandleWrite <handle> RETURNS: TCL_OK Successful completion. TCL_ERROR Error occurred.

    dumpValueWrite

    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.

    dumpHandleRead

    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.

    schemaGetFromType

    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.

    schemaGet

    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.

    dumpRead

    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.

    dumpPrint

    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.

    schemaHashPrintStat

    Print the hashing statistics of the schema table. TCL SYNTAX: schemaHashPrintStat RETURNS: TCL_OK Successful completion. TCL_ERROR Error occurred.