A. Compile the extracted rfp*.f. using the highest compiler optimization level. If there are compilation errors, use the local editor to examine the Fortran source code in the problem area. Errors will probably be due to local differences in open/close or read/write statements. Seek local expert advice if the error is not obvious.

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:

device no.	function	filename
1	input ratmac source file	RFPRAT
2-5	included source files	<argument of include:>
6	output message file	RFPMES (or terminal device)
7	output Fortran file	RFPFTN
8	output list file	RFPLST
10	extruded source file	<argument of extrude:>

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 RFPRAT. The generated Fortran77 file is named as RFPFTN. The list file containing preprocessor information and/or dumps is opened as RFPLST.The preprocessor summary and error messages are attached to RFPERR.

C. Test RFP with a small ratmac source file (rfu.r is a good first test). If any errors occur these will probably be due to read, write or open statements which are inappropriate for your compiler. Apply RFP to an Xtal System source file to test the include and extrude functions. [To do the latter, remember that macro definitions in XMACRO must be checked first (see 2c and 2d below)].

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 aa.r as this will show how macros are used. Proceed systematically through the macros listed in XMACRO. Be very diligent with use of ifsel:. Wherever possible employ existing macro definitions, or a slight modification thereof. When you have completed the definitions for a new compiler, please send a copy of XMACRO to the Xtal Coordinator for distribution to other users, and for future releases.

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 aa.r. The recommended procedure for doing this is as follows.

A. All of the currently available Xtal3.2 programs are listed in the subroutine AA00 at the front of the file aa.r. Each program to be installed at your site must be preceded in this list by call:. Programs that you are not installing must be preceded in this list by xxxx:.The call: signals that a program will be available to be 'called' during execution. The xxxx: 'no-ops' this calculation. The insertion of call: and xxxx: in aa.r MUST match the list of object files used in linking procedure described later.

B. Preprocess aa.r. [Error messages will signal either incorrect macro definitions (check the compiler: code first) or the use of an inappropriate preprocessor version. If the error is not obvious from the ratmac source, look at the generated Fortran code in the RFPFTN file. Compile RFPFTN (step C below). This will indicate related errors in the Fortran code. Alternatively, insert a flagon:(S) macro at the start of the RFPRAT file and execute RFPP again. This will provide a listing of the source file on RFPLST with a message at the point where the error occurs. Note that the ratmac source and Fortran source line numbers are listed. The ratmac source numbers are only for the RFPRAT file - notfor included files.]

C. Compile aa.f (i.e. the Fortran file generated in step B and copied from RFPFTN). Check any errors or warnings carefully. These routines have been tested extensively and errors are probably due to inappropriate macro definitions for your site.

D. Retain the object file aa.o for use in the linking process described below.

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 (sx.r) and proceed immediately to the linking and testing steps below. This will provide a quick check that the macro definitions are correct for your site.] here are some special considerations when installing Xtal programs.

A. Most programs contain COMMON blocks identified by two-letter codes followed by COMN (e.g. for sx.r the common file is SXCOMN). These blocks are extruded and included in the same way as AACOMN is for the nucleus routines. This is done automatically by the preprocessor and the user should be aware of this because it creates the local files AACOMN and **COMN. These files make it possible to preprocess more than one Xtal program simultaneously in the same directory! The **COMN files should be deleted when the preprocessing is complete.

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 px.r source file to specify local graphical devices. The instructions for doing this are give at the front of px.r. Note that the installer must enter the specified 6-character names of the locally supported graphical devices into the Xtal User's Guide!

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 of the pg.r source file. Again, the 6-character names of the locally supported graphical devices must be written into the Xtal User's Manual!

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 aa.r) should not be linked into the executable module. Check AA00 to make sure that the link list and program calls match.

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.