1. OVERVIEW
2. INSTALLATION
3. CONQUEST 1.0 LICENSING
4. CSD SYSTEM DOCUMENTATION
5. RECOMPILING THE VERSION 5 CSD SYSTEM SOFTWARE
1. OVERVIEW
1.3 Recompiling Version 5 CSD System Software on Unsupported Platforms
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:
- Install the CSD System Software for PC (see Section 2.1.1) and for UNIX (see Section 2.1.2).
- Install the CSD System Database files (see Section 2.2)
- Register ConQuest when you first use it (see Section 2.4)
1.1 System Requirements
1.1.1 Supported Platforms
Version 5 CSD System Software is supplied for the following platforms:
- Silicon Graphics 32-bit running IRIX 5.3 or above
- Silicon Graphics 64-bit running IRIX 6.1 or above
- Sun SPARC and Intel running Solaris 2.6 or above
- IBM compatible PC running Linux (2.0.36)
- IBM RS6000 running AIX 4.3
- Hewlett Packard 9000/715 running HP-UX 10.20 or above
- DEC Alpha AXP running OSF/1 V3.2
In addition, ConQuest 1.0 executables are supplied for the following platforms:
- Silicon Graphics running IRIX 6.2 or above
- Sun SPARC and Intel running Solaris 2.6 or above
- IBM compatible PC running Linux
- IBM compatible PC running Windows 95/98/2000/NT 4.x
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:
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:
- Database UNIX/PC Windows - containing the main database files for both UNIX and PC Windows platforms
- 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.
- 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
UKE-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:
- The name and version number of the product you are having problems with.
- The make, model and operating system of the workstation you are using.
- A clear description of the problem and the circumstances under which it occurred.
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 Installation2.2 Installing the CSD Database Files
2.3 Setting up the CSD System Environment on UNIX
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.
To install ConQuest 1.0 on PC Windows:
- Load the Software PC Windows CD-ROM.
- On the machine you wish to install ConQuest, run:
X:\conquest\setup.exewhere 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.dllandGlu32.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:
- Mount the Software UNIX CD-ROM.
- As a non-root user on the machine you intend to run the CSD System, type:
sh <CDROM>/csdinstallwhere
<CDROM>is the mount point of your CD-ROM drive.
- 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
yat the prompt.If you want to install files for a different machine type
nat 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. EXITSelect the number of the appropriate installation option for your machine type from the list and press return.
- The install script will now prompt for a directory in which to create a
cambridgesubdirectory 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/cambridgeIf a
cambridgesubdirectory 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.
- 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
cambridgeIf 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: glReadPixelsthen 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.1http://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:
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:
as519be.inf
as519be.msk (95Mb)
as519be.tcd (535Mb)
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:
- Load the Database UNIX/PC Windows CD-ROM.
- Select a directory in which to put the main database files.
<install_dir>\csdwhere
<install_dir>is the top level directory of your ConQuest 1.0 installation, by default:C:\Program Files\CCDC\ConQuest 1.0However, if disk space constraints prevent you from putting the main database files in this directory they can be put elsewhere.
- Copy the following files from the CD-ROM to the directory you have selected:
as519be.inf as519be.msk as519be.tcd
- 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.infthe first time you start ConQuest 1.0. See Section 2.4 for more details.To access the main database files directly from CD-ROM:
- Load the Database UNIX/PC Windows CD-ROM.
- 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:
- . Mount the Database UNIX/PC Windows CD-ROM.
- Copy the following files from
<CDROM> to <CAMBRIDGE>/csd:as519be.inf as519be.msk as519be.tcdwhere
<CDROM>is the mount point of your CD-ROM drive and<CAMBRIDGE>is the top level of your CSD System installation.cp /CDROM/as519be.* /usr/local/cambridge/csd
- 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>/csdFor example, if you installed the CSD System software in
/usr/local/cambridgebut chose to copy the main database files to another disk (bigd) on a remote fileserver (/net/server):cp /CDROM/as519be.* /net/server/bigdthe 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.tcdTo access the main database files directly from CD-ROM:
- Mount the Database UNIX/PC Windows CD-ROM
- Create symbolic links for the main database files from
<CAMBRIDGE>/csdto<CDROM>, where<CDROM>is the mount point of your CD-ROM drive and<CAMBRIDGE>is the top level of your CSD System installation.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.tcdNote - 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
CSDHOMEand addCSDHOME/binto yourPATH.
- To set
CSDHOME for Bourne shell (sh) or Korn shell (ksh), type:CSDHOME=<CAMBRIDGE>; export CSDHOMEwhere
<CAMBRIDGE>is the top level directory of your CSD System installation.CSDHOME=/usr/local/cambridge; export CSDHOMESimilarly, to set
CSDHOMEfor C-shell (csh), type:setenv CSDHOME <CAMBRIDGE>where
<CAMBRIDGE>is the top level directory of your CSD System installation.setenv CSDHOME /usr/local/cambridge
- To add
CSDHOME/binto yourPATHfor Bourne shell (sh) or Korn shell (ksh), type:PATH=$CSDHOME/bin:$PATH; export PATHsetenv PATH $CSDHOME/bin:$PATH; rehashTo 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/profile2.4 Starting ConQuest 1.0
To start ConQuest 1.0 on PC Windows select:
Programs -> CCDC -> ConQuest 1.0To start ConQuest 1.0 on UNIX, ensure that
$CSDHOME/binis in yourPATH(see Section 2.3) and type:cqThe 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.infand 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
questv5 -j jobnameThe questv5 command replaces the
questcommand used previously. Thequestcommand 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:
prequestvista jobnamepluto jobname
3. CONQUEST 1.0 LICENSING
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:
- 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):
- Attempt to register online, by hitting the Register Online button in the dialogue box (see Section 3.1).
- 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:
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:
- Register ConQuest 1.0 on this machine as an evaluation (valid for the duration of the April 2000 CSD System release)
This option is available online.
- Purchase an additional ConQuest licence (valid until 31/12/2001 provided your basic CSD subscription does not lapse)
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:
The Site Code, Confirmation Code and Serial Number can be copied and pasted from the Registration dialogue box and included in an email to:
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 336033and 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.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.txtAlternatively, the CSD System Installation Notes can be accessed via the CCDC website at:
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.txtAlternatively the CSD System Release Notes can be accessed via the CCDC website at:
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.htmlAlternatively, the files can be accessed from the CCDC Website at:
5. RECOMPILING THE VERSION 5 CSD SYSTEM SOFTWARE
5.1 Creating the Source Code Directory
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:
- Copy
tsource.Zfrom the Software UNIX CD-ROM to the top level directory of your CSD System installation,<CAMBRIDGE>.cp /CDROM/tsource.Z /usr/local/cambridge/tsource.Z
- Uncompress
tsource.Zusing either the UNIXuncompresscommand orgunzip:uncompress tsource.ZThis will replace
tsource.Zwithtsource
- Extract the tar file by typing:
tar xvf tsourceThis will create a subdirectory
sourcein the top level directory of your CSD System installation,<CAMBRIDGE>. You can now deletetsource.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:
- Ensure that you have access to a C compiler (
cc/gcc)
- In the
<CAMBRIDGE>directory, run the configuration script,config.sh, by typing:sh config.shWhen 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.shas 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.
- When
config.shhas finished, in the<CAMBRIDGE>directory type:make softwareNote - when executing
make softwaresome users have found it useful to set the environment variableTMPDIRto 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 softwarestep fails it will terminate with an error message of the type:*** Error code nwhere n is greater than 0. For details about what to do in these circumstances see Section 5.3.
To restart
make softwareat approximately the point where it failed type:make restart
- Finally, to complete the recompilation, in the
<CAMBRIDGE>directory, type:make install5.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
makesoftwarecommand should run cleanly to the end.This section describes three common problems which may prevent you from rebuilding the Version 5 CSD System Software:
- System Problems: the environment in which you make the executables.
- Compilation Problems: F77 non-conformance.
- Execution Problems: Fortran-C argument mismatches and database byteorder & recordlength problems.
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 typemake 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 softwarecommand will increase the size of thesourcedirectory 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 directorysource/*/cc/d_<machine>has amakefilegenerated byconfig.shsuch that simply typing make while in these directories should produce the executables specified by the directory name (e.g. typingmakein thesource/quest/cc/d_<machine>directory will recompile the Quest executables).Start in the
src/cc/d_<machine>directory and build the library first, by typingmake. As you are compiling the C code, the 'f2c' library will also have to be created. Next typemakein the directoriesf2c/libf77andf2c/libi77.Now move to each of the directoriesclib, quest/cc/d_<machine>, pluto/cc/d_<machine>, vista/cc/d_<machine>, prequest/cc/d_<machine>,andgstat/cc/d_<machine>. Typingmakein each of these directories will create the associated executables.2. /tmp filesystem full
Many of the applications such as
ar, ccetc. store temporary files in the/tmpdirectory. 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 forar, you can redefine the temporary directory by setting an environment variable (such asTMPDIR) to point to a new (larger) directory. Other programs will do the same thing with a-tmp=newdiror-temp=newdircommand 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.shrequires the use of the C compiler.4. make fails with error sh: ....... : not found.
If
make softwarefails with an error such assh: /usr/bin/ar: not found *** Error code 1it probably means that you have not run
config.sh. (config.shcreates the makefiles found in thesourcesubdirectories from templates found inrc/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 ofconfig.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/includedirectory. You will need to add-I../../includeto the list of C compiler directives (CFLAGS) (best done by re-runningconfig.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 |