5.2.2 - Keyword Data Module (KDM) - JdlKeywordDataModule

John W. Campbell

5.2.2.1 Introduction

This class provides an object for defining and handling Keyworded data files. In general, such a file consists of a series of lines of parameter keywords followed by corresponding values. The class provides a general purpose way of handling such input. The basic development was done within the context of developing software for Protein Crystallography where such input files were used. This Java based implementation is based on an earlier 'C' based implementation of the Keyword Data Module (KDM). This is essentially a legacy item of software since its functions might well be replaced by, for example, the use of XML based data files though, for hand editing, simplicity and clarity, the keyword data files still have some merit. The keyword data module also enables parameter value changes to be monitored to determine, for example, whether re-calculations need to be made. The following is an extract of a keyworded file from the Protein Crystallographic program ROTGEN:
NUMSETS 1
SYSTEM Orthorhombic
LATTICE P
RESOLUTION 3.5
WAVELENGTH 1.7
SCAN_AXIS 0.0 0.0 1.0
A 64.5970 B 65.6768 C 155.4468
Parameters may be defined for individual 'sets' or 'subsets' within the overall data set. In general, a KDM set of parameters may have some parameters which apply to the dataset as a whole, some which have different values for each set and some which may have different values for each subset. An example woould be the ROTGEN program to predict unique data coverage for sets of rotation data. A 'set' in this context is a series of consecutive images collected from a start to end oscillation angle. Parameters such as the crystal system and lattice type apply to the whole dataset whereas parameters defining the oscillation range, number of images etc. are set based; this program does not require subset based parameters.

Parameters may be of type integer, double or String and normally have a single value associated with each keyword though some more complex options are also available. For a set based parameter the keyword may have a set number appended in square brackets e.g. ROTSTART[2] 50.0; if the set number is omitted, it is assumed that the value following the keyword refers to all sets e.g. NUMIMG 20. Similarly a subset based parameter may have a set and subset number appended e.g. SPOTW[2][3] 0.7; SPOTW 0.6 sets the same value for all sets and subsets; SPOTW[][3] 0.75 sets the same value for subset 3 of each set and SPOTW[2][] 0.55 sets the value for all subsets of set 2.

Other options for integer and double parameters are to have a fixed number of values (>1) e.g. for a vector or matrix. A further option can also associate a variable number of values with an integer or double value parameter. These are known as suffixed keyword parameters. The values for such parameters may be input as a variable length list of values or individual values may be input/accessed using the keyword name with a number appended indicating the position in the list of values associated with that keyword (The keywords for such parameters must not themselves end with a digit). For example take the rotation range start value parameter ROTSTART which normally has a single value e.g. ROTSTART 25.0. However if, for example, three rotation ranges are required, three values may be given e.g.
ROTSTART 25.0 66.5 120.0. 
In addition, the keywords ROTSTART1, ROTSTART2 and ROTSTART3 are automatically made available to set or access the individual values e.g.
ROTSTART1 25.0 
ROTSTART2 66.6 
ROTSTART3 120.0
The number of values currently defined for the parameter will be the largest of the number of values input following the keyword and the maximum index given in the keyword suffix. Thus for example, if ROTSTART6 180.0 was defined in addition to the previous definitions, The number of values currently defined would be taken as 6 and default values would be assigned to the values not explicitly defined e.g. for ROTSTART4 and ROTSTART5 in the above example. Naturally set/subset specifications can be added as with any of the single or fixed number of values integer/double parameters e.g. ROTSTART2[3] for the value of ROTSTART2 for the third set.

KDM files may contain references to further nested KDM files. These are specified by the '@' character followed by a file name. Comment lines are started by the character '!'. Continuation of the data onto the next record of a file is indicated by terminating a line with the character '-' or '&'.

The reading and parsing methods are designed so that data may be input from data files containing parameters from more than one KDM data set provided that there is no clash of keywords. It also enables crystallographic symmetry data to be included in the input data file though this has to be interpreted using the appropriate purpose built object methods in the Jdl.JdlPX package.

Constructors and Methods:

Class Details
Accessible Fields
Constructors
Define keyworded Parameters
Set and Get Parameter Values
Read and Parse KDM Data
Output KDM data
Monitor Parameter Changes
Specialist Methods

5.2.2.2 Class Details

Package:
Jdl.JdlKDM;
Class name:
JdlKeywordDataModule
Class definition:
public class JdlKeywordDataModule
Extends:
Object
Implements:
JdlStringWriter
Actions:
none

5.2.2.3 Accessible Fields

No fields with public, package or protected access defined.

5.2.2.4 Constructors

5.2.2.4.1 Introduction

The contructor sets up the basic KDM object ready for the individual keywords and parameter types to be defined. The current number of sets and numbers of subsets/set parameters will be used internally by the outputString(..) method when a keyworded dataset is being output.

List of Constructors:

Constructor 1

5.2.2.4.2 Constructor 1

Constructs an object for defining and handling Keyworded Data Module files.

Constructor Definition:
public JdlKeywordDataModule(int max_sets, int max_subsets, String nums_nam, String numss_nam, String snam, String ssnam)
Parameters List:
max_sets
Maximum number of sets for 'set specific' parameters. (0 if no set or subset parameters required)
max_subsets
Maximum number of subsets for 'subset specific' parameters. (0 if no subset parameters required)
nums_nam
Name of the keyword defining the current number of sets being used; this will be defined internally as an integer parameter (type=dataset) with limits from 1 to max_sets.
numss_nam
Name of the keyword defining the current number of subsets being used for each set; this will be defined internally as a 'set dependent' integer parameter with limits 1 to max_subsets.
snam
The string to be used for the 'set' parameter in messages e.g. 'set' or 'image'.
ssnam
The string to be used for 'subset' in messages e.g. 'subset' or 'layer'.

5.2.2.5 Define keyworded Parameters

5.2.2.5.1 Introduction

This section provides the methods which are used to define the keywords and parameter value types for the required Keyword Data Module. Standard options for data value checking are available as well as an option for supplying an object interface for additional checking options.

List of methods:

Define an integer KDM parameter - defineIntegerParameter
Define a double KDM parameter - defineDoubleParameter
Define a String KDM parameter - defineStringParameter
Define a mixed KDM parameter - defineVarrParameter

5.2.2.5.2 Define an integer KDM parameter - defineIntegerParameter

This method enables the definition of a keyword parameter which has an 'integer' value.

Method Definition:
public boolean defineIntegerParameter (String name, int minl, int ityp, boolean std, int nvals, int[] i_default, int i_min, int i_max, int chk_typ, JdlKDMDataChecker chk_handler, JdlError err)
Parameters List:
name
The parameter name (full).
minl
Minimum length of string for keyword matching.
ityp
Parameter type 1=dataset, 2=set, 3=subset specific.
std
Standard parameter for output (see outputString(..)) =true, yes, =false no.
nvals
No. of values associated with the keyword - normally 1. If -nvals is given, then the keyword is treated as a special case where from 1 up to nvals values may be specified (a suffixed keyword parameter - note that the basic keyword parameter name must not itself end with a digit in this case).
i_default
Default parameter values (nvals values).
i_min
Minimum allowed value (if chk_typ==5).
i_max
Maximum allowed value (if chk_typ==5).
chk_typ
Check value option:
= 0, any integer OK
= 1, any >=0
= 2, any >0
= 3, any <=0
= 4, any <0
= 5, must be in range i_min to i_max
= 6, check using supplied JdlKDMDataChecker object
= 7, 0<= ival<= max_sets
= 8, 0<= ival<= max_sub sets
chk_handler
JdlKDMDataChecker object (if chk_typ==6).
err
JdlError error handler object. If an error occurs 'err.err' will be returned as true and 'err.flag' may have the following values:
= 1, Keyword parameter name not given
= 2, Keyword parameter name not unique
= 3, Other error in method calling parameters
Method Return:
=true OK, =false error (see 'err' for details).

5.2.2.5.3 Define a double KDM parameter - defineDoubleParameter

This method enables the definition of a keyword parameter which has a 'double' value.

Method Definition:
public boolean defineDoubleParameter (String name, int minl, int ityp, boolean std, int nvals, double[] d_default, double d_min, double d_max, int chk_typ, JdlKDMDataChecker chk_handler, int nd, int default_nd, JdlError err)
Parameters List:
name
The parameter name (full).
minl
Minimum length for keyword matching.
ityp
Parameter type 1=dataset, 2=set, 3=subset specific.
std
Standard parameter for output (see outputString(..)) =true, yes, =false no.
nvals
No. of values associated with the keyword - normally 1. If -nvals is given, then the keyword is treated as a special case where from 1 up to nvals values may be specified (a suffixed keyword parameter - note that the basic keyword parameter name must not itself end with a digit in this case).
d_default
Default parameter values (nvals values).
d_min
Minimum allowed value (if chk_typ==5).
d_max
Maximum allowed value (if chk_typ==5).
chk_typ
Check value option:
= 0, any double OK
= 1, any >=0.0
= 2, any >0.0
= 3, any <=0.0
= 4, any <0.0
= 5, must be in range d_min to d_max
= 6, check using supplied JdlKDMDataChecker object
chk_handler
JdlKDMDataChecker object (if chk_typ==6).
nd
No. of decimal places for printing the value when it has been recalculated by a program.
default_nd
The number of decimal places for printing the default value.
err
JdlError error handler object. If an error occurs 'err.err' will be returned as true and 'err.flag' may have the following values:
= 1, Keyword parameter name not given
= 2, Keyword parameter name not unique
= 3, Other error in method calling parameters
Method Return:
=true OK, =false error (see 'err' for details).

5.2.2.5.4 Define a String KDM parameter - defineStringParameter

This method enables the definition of a keyword parameter which has a 'String' value.

Method Definition:
public boolean defineStringParameter (String name, int minl, int ityp, boolean std, String str_default, String[] valid_strings, int chk_typ, int match, JdlKDMDataChecker chk_handler, JdlError err)
Parameters List:
name
The parameter name (full).
minl
Minimum length for keyword matching.
ityp
Parameter type 1=dataset, 2=set, 3=subset specific for single token; 4=dataset, 5=set, 6=subset specific multiple token string.
std
Standard parameter for output (see outputString(..)) =true, yes, =false no.
s_default
Default pararameter value string.
valid_strings
Array of valid string values (for chk_typ == 1).
chk_typ
Check value option:
= 0, any string OK
= 1, check against valid strings
= 2, check using supplied JdlKDMDataChecker object
match
Minimum no. of characters to be matched if chk_typ==1; if -match given then only match characters will be checked and remainder will be ignored; if match==0 all characters will be checked.
chk_handler
JdlKDMDataChecker object (if chk_typ==2).
err
JdlError error handler object. If an error occurs 'err.err' will be returned as true and 'err.flag' may have the following values:
= 1, Keyword parameter name not given
= 2, Keyword parameter name not unique
= 3, Other error in method calling parameters
Method Return:
=true OK, =false error (see 'err' for details).

5.2.2.5.5 Define a mixed KDM parameter - defineVarrParameter

This method enables the definition of a keyword parameter which has a series of values, some of which are of type 'integer' and others of which are of type 'double'.

Method Definition:
public boolean defineVarrParameter (String name, int minl, int ityp, boolean std, int nvals, int nvals_min, int[] i_default, double[] d_default, int d_min, int d_max, int chk_typ, JdlKDMDataChecker chk_handler, int[] nd, int[] default_nd, int npr_dflt, JdlError err)
Parameters List:
name
The parameter name (full).
minl
Minimum length for keyword matching.
ityp
Parameter type 1=dataset, 2=set, 3=subset specific.
std
Standard parameter for output (see outputString(..)) =true, yes, =false no.
nvals
No. of values associated with the keyword.
nvals_min
Minimum number of values which must be given.
i_default
Default integer parameter values (nvals values). (Values for which irtyp[i]!=1 ignored)
d_default
Default double parameter values (nvals values). (Values for which irtyp[i]!=2 ignored)
irtyp
Parameter element type flags (nvals values)
= 1, for int
= 2, for double (any value!=1)
d_min
Minimum allowed value (if chk_typ==5).
d_max
Maximum allowed value (if chk_typ==5).
chk_typ
Check value option
= 0, any int/double respectivly OK
= 1, check using supplied JdlKDMDataChecker object
chk_handler
JdlKDMDataChecker object (if chk_typ==6).
nd
No. of decimal places for printing values when recalculated by a program (nvals values) - ignored for integer values.
default_nd
No. of decimal places for printing the default values (nvals values) - ignored for integer values.
npr_dflt
No. of values to print when outputting default value.
err
JdlError error handler object. If an error occurs 'err.err' will be returned as true and 'err.flag' may have the following values:
= 1, Keyword parameter name not given
= 2, Keyword parameter name not unique
= 3, Other error in method calling parameters
Method Return:
=true OK, =false error (see 'err' for details).

5.2.2.6 Set and Get Parameter Values

5.2.2.6.1 Introduction

This section contains the methods used to set the keyword parameter values and to retrieve these values from the Keyword Data Module.

List of methods:

Reset the default values - resetDefaults
Reset the default values - resetDefaults
Set a parameter value - setValue
Get a parameter value - getValueString
Get an integer value - getIntegerValue
Get suffixed integer - getSuffixedIntegerValue
Get a double value - getDoubleValue
Get suffixed double - getSuffixedDoubleValue
Get a parameter value - getValue

5.2.2.6.2 Reset the default values - resetDefaults

This method sets the default value or values for either a selected parameter or for all the parameters in the dataset. (The current number of values for the special suffixed parameters will remain unchanged)

Method Definition:
public boolean resetDefaults (String name, int iset, int isubset)
Parameters List:
name
Parameter name (null/blank string means all parameters).
iset
Set number, 0=all sets - ignored for single value type parameters.
isubset
Subset number, 0=all subsets - ignored for single value or set type parameters.
Method Return:
true OK, false error: parameter not found or invalid set/subset number.

5.2.2.6.3 Reset the default values - resetDefaults

This method sets the default value or values for either a selected parameter or for all the parameters in the dataset.

Method Definition:
public boolean resetDefaults (String name, int iset, int isubset, boolean reset_var)
Parameters List:
name
Parameter name (null/blank string means all parameters).
iset
Set number, 0=all sets - ignored for single value type parameters.
isubset
Subset number, 0=all subsets - ignored for single value or set type parameters.
reset_var
If true set current number of values back to 1 for integer or double parameters which may have a variable number of values (suffixed parameters). If false, leave this number unchanged - the default behaviour if the method is called without this parameter.
Method Return:
true OK, false error: parameter not found or invalid set/subset number.

5.2.2.6.4 Set a parameter value - setValue

This method is used to set a KDM parameter value for any of the available parameter types. The full keyword string for the parameter must be given. The values may be passed as a string or, in the case of integer or double values, in a data item of the corresponding data type. A value may be set for a single set/subset or globally for sets/subsets where relevant and where desired. When double values are input as strings, the number of decimal places used will be preserved for future printing of the parameter value; when input via a double variable, the default format for that parameter as defined via defineDoubleParameter(..) will be used when the parameter value is printed.

Method Definition:
public boolean setValue (String name, int iset, int isubset, String valstr, int[] ival, double[] dval, int iopt, JdlError err)
Parameters List:
name
The full parameter (keyword) name (For the special case of a suffixed keyword, the input will be treated as for a single value parameter if the suffix is given; if the keyword is unsuffixed, then values will be input as described for 'iopt' below).
iset
Set number, 0=all sets - ignored for single value type parameters.
isubset
Subset number, 0=all subsets - ignored for single value or set type parameters.
valstr
The parameter value (or values) as a string - ignored if iopt=1.
ival
Integer values for an integer parameter - used if iopt=1 (nvals values as defined via the defineIntegerParameter(..) method).
dval
Double values for a double parameter - used if iopt=1 (nvals values as defined via the defineDoubleParameter(..) method).
iopt
Flag indicating value input option:
= 0, use the value string (for a double value the number of decimal places for printing the value will be determined from this string)
> 0, Use ival if a integer parameter and dval for a double parameter value (invalid for a String parameter). For a variable array or suffixed integer/double parameter, iopt defines the number of values to be input from the ival and/or dval arrays. For double values the number of decimal places for printing the values will be set to use the pre-defined default.
< 0, Use ival if a integer parameter and dval for a double parameter value (invalid for a String parameter). For a variable array or suffixed integer/double parameter, -iopt defines the number of values to be input from the ival and/or dval arrays. For double values the number of decimal places for printing the values will be left at its current value.
err
Error return object. If an error was found err.err will be returned as true. An error message will be returned and err.flag will be set as follows:
= -100, No keyword parameters defined
= -1, Invalid set number
= -2, Invalid subset number
= -3, Invalid parameter name
= -4, Parameter may not be suffixed
= -5, Parameter suffix out of range
= 1, Syntax error
= 2, Out of range value (or invalid String)
Method Return:
Returns true if OK, otherwise false (details in JdlError object).

5.2.2.6.5 Get a parameter value - getValueString

This method returns the current value of a requested parameter as a String.

Method Definition:
public String getValueString (String name, int iset, int isubset, JdlInt j_stat, JdlInt j_typ, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>0) - ignored for single value type parameters.
isubset
The subset number (>0) - ignored for single value or set type parameters.
j_stat
Returns the parameter value status:
= 0, default
= 1, set explicitly
= 2, set globally
j_typ
Returns the parameter type:
= 1, integer (string also returned)
= 2, float (string also returned)
= 3, string (single token)
= 4, string (multiple tokens)
= 5, variable array
err
JdlError object to return error codes - see getValue(..) method for details.
Method Return:
Returns the value as a string (null if there was an error - see JdlError object for details).

5.2.2.6.6 Get an integer value - getIntegerValue

This method returns the value of an 'integer' parameter.

Method Definition:
public int getIntegerValue(String name, int iset, int isubset, JdlInt j_stat, JdlInt j_typ, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>0) - ignored for single value type parameters.
isubset
The subset number (>0) - ignored for single value or set type parameters.
j_stat
Returns the parameter value status:
= 0, default
= 1, set explicitly
= 2, set globally
j_typ
Returns the parameter type:
= 1, integer (string also returned)
= 2, double (string also returned)
= 3, string (single token)
= 4, string (multiple tokens)
= 5, variable array
err
JdlError object to return error codes - see getValue(..) method for details. (Also flag = -100 if not an integer parameter)
Method Return:
The value of the integer parameter (0 if invalid parameter or incorrect type of parameter - see the JdlError object for details).
(If used with an integer parameter with more than one value, only the first value will be returned. For a suffixed parameter the value will be returned as normal if the keyword has the suffix appended, otherwise the first value will be returned)

5.2.2.6.7 Get suffixed integer - getSuffixedIntegerValue

This method returns the value of a 'suffixed integer' parameter.

Method Definition:
public int getSuffixedIntegerValue(String name, int iset, int isubset, int suffix, JdlInt j_stat, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>0) - ignored for single value type parameters.
isubset
The subset number (>0) - ignored for single value or set type parameters.
suffix
The required suffix number (>0)
j_stat
Returns the parameter value status:
= 0, default
= 1, set explicitly
= 2, set globally
err
JdlError object to return error codes - see getValue(..) method for details. (Also flag = -100 if invalid suffix or not a suffixed integer parameter)
Method Return:
The value of the suffixed integer parameter (0 if invalid parameter or incorrect type of parameter - see the JdlError object for details).

5.2.2.6.8 Get a double value - getDoubleValue

This method returns the value of a 'double' parameter.

Method Definition:
public double getDoubleValue(String name, int iset, int isubset, JdlInt j_stat, JdlInt j_typ, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>0) - ignored for single value type parameters.
isubset
The subset number (>0) - ignored for single value or set type parameters.
j_stat
Returns the parameter value status:
= 0, default
= 1, set explicitly
= 2, set globally
j_typ
Returns the parameter type:
= 1, integer (string also returned)
= 2, float (string also returned)
= 3, string (single token)
= 4, string (multiple tokens)
= 5, variable array
err
JdlError object to return error codes - see getValue(..) method for details.
Method Return:
The value of the double parameter (0.0 if invalid parameter or incorrect type of parameter - see the JdlError object for details).
(If used with a double parameter with more than one value, only the first value will be returned. For a suffixed parameter the value will be returned as normal if the keyword has the suffix appended, otherwise the first value will be returned)

5.2.2.6.9 Get suffixed double - getSuffixedDoubleValue

This method returns the value of a 'suffixed double' parameter.

Method Definition:
public double getSuffixedDoubleValue(String name, int iset, int isubset, int suffix, JdlInt j_stat, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>0) - ignored for single value type parameters.
isubset
The subset number (>0) - ignored for single value or set type parameters.
suffix
The required suffix number (>0)
j_stat
Returns the parameter value status:
= 0, default
= 1, set explicitly
= 2, set globally
err
JdlError object to return error codes - see getValue(..) method for details. (Also flag = -100 if invalid suffix or not a suffixed double parameter)
Method Return:
The value of the suffixed double parameter (0.0 if invalid parameter or incorrect type of parameter - see the JdlError object for details).

5.2.2.6.10 Get a parameter value - getValue

General method to return a parameter value.

Method Definition:
public String getValue (String name, int iset, int isubset, double[] dval, int[] nd, int[] ival, JdlInt j_num_inp, JdlInt j_stat, JdlInt j_typ, JdlError err)
Parameters List:
name
The full parameter name.
iset
The set number (>0) - ignored for single value type parameters.
isubset
The subset number (>0) - ignored for single value or set type parameters.
dval
Returns 'nvals' double values as defined in the defineDoubleParameter(..) method or defineVarrParameter(..) method (Selected elements in the latter case).
nd
Returned no. of decimal places flags for a double type parameter (-ve for E format) (nvals values as defined via defineDoubleParameter(..)) or, in selected elements, for a variable length array parameter (see also j_num_inp).
ival
Returns 'nvals' integer values as defined in the defineIntegerParameter(..) method or defineVarrParameter(..) method (Selected elements in the latter case).
j_num_inp
Returns the number of values presently stored for a variable length array parameter (otherwise 0). For each array element from 0 to j_num_inp-1, a value will either be returned in either ival or dbl as defined when the parameter was set up.
j_stat
Returns the parameter value status:
= 0, default
= 1, set explicitly
= 2, set globally
j_typ
Returns the parameter type:
= 1, integer (string also returned)
= 2, float (string also returned)
= 3, string (single token)
= 4, string (multiple tokens)
= 5, variable array
err
JdlError object to return error codes etc. If an error was detected, ther err.err will be set to true, an error message will be returned and err.flag will be set as follows:
= -1, Parameter not found
= -2, Parameter may not be suffixed = -3, Parameter suffix out of current range = 1, Invalid set/subset number
Method Return:
Returns the value as a string (null if there was an error see JdlError object for details).

5.2.2.7 Read and Parse KDM Data

5.2.2.7.1 Introduction

This set of methods is used to read KDM data from an input file and to parse strings containing keyworded data.

List of Methods:

Read logical line - kdmReadLine
Read and Parse KDM String - kdmReadString
Parse a data line - parseKDMLine
Decode set/subset numbers - parseKDMItem
Check a parsed parameter - checkParsedParameter
Get data reference - getDataReference
Get data reference - getDataReference

5.2.2.7.2 Read logical line - kdmReadLine

Read the next logical line from a KDM parameters/control file. This method 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. If the character '@' is not followed by a file name is found, then all indirection is cancelled and the next line is read from the main input stream.

Method Definition:
public String kdmReadLine (BufferedReader bsr_in, JdlInt indirect, JdlError err) throws IOException
Parameters List:
bsr_in
BufferedReader for the KDM data file being read (top level).
indirect
Note: value may be modified by the method. It gives the current indirection level. The field 'indirect.value' MUST be set to 0 on the first call when reading a file and subsequently must be given as the previously returned value. The user should ensure that the program repeats calls to the method until 'err.flag' is returned as -1 (end of file) or until 'indirect.value' is returned as 0 (otherwise files will be left open).
err
Error object returning error data. If an error is found 'err.err' will be set to true. The flag 'err.flag will be set as follows:
= 0, OK
= -1, End of main file
= 1, Error opening an indirect file
Method Return:
The next logical line from the file; null if the end of the reading is reached (err.err = false & err.flag = -1) or an error was found (err.err = true and err.flag set as noted above).

5.2.2.7.3 Read and Parse KDM String - kdmReadString

This method is similar to 'kdmReadLine' 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 data file.

Method Definition:
public String kdmReadString (String line_in, JdlInt indirect, JdlInt iflag, JdlError err) throws IOException
Parameters List:
line_in
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.
indirect
(I/O) Note: value may be modified by the method. It gives the current indirection level. The field 'indirect.value' MUST be set to 0 on the first call when reading a file and subsequently must be given as the previously returned value. The user should ensure that the program repeats calls to the method until 'err.flag' is returned as -1 (end of file) or 'indirect.value' is returned as 0 (otherwise files will be left open).
iflag
Note: value will be set by the method. Return value 'iflag.value':
= 0, if it is the first call to the method and the string does not contain an indirect file specification. The input line will be returned by the method
= 1, Line read from indirect file
= -1, End of indirect data was reached
err
Error object returning error data. If an error is found 'err.err' will be set to true. The flag 'err.flag will be set as follows:
= 0, OK
= 1, Error opening an indirect file
Method Return:
The next line read from an indirect file (or the original line if no indirection found (or blank if the input line contained '@' only) or null if an error was found.

5.2.2.7.4 Parse a data line - parseKDMLine

This method 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 Keyword Data Module object. If the line does not contain KDM data for the requesting object, 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 object 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. A user supplied object may make an additional check on each KDM parameter and disable its update if desired.

Method Definition:
public int parseKDMLine (String line, JdlKDMUpdateChecker chk_upd, JdlError err)
Parameters List:
line
String containing line to be parsed (Assumes comments & continuations already removed).
chk_upd
A JdlKDMUpdateChecker object to make additional check on KDM parameters to restrict updates (or possibly return other information to the calling program about the parameters). May be null if not required.
err
Error flag with flag as for return below + error message.
Method Return:
Return flag as follows:
= 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)

5.2.2.7.5 Decode set/subset numbers - parseKDMItem

This method is used by the higher level parsing routine parseKDMLine(..) 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.

Method Definition:
public static String parseKDMItem (String str, JdlInt iset, JdlInt isubset, JdlInt iss, JdlError err)
Parameters List:
str
String containing the keyword string to be examined i.e. parameter name + any set/subset specifications.
iset
Returns the set specification if present in 'iset.value'.
isubset
Returns the subset specification if present in 'isubset.value'.
iss
Returns a flag in 'iss.value':
= 0, keyword only present
= 1, keyword + set specification present
= 2, keyword + subset specification present
err
Returns error details 'err.err' = true error, = false OK. The flag 'err.flag' returns:
= 0, OK
= 1, blank string
= 2, junk at end of string
= -3, syntax error in set/subset specification
Method Return:
Returns the keyword name. Null if a blank string was found or if there was a syntax error in the set/subset specification error see 'err'. If there is junk at the end of the string, the returned values will be OK but the return values in 'err' will indicate an error.

5.2.2.7.6 Check a parsed parameter - checkParsedParameter

Check from a parsed parameter keyword string whether the parameter is present in the KDM module and, if so, return details of the parameter type. The keyword name and any set/subset specifications must be previously parsed from the keyword string (e.g. determined using parseKDMItem(..) ). Parameter details are returned in a JdlKDMParType object.

Method Definition:
public boolean checkParsedParameter(String keyword, int iset, int isubset, int iss, JdlKDMParType partyp, JdlError err)
Parameters List:
keyword
The input parameter name (or alias name). This need only have the minimum number of characters required for the parameter name in question.
iset
The set number from the parsed parameter keyword string.
isubset
The subset number from the parsed parameter keyword string.
iss
A flag:
= 0, keyword only present
= 1, keyword + set specification present
= 2, keyword + subset specification present
partyp
A JdlKDMParType object in which the parameter details will be returned if it is found.
err
Returns error details 'err.err' = true error, = false OK. The flag 'err.flag' returns:
= 0, OK
= 1, Parameter not found (or no keywords yet defined)
= -1, Set number outside valid range or not a set based parameter
= -2, Subset number outside valid range or not a subset based parameter
Method Return:
Returns true if the parameter found & OK, otherwise returns false - see 'err' for details.

5.2.2.7.7 Get data reference - getDataReference

This method enables a reference to be returned for the actual object which holds the data for the parameter. It is not intended for general use and it cannot be guaranteed that the data storage details will remain fixed.

Method Definition:
public KeyPar getDataReference(String name)
Parameters List:
name
The full parameter name (unsuffixed).
Method Return:
A reference to the stored data object (which will be a sub-class) of the returned KeyPar object (null if parameter not found).

5.2.2.7.8 Get data reference - getDataReference

This method enables a reference to be returned for the actual object which holds the data for the parameter. It is not intended for general use and it cannot be guaranteed that the data storage details will remain fixed.

Method Definition:
public KeyPar getDataReference(int ipar)
Parameters List:
ipar
The parameter number.
Method Return:
A reference to the stored data object (which will be a sub-class) of the returned KeyPar object (null if parameter not found).

5.2.2.8 Output KDM data

5.2.2.8.1 Introduction

This section comprises methods to output a complete KDM data file or data from selected or individual KDM parameters.

List of Methods:

Write a KDM file - writeKDM
Write a KDM file - writeKDM
Write a KDM file - writeKDM
Form an output string - outputString

5.2.2.8.2 Write a KDM file - writeKDM

This method enables a complete KDM file to be written. In this version of the method a BufferedWriter object for writing the output. 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.

Method Definition:
public boolean writeKDM (BufferedWriter bwr, int out_type, int ichanged, int width, JdlError err)
Parameters List:
bwr
A buffered writer for the output.
out_type
Type of output flag:
= 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 parameters and individual values given explicitly for all set/subset parameters
ichanged
Changed parameters flag:
= 0, Output all parameters
= 1-16, Write changed parameter values since last reset of the flag for channel 'ichanged'
width
The maximum number of columns for the output.
err
Returns error data when the method return is false; If an error was found 'err.err' will be set to true, a message will be returned and 'err.flag' will be set as follows:
= 1, Invalid value for 'ichanged' flag
= 2, Invalid value of 'out_type' flag
= -10, File writing error
Method Return:
True if OK, false if error found - see 'err'

5.2.2.8.3 Write a KDM file - writeKDM

This method enables a complete KDM file to be written. In this version of the method a JdlStringWriter implementing object is passed to the method to perform the actual output. 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.

Method Definition:
public boolean writeKDM (int out_type, int ichanged, JdlStringWriter s_write, int width, JdlError err)
Parameters List:
out_type
Type of output flag:
= 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 parameters and individual values given explicitly for all set/subset parameters
ichanged
Changed parameters flag:
= 0, Output all parameters
= 1-16, Write changed parameter values since last reset of the flag for channel 'ichanged'
s_write
A JdlStringWriter implementing object to output the data strings.
width
The maximum number of columns for the output (will be passed to 's_write').
err
Returns error data when the method return is false; If an error was found 'err.err' will be set to true, a message will be returned and 'err.flag' will be set as follows:
= 1, Invalid value for 'ichanged' flag
= 2, Invalid value of 'out_type' flag
= -10, Error from output 's_write' object
Method Return:
True if OK, false if error found - see 'err'

5.2.2.8.4 Write a KDM file - writeKDM

This method enables a complete KDM file to be written. In this version of the method a JdlStringWriter implementing object is passed to the method to perform the actual output. 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.

Method Definition:
public boolean writeKDM (int out_type, int ichanged, int ns, int[] nss, JdlStringWriter s_write, int width, JdlError err)
Parameters List:
out_type
Type of output flag:
= 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 parameters and individual values given explicitly for all set/subset parameters
ichanged
Changed parameters flag:
= 0, Output all parameters
= 1-16, Write changed parameter values since last reset of the flag for channel 'ichanged'
ns
Number of sets:
> 0, The number of sets (for printing and to update the currently set value if different); The numbers of subsets will be updated from the values in the nss array
= 0, Use currently stored values for the number of sets and numbers of subsets
= -1, Update the number of sets and numbers of subsets via the JdlKDMPrintOptions object if defined or leave unchanged if this object has not been defined (see setPrintChecker(..) method) defined;
nss
An array with the number of subsets for each set for the first 'ns' sets (only used if 'ns' > 0).
s_write
A JdlStringWriter implementing object to output the data strings.
width
The maximum number of columns for the output (will be passed to 's_write').
err
Returns error data when the method return is false; If an error was found 'err.err' will be set to true, a message will be returned and 'err.flag' will be set as follows:
= 1, Invalid value for 'ichanged' flag
= 2, Invalid value of 'out_type' flag
= -10, Error from output 's_write' object
Method Return:
True if OK, false if error found - see 'err'

5.2.2.8.5 Form an output string - outputString

Get an output string for a KDM parameter forming a string with a KDM keyword and its value(s). It has an option to check for outputting only changed values for a requested change channel number. The method may also suppress default values if required and indicates whether only default values are present for the parameter in question. For set/subset type parameters there is an option to reduce the amount of output where possible e.g. by combining values if they are all the same for a set etc. A user supplied object implementing the JdlStringWriter Interface may be used to do the actual output if required.

Method Definition:
public String outputString(String name, int ichanged, int ireduce, JdlStringWriter s_write, int width, JdlError err)
Parameters List:
name
The parameter name.
ichanged
Parameter selection flag:
= 0, print parameter anyway
1-16, (Channel number ) Only create an output parameter value string if the parameter changed flag is set for that channel for the parameter.
ireduce
Flag to reduce the amount of output:
= 0, output all values for all sets & subsets
= 1, reduce output where feasible by recombining values if all the same for a set etc.
= 2, as for 1 but suppress default values for non 'standard print' parameters = 3, as for 1 but suppress default values for all parameters (ignored if (ichanged==1))
s_write
A JdlStringWriter implementing object to output the string if required (may be null if not required).
width
The maximum number of columns for the output (will be passed to 's_write' if that was defined).
err
Returns error data when output string is null; If an error was found 'err.err' will be set to true, a message will be returned and 'err.flag' will be set as follows:
= 1, Invalid value for 'ichanged' flag
= 2, Parameter not found
= 3, No values defined with this suffix for a suffixed parameter
Method Return:
The output string for printing (null if an error was found - see 'err' for details).

5.2.2.9 Monitor Parameter Changes

5.2.2.9.1 Introduction

Methods are available to assist with the monitoring of changes to KDM parameter values during the running of a program. Sixteen channels may be used to monitor changes to any parameter values since the parameter changed flag for a channel was last reset. These flags may be used by a program to determine, for example, if some recalculation is required because a parameter value has been changed. One channel might be used, for example, to monitor whether any parameter value has been changed throughout the running of the program so that an updated data file may be output at the end. The outputString(..) method may be used to output such changed values when required.

List of Methods:

Reset 'changed' flags - changedReset
Test for any 'changed' - anyChanged
Test for 'changed' value - valueChanged

5.2.2.9.2 Reset 'changed' flags - changedReset

Reset the parameter changed flags for a requested channel or for all channels.

Method Definition:
public void changedReset(int ichan)
Parameters List:
ichan
Channel number (1-16), 0 = all channels.

5.2.2.9.3 Test for any 'changed' - anyChanged

Test whether any parameter value has been changed for a requested channel or for all channels.

Method Definition:
public boolean anyChanged(int ichan)
Parameters List:
ichan
Channel number for test (1-16), 0 = all channels.
Method Return:
True if a parameter value was changed, otherwise false.

5.2.2.9.4 Test for 'changed' value - valueChanged

Test whether a parameter value has been changed for a requested channel.

Method Definition:
public boolean valueChanged(String name, int ichan, int iset, int isubset, int ipos)
Parameters List:
name
The parameter name.
ichan
Channel number for test (1-16).
iset
Set number (from 1 up) - ignored for dataset type parameter.
isubset
Subset number (from 1 up) - ignored for dataset type or set type parameter.
ipos
Position number (from 1 up) for an integer or double parameter with more than one value or range number for a suffixed integer or double parameter or 0 for any position/range changed.
Method Return:
True if a parameter value changed, otherwise false.

5.2.2.10 Specialist Methods

5.2.2.10.1 Introduction

This section contains a series of methods which may be useful in certain situations.

List of Methods:

Number of parameters - numberOfParameters
Get parameter name - parameterName
Return alias name - aliasName
Get parameter number - getParameterNumber
Set an alias name - setAliasName
Set check error message - setCheckMessage
Set the print name - setPrintName
Set print suffixes - setPrintSuffixes
Set print checker - setPrintChecker
Set decimal places - setDecimalPlacesVarr
Set standard parameter - setStandardParameterFlag
Set auto-count mode - setAutoCount
Get suffix limit - getSuffixLimit
Get number of values - getMaximumNvals
Get number of values - getMaximumNvalsAll
Split suffixed keyword - splitKeyword

5.2.2.10.2 Number of parameters - numberOfParameters

This method returns the number of keyword parameters defined.

Method Definition:
public int numberOfParameters()
Parameters List:
none
Method Return:
The number of keyword parameters defined.

5.2.2.10.3 Get parameter name - parameterName

This method returns the name of a keyword parameter from its position in the defined parameters list.

Method Definition:
public String parameterName(int ipar)
Parameters List:
ipar
The position in the list from 1 to numberOfParameters().
Method Return:
The full parameter name in upper case (null if not found) i.e. invalid value for idx.

5.2.2.10.4 Return alias name - aliasName

This method returns the alias name of a keyword parameter from its position in the defined parameters list.

Method Definition:
public String aliasName(int ipar)
Parameters List:
idx
The position in the list from 1 to numberOfParameters().
Method Return:
The full alias name in upper case (null if not found) i.e. invalid value for idx.

5.2.2.10.5 Get parameter number - getParameterNumber

This method returns the number within the parameter list of a requested parameter (from 1 to numberOfParameters()).

Method Definition:
public int getParameterNumber(String name, boolean check_alias)
Parameters List:
String
The parameter name (un-suffixed).
check_alias
Check against alias name as well as main parameter name =true yes, =false no.
Method Return:
The parameter number (index) (from 1 to numberOfParameters() or 0 if the parameter name not found.

5.2.2.10.6 Set an alias name - setAliasName

This method enables an alternative or alias name to be used for a keyword. It will be recognised when a keyworded data set is input. By default, the name used for the keyword when it is output/printed will be the original name but this may be changed using the setPrintName(..) method.

Method Definition:
public boolean setAliasName(String name, String alias, int minlen)
Parameters List:
name
The parameter name.
alias
The full alias name in upper case.
minlen
Minimum length of alias name for a valid match.
Method Return:
true OK, false error: parameter not found or alias name is non-unique or length < minlen.

5.2.2.10.7 Set check error message - setCheckMessage

This method may be called from an object implementing the JdlKDMDataChecker interface to set the error message when an invalid value is found. This message will be returned via the setValue(..) method if the data checker returns an error.

Method Definition:
public void setCheckMessage(String ermsg)
Parameters List:
none

5.2.2.10.8 Set the print name - setPrintName

This method determines which name is to be used for any output/printing if an alias has been defined for the keyword. No action will be taken if the parameter does not have an alias defined.

Method Definition:
public boolean setPrintName(String name, boolean use_alias)
Parameters List:
name
The parameter name (or alias name).
use_alias
If true use the alias name (or choose option via a checker object - see setPrintChecker(..) method), =false (the default case) use the normal parameter name.
Method Return:
true OK, false error: parameter not found or no alias defined.

5.2.2.10.9 Set print suffixes - setPrintSuffixes

This method determines which names are to be used for any output/printing of a suffixed parameter i.e. either the unsuffixed or suffixed options. If the parameter is not a suffixed parameter, no action will be taken.

Method Definition:
public boolean setPrintSuffixes(String name, boolean use_suffixes)
Parameters List:
name
The parameter name (or alias name).
use_suffixes
If true use the suffixed names (or choose option via a checker object - see setPrintChecker(..) method), =false (the default case) use the un-suffixed name.
Method Return:
true OK, false error: parameter not found or not a suffixed parameter.

5.2.2.10.10 Set print checker - setPrintChecker

This method sets an object implementing the JdlKDMPrintOptions interface to check the requirements for using an alias or suffixed names when a parameter is printed or for updating the numbers of sets/subsets at print time.

Method Definition:
public void setPrintChecker (JdlKDMPrintOptions checker)
Parameters List:
checker
This may be used to invoke a method to check whether or not the alias name is to be used in printing (the check might be based for example on the values of other parameters). It also has a method to update the number of sets and the numbers of subsets parameters; this may be called by the writeKDM(..) method. May be null if not required (or to remove).
Method Return:
true OK, false error: parameter not found or no alias defined.

5.2.2.10.11 Set decimal places - setDecimalPlacesVarr

Set a new number of decimal places flag for a variable array parameter.

Method Definition:
public boolean setDecimalPlacesVarr(String name, int itm, int nd_new)
Parameters List:
name
The parameter name.
itm
Variable array item no. (from 1 to the maximum defined for the parameter).
nd_new
The new no. of decimal places for printing the value of a double data value recalculated by the program - ignored for an integer value.
Method Return:
True if OK, false if parameter or item etc. not found.

5.2.2.10.12 Set standard parameter - setStandardParameterFlag

This method resets the 'standard parameter' flag for a parameter.

Method Definition:
public boolean setStandardParameterFlag(String name, int istd)
Parameters List:
name
The parameter name.
istd
Flag selecting the required option:
= 1, Set as a standard parameter
= 0, Set as not a standard parameter
= -1, Reset default status
Method Return:
True if OK, false if parameter not found.

5.2.2.10.13 Set auto-count mode - setAutoCount

This method determines whether or not the number of sets and numbers of subsets parameters are to be automatically updated when values are set (via setValue(..)) with a specified set and/or subset number.

Method Definition:
public void setAutoCount(boolean auto)
Parameters List:
auto
If true set the auto-count mode (the default mode) or false to turn it off.

5.2.2.10.14 Get suffix limit - getSuffixLimit

This method returns the suffix limit for a suffixed parameter.

Method Definition:
public int getSuffixLimit (String name, int iset, int isubset)
Parameters List:
name
The parameter name (without suffix).
iset
The set number, if 0 the maximum over all sets will be returned. Ignored if not a set or subset based parameter.
isubset
The subset number, if 0 the maximum over all subsets will be returned. Ignored if not a subset based parameter.
Method Return:
The required suffix limit (0 if not a suffixed parameter).

5.2.2.10.15 Get number of values - getMaximumNvals

Gets the maximum number of values associated with an integer or double parameter defined using the defineIntegerParameter(..) and defineDoubleParameter(..) methods.

Method Definition:
public int getMaximumNvals()
Parameters List:
none
Method Return:
Returns the number of values.

5.2.2.10.16 Get number of values - getMaximumNvalsAll

Get the maximum number of values associated with any integer or double or variable array parameter defined using the defineIntegerParameter(..), defineDoubleParameter(..) or defineVarrParameter(..) methods.

Method Definition:
public int getMaximumNvalsAll()
Parameters List:
none
Method Return:
Returns the number of values.

5.2.2.10.17 Split suffixed keyword - splitKeyword

This method splits a suffixed keyword into its component parts.

Method Definition:
public static String splitKeyword (String keyword, JdlInt suffix)
Parameters List:
keyword
The suffixed keyword string.
suffix
Returns the suffix in suffix.value (0 if no suffix present).
Method Return:
The keyword with the suffix removed.

⇑ Up 2   ⇑ Up 1   ⇑ Top of this