The ratmac preprocessor is used to convert all Xtal ratmac source
files into Fortran files. Versions of the preprocessor are supplied as Fortran
A. Compile the extracted
B. Link the object file. The preprocessor is now ready for use. Check the Fortran source for the I/O device numbers that need to be assigned for inputting the ratmac source file, outputting the new Fortran file, and for printing list files. The standard device numbers used are:
Prepare a command procedure (a script or JCL file) to apply the preprocessor
and the subsequent Fortran compilation as consecutive processes. The source
code to be preprocessed needs to be copied to the file
C. Test RFP with a small ratmac source file (
The next stage of the manual installation process is the definition of the Xtal System macros so that they are appropriate to your machine. This is the most critical part of the installation process because the correct macros are essential to everything that follows. Here is the recommended procedure for preparing the correct definitions.
A. The Xtal macros are grouped in order of importance. The first two macro statements define the version and update for the System. These should not be altered by the user. The next macro defines the compiler: type. If one of the listed compiler: codes is appropriate for your compiler enter this into the definition. This will cause the appropriate macro definitions for this compiler to be automatically selected during preprocessing.
If a suitable compiler: code is not available, you will need to new
machine-specific macro definitions for your compiler. This is not a difficult
task because most of the definitions needed will already exist as definitions
for other compiler types. To enter a new set of definitions, first read the
macro descriptions in the Developers Section. It will also help to list
B. Examine the installation-specific macro definitions. These must be modified for each installation according to local requirements. Refer to Developers Section for a detailed description of these macros. Always use the supplied definitions unless there is good reason not to do so.
C. The second group of macro definitions is compiler-specific. These definitions are automatically selected via the compiler: code defined earlier. It is always good practice to check these definitions. Descriptions are given in the Developers Section
D. The last group of macros are convenience definitions. These need not be altered
The next step in the manual installation process is to preprocess and compile
the nucleus program
A. All of the currently available Xtal3.2 programs are listed in the
subroutine AA00 at the front of the file
D. Retain the object file
Apply a similar procedure as in 2d to the individual Xtal program source files
that have been extracted. If possible process all source files as a single job
by looping the preprocesser and compiler commands. [If installing Xtal for the
first time, it is recommended that you process only the program STARTX
A. Most programs contain COMMON blocks identified by two-letter codes followed
B. Check all preprocessor or compiler error messages. Some compiler messages will be simply warnings (e.g. "Variable used before initialisation") but others may highlight special requirements of your machine. Remember that these routines have already been processed with the listed compiler types, so the most likely source of errors will be local macro definitions.
C. The programs PLOTX, PIG and DIFDATdeserve special consideration. They may require local adjustment for graphical devices or special file formats.
PLOTX converts the plot outputs of programs such as ORTEP, CONTRS, ABSORB and
NEWMAN into graphics commands suitable for a wide range of devices (e.g.
PostScript printers, graphics screens, HP plotters, etc.). This is done via
locally available version of the Graphics Kernel System (GKS), as well as using
inbuilt subroutines for HPGL, PostScript and Mathematica
commands. Small changes will need to made to the
PIG is an interactive molecular graphics program which uses the Graphics
Kernel System (GKS) as a software interface to the graphics screen. Selecting
the devices that your version of PIG will support is detailed at the beginning
DIFDAT as supplied will process CAD, Siemens, Rigaku and Tsukuba diffractometer files. If other diffractometer files need to be processed, the installer can proceed in one of two ways. Either use Howard Flack's DIFRAC program (which is supplied on the Xtal tape as standalone software), or adapt DIFDAT to read the local format. In the latter case, the installer should modify the routines DD31 or DD32. These read the raw diffractometer files and translate data into an machine independent which is then scaled and merged.
In this step the compiled object files from 2d and 2e are linked into an executable module. Linking is a OS-specific operation and each machine will have a different procedure for converting the object files into a single executable file.
The link process for non-Unix machines is of two types: virtual
memory linking and overlay linking. The former is straightforward
because the 'link' command simply concatenates the object files into an
executable module and adds the required library routines. The required plotting
libraries (such as GKS) must be included in the link instructions when PLOTX or
PIG are installed. Note also that programs not 'called' by AA00 (in
Overlay linking procedures are rarely used. These require a 'link map' file which specifies the precise 'calling' relationship between subroutines in order to minimize resident memory requirements. Get expert help if you have not done this before
If warning or error messages occur during linking because of 'unsatisfied external calls' or 'unresolved symbols' an function or subroutine has not been supplied. This can occur if the object files of programs called by the nucleus routine AA00 are not loaded; or if graphical or special library subroutines are inaccessible to the linking process. Check the libraries used in your linking procedure, and whether the directory paths are correct.