Crystals Manual
Chapter 2: Definitions And Conventions
- 2.1: Syntax of Commands
- 2.2: Types of Commands:
- 2.3: Immediate Instructions
- 2.4: Errors and Warnings
- 2.2: Types of Commands:
[Top] [Index] Manuals generated on Wed Jun 6 2001
2.1: Syntax of Commands
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 ) ...)
END
Items in round brackets '()' may be absent, items in square brackets '[]' are optional. Ellipsis '...' means the preceeding 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 preceeded 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.
example:
\DISTANCE
SELECT RANGE=LIMITS
LIM 0.0 1.9 0.0 0
END
Those parts of the manual describing data and instruction input will generally be in the following format:
1. A summary of the complete command, with all directives and
keywords. Ellipis (....) may be printed to represent omitted
but similar parameters.
2. An typical example. This may not demonstrate all the available
options
3. A description of all the directives and keywords.
[Top] [Index] Manuals generated on Wed Jun 6 2001
2.2: Types of Commands:
Lists
These contain related data items, grouped together so that CRYSTALS can check that the data is complete. These lists are stored in the CRYSTALS data-base. 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:
Keyed 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
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.
Instructions
These cause CRYSTALS to 'do' something, for example, compute a Fourier
map. There are two type of syntax for Instructions, similar to those used
for LISTS:
Keyed Instructions
Lexical Insructions
Immediate Instructions
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 an INSTRUCTION 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.
Comments
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 Wed Jun 6 2001
2.3: Immediate Instructions
\FINISH
This instruction 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 instruction 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 \ instructions 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 instructions. 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 instruction 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 JCL command
A JCL command can be issued from inside CRYSTALS with this instruction.
\SPAWN without a command spawns a sub-process and passes control of the
sub-process to the terminal. Return to CRYSTALS by LOGGING out of the
sub-process. ONLY available under VAX/VMS and UNIX.
\$ JCL command
A JCL command can be issued from inside CRYSTALS with this instruction.
A typical example is $ DIR.
$ JCLcommand
This facility works in exactly the same way as \SPAWN or \$, described
above.
\COMMANDS instruction
This instruction, which takes as parameter other instruction-names
(without the \ ), produces a listing of the available parameters,
keywords and defaults for those instructions. The listing is
derived directly from the 'command file', and is thus
completely up to date for the program being run. This instruction will
not operate correctly if the preceeding instruction ended in error. Clear
the error flag by performing some succesfull operation.
The facility
is an aide-memoire, and not intended to replace the manual.
The full significance of the output is detailed in the section
DATABASE.
? text
This facility allows the user to make brief inquiries from the command file on the instructions, directives, and parameters available at the current point in the job. If an instruction is not being processed, and '?' is enterd alone, a list of the instructions is displayed. If '? instruction' is entered, a list of the directives available with that instruction is dirplayed. If '? instruction directive' is entered, a list of parameters for the given instruction and directive is displayed, and so on.
If an instruction is currently being processed, the behaviour is similar,
but no instruction name is allowed. Then '?' gives a list of directives,
'? directive' a list of parameters, and so on. In this case care should
be
taken if a previous directive is CONTINUEd after using '?', as the parameter
index is reset, and as the system assumes the next parameter to be input
will
be number 1, its name should be given explicitly.
\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 instruction 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 instructions 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.
e.g.
\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 instruction. 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
The devices recognised by CRYSTALS are:
DISCFILE HKLI CONTROL PRINTER PUNCH LOG MONITOR SPY NEWDISC COMMANDS M32 M33 MT1 MT2 MT3 MTE SRQ FORN1 FORN2 SCPDATA
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 instruction 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 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 are also given for a Microvax 3800 (circa 1995)
\SET LIST state
This instruction allows the user to control the monitoring level of transfer of lists to and from the database in conjunction with the SET WATCH instruction. 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, so that only operations creating or modifying
list 5 will be monitored.
\SET WATCH number
This instruction 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 instruction 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.
\SET GENERATE state
This instruction 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.
\SET EXPORT state
If 'state' is 'on' then LISTS 5,12 and 16 are copied to the PUNCH file
when CRYSTALS closes down. These can be archived for safety, or exported
to another computer.
\SET UEQUIV state
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.
\SET MONITOR state
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 instruction 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.
\SET TERMINAL device
This instruction 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
On VAXs, VMS must know what terminal you are using before you start CRYSTALS.
\SET COMMUNICATION speed
This instruction 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 instruction 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.
\SET PRINTER state
This instruction is used to control output to the 'printer' file. The
state
OFF suppresses printer output.
\SET OPENMESSAGE state
This instruction is used to enable or disable file handling messages.
OFF suppresses messages.
\SET MESSAGE state
This instruction 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 instruction is used to control mirroring of CRYSTALS internal commands.
The normal state OFF suppresses the mirroring.
\BENCH nparam nref
This simulates sfls 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 are also given for a Microvax 3800 (circa 1995)
[Top] [Index] Manuals generated on Wed Jun 6 2001
2.4: Errors and Warnings
CRYSTALS recognises the following run time error categories,
in addition
to any detected by the operating system.
Warnings
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.
Errors
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.