Crystals Manual

Chapter 2: Definitions And Conventions

2.1: Syntax of Commands
2.2: Syntax of the manual
2.3: Types of Commands:
2.4: Immediate commands
2.5: Files
2.6: Errors and Warnings

[Top] [Index] Manuals generated on Wednesday 27 April 2011

2.1: Syntax of Commands

Commands are given to CRYSTALS as small packages, rather like sentences. This enables the program to recognise when the user thinks that a piece of input is complete and then, after inserting any default values and checking for errors, perform the task.
Format of Commands

All command packages follow the same general format. The command is introduced with a backslash (or alternatively, a hash symbol) and ends with the word 'END'.

      \COMMAND ([keyword=]value ) ...
      (DIRECTIVE ([keyword=]value ) ...)

Items in round brackets '()' may be absent, items in square brackets '[]' are optional. Ellipsis '...' means the preceding item may be repeated.

Actual data on a COMMAND or DIRECTIVE line is input in free format, with at least one space (or sometimes an optional comma) terminating an item. Data items may either be preceded with the keyword and its '=' sign, or if the order given in the definition is strictly followed, just by the data values. COMMANDS, DIRECTIVES and KEYWORDS can be abbreviated to the minimum string which resolves ambiguity. Both types of identification can be intermingled.

The following examples are all identical to the program. They use the command \DISTANCES to compute all interatomic distances in the range 0.0-1.9 Angstrom, and all interatomic angles involving bonds in the range 1.6-2.1 Angstrom.

      LIMITS DMIN=0.0 DMAX=1.9 AMIN=1.6 AMAX=2.1

      SE RA=LI
      LI 0.0 1.9 1.6 2.1

      LIMI DMAX=1.9 1.6 2.1

Note that in the last example, the value for DMIN is omitted (its default value turns out to be 0.0) and the list of parameters starts with a DMAX: CRYSTALS knows that the next parameter is AMIN so it need not be specified.

[Top] [Index] Manuals generated on Wednesday 27 April 2011

2.2: Syntax of the manual

Those parts of the manual describing data and command input will generally be in the following format:

      1. A summary of the complete command, with all directives and
         keywords. Ellipsis (...) may be printed to represent omitted
         but similar parameters.
      2. An typical example. This may not demonstrate all the available
      3. A description of all the directives and keywords.

For a simple example, see LIST 1, section 4.2.

[Top] [Index] Manuals generated on Wednesday 27 April 2011

2.3: Types of Commands:


These contain related data items, grouped together so that CRYSTALS can check that the data is complete. These lists are stored in the CRYSTALS database. Usually, input of a new list of a given type over-writes an existing list of the same type. In general, LISTS do not 'do' anything.

There are two types of syntax for LISTS:


In these, CRYSTALS can know in advance how much and what kind of input to expect. Each element of data is identified by an optional keyword. See, for example, LIST 1 (section 4.2).

Lexical LISTS

In these, CRYSTALS cannot know in advance what kind of data the user may wish to input. Each line of input is processed by a lexical scanner, and parsed to determine the action needed. See, for example, LIST 12 (section 7.11).

For a list of all the lists, see the Lists overview (section 3.3).


These cause CRYSTALS to 'do' something, for example, compute a Fourier map. There are two type of syntax for commands, similar to those used for LISTS:

Keyed Commands
Lexical Commands
Immediate Commands

These are special commands which are acted upon immediately they are issued. They are never more than one line long, and do not require an 'END'. They can be issued whenever the cursor is at the beginning of a line, even inside a COMMAND or LIST. They are not usually involved with the crystallographic calculation, but control some aspect of the way CRYSTALS works, such as hooking in an external data file, or changing the amount of output produced.

Any data line starting with a backslash or hash followed immediately with a space is ignored, and may thus be used as a comment, or to deactivate the line without deleting it from the file.

Continuation Lines
The directive CONTINUE indicates that the data on the current line is a continuation of the previous line.

[Top] [Index] Manuals generated on Wednesday 27 April 2011

2.4: Immediate commands


This command closes down CRYSTALS neatly.

\ ..... COMMENTS ....

This is a comment line. Column 1 contains the \ character and column 2 must be left blank. The remaining columns (3-80) may be used for a descriptive comment. Such a comment line may appear at any point in the input.

\TITLE ..... A title to be printed .....

This command changes the title that appears at the start of every operation. The characters \TITLE are terminated by a space in column 7 and the remainder of the line contains the title.

\TYPE 'filename'

The file 'filename' is typed on the users terminal without its contents being interpreted by CRYSTALS. Thus \ commands in this file are NOT acted on, giving the user a method of previewing a USE file.

\USE source

This command controls the source of commands for CRYSTALS. If 'source' is a filename then commands are read from that file. If 'source' is LAST ,the current USE file is closed and commands are read from the previous level USE file. If 'source' is CONTROL , all USE files open are closed and commands are read from the main control stream for the job , for example the terminal in an interactive job.

One USE file may contain other USE commands. The maximum depth of USE files allowed will be installation dependent. Note that the USEd file need not be a complete list - it can be as little as only one line. An indirect file should end with '\USE LAST' , '\USE CONTROL' , or '\FINISH' . This command is only available in some implementations.

\SCRIPT filename

This command is only available in interactive mode, and passes control to the 'script' file, which tries to assist the user by prompting him for data and information. A separate manual describes the writing of user define scripts.

\SPAWN 'shell command'

A 'shell command' can be issued from inside CRYSTALS with this command. \SPAWN without a command spawns a sub-process and passes control of the sub-process to the terminal. Return to CRYSTALS by closing the sub-process.

$ 'shell command'

A 'shell command' can be issued from inside CRYSTALS with this command. Typical examples are: $dir, $notepad, $edit afile, $netscape something.html

\COMMANDS command

This command, which takes other command-names as a parameter (without the \ ), produces a listing of the available parameters, keywords and defaults for those commands. The listing is derived directly from the 'command file', and is thus completely up to date for the program being run. This command will not operate correctly if the preceding command ended in error. Clear the error flag by performing some successful operation. The facility is an aide-memoire, and not intended to replace the manual. The full significance of the output is detailed in section 3.0 on the CRYSTALS database.

? text

This facility allows the user to make brief inquiries from the command file on the commands, directives, and parameters available at the current point in the job. If a command is not being processed, and '?' is entered alone, a list of the commands is displayed. If '? command' is entered, a list of the directives available with that command is displayed. If '? command directive' is entered, a list of parameters for the given command and directive is displayed, and so on.

If a command is currently being processed, the behaviour is similar, but no command name is allowed. Then '?' alone gives a list of directives, while '? directive' gives a list of parameters, and so on. In this case care should be taken: After a '?', CRYSTALS loses track of the last parameter that was input so using CONTINUE will have unpredictable results. To work around this, specify the parameter explicitly on the command line, for example:

  \  Start entering a new atom to be added to the model:
  ATOM U 1.0
  \  Refresh your memory as to the rest of the syntax:
  \  Carry on entering the atom, but give the 
  \ parameter name, X, explicitly.
  CONTINUE X=0.2 0.4 0.5

\MANUAL 'name'

The 'name' parameter is the name of the volume whose index is required. The special name 'INDEX' gives a list of subjects for each volume. The special name 'LISTS' gives a list of the function of each LIST.

\HELP 'topic'

The topic 'HELP' contains a list of topics for which help is given. This is likely to be very site-specific.

\OPEN devicename filename

This command is similar to RELEASE, except that a wider range of device names may be specified, and different messages are produced. An important facility available with this command is to open a named HKLI file, for the reflection input commands HKLI and LIST 6, using the device name HKLI. Similarly permanent files may be used in data reduction work by using the device names M32 and M33 overriding the default scratch files.

      \OPEN HKLI reflection.hkl


\CLOSE devicename

Any file on specified device is closed.

\RELEASE devicename filename

The file currently open on 'devicename' is closed, and a new file opened on that device if necessary. The file just closed can be examined using the \TYPE command. The filename parameter is optional. If it is specified, the new file will be opened with that name.

Useful devices currently available include PRINTER, PUNCH, LOG and MONITOR.

\APPEND devicename filename

Output to the specified device is appended to any output already in the specified file.

Device names

Devices are names used inside CRYSTALS to refer to files that it has opened. Deviecs recognised by CRYSTALS are:

DISCFILE - the database containing everything.
HKLI - an hkl file during input using \LIST 6 or \HKLI.
CONTROL - commands being input (can be a file if you type \USE filename, but is usually the command input line)
PRINTER - the listing file (bfilenn.lis by default)
PUNCH - the punch file (bfilenn.pch by default)
LOG - record of all commands issued (bfile.log by default)
MONITOR - obsolete, used to be text that appeared on the screen
SPY - obsolete, used to collect usage data (locally!).
NEWDISC - a second database, open during \PURGE commands.
COMMANDS - the file commands.dsc defines the syntax and data structures of all the commands and lists.
M32 M33 MT1 MT2 MT3 MTE - scratch files
SRQ - system request queue. Some high-level commands may issue other CRYSTALS commands using this file.
FORN1, FORN2 - output of data for 'foreign' (ie. external) programs.
SCPDATA - scripts can read directly from any file opened on this device (using EXTRACT script command)
SCP2 - scripts can read directly from any file opened on this device (using EXTRACT2 script command)s
SCPQUEUE - stores commands that scripts are building up.
Not all may be opened/closed by the user from a command prompt. Some are only available inside the initialisation file CRYSTSLS.SRC (See STORE below).

\PAUSE interval

This command causes the program to wait for 'interval' seconds before proceding. The maximum value of 'interval' is 200 seconds. It might be useful in a 'USE' file.

\BENCH nparam nref

This simulates sfls (structure factor least squares, i.e. a cycle of refinement, see 7.43). to enable processor speeds to be compared. No real refinement is done, and the structure is not modified.

      nparam defaults to 500
      nref   defaults to 5000

Times for a Microvax 3800 (circa 1995) are printed for comparison.


\SET LIST state

This command allows the user to control the monitoring level of transfer of lists to and from the database in conjunction with the SET WATCH command. There are four states available.

If state is OFF, no list logging information is produced.

If state is READ or WRITE, list logging information is only produced when lists are read or written respectively.

If state is BOTH, both reading and writing operations may be monitored. Note that the logging operation may be qualified by a list type specified by SET WATCH. The initial state is WRITE, with the specific watch set on list 5 (the model parameters), so that only operations creating or modifying list 5 will be monitored.

\SET WATCH number

This command is used in conjunction with SET LIST to control monitoring of list operations. If number is 0, operations on all list types may be monitored, according to the state set with SET LIST. If number is a positive integer, representing a list type, only operations on that list type may be monitored. The initial value for the list watch is 5, which in conjunction with the initial monitoring state means that operations creating or modifying list 5 will be monitored.

\SET FILE type

This command is used to control the case of file names generated by CRYSTALS. Possible values are:

 LOWER        Filenames are converted to all lower case.
 UPPER        Filenames are converted to all upper case.
 MIXED        Filenames are left as input or defined.


This command is used to control the generation of output file names and pseudo-generation numbers on non-VMS systems. By default, CRYSTALS modifies the root of filenames for files which should not be overwritten (normally .LIS, .MON, .LOG).

OFF suppresses automatic name generation.


If 'state' is 'on' then LISTS 5 (atoms), 12 (constraints) and 16 (restraints) are copied to the PUNCH file when CRYSTALS closes down. These can be archived for safety, or exported to another computer.

This controls the calculation of Uequiv. Both definitions are acceptable to Acta. The arithmetic mean of the principle axes is often similar to the refined value of Uiso. The geometric mean is more sensitive to long or short axes, and so is more useful in publications.
      ARITH = (U1+U2+U3)/3
      GEOM  = (U1*U2*U3)**1/3

\SET PAUSE value

This command sets a time, in seconds, for which the program will pause at the end of each screen full of output. It is only effective on DOS machines, and enables the user to use the 'pause' key to hold a selected screen. The maximum value of 'interval' is 200 seconds.

\SET LOG state

If state = ON then all user input commands are written to a log file.
If state = OFF then subsequent commands are not written to the log. Any change made to the log state applies only to the current level of USE file and any USE file called by it. Because the log file is a direct copy of the users commands, it may subsequently be used (probably after modification) as a control file.


If 'state' = ON, then all input is reflected in the monitor file. If 'state' = OFF, monitoring. is suppressed. Any change made to the monitoring state applies only to the current level of USE file and any USE file called by it.

\SET PAGE length

This command is used to change the length of the assumed 'page' when displaying files on the monitor channel, using the commands 'HELP', 'MANUAL', and 'TYPE'. The initial length is 20 lines. After the number of lines specified have been typed, the listing stops and a message indicates the program is waiting. A blank line or carriage return at this point will cause the listing to continue. Any other input is executed normally. If the length is set to zero, or a negative number, the feature is disabled.


This command controls the display of SCRIPT menus on some terminals. Possible device types are

 UNKNOWN This is the default, and requires no special terminal.
 VT52    For use on terminals with limited screen management facilities.
 VT100   For use on advanced terminals.
 VGA     For use on PC VGA terminals
 WIN     For use under Win32 and X-windows.


This command is used to indicate to the program the speed of the communication line or terminal on which it is being run. This indication is used by some facilities to determine how much output to produce on the monitor channel. The possible values for the speed are "SLOW" and "FAST". These keywords are not associated with any particular terminal speed, and the appropriate value will depend on the user's patience. The initial value is "FAST"

\SET TIME state

This command is used to indicate to the program whether the timing messages usually produced at the end of each facility are produced. If 'state' is "OFF" the messages are not displayed. If 'state' is "ON" the messages are displayed.


This command is used to control output to the 'printer' file. The state OFF suppresses printer output.


This command is used to enable or disable file handling messages. OFF suppresses messages.


This command is used to indicate to the program whether the command messages usually produced at the end of each facility are produced. If 'state' is "OFF" the messages are not displayed. If 'state' is "ON" the messages are displayed. Error messages are always displayed.

\SET SRQ state

This command is used to control mirroring of CRYSTALS internal commands. The normal state OFF suppresses the mirroring.


[Top] [Index] Manuals generated on Wednesday 27 April 2011

2.5: Files

When CRYSTALS runs it stores all crystallographic data in a single file, by default named crfilev2.dsc. This is a binary file and should not be opened with any other program.

CRYSTALS outputs results and analysis to several places:

The listing file: this will be called bfilenn.lis where nn is a number from 00-99, incremented each time the program is run. When nn reaches 99 this file will be continuously overwritten every time CRYSTALS is run.
The listing file contains verbose output about all the calculations that take place.
The punch file: called bfile.pch by default. The idea of 'punching' data is a throwback to the days of punched cards. This file is used to write out specific bits of data as commands that can then be read back into the program. For example, the parameters defining the crystallographic model are stored in CRYSTALS as a 'List 5'. Then 'Punching List 5':
  \PUNCH 5

will result in a full \LIST 5 command being written to the file bfile.pch. You can then recover that version of the model parameters by typing

  \USE bfile.pch

which causes the commands written in that file to be executed by CRYSTALS.

The monitor file: called bfilenn.mon this is obsolete. If there is any output in it, it is from a bit of the program that hasn't been looked at recently.
The log file: called bfilenn.log, this contains everything that you typed into CRYSTALS, and commands that were issued on your behalf by the menu system or script processor.

[Top] [Index] Manuals generated on Wednesday 27 April 2011

2.6: Errors and Warnings

CRYSTALS recognises the following run time error categories, in addition to any detected by the operating system.


These will occur only for tasks which produce user-readable output, and do not write to the database. The current task is abandoned if necessary, and the next task fetched from the input stream.


The error is such that the current task must be abandoned. In batch or online modes, the job will be terminated as well. In interactive mode the current task is abandoned , and control is returned to the user at terminal. The processing of any 'USE' file will be abandoned.

Severe Errors

The error detected is such that it is not possible for the job to continue. These errors are usually caused by database management failures.

Catastrophic Errors.

The job is completely terminated. This is usualy the consequence of errors in reading or writing to the database.

Programming Errors

The program has detected an inconsistency either in the code, or in the command file. A dump and error report will be generated if possible. The error and the conditions that cause it should be reported to Oxford.

Errors Detected During the Creation of a LIST

During all operations that create new versions of a list, either by input or internally, errors may be found that cause the new list not to be written to the database. To prevent the system using an old version of a list when the creation of the latest version has failed, the relevant list type is marked as an 'error list' in the 'list control table' (see below). This error flag is cleared when a new version of the list is created or by user action.

If a list which is marked as an error list is accessed, a message will be output, and the job terminated. However, for the printing of most lists, the error flags are not checked.

© Copyright Chemical Crystallography Laboratory, Oxford, 2011. Comments or queries to Richard Cooper - Telephone +44 1865 285019. This page last changed on Wednesday 27 April 2011.