Usage of dbClientAPI.py

Wanjuan Yang 17th April 2007

Overview

dbClientAPI.py is python client API for dbhandler. It contains python classes that interact with dbhandler and thus access to database backend. Currently, database backend includes database.def and SQLite.

Usage

A connection to the handler then can be made by creating an instance of HandlerConnection. e.g.

conn = dbClientAPI.HandlerConnection("MrBump",broadcast=True)

Part 1: Methods in handlerconnection class for interacting database.def backend are listed as follows:

CheckServerStatus

Summary: Get the status of the handler.

Returns:'Active' if the request is successful. Raise DbError otherwise.

Arguments:

None

DbSupported dbtype

Summary: Check if db handler supports the given db backend.

Returns:True if db handler supports the given db backend. False otherwise. Raise DbError if the request goes wrong.

Arguments:

dbtype database backend. e.g. def, SQLite

OpenProject project grablock readonly

Summary: Ask the database handler to open a project database

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project being opened
grablock (Optional) True or False. If it is true, the handler will over-ride any existing lock on the database file
readonly (Optional) True or False. If it is true, the handler will open database in readonly mode.

CreateProject project dir

Summary: Ask the database handler to create a project database

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
dir Directory of the project.

CloseProject project

Summary: Ask the database handler to close a project database

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.

NewJob project

Summary:Create a job in database.

Returns: jobid if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.

DeleteJob project jobid

Summary: Delete a job in database.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
jobidthe id of the job to be deleted.

ItemExists project jobid item

Summary: Check if the given item for the given job exists or not.

Returns:1 if the item exists. Raise DbError if the item doesn't exist or anything goes wrong with the request.

Arguments:

project Alias for the project.
jobidthe id of the job.
itemitem name.

SetData project jobid item value [ item2 value2 [...] ]

Summary: Set the value(s) of one or more data item(s) for a job in project.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
jobidthe id of the job.
itemitem name.
valuevalue of the item.

GetData project jobid item [ item2 ...]

Summary: Get the value(s) of one or more data item(s) for a job in project.

Returns:value(s) if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
jobidthe id of the job.
itemitem name.

SelectJobs project item pattern

Summary: Retrieve a list of jobs based on some selection criterion.

Returns:a list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
itemthe item name.
patternregular expression pattern.

GetDescription project joblist db_display db_display_format

Summary: Return a formatted list of jobs in report format.

Returns:a list formatted string populated with job data if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
joblista list of job ids tobe retrived description.
db_displayA list of the database item 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.

ListProjects

Summary: List all the user's projects.

Returns:A list of projects if the request is successful. Raise DbError otherwise.

Arguments:

None

GetProjectDir project

Summary:Get the directory name of the project.

Returns: the directory name if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.

ListDataDirs

Summary: Return a list of the user's default directories.

Returns:A list of the user's default directories if the request is successful. Raise DbError otherwise.

Arguments:

None

GetDatatDir def_dir

Summary:Return the directory corresponding to a def dir name.

Returns: the directory name if the request is successful. Raise DbError otherwise.

Arguments:

def_dir default directory name.

GetNJOB project

Summary:Return the last number of job in project.

Returns: the last number of job in the project if the request is successful. Raise DbError otherwise.

Arguments:

project Alias of the project.

GetNProject

Summary:Return the total number of projects.

Returns: the total number of projects if the request is successful. Raise DbError otherwise.

Arguments:

None

Updatetime project jobid

Summary: Update the time of job.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias for the project.
jobid the id of the job.

ListJobs project

Summary:List all the job ids of a project.

Returns: A list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project Alias of the project.

ImportProject project dir

Summary:Add a reference of a project(alias and path) in the directories.def file.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias of the project.
dir The directory of the project.

DeleteProject project

Summary:Delete the reference of a project in directories.def.

Returns: 1 if the request is successful. Raise DbError otherwise.

Arguments:

project Alias of the project.

AddDataDirRef dir_def path

Summary:Add a reference of a default directory in the directories.def file.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

dir_def The default directory name.
path The path of the default directory.

DeleteDataDirRef dir_def

Summary:Delete the reference of a default directory in directories.def.

Returns: 1 if the request is successful. Raise DbError otherwise.

Arguments:

def_dir The name of the default directory.

GetNextJobList project jobid

Summary:Return a list of job ids which are related to the given job.

Returns:A list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid The id of the job.

GetAllFileLinks project

Summary:Return a list of job pairs. Each pair of jobs indicates these two jobs are related to each other.

Returns: a list of job pairs if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.

GetFileLinks project joblist

Summary:Given the job list, for each job id in the job list, return a list of job pairs. Each pair of jobs indicates these two jobs are related to each other.

Returns:A list of job pairs if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
joblist A list of job ids.

GetAllChildren project jobid

Summary:For a particular project, given a job id, get all the jobs which are children(all levels) of this job.

Returns:A list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid The job id.

GetAllParents project jobid

Summary:For a particular project, given a job id, get all the jobs which are parents(all levels) of this job.

Returns:A list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid The job id.

GetChildren project jobid

Summary:For a particular project, given a job id, get all the jobs which are immediate children of this job.

Returns:A list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid The job id.

GetParents project jobid

Summary:For a particular project, given a job id, get all the jobs which are immediate parents of this job.

Returns:A list of job ids if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid The job id.

GetListofRecords project joblist itemlist

Summary:Get a list of job's item value.

Returns:A list of job item value if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
joblist A list of job ids.
itemlist A list of item names.

AddInputFile project jobid filen project_dir

Summary:Add a file to the list of input files for a job.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid A job id.
filen The name of the input file.
project_dir Optional. project directory.

AddOutputFile project jobid filen project_dir

Summary:Add a file to the list of output files for a job.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid A job id.
filen The name of the input file.
project_dir Optional. project directory.

SetLogfile project jobid logfile

Summary:Set the filename for the logfile for a job.

Returns:1 if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid A job id.
logfile The name of the log file.

GetFileList project jobid type

Summary:Return a list of files associated with a job.

Returns:A list of files with full path if the request is successful. Raise DbError otherwise.

Arguments:

project The alias of a project.
jobid A job id.
type The type of the file: INPUT or OUTPUT.

HandlerDisconnect

Summary: Disconnect from handler.

Returns:None

Arguments:

None

ShutDown

Summary: Shutdown the handler.

Returns:None.

Arguments:

None

Part 2: Methods for iteracting SQLite backend ( to be continued )

Last Update: $Date: 2008/04/02 15:28:12 $