database

Jump to Database Specification, Description, or Examples; explanation of how commands are documented.

Purpose

The database command performs operations on a database in the Discover environment.

Syntax

database operation arg1 ?arg2 ...?




Operation       Arguments                 Description


handle           varName          Assign to the TCL variable varName a
                ?dbHandle?        string which is a command name used to
                ?obName?          address the database specified by dbHandle. 
                                  The optional argument obName is used to 
                                  return an object that contains the row in the 
                                  Database table for the database handle just 
                                  created. Use a value of "" for dbHandle if 
                                  you want obName to relate to the current 
                                  database.

print            ?dbHandle?       Print out the contents of the database
                ?detail?          specified by dbHandle. The optional detail 
                                  argument allows you to control the amount of 
                                  information printed.

default          ?dbHandle?       Set the default database name for any 
                                  database type to that specified by dbHandle. 
                                  The default database type is always called 
                                  System.

delete           ?dbHandle?       Delete a database specified by dbHandle.
                                  Any objects referencing this database are
                                  no longer valid.

rename           ?-force?         Rename a database specified by dbHandle to 
                ?Type.?newName    newName. If Type is given, then this must be 
                *?dbHandle?       the same as the database type specified by 
                                  dbHandle; if the -force option is included, 
                                  no error is issued when a database matching 
                                  newName exists, and this old database is 
                                  deleted.

create           ?-force?         Create a new database with a type and name 
                varName           specified by Type.Name. The handle to the 
                Type.?Name?       new database is set to varName; if the 
                                  -force option is given, no error is issued 
                                  when a database matching Type.Name exists, 
                                  and this old database is deleted.


If dbHandle is not given, then the current System database is used by default.

Database Specification

Jump to Syntax, Description, or Examples

For most of the database command operations, the first argument after the operation keyword is the database specification (dbHandle). A database can be specified by a number associated with that database, by a string denoting the database's type and name, from an object handle, or from a previously defined database handle.

A numeric database specification has the form #Number, e.g., #2.

A string database specification has the form Type.Name, where both the Type and Name parts are optional. If the Type is omitted, the default database type becomes System. If the Name is omitted, the default database name is used for the specified database type. The specification string for database types and names is case-insensitive. The following table shows valid string database specifications: 


 dbHandle                Database Type      Database Name


 Type.Name                  Type              Name
 .Name or Name              System            Name
 Type.                      Type              current Type database name
 "" or "."                  System            current System database name
A database specification from an object or database handle usually has the value of the variable, e.g., $object or $db_handle.

Description

Jump to Syntax, Database Specification, or Examples

The database command has two main uses. First, it allows you to access the Discover databases, for printing, deleting, etc. Second, it allows you to create a handle to a database using the handle operation. Further manipulation of the data stored in that database is performed using this handle. (See database handle operations, examples, below, and documentation of databases in the Discover program.)

Example 1

Jump to Syntax, Database Specification, or Description

BTCL > readFile molecular_system file = protein system = prot
BTCL > readFile molecular_system file = rna system = rna
BTCL > database print system.rna
BTCL > database default prot
BTCL > database print
The two readFile statements in this example are used to read in two new molecular systems into the Discover system database with system names prot and rna. Note that, if a system name was not defined, these molecular systems would have been given the default system name ($PROJECT), and the previous system database with this name would have been deleted. The first database print command would then print out the rna system database (no output is shown). The database default command then sets the prot system database as the default, so that the next database print command causes that database to be printed.

Example 2

BTCL > database handle rnaDb rna
BTCL > $rnaDb get rnaMonomers Monomer.Type
BTCL > object rnaMonomers
BTCL > database delete $rnaDb
In this example, the database handle command associates a database handle (rnaDb) to the rna system database. This is then used to get the all the monomer types of the molecule(s) in the rna system. The subsequent object command is used to print those names (no output is shown here--refer to the object command). The last database delete command is used to remove the rna system database using the database handle as a reference ($rnaMonomers could also have been used).

Example 3

BTCL > database handle dbh_DB #0
BTCL > $dbh_DB print Database
"Database"
{
    Row  Type      Name      Methods     
    ---  --------  --------  ----------  
     0)  Database  Database  0x00000000
     1)  System    acenm     0x00000000
     2)  Energy    ()        0x00000000
}
This example shows how to obtain a database handle to the Database database, database number 0, which contains information about all other databases currently defined in the Discover program. For example, the types and names of the databases are stored in the Database table of the Database database.

Example 4

BTCL > database handle dbh #1 db_n
BTCL > object db_n print
 type:     relation
 items:    1
 elements: 1
 table:    Database
 database: 1
 contents:
    103
BTCL > $dbh_one get dbName Name $db_n
BTCL > object dbName
 acenm
BTCL > $dbh_one get dbType Type $db_n
BTCL > object dbType
 System
This example shows how to use the database handle command with the optional last argument to retrieve the object db_n. A handle is created (called dbh) to database number 1 (#1), which happens to be the acenm system database. Note that the object db_n contains a rid number, 103, which is the code for the row in the Database table containing information about database number 1. If this object were cast to an integer, using the object cast command, this value would become 1 (a row index value). The following database handle get operations show how the new object db_n can be used to retrieve information about a specified database, e.g., its name and type.
Main access page Advanced-Use access.

List of BTCL commands cellParameter command dbHandle

Copyright Biosym/MSI