$dbHandle

Jump to System Object Specification, Value Lists, or Examples; explanation of how commands are documented.

Purpose

Database handle operations are an extension of the database command. They are used to access the data within a particular database for which a database handle ($dbHandle) has been created with the database handle command.

Syntax

$dbHandle operation ?-option? arg1 ?arg2 arg3 ...?

The database command operations:



Operation                 Description
   Arguments

get                  Get the information from a particular table column to 
  varName            create an object handle varName. If spec is provided, 
  ?Table.?Column     the table specification is not required, since it is 
  ?spec?             specified implicitly by spec.

set                  Set the values in a particular table column to those
  valueList          specified in valueList. If spec is provided, the table
  ?Table.?Column     specification is not required, since it is specified 
  ?spec?             implicitly by spec. valueList must be a value 
                     specification of the correct type and must specify one 
                     or as many items as there are rows in the specified 
                     table.

unset                Set the values in a particular table column to their 
  ?Table.?Column     unset or undefined values.
  ?spec?

exists               Return 1 or 0 (true or false) if the specified table or 
  Table?.Column?     table column exists or does not, respectively.

rows                 Return the number of rows in the specified table. If the 
  Table              optional argument varName is supplied, a rid (row-ID) 
  ?varName?          BTCL object of this name is created, which contains rid 
                     numbers corresponding to these rows.

select               Return a rid object varName containing rid numbers for
  valueList          rows in table Table for which values in object
  ?Table.?Column     specification valueList match those in column Column.
  varName            If spec is provided and specifies a subset of rows in 
  ?spec?             the table, then the select is restricted to just these 
                     rows. This operation is identical to the object select
                     operation, except that the select space is a table row 
                     rather than another object.

sort                 Sort the values in the specified table column into
  ?Table.?Column     ascending order and return the rid numbers of the table
  varName            rows in this order to an object varName. If spec is 
  ?spec?             provided and specifies a subset of rows in the table,
                     then the sort is restricted to these rows (and the 
                     table does not need to be specified).

createTable          Create a new table in the database with the name Table.
  Table               

createColumn         Create a new column in the table Table of name Column 
  Table?.Column?     and type Type. The number of elements per item in the 
  {Type ?elements?}  new column is optionally given by elements (default = 1).
  ?Default | Ref?    The default value for the column is optionally given by 
                     Default (default = 0). If Type is reference, a reference
                     table name (Ref) may be specified (the default is
                     Column). The acceptable values for Type are all the valid 
                     BTCL object types (reference being synonymous with rid).

create               Create num new rows at the end of table Table. If varName 
  num                is provided, a rid object is created of this name, which 
  Table              contains the row-identification numbers for the new 
  ?varName?          table rows.

alias                Create an alias name, alias, for an existing table 
  alias              Table or an existing column Table.Column. A column may 
  Table?.Column      also be referenced as Table.alias.

delete               Delete part of a database base specified by spec, which 
  spec               may be Table, Table.Column, or an object handle. These 
                     specify the deletion of a table, column, or list of 
                     rids (table rows), respectively.

print                Print out information about table Table with an optional 
  Table              detail specification Detail. The Detail options are the 
  ?Detail?           same as for the database print command.

getIndex             Get a list of rows from a table index, specified by 
  varName            Table.Index, and return it as a BTCL object varName.
  Table.Index         

setIndex             Set a new index of rid numbers, specified by spec, to a 
  spec               table Table and with a name Index. The table part of the 
  ?Table.?Index      index specification, Table, is optional but must agree 
                     with that inferred by spec, if it is provided.

System Object Specification

Jump to Syntax, Value Lists, or Examples

A specification argument (spec in the table above) is usually an object containing a list of rids that was created previously, e.g., via a select command or select $dbHandle operation.

The specification spec may also be a valid specification string that could be accepted by the select command, e.g., *:(1..3):H*, although it is illegal in $dbHandle operations to re-specify the database, as in rna::*:(1..3):H*, for example. (Refer to the select command.) If you supply a string specification for spec, then this must specify a non-empty object, or an error will be reported. For example, rna would cause an error if the system database did not contain a molecule named rna. A specification is also only valid if $dbHandle is a handle to a system database.

Value Lists

Jump to Syntax, System Object Specification, or Examples

A value list specification (valueList in the table above) may be an object handle to some previously defined object containing a set of values.

The value list specification string may be a single string, e.g., "Zn-ion" or a list of strings, e.g., {string1 string2 string3}, such as might be used, for example, to set a list of strings to a Name column of a table.

The value list specification string may also be a vector command string type specification, e.g., {{1 2 3} {4 5 6}} (two 3 x 1 vectors--refer to the vector command). Note that if the table column is of type reference, e.g., Atom.Monomer, the value list is taken to be a set of integers which will be converted to rid numbers.

$dbHandle Options:


Operation       Option         Description

get          -grouping       The default action for a get operation is to 
                             create an object from a database table column 
                             with no grouping information. When the -grouping 
                             keyword is supplied, the grouping information is
                             transferred from the spec argument.

set          -nooverwrite    Prevent the $dbHandle set operation from writing
                             over existing data. The values in a database
                             column can be set with this option only if that
                             column was just created.

select       -bygroup        The $dbHandle select operation behaves like the
             -itempergroup   object select operation, except that the select
             -grouping       space is the specified database table column,
             -nosubdivide    restricted to the rows specified by the optional
             -regexp         spec argument (if provided). The grouping on spec
             -casesensitive  is used only when the -bygroup or -itempergroup
              != >= <= > <   option is specified. The -grouping option
             -anyof          specifies that the select operation is performed
             -noneof         with respect to grouping on valueList and insists
                             that the spec argument not be provided. If no
                             grouping options are provided, the grouping on 
                             the result, varName, is determined by the 
                             inherent grouping on the specified column.

sort         -nosubdivide    The $dbHandle sort operation behaves identically
             -reverse        to the object sort operation, the difference
             -casesensitive  being that the sort space is a database table
                             column rather than another BTCL object and the
                             options -value and -bygroup are not supported.

createColumn -nooverwrite    The -nooverwrite option specifies that the new
             -casesensitive  column is to be write-protected. The -hashed
             -hashed         option specifies that the data is to hashed for
             -nodelete       quicker select operations. This may be specified 
             -deleteref      only if the column is type string or the data 
             -nodeleteref    evenly divides into 4-byte words. The
                             -casesensitive option specifies that the new
                             column is case-sensitive with respect to the
                             select operation. This may be specified only for
                             columns of type string. The -nodelete, -deleteref
                             and -nodeleteref options may be specified only
                             for columns of type reference and specify how
                             the rows of that column and the reference column
                             interact when one or the other is deleted. By
                             default, a row in the reference column, e.g., a
                             Monomer, is deleted when all the rows in this
                             (the new) column, e.g., Atom.Monomer, which 
                             refer to it are deleted. The -nodeleteref option
                             specifies that the same Monomer would never be
                             deleted as a result of the Atoms which refer to
                             it being deleted, whereas -deleteref specifies
                             that the Monomer is deleted when any Atom that
                             refers to it is deleted. By default, a reference
                             column defaults to the condition that all rows,
                             e.g., Atoms, which refer to a row, e.g., a 
                             Monomer, are deleted if that row is deleted. The 
                             -nodelete option specifies that these rows are 
                             not deleted when the row referred to is deleted.

Example 1

Jump to Syntax, System Object Specification, or Value Lists

BTCL > database handle molecule_h
BTCL > $molecule_h createTable Trajectory
BTCL > $molecule_h createTable Trajectory.Frame int
BTCL > $molecule_h createColumn Trajectory.DipoleMoment {double 3} {0 0 0}

This example shows how a new table is created in the current system database. A database handle molecule_h is first created to address the current system database using the database command. This handle is then used to perform database handle operations. The first of these is the createTable operation, which creates a new table with the name Trajectory. A createColumn operation is then performed to create a column Frame in the Trajectory table, which contains integers (no default value for the column is supplied). Another createColumn operation is then performed to create a table DipoleMoment in the table Trajectory, which contains triplets of doubles (element size = 3) which have the default value of {0.0 0.0 0.0}.

Example 2

BTCL > select atoms mol:*:*
BTCL > $molecule_h get coords Coord $atoms
BTCL > $molecule_h get charges Charge $atoms
BTCL > vector dipole multiply $coords $charges
BTCL > vector dipole average $dipole

This example shows how the dipole moment of a molecule named mol is calculated using data from the Atom table in the current database. The select command is used to obtain a list of all the atoms in the current system (molecule). These are returned to an object called atoms, which actually contains a list of rows in the Atom table. Two $dbHandle get operations are then used to obtain objects called coords and charges, which contain lists of values from the Coord and Charge columns of the Atom table, respectively, for the rows specified by the object called atoms. Two vector commands are the performed to calculate the dipole moment vector to the object called dipole.

Example 3

BTCL > $molecule_h create 1 Trajectory trj_n
BTCL > $molecule_h set $frame Frame $trj_n
BTCL > $molecule_h set $dipole DipoleMoment $trj_n

This example continues from the last two examples. The $dbHandle operation create is used to create one new row in the Trajectory table, the new row being returned to an object called trj_n. The Frame column value for this new row, specified by $trj_n, is then set to the value $frame (an integer) by the first $dbHandle set operation. The DipoleMoment column value for this row is then set is the same manner to the calculated value $dipole. The sequence of commands in this and the previous example might be quite useful in a procedure or a loop that could, for example, be used to create a table of dipole moments from a set of coordinates in an archive file.

Example 4

BTCL > $molecule_h select options regexp "N.*" Atom.Name nitros
BTCL > $molecule_h get N-crds Coord $nitros

This example shows how the database tables may be directly accessed to obtain, for example, coordinates of the nitrogens atoms in the current system. First a select operation is performed with a regexp option to select all the rows from the Atom table which have a name beginning with N in the Name column. Using the rows obtained (in an object variable called nitros), the coordinates can now be retrieved from the Coord column of the Atom table, by using a get operation. Note that the table does not have to be re-specified, since this information is stored in the object variable nitros. The coordinates are returned as a (vector) object called N-crds.

Example 5

BTCL > $db_h select -1 Atom.P1Atom p1atoms
BTCL > $db_h select -1 Atom.AsymmetricAtom asymAtoms

It is often useful to have unset values in a column so that they may not be selected in the usual way. This feature is used frequently in the System databases. The unset values in a reference column (a column in a table which refers to rows in another table) may be selected using a value of -1. In the example above, the database handle $dbh refers to a periodic system which also has symmetry. Unset values in reference columns Atom.P1Atom and Atom.AsymmetricAtom indicate that the corresponding atoms (rows) are part of the P1 and asymmetric subunits defining the system. Using -1 allows a selection to be made on columns for unset values.

If just the P1 atoms of a system are required, then these may be obtained simply by using the following command:

BTCL > select p1atoms "*:*:Atom;*"

This is superior to the command above, since it does not fail if the system is not periodic. However, a more efficient way, taking advantage of the way System databases use unset values to denote periodic images, would be the following:

BTCL > $db_h select >= 0 Atom.Monomer p1atoms

Main access page

Advanced-Use access.

List of BTCL commands database command diffraction command