CCP4 web logo CCP4i: Graphical User Interface
Configuring CCP4i to Use Local Resources

next button

Introduction

Configure CCP4i
CCP4 Setup Command
Run CCP4i Command
Mail Address
The BLT Library
MTZ Column Label Display
Frame Length For Logfile Display
CCP4i Utilities
Loggraph
Mapslicer
Topdraw
CCP4mg
External Programs
Viewing HTML Help Text
Map File Format Conversion Options
Options for running MODELLER
Running SHELXS
Disable tasks with missing programs
Full paths of programs
Customize Joblist Colours
Help
Enabling Bubble Help
Hardware Resources
Running Jobs Remotely
Batch Queues

Postscript Files
Postscript Viewers
Printing Postscript Files
Networked Resources
Proxy Server
Sequence Database Retrieval Command
Fonts
Testing the Local Resources
BLT & Printing
Testing Running Jobs

Saving the Configuration Setup

Sending Mail

Introduction

The Interface needs to be configured to make use of other non-CCP4 software on your system and to provide easy access to hardware such as printers and remote machines or batch queues.

The local resources are defined in the file $CCP4I_top/etc/configure.def which can be edited using a graphical utility accessed by the command:

> ccp4i -c[onfigure]

It can also be accessed using the Configure Interface button on the bottom right of the Main Window.

This will bring up a window similar to the Interface task windows and you can enter the appropriate information for the parameters described below. When you have finished you should save the information to the installation file. There is also an option to save the information to the user's home directory (as a file $HOME/.CCP4/unix/configure.def). This option enables individual users to customise the system. Note that the user's settings will over-ride the central settings.

Configure CCP4i

CCP4 Setup Command

When the Interface runs a job remotely or in batch, it must setup the CCP4 program suite. You should enter the command that you use locally to do this.

Run CCP4i Command

This is the command used to run the scripts for a job. It should be set to ccp4ish, there are currently no alternatives.

Mail Address

The Mail CCP4 option on the main window makes it easy to mail the program developer with questions or problems. The mail address should be ccp4gui@dl.ac.uk

The BLT Library

The Loggraph Utility will generate Postscript plot files. It needs to have access to resource files in the BLT library which in a standard installation would be in the directory:
/usr/local/library/blt2.4
CCP4i will try to fill in the correct pathname for this the first time you open the Configure window. If Loggraph can not find the appropriate resource files when attempting to print out a plot, there will be an error message:

couldn't open prologue file

MTZ Column Label Display

If an MTZ file contains a large number of columns of data, then it is possible that the selection menu will be longer than the screen and some columns will be inaccessible. To prevent this, menus of MTZ columns are broken into several columns, with this option setting the maximum length of each column in the menu in terms of the number of MTZ labels.

Frame Length For Logfile Display

This sets the maximum number of lines of a logfile that CCP4i's built-in logfile browser will display in a single "frame". Logfiles that exceed this number of lines will be displayed as separate frames with this number of lines.

CCP4i Utilities

Loggraph

This is the command used to run the Loggraph Utility for displaying graphs and tables in CCP4 log files. It should be set to loggraph.

Mapslicer

This is the command used to run the Mapslicer Utility for displaying sections in CCP4 map and mask files. It should be set to mapslicer.

TopDraw

This is the command used to run the Topdraw Utility for drawing protein topology cartoons. It should be set to topdraw.

CCP4mg

This is the command used to run the CCP4mg (CCP4 molecular graphics) program. It should be set to the full path of the ccp4mg executable on your system.

See the CCP4mg on-line documentation

External Programs

Viewing HTML Help Text

This currently assumes the use of Netscape but can use alternative hypertext viewers. The exact usage depends on the version of Netscape. The distributed version is for Netscape30. When started up outside the Interface it works well in InternetExplorer, and older and newer versions of Netscape.

If there are problems this brief explanation may help in troubleshooting. The script $CCP4I_top/src/local.tcl contains the procedure open_url. For Netscape it checks to see whether there is a locally running version of the browser, and starts one (using the command given in this option) if not. After a delay, or if there is already a version running, then it tries to display the HTML file using the 'netscape -remote' option (you can read about this by entering 'netscape -help' on the command line or look at the Netscape help on this topic).

The procedure poll_netscape invoked from open_url is will make multiple attempts to open the page, in case there is a delay in Netscape responding to these requests when it is first launched.

Note that if you are running CCP4i on a remote machine over an X connection, but have Netscape running on the local machine, then CCP4i may start Netscape on the remote machine but then try to open the page via the local Netscape. This can be irritating but should be solved by opening the page a second time.

Map File Format Conversion Options

Converting maps to non-CCP4 formats requires running non-CCP4 programs. Currently O and Quanta formats are handled. The default conversion programs are: /o/rave_irix6/6d_mapman and /quanta97/maps/mbkall. You should change the program path names appropriately for your system.

Very large maps may exceed the default maximum size for the Mapman program and require an extra command MAPSIZE. CCP4i scripts will include an appropriate command if a map exceeds the value given here. This value can be found for your version of Mapman by running the program and noting the value for 'Max nr of points in map'. Individual users can choose the preferred output map format in the Preferences window - if most users on your site are liable to have the same preference then the system manager could set the installation default in the Preferences window (accessed from menu on the right-hand side of the main CCP4i window). By default CCP4i scripts will use the NORMALISE command in Mapman and produce normalised maps - this can also be changed in the Preferences window.

I am happy to add conversions for other graphics programs but will need information from you on the command string required to run the conversion program.

Options for running MODELLER

MODELLER is an homology modelling program which can be used to reduce manual editing of structures particularly in molecular replacement. CCP4i has a task interface to some limited functionality of MODELLER, called Edit Protein Structure, in the Molecular Replacement module. This program is not distributed by CCP4 but can be obtained from: Sali Lab at The Rockefeller University.

In the configure window you should enter the MODELLER install directory (called MODINSTALL in MODELLER documentation) and the install keyword which you must obtain following the instructions on the above web pages. Since alternative versions of the MODELLER program may be installed you must give the name of the one you want to use.

Running SHELXS

CCP4i has a task interface to the direct methods functionality of SHELX-90 in the Experimental Phasing module (the SHELXS program). This program is not distributed by CCP4 but can be obtained from: THE SHELX HOMEPAGE.

You should enter the full path name of the ShelxS program in the configure window. Note that similar configuration is not required for the newer ShelxC, D and E programs - as long as the programs appear in your PATH the interface should find them automatically.

Disable tasks with missing programs

Some tasks specify "prerequisites", which are programs that the task cannot be run without. If these prerequisites are missing from the path then the task button will be displayed in a disabled form, and will not be able to launch the task.

In some cases, for example when running on a remote machine which has programs that are missing from the local system, it is necessary to allow CCP4i to ignore missing prerequisites.

Note that not all tasks have prerequisities defined, and for these tasks the user may still launch them even though programs required may be missing.

Full paths of programs

This allows the specification of a full path (i.e. including the leading directory name) in order to overcome name conflicts (for example, where a system utility shares the name of a crystallographic program). Be aware that this may need to be updated whenever a new version of CCP4 is installed.

Customize Joblist Colours

This folder contains options to allow the user to select a colour scheme for the display of jobs in the main CCP4i window. The option to use the custom colours must first be turned on. The user can then choose default text and background colours to use, as well as selecting specific colours for each job based on job status, title, taskname and so on.

Help

Enabling Bubble Help

When the mouse moves over a widget in a CCP4i window, any associated help text will be displayed in the "message line" at the top of that window. If bubble help is enabled then, after a short time-delay, this text will also be displayed in a "bubble" or "balloon" next to the widget in question. If bubble help is not enabled then only the message line help will be visible.

Hardware Resources

Running Jobs Remotely

The Interface will run jobs on other machines on the same network which can see the same filesystem, using either the rsh or the ssh command. The Interface Run Remote command definitely will not work across any connection that either of these commands are unable to work across.

You should enter a list of the machines which users are encouraged to run large jobs on. The default choice of protocol is also specified here (either rsh or ssh, as noted above).

The procedure to run remote jobs is in $CCP4_top/src/local.tcl - you probably do NOT want to look at it!

Batch Queues

If you run a batch queue system, you will need to enter a name for the queue and then the command which will be used by the script to submit a job to that queue. The user is given the option to enter options at the time that they submit the job so the command takes the form:

 batch_queue_command  options csh_command_script
where csh_command_script is the name of a command script created automatically by CCP4i.

More information on batch queues can be found on a separate page.

Postscript Files

Postscript Viewers

Various programs can be used to display postscript files on screen. Set any local preferences here. The first option will be used by default.

Printing Postscript Files

The loggraph program has options to print postscript files in colour or monochrome and several places in the interface could potentially print out text files. You need to enter two separate lists for black&white printers and colour printers available at your site.

For each printer you should enter a single word name for the printer which will appear on the menu for the user to choose a printer and the command string required to send a job to that printer. The command string would usually be of the form: lp -c -Dprinter_name. The -c option is advisable as the interface may otherwise delete a temporary file before the printer has a chance to print it. The name of the file to be printed will be appended to the command string.

Networked Resources

Declare Proxy Server

Some CCP4 programs connect to external databases over the internet in order to download a requested file. If your site uses a proxy server for http requests, this should be declared here, otherwise the download will fail.

Sequence Database Retrieval Command

This option is explained in detail in the documentation for the Get Protein Sequence task; see the section on Changing the External Database.

Fonts

The fonts used by the Interface are defined in the file $CCP4I_top/etc/configure.def. If the default fonts are not available on your machine, you will not be able to run the Interface configure utility but will have to edit the configure.def file manually. The format of this file is: one parameter per line with three items on the line (the parameter name, a data type for the parameter and the default value for the parameter). If your machine does not support the fonts specified in the file, you will need to edit the file to change the default values of the following parameters: font_FIXED, font_REGULAR, font_ITALIC, font_BIG or font_SMALL.

The font which will probably cause problems, is the fixed width font. If attempts to run the Interface causes crashes with warning messages about font_FIXED, try the most generic form for this font, which is:

-*-Fixed-*-*-*-*-*-*-*-*-*-*-*-*

(that's a total of 14 fields separated by dashes!).

On SGIs and possibly other Unix/Linux systems the system utility xfontsel can be used to find a font.

The configure.def file contains the definition of two font sets - large and small. The value of the parameter font_SET should be 'large' or 'small'. The fonts in the large font set are L_font_REGULAR, L_font_ITALIC, L_font_BIG and L_font_SMALL. Similarly, the fonts in the small font set are S_font_REGULAR, S_font_ITALIC, S_font_BIG and S_font_SMALL. When the user selects to run either the large or small font set, the appropriate set of parameters are copied into the 'current' font set. If you want to support the large/small font option on your system, you will need to find appropriate values for both the large and small font set.

I would appreciate hearing from anyone who has problems with fonts on different machine types so we can try to avoid them in future.

Testing the Local Resources

The file $CCP4I_top/etc/configure.def contains the definition of local resources which can be viewed and edited in a graphical interface by entering the command:

> ccp4i -c[onfigure]

The Test button at the bottom of this window has options to test how well the Interface interacts with the various resources. These are described individually below.

NOTE: If you change any of the parameters in the window, you should save them to file using the Save button before trying any of the Test options.

Hypertext Viewer

As a test, this attempts to open this page using the hypertext viewer specified in the configuration settings. If successful the viewer should start, otherwise there will an warning displaying the last system error message.

BLT & Printing

This test option automatically runs the loggraph program to display the graphs defined in the file $CCP4I_top/test_data/scaleit.log. Once the loggraph window in displayed you should do the following:

You now have a window containing several print options - you can test the printers you have specified for monochrome and colour plots and the programs used for previewing the print.

There are several possible problems which could cause this test to fail - the symptoms and diagnoses are:

Warning message 'Failed to start loggraph program'

Check that the loggraph program $CCP4I_top/bin/loggraph will start up stand-alone. Failure is probably because it can not find the bltwish executable invoked at the top of the script.

When attempting to print or preview print warning message 'Error could not open prologue file'

This suggests that the BLT library directory set in the configure interface is wrong.

Testing Running Jobs

It is worthwhile testing the running of both local and remote jobs at installation time by following this simple example.

If you are running ccp4i with the configure option (i.e. ccp4i -c) then close this window and start the main interface with the command

> ccp4i
Select Configure Interface from near the bottom of the menu on the right-hand side of the Main Window. Select Running Task from the 'Test' menu at the bottom of the Configure window.

To test running a job, you will be given the interface to the Convert to MTZ & Standardise task with suitable parameters already set.

To test running on your local machine:

  1. From the Run menu on the bottom left of the window select Run Now.
  2. Watch in the centre of the Main Window where an 'import' job should be listed with status STARTING which changes to RUNNING and then to FINISHED.
  3. You can check the log file and command script through the View Files from Job menu on the right-hand side of the Main Window.

To test running on a remote machine:

  1. From the Run menu on the bottom left of the window select Run Remote/Batch/Later.
  2. In the Run Remote window select a machine and click the Run button.
  3. Watch in the centre of the Main Window where an 'import' job should be listed with status REMOTE which should change to FINISHED when the job completes.
  4. You can check the log file and command script through the View Files from Job menu on the right-hand side of the Main Window.

Possible problems:
symptomcause
When running remotely the job does not start (produces no log file) The command to set up CCP4 has not been set in the Configure interface

Saving the Configuration Setup

The configuration setup window has two options for saving the setup: either to Save to Installation File or to Save to User's Home Directory. You should only save to the installation file ($CCP4I_top/etc/configure.def) if you are the system manager responsible for installing CCP4i. If you are not the system manager, you should not have write permission to this file if your system manager has set things up wisely. The alternative is to save a personal configuration preference to your $HOME/.CCP4/unix/configure.def file.

Sending Mail

This is used by the Mail CCP4 button on the main interface to send mail to the Interface developer.

For Unix-type systems, the procedure SendMail in $CCP4I_top/src/local.tcl uses the system command mail to send mail. If this is inappropriate for your system, you will need to edit the local.tcl file. On Windows systems the URL http://www.ccp4.ac.uk/reportaprob.html is opened, which allows on-line reporting of bugs to the CCP4 staff.

next button