Use Cases for CCP4i

This document outlines the operations which are performed on the database using CCP4i. Some operations are initiated by the user, which then cause CCP4i to perform a series of operations in order to accomplish the requested task.

The purpose of this document is make it more clear what the requirements are within the current version of CCP4i for the database backend.

Case 1: Start-up

• User starts CCP4i
• CCP4i reads user's project directories information, which tells CCP4i the names of the projects for the user (and their associated directories) plus which of these is the "current project"
• CCP4i opens the current project: see case 2a.

Case 2: Open Project

Case 2a: Open Project Database

This is handled by the command DbOpen within CCP4i.

• CCP4i checks for a lock file on the database file (procedure DbInterrogateLock):
  • Lock exists: CCP4i reports to the user that there is a lock and ask whether to proceed by deleting the lock, or whether to close CCP4i
• Read the information from the database.def file into memory using the DbOpenDatabase command:
  • Load the database content into memory (command DbLoadFile):
    • Initialise the database array using the $CCP4/ccp4i/etc/database.def file as a template
    • Attempt to create a new lock file for this database
    • Read the information from the database.def into memory i.e. into the database array
    • Check whether there are any commands from running jobs to deal with in the command buffer (procedure DbFlushCommandBuffer)
  • For jobs with status RUNNING, HOLD or REMOTE, check the logfile to see if that job has since finished running and if so then update the status accordingly (DbUpdateStatus)
• Create the job list display in the main CCP4i window (procedure DbUpdateList): see case 8.

Case 2b: Change Project

This is performed by the DbChange procedure:

• User selects project alias from list of available projects
• Checks that selected project alias exists and is associated with a writeable directory with a valid CCP4_DATABASE subdirectory.
  • In the case that these conditions are not met then the project is not changed to the new database EXCEPT in the case where no project directory and/or database is is found - in this case the project is created on behalf of the user.
• CCP4i closes the current project (DbClose): see case XXX
• CCP4i updates the current project to be the new selected project
• CCP4i tries to open the current project (DbOpen): see case 2a.

Case 3: Create a New Project

CCP4i has no explicit command to create a new project - this happens implicitly the first time the user changes to a project for the first time (see case 2b).

Case 4: Run a Job

Case 4a: Run a Job

The run_command procedure (in runjob.tcl) is the driving procedure for running jobs within CCP4i. Strictly speaking running a job is not part of the database functionality however it is instructive to know how this interacts with the database.

• User selects "Run Now" or "Run&View Com File" options from a task interface window
• CCP4i executes the taskname_run command, if it exists
• For interactive jobs:
  • taskname_run fails: create a new job entry in the database with status FAILED
  • taskname_run finishes: create a new job entry in the database with status FINISHED
  In each case record the name of the associated logfile for this job. For interactive jobs the run_command procedure finishes here.
• For batch jobs (standard method for most CCP4i tasks):
  • CCP4i registers a new job with status STARTING, and gets the associated job id (DbRegisterJob)
  • CCP4i sets up a logfile name and associates this with the job id (DbSetJobData)
  • CCP4i refreshes the job display (DbUpdateList)
  • CCP4i executes the appropriate script for the task, via the RunScript command (which runs the job as a separate process). RunScript operates in different modes (background and edit are the most usual) but ultimately it executes ccp4ish -r def_file which in turn invokes the ExecuteScript command.

Case 4b: Running job communicates with database

Running jobs are independent processes to the main CCP4i process. A running job can communicate with the database via the main CCP4i process and has a limited number of commands which are available to the scripts from the execute.tcl file:

• RunNotification: invoked when the job starts running, to change the status in the database from STARTING to RUNNING (or REMOTE, for remote jobs).

RunNotification is called from ExecuteScript and opens a socket to the main CCP4i process which remains open for the lifetime of the job. This socket is used by the remaining commands below to pass data to the database:

• TerminateScript: invoked to terminate the running job cleanly from within the script. This wraps the DbReceive command which reports the appropriate status of the job (FINISHED, FAILED) to the main CCP4i process.
• FailNotification: invoked if the job fails, to change the status in the database to FAILED (using DbReceive)
• AddOutputDir: add a directory to the list of output files for this job
• AddOutputFile: add an output file to the list of output files for this job

Note that it is possible for scripts not written in Tcl to also be run in which case there is a separate mechanism to allow them to communicate with the database and issue the above commands.

A running job may also communicate with the main CCP4i process in the "Run&View Com File" mode. This is so that the main process can throw up the window which allows the user to edit the keyworded script for a program prior to it being run.

Case 5: View Files from Job

• User selects a job in the current project by highlighting it in the job list displayed in the main CCP4i window
• User selects "View Files From Job" option in main window
• CCP4i invokes DbViewJobMenu:
  • Get list of the output file names using DbGetJobFiles command:
    • This invokes DbGetData to fetch the lists of OUTPUT_FILES and OUTPUT_FILES_DIR from the database
    • For each file in the list it constructs the full file name and returns these as a list
  DbViewJobMenu then adds each of these to the menu of files along with a binding to launch the appropriate viewer command.

Case 6: Edit Job Data

Case 6a: Read/Edit Notebook

Case 6b: Edit Job Data

Case 6c: Enter Data for External Job

Case 7: Delete/Archive and Clean-up of Jobs

Case 8: Display Job List