The following table outlines the functions that are currently available
to a client application when using dbClientAPI.tcl. Note that the return
values from the funtions are the values returned to the client application
from dbClientAPI.tcl, not necessarily those returned from the handler.
|
OpenDatabase project db messageVar [ -grablock ]
|
|
Summary: Ask the database handler to open a project database
Description: Both the project alias and the directory path of the project
database (i.e. the directory containing the database.def file for this project)
must be specified. All subsequent commands assume that the database is already
open and only require the project alias to be specified.
Returns: LOCKED (if the database is locked), OK (if the database is
opened successfully) and ERROR (if the database open failed). (These are the
same status messages that are sent from the handler.) The client application
can access additional messages from the handler via the messageVar
variable.
|
Arguments: |
project | Alias for the project being opened |
| db | The full directory path of the project database |
| messageVar | Name of a variable to return any messages in |
| -grablock | (Optional) Over-ride any existing lock on the database
file |
|
CloseDatabase project
|
|
Summary: Close a currently open project database
Description: The client must previously have opened the database using
the OpenDatabase command, otherwise an error will be returned.
Returns: 1 on successful close, 0 on error notification from the
handler.
|
Arguments: |
project | Alias for the project being closed |
|
NewRecord project
|
|
Summary: Create a new record in a CCP4i project database
Description: Creates a new job in the specified job database and returns
the job id.
Returns: the job id for the new job, or 0 on error notification from the
handler.
|
Arguments: |
project | Alias for the project in which the job is being created |
|
DeleteRecord project job_id
|
|
Summary: Delete a record (job) from a CCP4i project database
Description: Removes the specified job id and associated data from the
specified project database.
Returns: 1 if the job is successfully removed, 0 on error notification
from the handler.
|
Arguments: |
project | Alias for the project from which the job is being removed |
| job_id | Number of the job being removed |
|
ItemExists project job_id item
|
|
Summary: Test for the existence of a data item. The item can be any
of the indexed parameters in the database.def file, namely TITLE, TASKNAME, STATUS,
DATE, INPUT_FILES, INPUT_FILES_DIR, OUTPUT_FILES, OUTPUT_FILES_DIR or LOGFILE.
Description: Returns 1 if the specified data item exists for the named job
and project database, and 0 if not.
Returns: 1 if the item exists, 0 if not (or on error notification
from the handler).
|
Arguments: |
project | Alias of the project |
| job_id | Number of the job being interrogated |
| item | Name of the data item being queried |
|
SetData project job_id item1 value1 [ item2 value2 [ ... ] ]
|
|
Summary: Set the values of one or more data items
Description: 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. The keys can be any of the indexed parameters in the database.def
file, namely TITLE, TASKNAME, STATUS, DATE, INPUT_FILES, INPUT_FILES_DIR,
OUTPUT_FILES, OUTPUT_FILES_DIR or LOGFILE.
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.
Returns: 1 on successful set operation, 0 otherwise.
|
Arguments: |
project | Alias of the project database |
| job_id | Number of the job for which the data is being set |
| item1 (, item2 ...) | Item name(s) to set the value of |
| value1 (, value2 ...) | Corresponding value(s) to set the item(s) to be |
|
GetData project job_id item1 [ item2 [ ... ] ]
|
|
Summary: Return the values of one or more data items
Description: 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. The keys can be any of
the indexed parameters in the database.def file, namely TITLE, TASKNAME, STATUS, DATE,
INPUT_FILES, INPUT_FILES_DIR, OUTPUT_FILES, OUTPUT_FILES_DIR or LOGFILE.
GetData can also be used to retrieve the NJOBS value for the current database.
This is a special parameter that is not associated with any job (note that a
job id must still be supplied when retrieving NJOBS, but it is ignored).
In spite of its name, NJOBS is not the number of jobs in the current database
but is in fact the highest job id number of any job in the database.
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.
Returns: A Tcl list of the retrieved values, or an empty string on error.
|
Arguments: |
project | Alias of the project database |
| job_id | Number of the job for which the data is being fetched |
| item1 (,item2 ...) | Item name(s) to get the value of |
|
SelectJobs project item pattern
|
|
Summary: Return a list of jobs matching a regular expression
Description: This command returns a list of job numbers where the values of
the specified item matches the supplied regular expression pattern. The item
can be any of the indexed parameters in the database.def file, namely TITLE, TASKNAME,
STATUS, DATE, INPUT_FILES, INPUT_FILES_DIR, OUTPUT_FILES, OUTPUT_FILES_DIR or
LOGFILE.
Returns: A Tcl list of job ids where the value of the item matched
the pattern, or an empty string if there were no matches. An empty string is
also returned on error.
|
Arguments: |
project | Alias of the project database |
| item | Item name being searched on |
| pattern | Regular expression pattern to search on |
|
GetDescription project job_list db_display db_display_format
|
|
Summary: Return a formatted list of jobs in report format
Description: 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.
The item names can be any of the indexed parameters in the database.def file,
namely TITLE, TASKNAME, STATUS, DATE, INPUT_FILES, INPUT_FILES_DIR, OUTPUT_FILES,
OUTPUT_FILES_DIR or LOGFILE. The format list consists of numbers which correspond
to the appropriate field widths for each of the items being displayed.
For example:
GetDescription { 1 2 3 } { TASKNAME STATUS TITLE } { 15 10 40 }
would generate a line for each of jobs 1, 2 and 3; each line would consist of the
taskname written in a field of 15 characters, the status written in a field of 10
characters, and the title written in a field of 40 characters.
This can be used to append all database information into one string for display
(this is how it is used within CCP4i).
Returns: A Tcl list with one list item per record description as
described above, or an empty string if there was an error.
|
Arguments: |
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. |
|
DbStartHandler [ broadcastCmd ]
|
|
Summary: Start a database handler, or connect to one already running
Description: 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. This function
then connects the client to the handler and registers the client.
Optionally the calling process can specify a callback
procedure which will be invoked each time a broadcast message is
received from the handler. The callback function broadcastCmd must be defined
in the application, and have the following syntax:
proc broadcastCmd { message } { ... }
Returns: 1 on successful start, 0 on failure.
|
Arguments: |
broadcastCmd | (Optional) Procedure to be invoked for broadcast messages |
|
DbHandlerConnect
|
|
Summary: Open socket and connect to (register with) database handler
Description: 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
(processHandlerMessage) 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.
Returns: currently nothing.
|
Arguments: |
None |
|
DbHandlerDisconnect
|
|
Summary: Disconnect socket from the database handler
Returns: currently nothing.
|
Arguments: |
None |
|
DbHandlerRequest messageVar command [ arguments ... ]
|
|
Summary: Send a request to the database handler and return the response.
Description: This function is not intended to be called directly by
the client application - instead it is the mechanism that the public API functions
use to send requests to the handler. The request consists of the command plus the
arguments supplied to this function. This function deals with the correct XML
wrapping of the request before sending it through the socket to the handler.
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. (This also uses the
processHandlerMessage helper function.)
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.
Returns: the return value of DbHandlerRequest is the status from the
handler (e.g. OK, ERROR ... ). DbHandlerRequest also returns ERROR to the calling
function if there is some other problem or failure. The message from the handler
is returned to the calling function via the messageVar variable.
|
Arguments: |
messageVar | Name of variable used to return output to the
calling procedure |
| command | Command to be sent to the handler |
| arguments | The set of arguments for the command |
|
processHandlerMessage client
|
|
Summary: Handler for messages recieved from the database server.
Description: This processes messages recieved from the handler process via
the socket connection. It unwraps the XML packaging and classifies the message,
which should fall into one of two catergories:
- responses to requests sent via DbHandlerRequest, or
- unsolicited "broadcast" messages from the handler.
The function acts together with DbHandlerRequest to enable multiple requests
to be sent through the same socket to the handler asynchronously. In the event
that a broadcast event is received from the handler, the appropriate
callback function broadcastCmd (if this has been specified by the
client application).
Returns: currently nothing.
|
Arguments: |
client | Socket id |
|
handlerAcceptConnect client clienthost clientport
|
|
Summary: Utility function used by DbStartHandler
Description: handlerAcceptConnect is invoked as a callback when a db server
function connects to the listening server connection in ClientAPI. Once a connection
is detected, the socket is configured to invoke handlerAcceptInput whenever there is
something to read from the socket.
This command should only be invoked as part of the
DbStartHandler start-up procedure, and should not be accessed directly
by the client application.
Returns: currently nothing.
|
Arguments: |
client | The client socket handle |
| clienthost | The host that the client is running on |
| clientport | The port of the client |
|
handlerAcceptInput client
|
|
Summary: Utility function used by DbStartHandler
Description: Once a database server has been connected to by the client API,
this command is called whenever input is recieved by the client from
the server. The only useful information that the server can send is the
information about the port number to use for further communications.
At this point the socket is closed and control is passed back to
DbStartHandler.
This command should only be invoked as part of the
DbStartHandler start-up procedure, and should not be accessed directly
by the client application.
Returns: currently nothing.
|
Arguments: |
client | The client socket handle |
When CCP4i starts running a job, it starts a new independent process.
This process must also communicate with the database handler, for example
to notify the handler when the job has finished.
In the current implementation of the Tcl handler, running jobs are treated
as a special kind of client and do not use dbClientAPI - instead they make
use of a command called DbReceive, which is actually implemented in
the handler (i.e. it is part of the notional dbAPI).
So running jobs cannot create new jobs, or query the database.
Keeping track of the "open" records in each project is an extra overhead
within the handler. It is also likely that in future we might want running
jobs to be able to interact more with the database, for example by creating
sub-jobs.
This section briefly describes the invocation order of functions in
dbClientAPI.tcl.
Later on more functions could be added for example to import and
export projects. (There are also issues of user privileges management
that will need to considered, for example: how do I access someone
else's project data? Maybe sketching the possible scenarios would
be a good idea first.)
We would also need a similar set of functions for dealing with
"default directories" (essentially short-cuts to non-project directories)
that CCP4i supports:
"Project history functions" refer to functions that provide information
on how jobs relate to each other. There are currently no project history
functions within dbClientAPI.tcl or the Tcl handler, and the def file
database doesn't store this kind of information.
We will need to work out how we will describe project history and
provide functions for storing and retrieving and/or generating this information.
I have some Tcl functions that are part of a prototype visualisation
client, which might be useful in this context however we would first need
to decide how jobs are going to be related to each other.