READ AND WRITE 'KDM' KEYWORDED DATA

INTRODUCTION

Fortran based routines are available to read and write Keyword Data Module (KDM) based keyworded data for inputting parameters to a program. In addition, symmetry keywords based on the Keyword Symmetry Module (KSM) may be processed. On input, lines not containing recognised KDM (or KSM) data will be returned to the program for further processing.

The following sets of routines are available:

Read Keyworded Data
Parse 'KDM' Keyworded Data
Parse 'KSM' Keyworded Data
Write 'KDM' (&'KSM') Data

READ KEYWORDED DATA

Introduction

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

Read Line of Data from a File - KWD_READLINE

This routine will return, on repeated calls, the next logical line of data read from a parameters file. Any indirectly referenced parameter files will be read as required. The logical line returned will contain any continuation lines present but will exclude any comments found.
 
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.

Handle Indirect File References in a String - KWD_READSTR

This routine is similar to KWD_READLINE in its handling of indirect files. The difference is that the line for examination is passed to the routine rather than being read from a top level parameter file.
 
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)

PARSE 'KDM' KEYWORDED DATA

Introduction

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

Parse Line Containing KDM Data - KWD_PARSEKDM

This routine parses a given line of data, examining it for the presence of a requested set of KDM data. Any such data found is automatically checked and, if valid, stored in the appropriate Keyword Data Module. If the line does not contain KDM data from the requested set, then it is merely passed back to the calling program to allow further interpretation by that program. KDM and non-KDM data (or data items from different KDM sets) must not be given in the same line of data and a line of data containing any valid KDM keyword for the KDM set being examined will be assumed to be a KDM parameter line. The calling program should also take account of the fact that incorrectly specified KDM keyords may result in the line being returned to the calling program.
 
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

Parse KDM Data with Additional Checking - KWD_CHK_PARSEKDM

This routine is similar to KWD_PARSEKDM but a user supplied routine may make an additional check on each KDM parameter and disable its update if desired.
 
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

Parse a Keyword Item - KWD_PARSEITEM

This routine is used by the higher level parsing routines described above but may be called by the user if required. It examines a given keyword string and determines any set/subset specifications attached to the keyword.
 
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 

PARSE 'KSM' KEYWORDED DATA

Introduction

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

Parse Line Containing Symmetry Data - KWD_PARSESYMM

This routine parses a given line of data, examining it for the presence of the keyword 'SYMMETRY' (as the first token) Any such data found is automatically checked and, if valid, stored in the appropriate Keyword Symmetry Module (KSM). If the line does not contain symmetry data from the requested set, then it is merely passed back to the calling program to allow further interpretation by that program. The symmetry data line must contain only symmetry data.
 
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

Parse Symmetry Data with additional check - KWD_CHK_PARSESYMM

This routine is similar to KWD_PARSESYM but a user supplied routine may make an additional check and disable its update if desired.
 
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

WRITE 'KDM' (&'KSM') DATA

Introduction

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

Output a KDM data set - KWD_WRITEKDM

This routine is used to output a KDM keyword parameter data set. A number of options are available to control the amount and style of the output and there is also an option to output only changed KDM parameter values.
 
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

Output a KDM data set and symmetry - KWD_WRITEKDM_SYMM

This routine is used to output a KDM keyword parameter data set and also the symmetry data if desired. A number of options are available to control the amount and style of the output and there is also an option to output only changed KDM parameter values.
 
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



John W. Campbell
CCLRC Daresbury Laboratory
Last update 28 Aug 1996