The following sets of routines are available:
Read Keyworded Data
Parse 'KDM' Keyworded Data
Parse 'KSM' Keyworded Data
Write 'KDM' (&'KSM') Data
A routine is available to read lines of keyworded data from a file, accessing indirect file references if present. An alternative routine will allow similar processing from a string again, following indirect file references if present.
The following routines are available:
Read Line of Data from a File - KWD_READLINE
Handle Indirect File References in a String - KWD_READSTR
Fortran call:
SUBROUTINE KWD_READLINE (IUN, KUN, INDIRECT, LINE, EOF, IERR)
Parameters:
IUN i (R) Logical unit number of file/stream being read.
KUN i (R) Start logical unit number for use with indirect files.
Unit nos. (up to MAXIND e.g. 20) in sequence will be
used but any already open will be skipped.
INDIRECT i (R/W) Current indirection level. MUST be set to 0 on first
call to read the file and subsequently must give the
previously returned value. User should ensure that the
program repeats calls to the routine until EOF is
returned as .TRUE. or INDIRECT is returned as 0
(otherwise files will be left open)
LINE c (W) Returns the next logical line with comments removed and
with all continuation lines concatenated.
EOF l (W) .TRUE. End of file encountered on main input stream
(IUN)
.FALSE. No end of file on main input stream.
IERR i (W) Returned error flag = 0 OK
= 1 LINE too short, data truncated
= 2 Error opening indirect file
= 3 Maximum allowed level of
indirection exceeded
= 4 Insufficient Fortran units
available for opening indirect
files
= 5 Calling error (invalid INDIRECT
value)
For error flags > 1, all opened indirect files will be
closed
Notes: Allows for indirect reads from specified files up to MAXIND
levels (e.g. 20) in depth.
Conventions for comments & continuations similar to CCP4 parser
but only '!' introduces comments (and not '#')
If '@' not followed by a file name is found, then all
indirection is cancelled and the next line is read from
the main input stream.
Fortran call:
SUBROUTINE KWD_READSTR (LINE, KUN, INDIRECT, IFLAG, IERR)
Parameters:
LINE c (R/W) On input is the line to be decoded for indirect file
specification. The string should not contain comment or
continuation characters and, if an indirect file
specification is used, then it should only contain that
specification.
On output is the next line read from an
indirect file (or the original line if no indirection
found (or blank if the input line contained '@' only)).
KUN i (R) Start logical unit number for use with indirect files.
Unit nos. (up to MAXIND e.g. 20) in sequence will be
used but any already open will be skipped.
INDIRECT i (R/W) Current indirection level. MUST be set to 0 on first
call to read the file and subsequently must give the
previously returned value. User should ensure that the
program repeats calls to the routine until IFLAG or
INDIRECT are returned as 0 (otherwise files will be
left open).
IFLAG i (W) Flag = 0, if first call and string does not contain
an indirect file specification. 'LINE' is
returned as input.
= 1, Line read from indirect file
=-1, End of indirect data reached
IERR i (W) Returned error flag = 0 OK
= 1 LINE too short, data truncated
= 2 Error opening indirect file
= 3 Maximum allowed level of
indirection exceeded
= 4 Insufficient Fortran units
available for opening indirect
files
= 5 Calling error (invalid INDIRECT
value)
For error flags > 1, all opened indirect files will be
closed
Notes: Allows for indirect reads from specified files up to MAXIND
levels (e.g. 20) in depth.
Conventions for comments & continuations similar to CCP4 parser
but only '!' introduces comments (and not '#'). These only
apply to lines read from an indirect file.
If '@' not followed by a file name is found, then all
indirection is cancelled. A blank line will be returned
and IFLAG will be returned as 0 (see above)
A routine is available to examine input lines for the presece of KDM data; if such data are found, the data will be checked for validity and stored in the Keyword Data Module. Any non-KDM data lines will be returned to the calling program for interpretation by that program and thus both KDM and other control or parameters data may be included in the file being read. Another routine enables additional parameter checking to be carried out.
The following routines are available:
Parse Line Containing KDM Data - KWD_PARSEKDM
Parse KDM Data with Additional Checking - KWD_CHK_PARSEKDM
Parse a Keyword Item - KWD_PARSEITEM
Fortran call:
SUBROUTINE KWD_PARSEKDM (KDX, LINE, IFLAG, BADTOK, ERRSTR)
Parameters:
KDX i (R) Index to required KDM data set.
LINE c (R) Character string containing line to be parsed
(Assume comments & continuations already removed)
IFLAG i (W) Return flag = 0, KDM data found & OK
= 1, Not KDM data of requested set
= 2, No non-blank tokens
< 0, KDM data but error(s)
=-1, Invalid or inappropriate set
specification
=-2, Invalid or inappropriate subset
specification
=-3, Syntax error in set/subset
specification
=-4, Invalid value
=-5, Non-KDM data mixed with KDM data
or mixed KDM datasets.
(Possibly miss-spelt keyword)
-100, Coding error in KWD routines,
information supposedly already
checked is found later to be invalid!
BADTOK c (W) Returns the token string for an invalid token
ERRSTR c (W) Error string (max 80 chars) if IFLAG<0
Fortran call:
SUBROUTINE KWD_CHK_PARSEKDM (KDX, LINE, PGM_CHK, IFLAG, BADTOK,
+ ERRSTR)
Parameters:
KDX i (R) Index to required KDM data set.
LINE c (R) Character string containing line to be parsed
(Assume comments & continuations already removed)
PGM_CHK s (R) Subroutine to make additional check on KDM parameters
to restrict updates (or return other information to
calling program about the parameters found via common
blocks)
The call will be as follows: CALL PGM_CHK (KEYWORD, OK)
KEYWORD (R) CHARACTER*(*) variable holding the full
name of the KDM parameter.
OK (W) Logical flag; return .TRUE. if parameter
may be updated or .FALSE. if it may not.
IFLAG i (W) Return flag = 0, KDM data found & OK
= 1, Not KDM data
= 2, No non-blank tokens of requested set
< 0, KDM data but error(s)
=-1, Invalid or inappropriate set
specification
=-2, Invalid or inappropriate subset
specification
=-3, Syntax error in set/subset
specification
=-4, Invalid value
=-5, Non-KDM data mixed with KDM data
(Possibly miss-spelt keyword)
-100, Coding error in KWD routines,
information supposedly already
checked is found later to be invalid!
BADTOK c (W) Returns the token string for an invalid token
ERRSTR c (W) Error string (max 80 chars) if IFLAG<0
Fortran call:
SUBROUTINE KWD_PARSEITEM (STR, KEYWORD, ISET, ISUBSET, ISS, IERR)
Parameters:
STR c (R) String containing the keyword string to be examined
KEYWORD c (W) Returns the keyword name without any attached
set/subset specification
ISET i (W) Returns set specification if present
ISUBSET i (W) Returns subset specification if present
ISS i (W) =0 keyword only present, =1 keyword + set specification
present, =2 keyword + subset specification present
IERR i (W) Error flag = 0 OK
= 1 blank keyword
=-3 Syntax error in set/subset
specification
A routine is available to examine input lines for the presece of KSM symmetry data; if such data are found the data will be checked for validity and stored in the Keyword Symmetry Module. Another routine enables additional parameter checking to be carried out.
The following routines are available:
Parse Line Containing Symmetry Data - KWD_PARSESYMM
Parse Symmetry Data with additional check - KWD_CHK_PARSESYMM
Fortran call:
SUBROUTINE KWD_PARSESYMM (LINE, IFLAG, BADTOK, ERRSTR)
Parameters:
LINE c (R) Character string containing line to be parsed
(Assume comments & continuations already removed)
IFLAG i (W) Return flag = 0, Symmetry data found & OK
= 1, Not symmetry data
= 2, No non-blank tokens
< 0, Symmetry data but error(s)
=-1, Inappropriate set
specification
=-2, Innappropriate subset
specification
=-3, Syntax error in set/subset
specification
=-4, Invalid value
-100, Coding error in KWD routines,
information supposedly already
checked is found later to be invalid!
BADTOK c (W) Returns the token string for an invalid token
ERRSTR c (W) Error string (max 80 chars) if IFLAG<0
Fortran call:
SUBROUTINE KWD_CHK_PARSESYMM (LINE, PGM_CHK, IFLAG, BADTOK,
+ ERRSTR)
Parameters:
LINE c (R) Character string containing line to be parsed
(Assume comments & continuations already removed)
PGM_CHK s (R) Subroutine to make additional check on symmetry
to restrict update (or return other information to
calling program about the parameters found via common
blocks)
The call will be as follows: CALL PGM_CHK (OK)
OK (W) Logical flag; return .TRUE. if parameter
may be updated or .FALSE. if it may not.
IFLAG i (W) Return flag = 0, Symmetry data found & OK
= 1, Not symmetry data
= 2, No non-blank tokens
< 0, Symmetry data but error(s)
=-1, Inappropriate set
specification
=-2, Innappropriate subset
specification
=-3, Syntax error in set/subset
specification
=-4, Invalid value
-100, Coding error in KWD routines,
information supposedly already
checked is found later to be invalid!
BADTOK c (W) Returns the token string for an invalid token
ERRSTR c (W) Error string (max 80 chars) if IFLAG<0
A routine is available to write out, with various options, the Keyword Data Module (KDM) keyworded parameter data. An alternative routine will allow the symmetry (KSM) data to be written in addition to the KDM data.
The following routines are available:
Output a KDM data set - KWD_WRITEKDM
Output a KDM data set and symmetry - KWD_WRITEKDM_SYMM
Fortran call:
SUBROUTINE KWD_WRITEKDM (KDX, IUNOUT, IOPTYP, ICHANGED, IERR)
Parameters:
KDX i (R) Index to required KDM dataset
IUNOUT i (R) Unit number for output (if <0 then terminal output is
required on unit -IUNOUT)
IOPTYP i (R) Type of output = 1 minimum, do not o/p parameters with
default values
= 2 standard output, do not o/p parameters
with default values except for those
which have been flagged to be printed
as standard.
= 3 full (all parameters will be included)
but with reduced output where feasible
by recombining values if all the same
for a set etc.
= 4 all pamaeters and individual values
given explicitly for all set/subset
parameters.
ICHANGED i (R) =0 Output all parameters
1-16 Write changed parameter values since last reset of
flag for channel ICHANGED
IERR i (W) Error flag = 0 OK
= 1 Invalid KDM index or invalid parameter
Fortran call:
SUBROUTINE KWD_WRITEKDM_SYMM (KDX, IUNOUT, IOPTYP, ICHANGED,
+ ISYMM, IERR)
Parameters:
KDX i (R) Index to required KDM dataset
IUNOUT i (R) Unit number for output (if <0 then terminal output is
required on unit -IUNOUT)
IOPTYP i (R) Type of output = 1 minimum, do not o/p parameters with
default values
= 2 standard output, do not o/p parameters
with default values except for those
which have been flagged to be printed
as standard.
= 3 full (all parameters will be included)
but with reduced output where feasible
by recombining values if all the same
for a set etc.
= 4 all pamaeters and individual values
given explicitly for all set/image
parameters.
ICHANGED i (R) =0 Output all parameters
1-16 Write changed parameter values since last reset of
flag for channel ICHANGED
ISYMM i (R) Output symmetry at position 'ISYMM' in the output KDM
and symmetry parameters list (=0 no symmetry output)
IERR i (W) Error flag = 0 OK
= 1 Invalid KDM index or invalid parameter