14.3 Database commands

These commands are useful to manage the databases trough a script.

 

DBCLOSE   (UINT)Handle
Close a database and release its resources.

Parameters:
Handle    It's the database handle returned by the DBOPEN command.

Return values:
If it fails (e.g. the database is already closed or the handle is invalid), 0 (false) is returned, otherwise 1 (true) is set.

 

Example:
DBCLOSE   13423

 

See also:
DBCREATE, DBOPEN, DBGET, DBGETID, DBPUT.


DBCREATE   (CHAR)FileName   (CHAR)DbaseFormat   (CHAR)MolFormat   (CHAR)MolCompression   (INT)Flags
Create a new empty database. Please remember that you need call the DBOPEN function to change the database contents after its creation.

Parameters:
FileName    File name or directory name with or without full path. The extension is added automatically.
DbaseFormat  Database format. The allowed keywords are:
  
Keyword Description
File Directory/file database.
Sdf SD file.
SqLite SqLite database.
Zip Zip archive.
  
MolFormat Default molecule format (see -f command line option). This field is ignored by SD files.
MolCompression Default molecule compression (NONE, BZIP2, GZIP, POWERPACKER, ZCOMPRESS). This field is ignored by Sdf, SqLite and Zip database format.
Flags Default database flags. These flags can be combined with the OR operator.
Value Description
0 None.
1 Write the connectivity if the molecule file format supports it.
2 Write the constraints if the molecule file format supports it.

Return values:
Error code if it fails.

 

Example:
DBCREATE   "NewDatabase"   zip   pdb   none   0

 

See also:
DBCLOSE, DBOPEN, DBGET, DBGETID, DBPUT.


DBGET   (UINT)Handle   (CHAR)MolName   (MCHAR)Mode
Extract a molecule from the database specifying its name.

Parameters:
Handle    It's the database handle returned by the DBOPEN command.
MolName Name of the molecule to extract (with the file extension).
Mode It's the extraction mode, that can be:
Mode Description
Add Append the extracted molecule to the current.
Replace Replace the current molecule.
Workspace Create a new workspace and extract the molecule to it.

Return values:
If it fails (e.g. the database handle is invalid or the molecule name is wrong), 0 (false) is returned, otherwise 1 (true) is set.

 

Example:
DBGET   13423   Water.iff   Replace

 

See also:
DBOPEN, DBCLOSE, DBGETID, DBGETROWID, DBPUT.


DBGETID   (UINT)Handle   (CHAR)MolID   (MCHAR)Mode
Extract a molecule from the database specifying its identification number (ID). Each database record has an ID that is a progressive number starting from zero to the total number of record minus one. To obtain the total number of molecules in a database, see the DBINFO command.

Parameters:
Handle    It's the database handle returned by the DBOPEN command.
MolID Molecule identification number.
Mode It's the extraction mode, that can be:
Mode Description
Add Append the extracted molecule to the current.
Replace Replace the current molecule.
Workspace Create a new workspace and extract the molecule to it.

Return values:
If it fails (e.g. the database handle is invalid or the molecule ID is wrong), 0 (false) is returned, otherwise 1 (true) is set.

 

Example:
DBGETID   13423   4   Replace

 

See also:
DBOPEN, DBCLOSE, DBGET, DBGETROWID, DBINFO, DBPUT.


DBGETROWID   (UINT)Handle   (CHAR)RowID   (MCHAR)Mode
Extract a molecule from the database specifying its primary key (Row ID). This command is useful for SQL database in which each record has an unique ID. If the database is not SQL, the command is automatically translated to DBGETID.

Parameters:
Handle    It's the database handle returned by the DBOPEN command.
RowD Primary key.
Mode It's the extraction mode, that can be:
Mode Description
Add Append the extracted molecule to the current.
Replace Replace the current molecule.
Workspace Create a new workspace and extract the molecule to it.

Return values:
If it fails (e.g. the database handle is invalid or the row ID is invalid), 0 (false) is returned, otherwise 1 (true) is set.

 

Example:
DBGETROWID   13423   98   Add

 

See also:
DBOPEN, DBCLOSE, DBGET, DBGETID, DBINFO, DBPUT.


DBINFO   (UINT)Handle   (MCHAR)Variable
Obtain the value of a database variable.   

Parameters:
Handle    Database handle returned by the DBOPEN command.
Variable Database system variable. It can be:
Variable Description
CurMolName The name of the latest processed molecule.
FileName Database file name with full path.
Format Database format (UNKNOWN, FILE, SDF, ZIP).
Molecules Number of molecules stored in the database.
MolFlags Flags for the default file formats:
1 = write the connectivity;
2 = write the constraints.
These flags can be combined with the OR logical operator.
MolFormat Default file format of the stored molecules. It uses the same format naming of the -f command line option.

Return values:
If the database exists, the variable value is returned.

 

Example:
DBINFO   26123   MOLECULES

 

See also:
DBCLOSE, DBGET, DGETID, DBOPEN, DBPUT.


DBOPEN   (CHAR)DbName
Open an existing database. This command is required to access (read and write operation) to an existing database.     

Parameters:
DbName    Database file name whit full path.

Return values:
If the database exists, its handle is returned, otherwise the function returns 0 (error condition).

Example:
DBOPEN   "Vega\Data\Fragments\Solvents.zip"

See also:
DBCLOSE, DBCREATE, DBGET, DBGETID, DBINFO, DBPUT.


DBPUT   (UINT)Handle   (CHAR)MolName
Put the current molecule in the specified database.

Parameters:
Handle    It's the database handle returned by the DBOPEN command..
NolName   Name of the molecule to put with the file extension, if the database format requires it (e.g. file and zip). If the molecule is already present in the database, it will be replaced by the new one (update mode).

Return values:
If it fails (e.g. the database handle is invalid), 0 (false) is returned, otherwise 1 (true) is set.

 

Example:
DBPUT   13182   "MyMolecule"

 

See also:
DBCLOSE, DBCREATE, DBGET, DBGETID, DBINFO, DBOPEN.


Back to the command index