CCP4 web logo CCP4i: Graphical User Interface
Documentation for Programmers
Task Interface Overview

next button top button

The Organisation of CCP4i Directories

Overview of Files Required for a Task Interface
The Command Template File
The Work Script File
The .def File
The Tcl File

How Parameters Get from Interface to Program

How Tasks are Run

The Organisation of CCP4i Directories

Within the top direcectory usually referenced by the environment variable $CCP4I_top, are the following directories:

bin contains short scripts ccp4i, loggraph etc., which are invoked to start up the ccp4i or the loggraph utilities. These startup scripts source the required files from the src directory
etc contains various parameter files
help contains HTML documentation for the Interface
loggraph contains the source code for the loggraph utility
mapslicer contains the source code for the MapSlicer utility
scripts contains the 'work' scripts which actually run the CCP4 (or other) programs. There is one work script for every task in the Interface
sketch contains the source code for the Monomer Sketcher utility
src contains the main source code for the Interface. Each file in this directory contains a group of procedures of related function, and each file is, in some ways, similar to a Fortran library (such as mtzlib or cciflib). However, Fortran libraries are linked in to the programs which require them, but Tcl scripts are not compiled or linked, so these files are sourced by the scripts which require them
tasks contains one file with the source code for each individual task in the Interface and also one .def file (i.e. the parameter initialisation file) for each task in the Interface
templates contains a program command template for each program run by the Interface. Note that if the same program is used by several tasks they should all use the same command template file

Overview of Files Required for a Task Interface

To write an interface to a single task you will normally need to create four files - their format and function is introduced by some simple examples below. It is necessary to give these files the right names and put them in the right directories for the main Interface program to find them.

The example used throughout this overview is for a task called fiddleit which is an interface to a single program called fiddleprog. You can look at this task interface by typing the command:

> ccp4i -task fiddleit

The fiddleit task interface will be displayed. If you enter some parameters and then choose Run&View Com File from the Run menu at the bottom left of the task window, you will see the program command line and command file that is created. You should then Abort rather than try to run the program, as a fiddleprog program does not exist.

The Command Template File

A full description of the command template file can be found elsewhere.

CCP4 programs expect most of their input in a keyworded command file. The Interface uses a command template file to generate a command file. The format of this template file has been devised for the CCP4Interface - it is not Tcl.

The command template contains the keywords and names of parameters required by the program. The parameter values will be automatically substituted into the template when the user runs the task. The command template also has a simple control language (i.e. it allows IFs, ELSEs and loops etc.) which is necessary for all but the simplest of program input. Look, for example, at $CCP4I_top/templates/ in conjunction with the documentation for the FFT program.

Assume the program fiddleprog expects the following keywords:

title <title>
fiddlefactors <factor_1> <factor_2> [<factor_3>]
i.e. the keyword title followed by some parameter called <title>, and the keyword fiddlefactors followed by parameters <factor_1> <factor_2> and optionally <factor_3>.

The command template is then called $CCP4I_top/templates/ and contains a few lines which look like this:

1 title $TITLE
1 fiddlefactors $FACTOR_1 $FACTOR_2

The format is explained fully later but note the following two important features:

  • If a line begins with a '-' it is a continuation of the previous line
  • The first, non '-', word on a line is a logical value which determines if the line is written to the command file. If the logical is 'true' (or 1) the line is written; if the logical is 'false' (or 0) the line is not written.

Assume the user has set the following parameters (via the Interface):

set TITLE "This should be a really good fiddle"
set FACTOR_1 0.1
set FACTOR_2 400
set FACTOR_3 27.1
Note: EXTRA_FIDDLE is set to 1 or 'true'

Then these values will be substituted into the template to generate the following command file:

title 'This should be a really good fiddle'
fiddlefactors 0.1 400 -
  • Note that the '-' character on the end of the second line is the usual CCP4 line continuation character
  • If the parameter EXTRA_FIDDLE had been zero (i.e. 'false') the final line containing the parameter FACTOR_3, and the dash on the second line, would not have been written to the command file.

The Work Script File

A full description of work files can be found elsewhere.

The work file contains the functionality which is invoked when the user hits the Run button on the task window. The work file is written in Tcl which is an excellent language to use when you need to write complex scripts. For a simple case where one task corresponds to running one program, the work file can be very simple. For our example it could contain:

CreateComScript $CCP4I_top/templates/ fp_script

Execute "fiddleprog HKLIN datain.mtx HKLOUT fiddleddata.mtz" \
      $fp_script $LOG_FILE program_status report

This script just calls the commands CreateComScript and Execute.
N.B. the backslash at the end of the second line is the line continuation character in Tcl scripts.

The command CreateComScript uses the command template file (as described above) to generate a useable program command file, substituted with the parameters from the Interface (how this is done is described later). The command has two arguments: the name of the command template file is input, and the name of a temporary program command file is returned.

The command Execute will run a CCP4 program (or any other program) using the command line which is given as its first argument . Note that, as is usual with CCP4 programs, this command line includes the definition of the input and output files, HKLIN and HKLOUT.

The second argument to this command is the name of the temporary file which contains the keyworded input generated by CreateComScript. The remaining arguments will be described in more detail later.

If the task is an interface to multiple programs, the work file will become more complex as it will usually have some flow control and may have to perform functions such as extracting information from log files. For two of the more complex examples look at $CCP4I_top/scripts/fft.script and $CCP4I_top/scripts/patterson.script.

CCP4i provides a library of commands which could be useful in a work file, including CreateComScript and Execute, but someone writing a complex script may need to be familiar with some basic Tcl commands - particularly for control structures (i.e. IFs and loops etc.).

The .def File

A more detailed description of the .def file can be found elsewhere.

The .def file defines the type and initial value for the parameters. A file of similar format is used to save parameters if the user picks the Save Parameters option at the bottom of the task window.

For our example the .def file $CCP4I_top/tasks/fiddleit.def is:

#CCP4I VERSION CCP4Interface 1.0
#CCP4I SCRIPT DEF fiddleit
#CCP4I DATE 25/06/97
#CCP4I USER lizp
TITLE _text ""
FACTOR_1 _fraction 0.1
FACTOR_2 _positiveint 200
FACTOR_3 _real 20.0
EXTRA_FIDDLE _logical 0

The file identifiers, in lines beginning #CCP4I, which appear at the top of all .def files are important to ensure the file is recognised and not used inappropriately.

In the subsequent lines the parameters required by the program are defined.

TITLE is defined as type _text with an initial value of "" (i.e. an empty string), FACTOR_1 is of type _fraction and has initial value 0.1 etc.

The Tcl File

For our example the tcl file has the name $CCP4I_top/tasks/fiddleit.tcl. This file is written in Tcl and contains the code to generate the graphical interface.

CCP4i provides a library of commands to create the graphical window and most task windows can be created using just a handful of commands with minimal 'raw' Tcl. For example, to create the input widgets for the parameters in our example requires:

CreateLine line \
     message "Enter a title for this job (TITLE)" \
     label "Title" \
     widget TITLE -width 80
CreateLine line \
     message "Enter the fiddle factors (FIDDLEFACTORS)" \
     label "Fiddle factors: first" \
     widget FACTOR_1 \
     label "second" \
     widget FACTOR_2
CreateLine line \
     message "Use extra fiddle factor for really rough problem \
     widget EXTRA_FIDDLE \
     label "Use third fiddle factor" \
     widget FACTOR_3

Here the command CreateLine has been used three times to create three lines in the task window. Note that the backslash at the end of lines is the line continuation character, so each call to the command has a long argument list but it has been laid out in this fashion to simplify reading. The CreateLine command has very flexible arguments - the only fixed argument is the first one (line) which returns an identifier for the line which is created. The remaining arguments to the command usually come in pairs - a keyword and a parameter:

followed by a short line of help text which will appear in the message line when the user puts the mouse over any of the widgets in the line.
followed by the text which the user will see on the task window.
followed by the name of a parameter which must have been defined in the def file. This keyword will create either a menu or a button or an entry field (that is a field for the user to type in a parameter) dependent on the data type (defined in the def file) for the parameter. For all the parameters TITLE, FACTOR_1, FACTOR_2 and FACTOR_3 a simple entry field will be created with the initial value set to the initial value given in the def file. The widget for EXTRA_FIDDLE, which has data type _logical, will be different: it will be a small checkbutton.

Some keywords have optional extra parameters. In the first call to CreateLine in the example above, the keyword-parameter pair 'widget TITLE' is followed by the extra parameter '-width 80', which specifies that this field must be 80 characters wide.

Most of the commands used to define the task window have a similar form - they return an identifier and have some fixed arguments and several optional arguments which have keywords beginning with a '-' character.

How Parameters Get from Interface to Program

The above descriptions of the different files do not really explain how the parameters get passed from the task window to the program. Here is a quick explanation.

When the user clicks the Run button, the Interface creates a new script file called a .run file in the user's scratch directory. You should run a simple task and then look at the file with the extension .run in your scratch directory. At the top of the run file the values of the parameters from the task interface are declared. Below these is the script which has been copied from the work file. The run file is then run as an independent process. It will generate the program command script(s) and run the program(s).

The CreateComScript command which creates the program command script does something which may seem impossible to a Fortran programmer: it can 'see' the values of the parameters although they have not been explicitly passed to command. It manages to do this by using the uplevel command to see variables at a different level in the stack and so is able to substitute the values declared in the run script into the command template file.

How Tasks are Run

When the user opts to run a task, the main ccp4i process does the following:

  • Saves the paramters set up for the task; to a .def file in the CCP4_DATABASE directory for the current project
  • Start a completely separate process (usually referred to as the run process).

The run process then:

  • Reads a small library of utiliy procedures which can subsequently be used by the script which controls the running of the program(s).
  • Sends a message to the original ccp4i process to say that the job is RUNNING
  • Reads the parameters from the saved .def file
  • Sources the appropriate script file for the task: $CCP4I_top/scripts/taskname.script. This script controls the running of the program(s) and will be referred to as the task script.
  • When the script complete, sends a message to the original ccp4i process to say that the job has finished.
  • Terminates the process

The Task Script

The script which controls the running of a particular task is $CCP4I_top/scripts/taskname.script. For the simplest case of running just one program, this script might be only one or two lines long but it can potentially be much longer and run several programs, extract data from files and do significant processing of the data. The script is written in Tcl (but with no Tk which is the X-windows graphical part of Tcl/Tk). There is a library of utilities available to the task script and a simple script will need to use just one or two of the utility procedures and the programmer will need to know only very minimal Tcl.

Most CCP4 programs expect both command line input (which usually specifies the input and output file names) and some additional commands which, when running from a script, can be piped in or read from a command file. CCP4i currently works by writing a temporary command file for each program that the script runs.

A simple example to run the program demoprog which assumes that the parameters HKLIN, HKLOUT, RESOLUTION and MODE have been set:

set comfile [GetTmpFileName -ext com]
WriteFile $comfile \
       "/mode $MODE
         reso $RESOLUTION"

Execute "demoprog hklin $HKLIN hklout $HKLOUT"
$comfile program_status report

In this script the first line calls the utility procedure GetTmpFileName to assign a name for a temporary command file, comfile. This utility return a file name which includes the users project name and job id the arguments -ext com mean that 'com' is included in the file name to identify the file as a command file.
The next three lines call the procedure WriteFile which will write to the file comfile the short command script enclosed in double quotation marks.
The final line of the script actually runs the program using the Execute procedure. The procedure does more than just run the program - it should handle program failures, puts output to the log file, and it can display the command script to the user and allow editing before running the program. The arguments to the Execute command are: the command line which is enclosed in double quotation marks, and the name of the command file comfile.