thorlist

Daylight v4.9
Release Date: 1 February 2008

Name

thorlist - dump the contents of a Thor database to a TDT file

Unix Synopsis

thorlist [options ...] database [outputfile.tdt]

Description

thorlist dumps all of the Thor Datatrees (TDTs) from a Thor database (via a Thor server) into a file.

TDTs are stored in outputfile; if it is not specified, standard output is used.

Options

-THOR_OUTPUT_FORMAT LIST|DUMP

Specify whether TDTs are written in "list" format (one line per dataitem), or "dump" format (one line per TDT). Default is LIST.

-KEEP_INDIRECT_DATA TRUE|FALSE

If FALSE, indirect references are replace with their expansions in the output TDTs. If TRUE, the original unexpanded indirect references (i.e. the original data) are kept in the output TDTs. Default is TRUE.

-DO_RECORDS N

Write N records to the output file then quit. A typical use of this option might be in conjunction with the -SKIP_RECORDS option (below) to process a file in "chunks". Default is -1 (do all records).

-SKIP_RECORDS N

Indicates that the first N records in the database are to be ignored. This is useful for resuming an interrupted database dump. Default is zero.

-DEAL n/N

Only output the nth of each N TDTs (similar in concept to dealing cards to players).

-BEFORE YYYY[MM[DD[HH[MM[.SS]]]]]

Only output the TDTs with a timestamp that is older than specified. The letter codes are: Y=year, M=month, D=day, H=hour, M=minute, S=second. Each code is a 2-digit field except for the year, which is 4 digits. Optional portions of the date and time are initialized to zero. For example, specifying the year only, i.e., '-BEFORE 2001', is equivalent to '-BEFORE 200100000000.00'. The default is infinity (actually 999999999999.99)

-SINCE YYYY[MM[DD[HH[MM[.SS]]]]]

Only output the TDTs with a timestamp that is equal to or newer than specified. The letter codes are: Y=year, M=month, D=day, H=hour, M=minute, S=second. Each code is a 2-digit field except for the year, which is 4 digits. Optional portions of the date and time are initialized to zero. For example, specifying the year only, i.e., '-SINCE 2001', is equivalent to '-SINCE 200100000000.00'. The default is 198410010000.00 (date of the first Thor ever)

STANDARD THORFILTER OPTIONS:
----------------------------

The following options are common to most or all "thorfilter" programs. They are described in more detail in thorfilters(1).

-SECURE_PASSWORDS TRUE|FALSE

TRUE means don't allow passwords on the command line (require interactive entry). Default: TRUE.

-THOR_IPC_SERVICE service

Names the default TCP/IP service or "port" of the Thor server. Default: thor.

-MINOR_REPORT N

The interval (number of TDTs) between minor reports. The minor report is a period "." printed on "standard error". N = 0 suppresses the minor report. Default is 10.

-MAJOR_REPORT N

The interval (number of TDTs) between major reports. The major report prints the number of TDTs processed and the number of errors so far, followed by a newline, to "standard error". N = 0 suppresses the major report. If both MINOR_REPORT and MAJOR_REPORT are zero, summary information that is normally printed at the end is also suppressed. Default is 500.

Return Value

Return status is zero if the dump succeeds, or one if a problem is detected. Also prints the number of TDTs processed on standard error when finished.

Examples

thorlist pomona93c@dbserver /usr/local/tdt/pomona93c.tdt

Dumps the database "pomona93c" on the host "dbserver"; store the TDTs in the file "/usr/local/tdt/pomona93c.tdt". The database's read password and the server's password are obtained interactively.

thorlist -SKIP_RECORDS 10000 mydb

Dumps the database "mydb" on the current host to standard output, but skips (doesn't write) the first 10000 TDTs. Passwords are obtained interactively.

It is often necessary to apply some operation to every TDT in a database. Because of some tricks used in the Thor server, it is possible to use thorlist(1) and thorload(1) at the same time yet still process each TDT in the database just once.

For example, suppose we wanted to re-fingerprint the database "medchem95c". One approach might be to dump the database to a TDT file, then refingerprint it and load it:

thorlist medchem95c >tmpfile.tdt
fingerprint <tmpfile.tdt | \\
thorload -OVERWRITE TRUE -MERGE FALSE medchem95c
rm tmpfile.tdt

(Note the use of OVERWRITE and MERGE - we want to overwrite rather than merge, as merging will leave two fingerprints in each TDT).

Because of the above-mentioned ability to use thorlist(1) and thorload(1) simultaneously, the intermediate "tmpfile.tdt" is unnecessary:

thorlist medchem95c | fingerprint | \\
thorload -OVERWRITE TRUE -MERGE FALSE medchem95c

The simultaneous thorlist/thorload trick shown above DOES NOT WORK correctly with the "DEAL" option. In particular, the DEAL option won't deal out TDTs correctly if the database is being simultaneously modified. Thus, you can't take the above example and, using the DEAL option, split it between two CPUs.

Files

$DY_ROOT/bin/thorlist

Daylight License

programs: thormanager

Bugs

None known.