Thorfilters Tutorial

1. Introduction:

Thorfilters provides a command line interface to the Thor and Merlin servers.
They can be used to create Thor Databases and also enable the manipulation and administration of Thor and Merlin Databases.

Database Syntax:

%thorfilter database%dbpass@host:service:user%userpass

             Where:
             database - name of the database being opened
             dbpass - password for the database
             host - hostname of computer on which the server is running
             service - IPC service (or "port") the server is using
             user - user name for logging into server
             userpass - password for "user" for logging into server

2. Thor Commands:

tdtcat, tdtcount, thorchange, thorcrunch, thordbinfo, throdbping,
thordelete, thordestroy, thordiff, thordump, thorlist, thorload,
thorlookup, thorls, thormake, thorping, thorwho

thorping

Determines whether the Thor server is running

* To see whether host1 is running:

	% thorping host1
    	thorping: Connection to host1:thor succeeded

* To see the process id of the Thor server:

	% thorping host1 -PROCESS_ID TRUE
	thorping: Connection to host1:thor succeeded
	Process id of server: 625

thorls

Asks a Thor server to list its databases

* To see the Thor databases on node host1:

   	% thorls host1
 	acd021demo
  	asinex00demo
  	bioscr00demo
	chemsynth97demo
        maybridge00demo
   	medchem02demo
    	mix97demo
    	nci00demo
    	spresi95demo
     	spresirxn98demo
    	wdi023demo

thorwho

Asks a Thor server to list current users

* To see current users on host1:

	% thorwho @host1
	@host1:thor
	  heather@host1   1

tdtcount

Counts bytes, identifiers (a name to which you attach data),

non-identifiers (dataitems associated with identifiers), smiles and TDTs

* To count the number of tdts in file example.tdt

	% tdtcount example.tdt
	270398 1601 3333 232 232 example.tdt

The output tells us that there is 270,398 bytes, 1601 identifiers, 3333 non-identifiers

232 smiles and 232 tdts in the file example.tdt

* To count the number of tdts in file example_datatypes:

	% tdtcount example_datatypes.tdt
	9562 32 231 0 32 example_datatypes.tdt

thormake

Creates a Thor database and/or set its properties

To make an example_db database to include information from the file example.tdt,

we need to determine the values for sizepri and sizexref.

The value for sizepri (the number of primary identifiers) should be equal to

the total number of TDTs that will be stored in the database, in this case 232

(as determined above using the tdtcount thorfilter). The value for sizexref should be

equal to the number of cross-referencing identifiers in the database. In this case,

the number of identifiers is 1601 (again, as determined above using the tdtcount thorfilter).

(Note: If you are planning on adding information to this database, you will have to

determine these values based on the quantitiy of data you plan to add.)

* To make example_db:

	% thormake '$DY_THORDB/example_db' 232 1601 
	Enter server access password for host1:thor:heather >> 
	Enter   READ password for database: 
	Confirm READ password for database: 
	Enter   WRITE password for database: 
	Confirm WRITE password for database: 
	Enter   EXECUTIVE password for database: 
	Confirm EXECUTIVE password for database: 
	Created database.
	thormake: Done.

We want to make a datatypes database for our example_db, we can use the

example_datatypes.tdt. As seen from the examples for tdtcount,

the values for sizepri and sizexref should be 32.

* To make example_db_datatypes.tdt:

	% thormake '$DY_THORDB/example_db_datatypes' 32 32
	Enter server access password for host1:thor:heather >> 
	Enter   READ password for database: 
	Confirm READ password for database: 
	Enter   WRITE password for database: 
	Confirm WRITE password for database: 
	Enter   EXECUTIVE password for database: 
	Confirm EXECUTIVE password for database: 
	Created database.
	thormake: Done.

* In order to use some of the later examples, we need to make another database

using the same example.tdt input information. We will call

this database example2_db and in this case, we will set the

DATATYPES_DATABSE with command line options. Because we did not

do this when we made example_db, we will have to change it later using thorchange.

	% thormake -DATATYPES_DATABASE example_db_datatypes \
		'$DY_THORDB/example2_db' 232 1601
	Enter server access password for host1:thor:heather >> 
	Enter   READ password for database: 
	Confirm READ password for database: 
	Enter   WRITE password for database: 
	Confirm WRITE password for database: 
	Enter   EXECUTIVE password for database: 
	Confirm EXECUTIVE password for database: 
	Created database.
	Datatypes database set.
	thormake: Done.

thorchange

Changes the properties of a Thor database

* To change the DATATYPES_DATABASE in our example_db from

default : none to the example_db_datatypes database we created:

(NOTE: As seen in making exapmle2_db, it is possible to set the

DATATYPES_DATABASE using command line options when using thormake)

	% thorchange '$DY_THORDB/example_db' -DATATYPES_DATABASE \ 
		'$DY_THORDB/example_db_datatypes'
	Enter server access password for host1:thor:heather >> 
	Enter EXECUTIVE password for database: 
	thorchange: Database opened.

	Changing passwords: [Return] means no change
       	             "" means remove existing password

	Enter   READ password for database: 
	Confirm READ password for database: 
	Enter   WRITE password for database: 
	Confirm WRITE password for database: 
	Enter   EXECUTIVE password for database: 
	Confirm EXECUTIVE password for database: 
	Datatypes database set.
	thorchange: Done.

thordbping

Verifies the existence of a Thor Database

* To check for example_db:

	% thordbping example_db
	Enter server access password for host1:thor:heather >>
	Enter password for database example_db@host1:thor:* >>
	Opened "/usr/local/daylight/thordb/example_db.THOR@host1:thor" \
		with permission "r".

thorload

Loads data into a Thor database

In order to load data into our example_db,

we first need to load data into the example_db_datatypes database:

 
	% thorload example_db_datatypes example_datatypes.tdt
	Enter server access password for host1:thor:heather >> 
	Enter password for database example_db_datatypes@host1:thor:* >> 
	...
	Done: 32 TDTs, 0 errors

* To load example.tdt into database example_db:

% thorload example_db example.tdt
	Enter server access password for host1:thor:heather >> 
	Enter password for database example_db@host1:thor:* >> 
	.......................
	Done: 232 TDTs, 0 errors

* Repeat the above to load the data in to example2_db:

	% thorload example2_db example.tdt 
	Enter server access password for host1:thor:heather >>
	Enter password for database example2_db@host1:thor:* >>
	.......................
	Done: 232 TDTs, 0 errors

thordbinfo

Reports the configuration of a Thor Database

* To obtain the configuration of our example_db:

	% thordbinfo example_db
	Enter server access password for host1:thor:heather >> 
	Enter password for database example_db@host1:thor:* >> 
                   name: /usr/local/daylight/thordb/example_db.THOR
               modified: Wed Jul 23 10:06:46 2003
           datatypes db: $DY_THORDB/example_db_datatypes
            indirect db: 
            Number TDTs: 232
           Number Xrefs: 1369
              TDT bytes: 286116
             Xref bytes: 110484
         TDT hash table: 251
        Xref hash table: 1709
       Autocrunch limit: 50%
        "HOLD" database: FALSE
              Read-only: FALSE
         Record locking: DISABLED

* To obtain the configuration for Database Medchem02demo:

	% thordbinfo medchem02demo
	Enter server access password for cooper:thor:heather >>
	Enter password for database medchem02demo@cooper:thor:* >>
        NOTE: **************************************************************
        NOTE: *                                                            *
        NOTE: *   [DEMO]    Medchem Database [c] Medchem02    [DEMO]       *
        NOTE: *                                                            *
        NOTE: * Database maintained and published by BioByte Corp. and     *
        NOTE: * Pomona College in cooperation with Daylight.  Copyright    *
        NOTE: * 1982-2002 BioByte Corp. and Pomona College.  All rights    *
        NOTE: * reserved.                                                  *
        NOTE: **************************************************************
                 name: /usr/local/daylight/thordb/medchem02demo.THOR
             modified: Mon Dec  9 12:01:50 2002
         datatypes db: medchem02demo_datatypes
          indirect db: medchem02demo_indirect
          Number TDTs: 2085
         Number Xrefs: 12254
            TDT bytes: 2512416
           Xref bytes: 1016796
       TDT hash table: 1009
      Xref hash table: 4001
     Autocrunch limit: 50%
      "HOLD" database: FALSE
            Read-only: TRUE
       Record locking: DISABLED

thorlookup

Retrieves a TDT in a Thor database

* To lookup the tdt for valium in the example_db database, we first need to make a file named

valium.smi that contains only a single line of information of the SMILES for valium:

CN1C(=O)CN=C(c2ccccc2)c3cc(Cl)ccc13

We will then direct the output of thorlookup into a file called valium.tdt

	% thorlookup -SECURE_PASSWORDS FALSE example_db%@host1:thor:thor% \
		< valium.smi > valium.tdt

thordelete

Deletes TDTs from a Thor database

* To delete valium.tdt from example2_db:

	% thordelete example2_db valium.tdt 
	Enter server access password for cooper:thor:heather >> 
	Enter password for database example2_db@cooper:thor:* >> 
   
	thordelete done: 1 TDTs deleted, 0 not found, 0 errors

thordiff

Compares the contents of two THOR databases

* To compare the contents of example_db and example2_db (which now has valium.tdt removed):

	% thordiff -EXCLUDE_DATATYPES TS example_db example2_db
	Enter server access password for host1:thor:heather >> 
	Enter password for database example_db@host1:thor:* >> 
	Enter server access password for host1:thor:heather >> 
	Enter password for database example2_db@host1:thor:* >> 
	.................----------
	1: $SMI
	1: $NAM
	1: $NAM
	#Most Output Ommited#
	1: |
	......
	Done: 231 TDTs, 0 different, 1 missing

thordestroy

Destroys a Thor database (permanently erase it)

* To destroy our example2_db:

	% thordestroy '$DY_THORDB/example2_db'
	Enter server access password for host1:thor:heather >> 
	Enter password for database $DY_THORDB/example2_db@host1:thor:* >> 

	===========================================================
	  WARNING: You are about to destroy the database:

	     $DY_THORDB/example2_db@host1:thor

	  If you answer "yes" to the next question, ALL DATA IN
	      THIS DATABASE WILL BE PERMANENTLY LOST.
	===========================================================

	Destroy database? (no) >> yes
	thordestroy: Destroyed database $DY_THORDB/example2_db@host1:thor

Note: You can verify the database has been destroyed by using thorls.

tdtcat

Reads and writes Thor Data Trees(TDTs)

* To see the contents of example.tdt:

	% tdtcat example.tdt | more
	$SMI
	FP<59hxCSUP.7Fbx0JE5x6MKU..1;2048;74;128;60;1;P93>
	PCN
	CL<198;30;P93;0.4083>
	  (Only the first four lines are displayed)

* To combine file1.tdt and file2.tdt into a file named combined.tdt:

(Note: file1.tdt and file2.tdt are not in $DY_ROOT/data; they are fictitious)

	% tdtcat file1.tdt file2.tdt > combined.tdt

thorcrunch

Recovers unused space in a Thor database

Unused space in a Thor database is created when records are deleted

or when data is added to a tdt. When large amounts of data is being

added or removed from the database, thorcrunch can be used to recover space.

* To determine whether example_db has significant unused space and requires thorchrunch:

	%thorcrunch -REPORT_ONLY TRUE example_db
	Enter server access password for host1:thor:heather >> 
	Enter password for database example@host1:thor:* >>
	Primary datafile:          0.0% unused space
	Cross-reference datafile:  0.0% unused space

thorlist

Dumps the contents of a Thor database to a TDT file

* To dump the contents of example_db into example_db.tdt:

(Note: example_db.tdt should be identical to example.tdt

since we made no changes to example_db, only to example2_db.)

	% thorlist example_db example_db.tdt
	Enter server access password for cooper:thor:heather >> 
	Enter password for database example_db@cooper:thor:* >> 
	.......................
	Done: 232 TDTs written, 287485 bytes total

thordump

Directly dumps the contents of a Thor database to a TDT file

thordump is intended for last-ditch situations, where a THOR database is damaged

and can't be opened by thorserver. thorlist should be used if it is possible

to connect to the database by the thorserver.

* To recover example_db and save it in Daylights Home Directory as recover_example_db.tdt:

	% thordump example_db.DP > $DY_ROOT/recover_example_db.tdt
	.......................
	232 TDTs total

3. Merlin Commands:

merlindbping, merlinload, merlinls, merlinping, merlinwho

merlinping

Determines whether the Merlin Server is Running

* To see whether host1 is running:

	% merlinping
	merlinping: Connection to host1:merlin succeeded
	[1]  + Done                          merlinserver

merlinwho

Asks a Merlin server to list current users

* To see current users on host1:

	% merlinwho
	@host1:merlin
	  heather@host1   1

merlinload

Loads a database into the Merlin server's memory

* To load example_db into a Merlin server's memory:

	% merlinload example_db
	Enter server access password for host1:merlin:heather >> 
	Enter password for database example_db@host1:merlin:* >> 
	merlinload: Database loaded.

* To load wdi023demo into a Merlin server's memory:

	% merlinload wdi023demo
	Enter server access password for host1:merlin:heather >> 
	Enter password for database wdi023demo@host1:merlin:* >> 
	merlinload: Database loaded.

merlindbping

Verifies a database is loaded into Merlin server's memory

* To check to see if example_db is loaded:

	% merlindbping example_db
	Enter server access password for host1:merlin:heather >> 
	Enter password for database example_db@host1:merlin:* >> 
	Opened "/usr/local/daylight/thordb/example_db.THOR@host1:merlin" \
		with permission "r".

merlinls

Asks a Merlin server to list its databases

* To see what databases are currently loaded into Merlin:

	% merlinls
	  example_db
	  wdi023demo

4. Other Commands:

dayevict, daymessage

dayevict

Forcibly logs out users from Thor/Merlin server or database

* First see who is logged on to the thor server:

	% thorwho @host1:thor
	@host1:thor
	  heather@host1   1

* To evict user heather from host1 immediately (with a GRACE_TIME of zero):

	% dayevict heather@host1 -GRACE_TIME 0
	Evict heather@host1 from @host1:thor? (no) >> yes
	Evicted heather@host1 from @host1:thor (1 actual user)

daymessage

Sends message to users Thor/Merlin clients

* To sent a message to those logged on host1:

	% echo "The Thor Server will be going down tonight at Midnight" \
		|daymessage -MESSAGE now
	Enter server access password for host1:thor:heather >> 
	Connected to server.
	daymessage: Broadcast message to clients using @host1:thor

ThorFilters Exercise #1
ThorFilters Exercise #2

Thorfilters Tutorial

Table of Contents

1. Introduction:

2. Thor Commands:

3. Merlin Commands:

4. Other Commands: