Functions for applications interacting with the DB server

These are the commands that can be invoked by a client of the database server in order to communicate with it. The commands map onto the commands provided in the database server.

The commands are provided with a Tcl namespace called "dbClientAPI" in order to avoid potential name clashes with procedures that might be defined within the client application using the API. In order to use the client API functions, either:

1) specify the fully-qualified names e.g. ::dbClientAPI::DbStartHandler, or

2) use the "namespace import" command in order to make the API functions available without the leading ::dbClientAPI:: qualification - e.g. namespace import ::dbClientAPI::DbStartHandler will enable the client application to invoke "DbStartHandler" directly.

It is possible to use namespace import ::dbClientAPI::* in order to import all the procedures in the client API. However it is possible in this case that you may encounter a clash of names.

Interacting With The Database Handler

Interacting With The Database Handler

These commands are for initiating, interrogating and stopping the database handler process, and for setting up a connection from the application to the process in order to add, fetch and manipulate the stored data.

Argument list: <directories> <>

This command opens a server socket and starts a new handler process in background. The handler process sends back a port number for the client application to use when connecting to the handler.

As this command is now called from within DbHandlerConnection it is not necessary to call it explicitly.

Argument list: <userAgent> <args>

This command should only be invoked by the client application after DbStartHandler, which establishes the correct port number to use to communicate with the database server process.

It sets up a client socket with a callback procedure (db_handler_processResponse) which is invoked whenever the socket becomes readable (corresponding to data being sent from the handler). This command then connects to the handler, allowing the other database requests to be made via the appropriate API commands.

Optionally the calling process can specify its own callback procedure which will be invoked each time a broadcast message is received from the handler. The callback function must be defined in the application.

By default the connection is made to a handler process on the local machine, and a new handler will automatically be started if necessary. However a connection can also be made to an existing handler process on a remote machine, provided that the name of the machine and the port number are explicitly specified.

Return 1 on success and 0 on failure

useragent The application name which connects to the handler

-broadcastHandler

Name of a callback function that will be invoked whenever a broadcast message is received from the handler.

-host

The name of the host that the handler process is running on. If the host is not specified then localhost is assumed.

-port

The port number to connect to the handler on. If the host is not set, or is set to localhost, then the command will try to acquire the port number automatically. For remote machines the port number must be specified explicitly.

-directories

Name of a file containing the directories data which will be used instead of the default directories.def file.

Argument list: None

::dbClientAPI::DbHandlerPort Return the port number that the handler is using

Argument list: <args>

This returns the port number, or -1 if a port number cannot be acquired.

It is a wrapper for db_get_handler_port and takes the same arguments as that command.

Argument list: None

Return 1 if the connection exists and is working, return 0 otherwise.

Wrapper for DbRequestStatus command in the handler.

Argument list: None

This should return a list of key-value pairs as a simple list of strings.

e.g. "Version 1.3-dev" indicates the handler version number.

Argument list: <DB>

For a particular database backend type, this function returns 1 if that backend is supported in the handler, and 0 if not.

The backends can be "def" and "SQLite".

DB The database backend type being checked for

Argument list: None

Cache project and update cache

Cache project and update cache

These commands are used for cache a project, update the cache and get data from cache.

Argument list: <project>

::dbClientAPI::updateCachedJob update the database array

Argument list: <id>

::dbClientAPI::deleteCachedJob delete a job in the database array

Argument list: <id>

::dbClientAPI::getCachedData get the data from cached project

Argument list: <id> <item>

Projects and Directories

Projects and Directories

These are commands for requesting information about the available projects and default directories.

Argument list: None

::dbClientAPI::GetNProjects Request the number of projects

Argument list: None

This returns the number of projects currently defined in the user's database.

Argument list: None

Returns a list of aliases for the user's data directories.

Argument list: <project>

This removes the project reference from the user's database, but the project directory, files and job database are not removed. The project can be restored using the ImportProject command.

project Alias for the project being deleted

Argument list: <alias> <path>

This adds a reference to the specified project to the user's database. The project directory and job database must already exist.

Alias the project being added

path the project directory

Argument list: <def_dir> <path>

def_dir the default directory name

path the full path of the default directory

Argument list: <def_dir>

def_dir the default directory name

Argument list: <project>

project Alias for the project which the directory contains

Argument list: <project>

project Alias for the project which the directory contains

Argument list: <dirn>

Return the name of the project for which the supplied directory path corresponds to the project directory, or an empty string if no match is found.

dirn Path to the directory that is being looked up

Argument list: <dirn>

Return the name of the data dir for which the supplied directory path corresponds to the data directory, or an empty string if no match is found.

dirn Path to the directory that is being looked up

Argument list: <def_dir>

def_dir the default directory name

Argument list: <args>

This command allows the client to retrieve many data items related to several different projects and data dirs in one call.

The syntax is GetDirectoriesData keyword alias [keyword alias ...]

Each pair of arguments consists of a project or data dir alias name following a keyword indicating the data that is to be fetched:

ProjectDir: the path to the directory corresponding to the alias, if it's a project

ProjectDBDir: the path to the database directory for the project

DataDir: the path to the directory corresponding to the alias if it's a data dir

Returns a list with one item resulting from each alias-keyword pair that was supplied.

alias

The name of a project or defdir

keyword

A keyword to indicate the data to retrieve (see above)

Creating, Opening and Closing Projects

Creating, Opening and Closing Projects

These functions allow project databases to be created, opened for reading and writing, and closed again.

Argument list: <project> <args>

If the first argument doesn't start with a hyphen then it's assumed to be the name of a variable in the calling procedure in which to report any message returned from the handler. All other options must come after this and must start with a hyphen.

Return 1 on success and 0 on failure.

project Alias for the project being opened

Argument list: <project> <db> <messageVar> <args>

project Alias for the project being created

db The full directory path of the project database

messageVar Name of a variable to return any messages in

Argument list: <project>

The client must previously have opened the project using the OpenProject command, otherwise an error will be returned.

project Alias for the project being closed

Argument list: <project>

Return 1 if the connection has write access to the job database for the project, zero otherwise.

-1 is returned in the event of an error.

project Name of the project

Argument list: <project>

Return 1 if the connection has read access to the job database for the project, zero otherwise.

-1 is returned in the event of an error.

project Name of the project

Argument list: <project>

This command forces the handler to reacquire the lock on the job database for the specified project. This is useful in the case that the handler has lost write access to the project.

Return 1 if the reacquisition was successful, 0 in the case of failure, and -1 if there was an error.

project Name of the project

Job History

Job History

These are commands for requesting information about the links between the jobs in a project.

Argument list: <project>

::dbClientAPI::GetFileLinks Ask the database handler to get a project's history link between jobs

Argument list: <project> <jobs>

::dbClientAPI::GetNextJobList Ask the database handler to a job's next job list of a given project

Argument list: <project> <jobid>

::dbClientAPI::GetAllChildren Return all the jobs which are decendent of this job.

Argument list: <project> <jobid>

::dbClientAPI::GetChildren Return a job's next job list

Argument list: <project> <jobid>

::dbClientAPI::GetAllParents Return all the anscendent of a job.

Argument list: <project> <jobid>

::dbClientAPI::GetParents Return a job's previous job list

Argument list: <project> <jobid>

::dbClientAPI::GetAllParentsChildren Return all the jobs that related to the given job.

Argument list: <project> <jobid>

Requesting and Manipulating Job Data

Requesting and Manipulating Job Data

These commands provide functions for creating and deleting job records, and for setting and fetching data associated with the jobs.

Argument list: <project>

::dbClientAPI::ListJobs Request a list of job ids in a project, or subjobs in a job

Argument list: <project> <jobid> <>

ListJobs invoked with just a project name returns a list of all "top-level" job ids in that project. If a job id is also specified then a list of the subjob ids associated with that job is returned instead.

project Name of the project

jobid (Optional) Job id for which subjobs should be returned

Argument list: <project>

::dbClientAPI::NewJob Create a new record in a CCP4i project database

Argument list: <project>

Creates a new job in the specified job database and returns the job id.

project Alias for the project in which the job is being created

Argument list: <project> <job_id>

Removes the specified job id and associated data from the specified project database.

project Alias for the project from which the job is being removed

job_id Number of the job being removed

Argument list: <project> <job_id>

project project name

Argument list: <project> <job_id> <item>

Returns 1 if the specified data item exists for the named job and project database, and 0 if not.

project Alias of the project

job_id Number of the job being interrogated

item Name of the data item being queried

Argument list: <project> <job_id> <args>

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the server.

project Alias of the project database

job_id Number of the job for which the data is being set

item1 Item name to set the value of

value1 Corresponding value to set item1 to be

Argument list: <project> <job_id> <args>

This returns the values of multiple data items for a particular job in the specified project database. The argument list should consist of keys. A list of the corresponding values will be returned.

Retrieving multiple data items in a single GetData command is recommended as this minimises the number of socket transactions required to fetch the data from the server.

project Alias of the project database

job_id Number of the job for which the data is being fetched

item1 Item name to get the value of

Argument list: <project> <item> <pattern>

This command returns a list of job numbers where the values of the specified item matches the supplied regular expression pattern.

project Alias of the project database

item Item name being searched on

pattern Regular expression pattern to search on

Argument list: <project> <job_list> <db_display> <db_display_format>

This command takes a list of job numbers, a list of item names and a format description, and returns a report as a Tcl list with one job description (generated according to the lists of items and formats) per item.

This can be used to append all database information into one string for display.

project The alias for the project to access

job_list List of job ids

db_display A list of the database parameters to be displayed

db_display_format A list of the field widths (as integers) to use for displaying the items in the db_display list.

Argument list: <project> <jobid>

Input and Output Files For Jobs

Input and Output Files For Jobs

Commands for adding, listing and removing references to the input and output files for jobs.

Argument list: <project> <job_id> <filen> <alias> <>

This command wraps the AddFile command.

project Alias of the project database

job_id Number of the job for which the data is being updated

filen Name of the file to add

alias (optional) Name of a project alias to associate with the file

Argument list: <project> <job_id> <filen> <alias> <>

This command wraps the AddFile command.

project Alias of the project database

job_id Number of the job for which the data is being updated

filen Name of the file to add

alias (optional) Name of a project alias to associate with the file

Argument list: <project> <joblist> <itemlist>

This returns the values of multiple data items for a list of given jobs in the specified project database. The argument list should consist of keys. A list of the corresponding values will be returned.

Retrieving multiple data items of multiple jobs in a single GetData command is recommended as this minimises the number of socket transactions required to fetch the data from the server.

project Alias of the project database

job_id Number of the job for which the data is being fetched

item1 Item name to get the value of

Argument list: <project> <jobid> <type>

project Alias of the project database

jobid Number of the job

type 'INPUT' or 'OUTPUT'

Argument list: <project> <jobid>

project Alias of the project database

jobid Number of the job

Argument list: <project> <jobid>

project Alias of the project database

jobid Number of the job

Storing and retrieving subjobs

Storing and retrieving subjobs

These commands dealing with subjobs

Argument list: <project> <jobid> <taskname> <title>

project Alias of the project database

jobid Number of the parent job

taskname Name of the task or application associated with the job

title User-readable title

Argument list: <project> <jobid> <item> <pattern>

project Alias of the project database

jobid Number of the job

item Item name being searched on

pattern Regular expression pattern to search on

Argument list: <project> <jobid>

This command returns 1 if the specified job has an associated subjob database, and 0 if there are no subjobs or if an error occurred.

project Alias of the project database

jobid Number of the job

Argument list: <project>

project Alias of the project database

Generic commands for interacting with a SQL Database for a particular project

Generic commands for interacting with a SQL Database for a particular project

These commands allow interactions with the SQLite database backend which stores knowledge base data.

Argument list: <project> <table> <args>

project Alias of the project database

table table name

args attribute-value pairs of the table

Argument list: <project> <table> <recordid>

project Alias of the project database

table table name

args attribute-value pairs of the table

Argument list: <project> <table> <condition>

project Alias of the project database

table table name

args attribute-value pairs of the table

Argument list: <project> <table> <tableid> <attribute> <value>

project Alias of the project database

table table name

tableid the id of the record in the table

attribute the attribute of the value

value

Argument list: <project> <table> <tableid> <attribute>

project Alias of the project database

table table name

tableid the id of the record in the table

attribute the attribute of the value

Argument list: <project> <table> <attributes>

project Alias of the project database

table table name

attributes list of attributes

Argument list: <project> <table> <attributes> <condition>

project Alias of the project database

table table name

attributes list of attributes

Argument list: <project> <table> <condition>

table table name

condition the where clause of SQL

commands for Knowledge base

commands for Knowledge base

These commands allow interactions with Knowledge base table backend which stores knowledge base data.

Argument list: <project> <DatasetName> <MTZfile> <Fmean> <SigFmean> <args>

project project alias

DatasetName An identifier for the dataset

MTZfile The name of the source MTZ file that holds the reflection data for the dataset

Fmean MTZ column label indicates the column that holds the mean structure factors

SigFmean MTZ column label indicates the column with sigmas corresponding to the Fmean values

Argument list: <project>

project alias of the project

Argument list: <project> <DatasetName>

project alias of project

DatasetName

Argument list: <project> <DatasetName>

project alias of the project

DatasetName

Argument list: <project> <DatasetName> <itemName>

project alias of the project

DatasetName

itemName attribute of Dataset table

Argument list: <project> <HAid> <itemName>

project alias of project

HAid record id in HA table

itemName attribute of HA table

Argument list: <project> <HAfile> <DatasetName> <args>

HAfile name of the file containing the data for the current heavy atom substructure in CCP4i's .ha format.

DatasetName

Argument list: <project> <DatasetName>

project alias of the project

DatasetName

Argument list: <project> <DatasetName> <HAid>

project alias of the project

DatasetName

HAid

Interacting with an SQL Database for a particular project

Interacting with an SQL Database for a particular project

These commands allow interactions with the SQLite database backend which store addional job data.

Argument list: <project> <jobid> <quality>

project Alias of the project database

jobid Number of the job

quality the value could be 1, 0 or -1 which indicates good, marginal and bad.

Argument list: <project> <jobid>

project Alias of the project database

jobid Number of the job

Argument list: <project>

Query whether there is an SQLite database associated with the named project. Returns 1 if there is an associated SQLite db, and zero otherwise. Zero is also returned in the event that the request failed for some other reason (e.g. the project hasn't been opened yet).

project Alias of the project database

Argument list: <project> <itemlist>

project Alias of the project database

itemlist the attributes of tables

Argument list: <project> <jobid> <items>

project Alias of the project database

jobid Number of the job

items item for the job

Interacting with a central SQL Database

Interacting with a central SQL Database

These commands allow interactions with the SQLite database backend.

Argument list: <dbname> <dir>

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the serve

job_id Number of the job for which the data is being s

Argument list: <job_id> <args>

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the serve

job_id Number of the job for which the data is being s

Argument list: <projectname>

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the server.

dbname Alias of the project database

dir Number of the job for which the data is being set

Argument list: <projectname>

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the server.

dbname Alias of the project database

dir Number of the job for which the data is being set

Argument list: <jobid> <args>

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the server.

dbname Alias of the project database

dir Number of the job for which the data is being set

Argument list: None

This sets the values of multiple data items for a particular job in the specified project database. The argument list should consist of key-value pairs.

Setting multiple data items in a single SetData command is recommended as this minimises the number of socket transactions required to send the data to the server.

dbname Alias of the project database

dir Number of the job for which the data is being set

Client API Configuration

Client API Configuration

These are commands for configuring attributes of the client API.

Argument list: None

The timeout is the length of time that the client API will wait after sending a request to the handler, before giving up and returning control to the client application.

The timeout is a number of milliseconds, with a minimum value of zero.

Argument list: <timeout>

timeout Length of the timeout in milliseconds

Internal Procedures

Internal Procedures

Functions used internally to the client API.

Argument list: None

Remove socket connection and reset internal parameters

Argument list: <messageVar> <command> <args>

The request consists of the all arguments in args, excluding the After the request is sent to the handler this procedure waits until a response is recieved i.e. it operates in a pseudo-synchronous manner.

Responses from the handler consist of Tcl lists - the first element in the list is the return value of this procedure, the remainder is returned in the variable named by the last argument in args.

In case of failure, ERROR will be returned.

messageVar Name of variable used to return output to the calling procedure

command Command to be sent to the handler

Argument list: <client>

This processes messages recieved from the handler process via the socket connection. Messages should fall into two catergories, either: 1. responses to requests sent via db_handler_request, or 2. unsolicited "broadcast" messages from the handler.

client Socket id

Argument list: None

This procedure allows the wait status of the API to be determined by the calling application.

It returns the number of requests queued up and waiting for responses from the database server.

Argument list: None

This returns the error message (blank if no error occurred since last time the error was read) and resets the message.

Argument list: None

This returns a list with two elements.

The first element is the status returned from the handler in response to the last request sent via the client API.

The second element is the result for that request.

Argument list: <args>

This is a fast and dirty way to acquire the port number for the database handler process - it looks at the handler lock file and tries to read the port number from it.

The lockfile is called dbccp4i.LOCK and has the following content:

port number is:4090

The procedure will try multiple attempts to get the port number unless the -nowait option is specified (in which case it will try just once). Multiple tries are used when the handler is starting up and the lock file is not immediately available.

The procedure returns the port number, or -1 if a port number cannot be acquired.

-nowait

Only try once to get the port number

-directories

Name of the (non-default) directories data file

Argument list: <code> <message>

The reporting function resets the log file for each new invocation of the client API.

code A code number, not currently used

message The message to echo to the logfile

Handling dbCCP4i pseudo-XML (ClientAPI/dbxml.tcl)

Internal Commands for Wrapping & Unwrapping pseudo-XML

These are

Argument list: <flag> <>

The value of the debug flag determines whether diagnostic output is produced by the DbXML functions - if the flag is zero then no output is produced, otherwise diagnostics are printed to screen.

The function always returns the current status of the debugging flag.

flag (Optional) new value for the debug flag (0 or 1)

Argument list: None

Extract and return the version number from the RCS revision string (updated automatically by CVS) for this file.

Argument list: <id> <command> <args>

This command wraps the components of a request to the handler in the appropriate XML tags.

Each argument in "args" is wrapped in ... tags. However: if the argument should be treated as a list then it must be preceeded by a "-list" argument.

command Handler command

args List of arguments for the command

id Request id string

Argument list: <line> <commandVar> <arglistVar> <idVar>

WrapDbResponse Wrap a db_response in pseudo-XML to send to the handler

Argument list: <args>

UnwrapDbResponse Break a db_response pseudo-XML command into components

Argument list: <line> <statusVar> <resultVar> <idVar>

Return 1 on success, 0 if there is an error

Argument list: <message>

UnwrapDbBroadcast Break a db_broadcast pseudo-XML message into components

Argument list: <line> <broadcastVar>

Return 1 on success, 0 if there is an error

Argument list: <cdata>

This function returns the cdata string with any XML special characters (<,> and &) converted to their escaped form ("<", ">" and "&" respectively).

cdata The character data to be converted

Argument list: <cdata>

This function returns the cdata string with any escaped XML special characters ("<", ">" and "&") converted to their original (unescaped) form ("<", ">" and "&" respectively).

It turns out that the xml.tcl parser functions perform the unescaping functions automatically, so for now this function is not required. It is retained because it may be useful in future.

cdata The character data to be converted

CCP4i Functions (ClientAPI/ccp4ilite.tcl)

Duplicates of CCP4i functions that can be used without CCP4i

Functions that replicate those found in the main CCP4i source code. There are made available here so that the full set of CCP4i source files do not need to be loaded, hopefully enabling the creation of lighter weight standalone Tcl applications.

Argument list: None

GetDotCCP4 Return the location of the .CCP4 directory

Argument list: None

The .CCP4 directory is used to store user-specific CCP4 data.

This code was originally copied from ccp4i/src/system.tcl

Argument list: None

Returns the upper-cased platform type e.g. UNIX or WINDOWS.

Argument list: <var> <report> <1>

Return a path name associated with an environment variable - in a Windows system the separators are converted to forward slash. Return an empty string if no environment variable found.

This procedure was copied from ccp4i/src/system.tcl but has been modified to use the GetOPSYS procedure

var Environment variable

report Optional - default 1. If true (1) then output warning message if environment variable not found.

Argument list: <message>

This is a non-graphical placeholder for the WarningMessage function in the core CCP4i