CSD System Installation Notes



1. OVERVIEW

1.1 System Requirements

1.2 CD-ROM Contents

1.3 Recompiling Version 5 CSD System Software on Unsupported Platforms

1.4 User Support

This document describes how to install the April 2000 UNIX/PC Windows release of the Cambridge Structural Database (CSD) System, comprising CSD V5.19, Version 5 CSD System Software (PreQuest, Quest, Vista and Pluto) for UNIX and ConQuest 1.0 for UNIX and PC Windows.

A typical installation will involve the following steps:


1.1 System Requirements

1.1.1 Supported Platforms

Version 5 CSD System Software is supplied for the following platforms:

In addition, ConQuest 1.0 executables are supplied for the following platforms:

The Linux version of ConQuest 1.0 has been tested on RedHat 5.2 (2.0.36) and RedHat 6.1 (2.2.12-20) only. If you encounter any problems with other versions of Linux, please let us know.

ConQuest 1.0 executables for other platforms, particularly IBM RS6000 will be available shortly. For the latest information about supported platforms, please visit the CCDC website at:

http://www.ccdc.cam.ac.uk/conquest

1.1.2 Disk Space Requirements

A complete installation of the UNIX version of the April 2000 release of CSD System (including ConQuest 1.0 and all of the CSD V5.19 database files) requires 705Mb of disk space, a UNIX installation without ConQuest 1.0 requires 675Mb of disk space. If disk space is limited it is possible to read the main CSD System database files (630Mb) directly from CD-ROM.

A complete installation of ConQuest 1.0 (including CSD V5.19) on PC Windows requires 680Mb of disk space. If disk space is limited it is possible to read the main CSD System database files (630Mb) directly from CD-ROM.

1.2 CD-ROM Contents

The April 2000 UNIX/PC Windows release of the CSD System is supplied on three CD-ROMs:

  1. Database UNIX/PC Windows - containing the main database files for both UNIX and PC Windows platforms

  2. Software UNIX - containing the Version 5 CSD System Software for all supported UNIX platforms, ConQuest 1.0 for SGI IRIX, Sun Solaris and Linux and various subsidiary database files.

  3. Software PC Windows - containing ConQuest 1.0 for Windows 95/98/2000/NT 4.x and various subsidiary database files.

1.3 Recompiling Version 5 CSD System Software on Unsupported Platforms

In addition to the distributed executables, source code for the Version 5 CSD System Software is included on the Software UNIX CD-ROM. This allows users of unsupported UNIX platforms (not listed in section 1.1.1 above) to compile the Version 5 CSD System Software locally.

To compile the Version 5 CSD System Software on an unsupported UNIX platform you will require an ANSI or K & R C-compiler. Further details are given in Section 5.

1.4 User Support

If you encounter problems installing the April 2000 release of the CSD System then please contact our User Support Service:

User Support
Cambridge Crystallographic Data Centre
12 Union Road
Cambridge CB2 1EZ
UK

E-mail: support@ccdc.cam.ac.uk
Tel: +44 1223 336022
Fax: +44 1223 336033

If you need to contact User Support please try to provide the following information:

Also be prepared to email or fax error messages and other output. This information is always useful when trying to determine the cause of a problem.


2. INSTALLATION

2.1 Installing the CSD System Software

2.1.1 PC Windows Software Installation

2.1.2 UNIX Software Installation

2.2 Installing the CSD Database Files

2.3 Setting up the CSD System Environment on UNIX

2.4 Starting ConQuest 1.0

2.5 Starting the Version 5 CSD System Software on UNIX


2.1 Installing the CSD System Software

2.1.1 PC Windows Software Installation

The Software PC Windows CD-ROM contains ConQuest 1.0 for Windows 95/98/2000/NT 4.x.

Installation of ConQuest on Windows NT must be performed using an account with full system administrator privileges. Specifically, the account must be a member of either the local Administrators or Domain Admins groups.

To install ConQuest 1.0 on PC Windows:

  1. Load the Software PC Windows CD-ROM.

  2. On the machine you wish to install ConQuest, run:

       	 X:\conquest\setup.exe
    

    where X is the drive letter for your CD-ROM drive.

    The installation wizard will take you through the steps necessary to install ConQuest 1.0.

To complete your installation of ConQuest 1.0 you must now install the CSD Database files as described in Section 2.2.

Note to Windows 95 Users:

If you have an older configuration of Windows 95 (before Windows 95 OSR2), you might need to install the OpenGL DLLs (Opengl32.dll and Glu32.dll). These can be installed by obtaining and running the following file from the Microsoft FTP site:

ftp://ftp.microsoft.com/softlib/mslfiles/opengl95.exe(483 KB)

2.1.2 UNIX Software Installation

The Software UNIX CD-ROM contains the Version 5 CSD System Software for all supported UNIX platforms and ConQuest 1.0 for SGI IRIX, Sun Solaris and Linux.

To install ConQuest 1.0 and the Version 5 CSD System Software on UNIX:

  1. Mount the Software UNIX CD-ROM.

  2. As a non-root user on the machine you intend to run the CSD System, type:

       	 sh <CDROM>/csdinstall
    

    where <CDROM> is the mount point of your CD-ROM drive.

  3. The install script will attempt to identify your machine type and ask if you wish to install files for this platform.

    To confirm that you wish to install files for this machine type y at the prompt.

    If you want to install files for a different machine type n at the prompt. You will be presented with a list of machine types for which the software is available. Choose the machine type you wish to install executables for.

    If the install script is unable to identify your machine type it will show you a list of machine types for which the software is available:

       Installation Options
       --------------------
       
          1. Install software for Silicon Graphics
          2. Install software for Linux
          3. Install software for Solaris (Sparc)
          4. Install software for Solaris (Intel)
       
          5. Install software for IBM RS6000 (AIX)
          6. Install software for DEC Alpha AXP (OSF/1, Digital UNIX)
          7. Install software for Hewlett Packard (HP-UX)
       
          9. EXIT 
    

    Select the number of the appropriate installation option for your machine type from the list and press return.

  4. The install script will now prompt for a directory in which to create a cambridge subdirectory where the CSD System will be installed:

       - Please specify the full path of a directory in which to create 
         a 'cambridge' subdirectory.
    
       - If you specify, e.g., /usr/local then CSD System files 
         will be installed in: /usr/local/cambridge 
    

    If a cambridge subdirectory already exists in the location you specify, CSD System files will be written to that subdirectory and the files it contains may be overwritten.

    For this reason we recommend that you do not install the April 2000 release of the CSD System directly on top of a previous installation of the CSD System. Use a new directory instead.

  5. If executables for ConQuest 1.0 are available for your machine type, the install script will now install both ConQuest 1.0 and the Version 5 CSD System Software (PreQuest, Quest, Vista and Pluto) in the subdirectory cambridge

    If executables for ConQuest 1.0 are not available for your machine type, only the Version 5 CSD System Software (PreQuest, Quest, Vista and Pluto) will be installed.

To complete your installation of the CSD System you must now install the CSD System database files as described in Section 2.2.

Note to SG Users:

If on starting ConQuest you get an error similar to:

   Traceback (innermost last): 
   [...] 
   ImportError: 16045:python1.5: 
   rld: Fatal Error: unresolvable symbol in openglutil.so: glReadPixels

then you will need to apply the following patch (provided by Silicon Graphics) to the runtime linker on your SG:

   patchSG0003458 for IRIX 6.2, 6.3, 6.4, 6.5 and 6.5.1

This can be downloaded from

http://support.sgi.com/irix/content/patches_nosupport/html/pinfo3458.html

provided that you are subscribed to SGI's Supportfolio Online service (registration is free). If you are not already registered, go to:

http://support.sgi.com/

2.2 Installing the CSD Database Files

The Database UNIX/PC Windows CD-ROM contains the following main CSD V5.19 database files for both UNIX and PC Windows platforms:

Additional database files are included in both the PC and UNIX software installations described in Section 2.1.1 and Section 2.1.2.

The main CSD V5.19 database files can be accessed in one of two ways:

Accessing the main database files from the CD-ROM will result in slower search speeds although, depending on the speed of your CD-ROM drive and the likely number of simultaneous accesses, these will be acceptable. If you are likely to run more than one search at a time, or more than one person will be accessing the CSD at the same time, it is advisable to copy the main database files to a local disk.

The main database files require 630Mb of disk space.

2.2.1 PC Windows Database Installation

To install the main database files on a local disk:

  1. Load the Database UNIX/PC Windows CD-ROM.

  2. Select a directory in which to put the main database files.

    The standard location is:

       <install_dir>\csd
    

    where <install_dir> is the top level directory of your ConQuest 1.0 installation, by default:

       C:\Program Files\CCDC\ConQuest 1.0
    

    However, if disk space constraints prevent you from putting the main database files in this directory they can be put elsewhere.

  3. Copy the following files from the CD-ROM to the directory you have selected:

       as519be.inf   as519be.msk   as519be.tcd
    

  4. If you choose to copy the main database files to a non-standard location you may be prompted for the location of the file as519be.inf the first time you start ConQuest 1.0. See Section 2.4 for more details.

To access the main database files directly from CD-ROM:

  1. Load the Database UNIX/PC Windows CD-ROM.

  2. The first time you start ConQuest 1.0 you will be prompted for the location of the file as519be.inf. See Section 2.4 for more details.

Note - If you choose to access the main database files in this way, the Database UNIX/PC Windows CD-ROM must be loaded for the CSD System to be usable.

2.2.2 UNIX Database Installation

To install the main database files on a local disk:

  1. . Mount the Database UNIX/PC Windows CD-ROM.

  2. Copy the following files from <CDROM> to <CAMBRIDGE>/csd:

       as519be.inf   as519be.msk   as519be.tcd
    

    where <CDROM> is the mount point of your CD-ROM drive and <CAMBRIDGE> is the top level of your CSD System installation.

    For example:

       cp /CDROM/as519be.* /usr/local/cambridge/csd
    

  3. If disk space constraints prevent you from putting the main database files in this directory they can be put elsewhere on your file system. However, you must then create symbolic links to them from <CAMBRIDGE>/csd

    For example, if you installed the CSD System software in /usr/local/cambridge but chose to copy the main database files to another disk (bigd) on a remote fileserver (/net/server):

    	 
       cp /CDROM/as519be.* /net/server/bigd
    

    the following symbolic links would be required:

       ln -s /net/server/bigd/as519be.inf /usr/local/cambridge/as519be.inf
       ln -s /net/server/bigd/as519be.msk /usr/local/cambridge/as519be.msk   
       ln -s /net/server/bigd/as519be.tcd /usr/local/cambridge/as519be.tcd
    

To access the main database files directly from CD-ROM:

  1. Mount the Database UNIX/PC Windows CD-ROM

  2. Create symbolic links for the main database files from <CAMBRIDGE>/csd to <CDROM>, where <CDROM> is the mount point of your CD-ROM drive and <CAMBRIDGE> is the top level of your CSD System installation.

    For example:

       ln -s /CDROM/as519be.inf /usr/local/cambridge/as519be.inf  
       ln -s /CDROM/as519be.msk /usr/local/cambridge/as519be.msk
       ln -s /CDROM/as519be.tcd /usr/local/cambridge/as519be.tcd
    

Note - If you choose to access the main database files in this way, the Database UNIX/PC Windows CD-ROM must remain mounted for the CSD System to be usable.

2.3 Setting up the CSD System Environment on UNIX

To run the Version 5 CSD System Software (PreQuest, Quest, Vista and Pluto) you must set the CSD environment variable CSDHOME and add CSDHOME/bin to your PATH.

  1. To set CSDHOME for Bourne shell (sh) or Korn shell (ksh), type:

       CSDHOME=<CAMBRIDGE>; export CSDHOME
    

    where <CAMBRIDGE> is the top level directory of your CSD System installation.

    For example:

       CSDHOME=/usr/local/cambridge; export CSDHOME
    

    Similarly, to set CSDHOME for C-shell (csh), type:

       setenv CSDHOME <CAMBRIDGE>
    

    where <CAMBRIDGE> is the top level directory of your CSD System installation.

    For example:

       setenv CSDHOME /usr/local/cambridge
    

  2. To add CSDHOME/bin to your PATH for Bourne shell (sh) or Korn shell (ksh), type:

       PATH=$CSDHOME/bin:$PATH; export PATH
    

    Or for C-shell (csh) type:

       setenv PATH $CSDHOME/bin:$PATH; rehash
    

To make these changes permanent, add the commands executed in steps 1. and 2. to all your CSD System users' .login (csh) or .profile (sh, ksh) files. Alternatively, place the commands in a system-wide login or profile script such as /etc/profile

2.4 Starting ConQuest 1.0

To start ConQuest 1.0 on PC Windows select:

Programs -> CCDC -> ConQuest 1.0

from the Windows Start menu.

To start ConQuest 1.0 on UNIX, ensure that $CSDHOME/bin is in your PATH (see Section 2.3) and type:

   cq

The first time users start ConQuest 1.0, the following may be required:

2.4.1 Registration Details

To register ConQuest 1.0 you may require your Site Code and Confirmation Code. These are supplied in a letter accompanying this release. For more information about registration and licensing see Section 3.

2.4.2 Search Data Directory

Before using ConQuest 1.0 you may be required to identify a Search Data directory. This will be used to store temporary files for running searches. It will also be the default directory for saving some ConQuest files.

2.4.3 Database Location

Before using ConQuest 1.0 you may be required to locate the main database files.

The location of these files is identified by selecting a CSD database information file. For ConQuest 1.0 this information will be called as519be.inf and will be found in the directory to which you copied the main database files as described in Section 2.2.

2.5 Starting the Version 5 CSD System Software on UNIX

To start Quest type:

   questv5 -j jobname

The questv5 command replaces the quest command used previously. The quest command has been retained but now has a different function depending on the nature of your CSD System installation, as described below:

If ConQuest 1.0 is installed on your UNIX system, the quest command starts ConQuest (and is therefore equivalent to cq)

If, however, ConQuest 1.0 has not been installed on your UNIX system, the quest command starts Quest (and is therefore equivalent to questv5).

The commands used to start the other Version 5 CSD System Software programs are unchanged:

To start PreQuest, type:

   prequest

To start Vista, type:

   vista jobname

To start Pluto, type:

   pluto jobname


3. CONQUEST 1.0 LICENSING

3.1 Online Registration

3.2 Offline Registration

ConQuest 1.0 is licenced on a per machine basis. Your site has a Licence of Access Agreement that entitles you to install the CSD System (including ConQuest 1.0) on specified machines. Additional free evaluation licences are available for ConQuest 1.0.

The first time you attempt to run ConQuest 1.0 on a particular machine you must register the installation using the process described below:

  1. Enter your Site Code and 6-digit Confirmation Code in the dialogue box shown below. These codes are supplied in a letter accompanying this release. (In some circumstances the Codes will already be displayed in the dialogue box):

    Image - images/install1.jpg

  2. Attempt to register online, by hitting the Register Online button in the dialogue box (see Section 3.1).

  3. If your machine is not connected to the internet or if online registration fails you must register offline (see Section 3.2).


3.1 Online Registration

To register online, hit the Register Online button.

If online registration is successful you will see the following dialogue box:

Image - images/install2.jpg

If the number of machines on which ConQuest 1.0 has been run at your site exceeds the number specified in your Licence of Access agreement then you have the following options:

This option is available online.

This option is not available online. In order to purchase additional ConQuest licences you must contact the CCDC using the phone, fax or email displayed.

This option is available online and enables you to reassign one of your existing ConQuest licences from another machine. This may be necessary if, for example, the original machine has been decommissioned or has suffered a system crash. The number of times that licences can be reassigned is limited so this option may not be available. If you wish to transfer a licence but you are not offered this option then please contact the CCDC using the phone, fax or email displayed.

3.2 Offline Registration

If your machine is not connected to the internet or if online registration fails you must register offline. In order to do this you will need to send the following information to the CCDC:

The Serial Number will be displayed in an extension to the original Registration dialogue box which appears after you hit the Register Offline button:

Image - images/install3.jpg

The Site Code, Confirmation Code and Serial Number can be copied and pasted from the Registration dialogue box and included in an email to:

licence@ccdc.cam.ac.uk

You should automatically receive a Validation Number by return email.

To complete your registration you must enter this Validation Number in the space provided at the bottom of the Registration dialogue box as it appears after the Register Offline button has been hit.

If you are unable to obtain a Validation Number by automated email then contact the CCDC with your Site Code, Confirmation Code and Serial Number using:

Email: licence_help@ccdc.cam.ac.uk
Phone: +44 1223 762914
Fax: +44 1223 336033

and a Validation Number will be issued to you.


4. CSD SYSTEM DOCUMENTATION

The April 2000 release of the CSD System is supplied with the following documentation.

4.1 CSD System Installation Notes

4.2 CSD System Release Notes

4.3 ConQuest 1.0 User Guide

4.4 ConQuest 1.0 Tutorials

4.5 Version 5 Documentation


4.1 CSD System Installation Notes

The CSD System Installation Notes describe how to install and run the CSD System. They are supplied in hardcopy form and electronically in the top level of the Software UNIX and Software PC Windows CD-ROMs as both HTML and plain text files:

   install.html
   install.txt

Alternatively, the CSD System Installation Notes can be accessed via the CCDC website at:

http://www.ccdc.cam.ac.uk/support/csd_doc/zdocmain.html

4.2 CSD System Release Notes

The CSD System Release Notes describe the changes that have been made to the CSD System since the last release. They are supplied in electronic form in the top level of the Software UNIX and Software PC Windows CD-ROMs as both HTML and plain text files:

   release.html
   release.txt

Alternatively the CSD System Release Notes can be accessed via the CCDC website at:

http://www.ccdc.cam.ac.uk/support/csd_doc/zdocmain.html

4.3 ConQuest 1.0 User Guide

The ConQuest 1.0 User Guide describes in detail all the features of ConQuest 1.0 and how to use them. The document is supplied in hardcopy form and is also available electronically via the Help option in ConQuest.

Alternatively, the ConQuest 1.0 User Guide can be accessed via the CCDC website at:

http://www.ccdc.cam.ac.uk/support/csd_doc/conquest/index.html

4.4 ConQuest 1.0 Tutorials

The ConQuest 1.0 Tutorials are a series of worked examples which illustrate the use of the various features of ConQuest 1.0. They are supplied in hardcopy form and are also available electronically via the Help option in ConQuest.

Alternatively, the ConQuest 1.0 Tutorials can be accessed via the CCDC website at:

http://www.ccdc.cam.ac.uk/support/csd_doc/conquest/index.html

4.5 Version 5 Documentation

Documentation for the Version 5 CSD System Software is supplied in electronic form on the Software UNIX CD-ROM. The files, which are in HTML format, can be accessed from the top level page:

   <CDROM>/html/zdocmain.html

Alternatively, the files can be accessed from the CCDC Website at:

http://www.ccdc.cam.ac.uk/support/csd_doc/zdocmain.html


5. RECOMPILING THE VERSION 5 CSD SYSTEM SOFTWARE

5.1 Creating the Source Code Directory

5.2 Recompiling

5.3 Troubleshooting


5.1 Creating the Source Code Directory

The C source code for the Version 5 CSD System software can be found on the Software UNIX CD-ROM in a compressed tar file, tsource.Z.

To create a source code directory on your hard disk:

  1. Copy tsource.Z from the Software UNIX CD-ROM to the top level directory of your CSD System installation, <CAMBRIDGE>.

    For example:

       cp /CDROM/tsource.Z /usr/local/cambridge/tsource.Z
    

  2. Uncompress tsource.Z using either the UNIX uncompress command or gunzip:

       uncompress tsource.Z
    

    This will replace tsource.Z with tsource

  3. Extract the tar file by typing:

       tar xvf tsource
    

    This will create a subdirectory source in the top level directory of your CSD System installation, <CAMBRIDGE>. You can now delete tsource.

5.2 Recompiling

In addition to the expanded source subdirectory, the following must be also present in <CAMBRIDGE> in order to recompile the Version 5 CSD System software:

   config.sh       configuration script (file)
   rc              auxiliary configuration scripts (directory)
   csds            auxiliary ASCII files (directory)

To recompile the Version 5 CSD System Software:

  1. Ensure that you have access to a C compiler (cc/gcc)

  2. In the <CAMBRIDGE> directory, run the configuration script, config.sh, by typing:

       sh config.sh
    

    When prompted, confirm that you wish to compile the executables from source code and answer the subsequent questions. If you are unsure as to what the answer to a particular question is, accept the default answer supplied in square brackets [ ].

    You can run config.sh as many times as you wish until you are satisfied.

    You will be compiling only C source code, so you should answer none when prompted for the name of your FORTRAN compiler.

  3. When config.sh has finished, in the <CAMBRIDGE> directory type:

       make software
    

    Note - when executing make software some users have found it useful to set the environment variable TMPDIR to point to a directory situated in a larger disk partition than that of /tmp, for example:

       setenv TMPDIR .
    

    This is especially true of Silicon Graphics machines.

    If the make software step fails it will terminate with an error message of the type:

       *** Error code n
    

    where n is greater than 0. For details about what to do in these circumstances see Section 5.3.

    To restart make software at approximately the point where it failed type:

       make restart
    

  4. Finally, to complete the recompilation, in the <CAMBRIDGE> directory, type:

       make install
    

5.3 Troubleshooting

The C source code supplied has been successfully compiled on different UNIX platforms using both K&R and ANSI-C compilers. On machines for which we have supplied executables the make software command should run cleanly to the end.

This section describes three common problems which may prevent you from rebuilding the Version 5 CSD System Software:

Once you have found and corrected the problem you can restart the compilations by typing make restart. If you want to restart from the very beginning type make software.

5.3.1 System Problems

1. Not Enough room

Most common system problems are associated with lack of file space. While compiling and linking, the make software command will increase the size of the source directory to almost 60Mb. Check that a filesystem full line hasn't appeared on your console.

You can compile the CSD System incrementally, deleting the object '*.o' files after each executable or library has been built. Each directory source/*/cc/d_<machine> has a makefile generated by config.sh such that simply typing make while in these directories should produce the executables specified by the directory name (e.g. typing make in the source/quest/cc/d_<machine> directory will recompile the Quest executables).

Start in the src/cc/d_<machine> directory and build the library first, by typing make. As you are compiling the C code, the 'f2c' library will also have to be created. Next type make in the directories f2c/libf77 and f2c/libi77. Now move to each of the directories clib, quest/cc/d_<machine>, pluto/cc/d_<machine>, vista/cc/d_<machine>, prequest/cc/d_<machine>, and gstat/cc/d_<machine>. Typing make in each of these directories will create the associated executables.

2. /tmp filesystem full

Many of the applications such as ar, cc etc. store temporary files in the /tmp directory. If this is located within a small filesystem then it may rapidly fill up. Again, check for a filesystem full warning. For some utilities, notably for ar, you can redefine the temporary directory by setting an environment variable (such as TMPDIR) to point to a new (larger) directory. Other programs will do the same thing with a -tmp=newdir or -temp=newdir command line directive. You will have to check the appropriate man pages.

3. No compiler

For some networks, use of the compilers is regulated by a network licence manager. Check that the network has remained up and that the C compiler is available. Note that the script config.sh requires the use of the C compiler.

4. make fails with error sh: ....... : not found.

If make software fails with an error such as

   sh: /usr/bin/ar: not found
   *** Error code 1

it probably means that you have not run config.sh. (config.sh creates the makefiles found in the source subdirectories from templates found in rc/makefils/ adding a "header" specific to the current target machine on which it is run.) The current makefiles are probably targeted for another machine-type from a previous run of config.sh.

5.3.2 Compilation Problems

1. Header files missing

Some machines do not have any X11 header files (they may not have been included when the system was installed). Some copies are contained in the source/include directory. You will need to add -I../../include to the list of C compiler directives (CFLAGS) (best done by re-running config.sh). These should not be used unless absolutely necessary.

5.3.3 Execution Problems

1. Quest cannot find/read the database

If Quest cannot find the database, go to Section 2.2 and ensure that the appropriate symbolic links are in place, so that the CSD System Software can locate the main database files.


Cambridge Crystallographic Data Centre
http://www.ccdc.cam.ac.uk
General Enquiries: +44 1223 336408
Fax: +44 1223 336033
Support Email: support@ccdc.cam.ac.uk
Support Phone: +44 1223 336022