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