CCP4 web logo CCP4i: Graphical User Interface
Documentation for Programmers
Run Scripts

next button previous button top button

Run Scripts

See documentation on How Jobs are Run.

Every task taskname must have a run script file $CCP4I_top/script/taskname.script. The simplest run script will just run the required program, but a complex script could run several programs, include some quite complex flow control and possibly do other work such as analysing the log file output from the programs. The run scripts are written in the Tcl scripting language though technically it should be possible to use alternative scripting languages in this context within the general framework of CCP4i.

There is a library of CCP4i commands, some of which are specific for run scripts, which simplify script writing.

A simple script to run one program will do three things:

  • define the command line for the program
  • write a command script (if the program requires a script)
  • use the CCP4i library command Execute to run the program

Besides running the program, the Execute command has functionality to enable the user to view and edit the command line or input script, and functionality to terminate the run script cleanly if the program fails. This command requires, as input, the command line to run the program and the script that the program will read.

For any program which requires command script input (i.e. most CCP4 programs) the run script must generate the command script. There are two means to generate command scripts: either they can be written explicitly (which is good for short, simple scripts) or they can be generated automatically using the program command templates.

To write command scripts explicitly, use the OpenTmpScriptFile and WriteTmpFile commands, and do not forget to CloseFile.

Command templates are described elsewhere. There is usually one command template per program. If the same program is used by more than one task (e.g. the FFT program is used by both the 'FFT' and the 'Generate Patterson' tasks), the same command template can be reused. The CCP4i library command CreateComFile requires the name of a command template file as argument and will create a command script by substituting the parameters set in the run file into the command template. This requires a feat which might seem impossible to Fortran programmers: the CreateComFile command must be able to 'see' the parameters set in the run file without them been explicitly passed to the command. This is achieved using the Tcl uplevel command. The CreateComFile command returns the name of the command script which can then be passed on to the Execute command.

All of the parameters set in the task interface are written to a .def file which is read by the ccp4ish process and all of the parameters set in the .def file are visible when ccp4ish sources the run script. The .def file for a job also contains come job control parameters at the top of the file; these are on lines beginnning with #CCP4I. These parameters are loaded into an array called job_params which is accessed by the CCP4i library routines such as Execute and TerminateScript.