KEYWORD DATA MODULE (KDM) ========================= INTRODUCTION The Keyword Data Module (KDM) routines enable a set of keyworded parameters to be defined. Parameters may de defined for individual sets or subsets within the overall data set. In general, a KDM set of parameters may have some parameters which apply too 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. An example of a dataset with all three classes of parameter would be analogous to that used in the Laue Data Module where a set would refer to a pack of images and a subset parameter would refer to each individual image within the pack. Parameters may be of type integer, real or character 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. The following sets of routines are available: Initialise a KDM Dataset Get Details from a KDM Set Define KDM Parameters KDM Name Aliases Set KDM Parameter Values Get KDM Parameter Values Output Keyword and Value Strings Monitor KDM Parameter Changes Routines for User Supplied Functions Fortran Character String Parameters 'C' Routines to Read KDM Data 'C' Routines to Parse 'KDM' Keyworded Data 'C' Routine to Write KDM Data INITIALISE A KDM DATASET Introduction A KDM dataset must be initialised before the keyword parameters are defined. The following routines are available: Initialise a KDM keyword set - kdm_init Initialise a KDM keyword set - kdm_init The initialisation routine kdm_init (kdmf_init) initialises a new keyword data module set of keyword parameters. An index is returned to be used with all calls for that parameter set. Fortran call: CALL KDMF_INIT (MAXSETS, MAXSUBSETS, KDM(NUMS_NAM), LENS, + KDMSTR(NUMSS_NAM), LENSS, + KDMSTR(SNAM), LENSNAM, + KDMSTR(SSNAM), LENSSNAM, KDX, IERR) Parameters: MAXSETS i (R) Maximum no. of sets for set specific parameters MAXSUBSETS i (R) Maximum no. of subsets for subset specific parameters NUMS_NAM c (R) Name of the keyword defining the current number of sets being used; if used, this must be defined as an nteger parameter (type=dataset) using the KDMF_DEFINE_INT routine. ** Pass address index using the KDMSTR function ** LENS i (R) Length of NUMS_NAM string NUMSS_NAM c (R) Name of the keyword defining the current number of subsets being used for each set; if used, this must be defined as an integer parameter (type=set dependent) using the KDMF_DEFINE_INT routine. ** Pass address index using the KDMSTR function ** LENSS i (R) Length of NUMSS_NAM string SNAM c (R) String for 'set' in message e.g. 'set or 'pack' ** Pass address index using the KDMSTR function ** LENSNAM i (R) Length of SNAM string SSNAM c (R) String for 'subset' in message e.ge. 'subset', or 'plate' ** Pass address index using the KDMSTR function ** LENSSNAM i (R) Length of SSNAM string KDX i (W) Index to be used in subsequent calls to kdm routines for this keyword set IERR i (W) Error return code from kdm_init call Note: The current number of sets and numbers of subsets/set parameters may be used internally by the kdm_output (kdmf_output) routine. If this option is to be used, both parameters must be set up as described. If they are not required, the the current number of sets and numbers of subsets/set must be explicitly passed to the kdm_output (kdmf_output) routine; blank names may be passed in this latter case. Also, if internal names are being used, then a blank set name implies 1 set and a blank subset name implies one subset/set; no parameters are set up via define routines for such blank names; an error will be returned for any other set or subset names if the corresponding parameters are not defined. 'C' call: int kdm_init (int maxnum_sets, int maxnum_subsets, char * nums_nam, int lens, char * numss_nam, int lenss, char * snam, int lensnam, char * ssnam, int lenssnam, int * kdx) Parameters: int maxnum_sets; Maximum no. of sets for set specific parameters (R) int maxnum_subsets; Maximum no. of subsets for subset specific parameters (R) char * nums_nam; Name of the keyword defining the current number of sets being used; this must be defined as an integer parameter (type=dataset) using the kdm_define_int routine. (R) int lens; Length of nums_nam string; may be 0 if nums_nam is null terminated (R) char * numss_nam; Name of the keyword defining the current number of subsets being used for each set; this must be defined as an integer parameter (type=set dependent) using the kdm_define_int routine. (R) int lenss; Length of numss_nam string; may be 0 if numss_nam is null terminated (R) char * snam String for 'set' in message e.g. 'set or 'pack' (R) int lensnam; Length of snam string; may be 0 if snam is null terminated (R) char * ssnam String for 'subset' in message e.g. 'subset' or 'plate' (R) int lenssnam; Length of ssnam string; may be 0 if ssnam is null terminated (R) int *kdx; Index to be used in subsequent calls to kdm routines for this keyword set (W) Note: The current number of sets and numbers of subsets/set parameters may be used internally by the kdm_output (kdmf_output) routine. If this option is to be used, both parameters must be set up as described. If they are not required, the the current number of sets and numbers of subsets/set must be explicitly passed to the kdm_output (kdmf_output) routine; blank names may be passed in this latter case. Return: Error flag =0 no error; =1 invalid parameter maxnum_sets<1 or maxnum_subsets<1 or (maxnum_subsets>0 and maxnum_sets<=0) =-1 unable to allocate memory for new keyword set GET DETAILS FROM A KDM SET Introduction Routines are available to return the number of parameters defined for a KDM data set and the keyword names of the parameters. The following routines are available: Get number of parameters - kdm_numpars Get parameter name - kdm_parname Check a parsed parameter keyword string - kdm_checkpar Get number of parameters - kdm_numpars The routine kdm_numpars (kdmf_numpars) returns the number of parameters currently defined for a KDM keyword data set. Fortran call: CALL KDMF_NUMPARS (KDX, NUMP, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT NUMP i (W) No. of parameters in the KDM data set IERR i (W) Error return code from kdm_numpars call 'C' call: int kdm_numpars (int kdx, int * nump) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) int * nump; Returns the no. of parameters in the KDM data set (W) Return: Error flag =0 no error; =1 KDM dataset not set up Get parameter name - kdm_parname The routine kdm_parname (kdmf_parname) returns the name of a KDM keyword parameter for a requested parameter number. Fortran call: CALL KDMF_PARNAME (KDX, IPAR, KDMSTR(NAME), MAXN, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT IPAR i (R) The parameter number from 1 to the NUMP value returned by KDMF_NUMPARS NAME c (W) Returns the full keyword parameter name in upper case ** Pass address index using the KDMSTR function ** MAXN i (R) Maximum length allowed for returned name IERR i (W) Error return code from kdm_parname call 'C' call: int kdm_parname (int kdx, int ipar, char * name, int maxn) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * name; Returns full parameter name in upper case (W) int maxn; if >0 Maximum length of returned name string allowed (excluding terminating null - name must be at least maxn + 1 characters in length) if <0 abs(maxn) characters will be returned padded with blanks if needed (for 'fortran' use) (R) Return: Error flag =0 no error; =1 KDM dataset not set up =2 Invalid parameter number Check a parsed parameter keyword string - kdm_checkpar The routine kdm_checkpar (kdmf_checkpar) is used to check for the presence of a parameter within a KDM data set. The keyword name and any set/subset specifications must be previously parsed from the keyword string. The input parameter name need only have the minimum number of characters defined for the parameter in question via the appropriate kdm_define_... (kdmf_define_...) call. The full parameter name is returned together with a flag indicating the parameter type. Fortran call: CALL KDMF_CHECKPAR (KDX, KDMSTR(KEYWORD), LENK, ISET, ISUBSET, + ISS, NAME, MAXN, ITYP, NVALS, IPAR, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name character string (at least minimum required characters in length) ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ISET i (R) Set number from parsed keyword string ISUBSET i (R) Subset number from parsed keyword string ISS i (R) Flag =0 keyword had no set/subset specification attached =1 keyword had set specification attached =2 keyword had subset specification attached NAME c (W) Returns the full keyword parameter name in upper case ** Pass address index using the KDMSTR function ** MAXN i (R) Maximum length allowed for returned name ITYP i (W) Returns parameter type flag = 1 integer = 2 set dependent integer parameter = 3 subset dependent integer parameter = 4 float = 5 set dependent float parameter = 6 subset dependent float parameter = 7 string (single token) = 8 set dependent string parameter (single token) = 9 subset dependent string parameter (single token) = 10 string (multiple token) = 11 set dependent string parameter (multiple token) = 12 subset dependent string parameter (multiple token) = 13 variable array parameter = 14 set dependent variable array parameter = 15 subset dependent variable array parameter NVALS i (W) No. of values associated with the keyword for integer or float type parameters or maximum for a variable length array of (mixed) int/real values. IPAR i (W) The number of the parameter in the keyword parameters list (from 1 upwards); 0 if not found IERR i (W) Error return from kdm_checkpar routine Note: Can pass ISET=0, ISUBSET=0 & ISS=0 to check keyword and return the KDM parameter type 'C' call: int kdm_checkpar (int kdx, char * keyword, int lenk, int iset, int isubset, int iss, char * name, int maxn, int * ityp, int *nvals, int * ipar) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string at least minimum no. of characters required (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int iset; Set number from parsed keyword string (R) int isubset; Subset number from parsed keyword string (R) int iss; Flag =0 keyword had no set/subset specification attached =1 keyword had set specification attached =2 keyword had subset specification attached (R) char * name; Returns full parameter name in upper case (W) int maxn; if >0 Maximum length of returned name string allowed (excluding terminating null - name must be at least maxn + 1 characters in length) if <0 abs(maxn) characters will be returned padded with blanks if needed (for 'fortran' use) (R) int * ityp; Returns parameter type flag = 1 integer = 2 set dependent integer parameter = 3 subset dependent integer parameter = 4 float = 5 set dependent float parameter = 6 subset dependent float parameter = 7 string (single token) = 8 set dependent string parameter (single token) = 9 subset dependent string parameter (single token) = 10 string (multiple token) = 11 set dependent string parameter (multiple token) = 12 subset dependent string parameter (multiple token) = 13 variable array parameter = 14 set dependent variable array parameter = 15 subset dependent variable array parameter (W) int * nvals; No. of values associated with the keyword for integer or float type parameters or maximum for a variable length array of (mixed) int/real values. (W) int * ipar; Returns the number of the parameter in the parameter list (from 1 upwards); 0 if not found (W) Note: Can pass iset=0, isubset=0 & iss=0 to check keyword and return the KDM parameter type Return: Error flag = 0 OK KDM parameter = 1 Not a KDM parameter of this keyword dataset =-1 Set specified when none allowed or out of valid range =-2 Subset specified when none allowed or out of valid range DEFINE KDM PARAMETERS Introduction Routines are available to define the keywords for various types of parameter including integer, real and character string. The following routines are available: Define an integer parameter keyword - kdm_define_int Define a float parameter keyword - kdm_define_float Define a string parameter keyword - kdm_define_str Define a variable array keyword - kdm_define_varr Define an integer parameter keyword - kdm_define_int The routine kdm_define_int (kdmf_define_int) is used to define a new integer value parameter keyword. The type of parameter value checking is defined which may be a standard type or done via a user supplied routine. Fortran call: CALL KDMF_DEFINE_INT (KDX, KDMSTR(NAME), LENN, MINL, ITYP, ISTD, + NVALS I_DEFLT, I_MIN, I_MAX, + ICHK, CHKFUN, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT NAME c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENN i (R) Length of name MINL i (R) Minimum length for keyword match ITYP i (R) Parameter type 1=dataset, 2=set, 3=subset specific ISTD i (R) Standard parameter for output (see KDMF_OUTPUT) = 1 yes, =0 no NVALS i (R) No. of values associated with the keyword - normally 1 I_DEFLT() i (R) Default parameter values (NVALS values) I_MIN i (R) Minimum allowed value (if ICHK==5) I_MAX i (R) Maximum allowed value (if ICHK==5) ICHK i (R) 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 function CHKFUN =7 0<= ival<= max_sets =8 0<= ival<= max_sub sets CHKFUN s (R) Check value function (used if ICHK==6) Call will be I = CHKFUN (IVAL) IVAL (R) Value to be checked RETURN 0 OK, 1 error Use KDMF_SET_CHKERR within CHKFUN to set error string IERR i (W) Error return status flag from the kdm_define_int call 'C' call: int kdm_define_int (int kdx, char * name, int lenn, int minl, int ityp, int std, int nvals, int * i_default, int i_min, int i_max, int chk_typ, int (*chk_func)()) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * name; Parameter name (full) (R) int lenn; Length of name string (may be 0 if null term) (R) int minl; Minimum length for keyword matching (R) int ityp; Parameter type 1=dataset, 2=set, 3=subset specific (R) int std Standard parameter for output (see kdm_output) = 1 yes, =0 no (R) int nvals; No. of values associated with the keyword - normally 1 (R) int *i_default; Default parameter values (nvals values) (R) int i_min; Minimum allowed value (if chk_typ==5) (R) int i_max; Maximum allowed value (if chk_typ==5) (R) int 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 function called with chk_func. Must return 0 if OK, 1 if error. =7 0<= ival<= max_sets =8 0<= ival<= max_sub sets (R) int (*chk_func)(); Check value function (used if chk_typ==6) call will be i = chk_func (ival); return 0 ok, 1 error int *ival (r) value to be checked Use kdm_set_chkerr within chk_func to set error string (R) Return: Error flag = 0 no error; =-1 memory allocation error =-2 a previous memory allocation error had occurred = 1 parameter name too long = 2 other invalid parameter passed to the routine = 3 'kdm' routines not initialised Define a float parameter keyword - kdm_define_float The routine kdm_define_float (kdmf_define_float) is used to define a new floating point value parameter keyword. The type of parameter value checking is defined which may be a standard type or done via a user supplied routine. Fortran call: CALL KDMF_DEFINE_FLOAT (KDX, KDMSTR(NAME), LENN, + MINL, ITYP, ISTD, NVALS, F_DEFLT, F_MIN, + F_MAX, ICHK, CHKFUN, ND, ND_DEFAULT, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT NAME c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENN i (R) Length of name MINL i (R) Minimum length for keyword match ITYP i (R) Parameter type 1=dataset, 2=set, 3=subset specific ISTD i (R) Standard parameter for output (see KDMF_OUTPUT) = 1 yes, =0 no NVALS i (R) No. of values associated with the keyword - normally 1 F_DEFLT() r (R) Default parameter values (NVALS values) F_MIN r (R) Minimum allowed value (if ICHK==5) F_MAX r (R) Maximum allowed value (if ICHK==5) ICHK i (R) Check value option =0 any float OK, =1 any >=0.0 =2 any >0.0 =3 any <=0.0 =4 any <0.0 =5 must be in range f_min to f_max =6 check using supplied function CHKFUN CHKFUN s (R) Check value function (used if ICHK==6) Call will be I = CHKFUN (FVAL) FVAL (R) Value to be checked RETURN 0 OK, 1 error Use KDMF_SET_CHKERR within CHKFUN to set error string ND i (R) No. of decimal places for printing value when it was recalculated by a program ND_DEFLT i (R) No. of decimal places for printing the default value IERR i (W) Error return status flag from the kdm_define_int call 'C' call: int kdm_define_float (int kdx, char * name, int lenn, int minl, int ityp, int std, int nvals, float *f_default, float f_min, float f_max, int chk_typ, int (*chk_func)(), int nd, int default_nd) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * name; Parameter name (full) (R) int lenn; Length of name string (may be 0 if null term) (R) int minl; Minimum length for keyword matching (R) int ityp; Parameter type 1=dataset, 2=set, 3=subset specific (R) int std Standard parameter for output (see kdm_output) = 1 yes, =0 no (R) int nvals; No. of values associated with the keyword - normally 1 (R) float *f_default; Default parameter values (num_vals values) (R) int f_min; Minimum allowed value (if chk_typ==5) (R) int f_max; Maximum allowed value (if chk_typ==5) (R) int chk_typ; Check value option =0 any float OK, =1 any >=0.0 =2 any >0.0 =3 any <=0.0 =4 any <0.0 =5 must be in range f_min to f_max =6 check using supplied function chk_func. int (*chk_func)(); Check value function (used if chk_typ==6) call will be i = chk_func (fval); return 0 ok, 1 error float *fval (r) value to be checked Use kdm_set_chkerr within chk_func to set error string (R) int nd; No. of decimal places for printing value when it was recalculated by a program (R) int default_nd; No. of decimal places for printing the default value (R) Return: Error flag = 0 no error; =-1 memory allocation error =-2 a previous memory allocation error had occurred = 1 parameter name or too long = 2 other invalid parameter passed to the routine = 3 'kdm' routines not initialised Define a string parameter keyword - kdm_define_str The routine kdm_define_str (kdmf_define_str) is used to define a new string value parameter keyword. The type of parameter value checking is defined which may be to check a standard list of parameter value strings or to use a user supplied checking routine. Fortran call: CALL KDMF_DEFINE_STR (KDX, KDMSTR(NAME), LENN, + MINL, ITYP, ISTD, MAXLEN, + KDMSTR(S_DEFLT), LEND, + KDMSTR(STRINGS), NUMS, LENS, ICHK, MATCH, + CHKFUN, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT NAME c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENN i (R) Length of name MINL i (R) Minimum length for keyword match ITYP i (R) Parameter type 1=dataset, 2=set, 3=subset specific for single token; 4=dataset, 5=set, 6=subset specific multiple token string ISTD i (R) Standard parameter for output (see KDMF_OUTPUT) = 1 yes, =0 no MAXLEN i (R) Maximum string length for parameter value S_DEFLT c (R) Default character string ** Pass address index using the KDMSTR function ** LEND i (R) Length of default string STRINGS() c (R) Array of character strings containing allowed values CHARACTER*LENS STRINGS(NUMS) ** Pass address index using the KDMSTR function ** NUMS i (R) No. of strings in STRINGS LENS i (R) Length of each character string element in the STRINGS array ICHK i (R) Check value option =0 any string OK =1 check using allowed strings =2 check using supplied function CHKFUN MATCH i (R) Minimum no. of characters to be matched if ICHK==1; if -MATCH given then only MATCH characters will be checked and remainder will be ignored; if MATCH==0 all characters will be checked CHKFUN s (R) Check value function (used if ICHK==2) Call will be I = CHKFUN (IDUM) IDUM (R) Dummy parameter RETURN 0 OK, 1 error Use KDMF_SET_CHKERR within CHKFUN to set error string To get the value of the string to be checked within the CHKFUN routine, use the function KDM_STRVAL CALL KDMF_STRVAL (KDMSTR(VALSTR), MAXL) VALSTR (W) Returns the value string ** Pass address index using the KDMSTR function ** MAXL (R) Maximum length allowed for the string (must be at least MAXLEN characters long) IERR i (W) Error return status flag from the kdm_define_int call 'C' call: int kdm_define_str (int kdx, char * name, int lenn, int minl, int ityp, int std, int maxlen, char * s_default, int lend, char ** strings, int nums, int lens, int chk_typ, int match, int (*chk_func)()) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * name; Parameter name (full) (R) int lenn; Length of name string (may be 0 if null term) (R) int minl; Minimum length for keyword matching (R) int ityp; Parameter type 1=dataset, 2=set, 3=subset specific for single token; 4=dataset, 5=set, 6=subset specific multiple token string (R) int std Standard parameter for output (see kdm_output) = 1 yes, =0 no (R) int maxlen; Maximum string length for parameter value (R) char * s_default; Default value string (R) int lend; Length of default string (may be 0 if null term) char ** strings; Value strings - this may either be an array of pointers to 'nums' null terminated character strings (lens==0) or a character string nums*lens in length with each value string occupying lens characters (left justified and padded to the right with blanks if needed. (R) (used if chk_typ==0) (R) int nums; The number of values in strings (R) int lens; Values strings length (0 = array of pointers to null terminated character strings (e.g. for 'C' programs) or the length of each value string (e.g. for Fortran programs). See also the previous item. (R) int chk_typ; Check value option =0 any string OK =1 check using allowed strings =2 check using supplied function chk_func (R) int 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 (R) int (*chk_func)(); Function to check value (if chk_typ==1) call will be i = chk_func (dum); int *idum (r) dummy value return 0 ok, 1 error Use kdm_set_chkerr within chk_func to set error string within chk_func, get the value of the parameter string to be checked using the function (void) kdm_strval (valstr, maxl) char * valstr (w) string into which value is to be returned (it will be null terminated) must be at least maxl+1 characters in length int maxl (r) maximum length for returned string (must be at least maxlen) (R) Return: Error flag = 0 no error; =-1 memory allocation error =-2 a previous memory allocation error had occurred = 1 parameter name too long = 2 other invalid parameter passed to the routine = 3 'kdm' routines not initialised Define a variable array keyword - kdm_define_varr The routine kdm_define_varr (kdmf_define_varr) is used to define a new parameter keyword which has a variable length array of integer/real values following it (up to some maximum specified number of words). There is either no value checking done or it is done via a user supplied routine. Fortran call: CALL KDMF_DEFINE_VARR (KDX, KDMSTR(NAME), LENN, + MINL, ITYP, ISTD, NVALS, NVALS_MIN, + I_DEFLT, F_DEFLT, IRTYP, ICHK, CHKFUN, + ND, ND_DEFAULT, NPR_DFLT, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT NAME c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENN i (R) Length of name MINL i (R) Minimum length for keyword match ITYP i (R) Parameter type 1=dataset, 2=set, 3=subset specific ISTD i (R) Standard parameter for output (see KDMF_OUTPUT) = 1 yes, =0 no NVALS i (R) Max no. of values associated with the keyword NVALS_MIN i (R) Minimum no. of values which must be given (>=1) I_DEFLT() i (R) Default integer parameter values (NVALS values) (Values for which IRTYP(i).NE.1 ignored) F_DEFLT() r (R) Default real parameter values (NVALS values) (Values for which IRTYP(i).NE.2 ignored) Note: I_DEFLT and F_DEFLT can be equivalenced IRTYP() i (R) Integer/real flags for NVALS elements flag =1 for integer, =2 for real (any value!=1) ICHK i (R) Check value option =0 any integer OK, =1 check using supplied function CHKFUN CHKFUN s (R) Check value function (used if ICHK==6) Call will be I = CHKFUN (IVALS, FVALS, IRTYP, NINP) IVALS (R) Array of integer values to be checked (ignore elements unless IRTYP(i).EQ.1) FVALS (R) Array of real Values to be checked (ignore elements unless IRTYP(i).EQ.2) IRTYP (R) Array of element type flags. flag =1 for integer, =2 for real NINP (R) No. of input values to check. RETURN 0 OK, 1 error Use KDMF_SET_CHKERR within CHKFUN to set error string ND() i (R) No. of decimal places for printing values when a real was recalculated by a program (NVALS values) - ignored for integer values. ND_DEFLT() i (R) No. of decimal places for printing a default real value (NVALS values) - ignored for integer values NPR_DFLT i (R) No. of values to print when outputting default value (>=1) IERR i (W) Error return status flag from the kdm_define_varr call 'C' call: int kdm_define_varr (int kdx, char * name, int lenn, int minl, int ityp, int std, int nvals, int nvals_min, int *i_default, float *f_default, int *irtyp, int chk_typ, int (*chk_func)(), int *nd, int *default_nd, int npr_dflt) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * name; Parameter name (full) (R) int lenn; Length of name string (may be 0 if null term) (R) int minl; Minimum length for keyword matching (R) int ityp; Parameter type 1=dataset, 2=set, 3=subset specific (R) int std Standard parameter for output (see kdm_output) = 1 yes, =0 no (R) int nvals; No. of values associated with the keyword (maximum) (R) int nvals_min; Minimum no. of values which must be give (>=1) (R) float *i_default; Default parameter values (num_vals values) (Values for which irtyp(i)!=1 ignored) (R) float *f_default; Default parameter values (num_vals values) (Values for which irtyp(i)!=2 ignored) (R) int *irtyp; Parameter element type flags (num_vals values) flags = 1 for int, =2 for float (any value!=1) (R) int chk_typ; Check value option =0 any float OK, =1 check using supplied function chk_func . int (*chk_func)(); Check value function (used if chk_typ==1) call will be i = chk_func (ivals, fvals, irtyp, ninp); return 0 ok, 1 error int *ivals (r) Array of int values to be checked (ignore elements unless irtyp[i]==1) float *fvals (r) Array of float values to be checked (ignore elements unless irtyp[i]==2) int *irtyp (r) Array of element type flags =1 int, =2 float int *ninp (r) No. of input values to be checked. Use kdm_set_chkerr within chk_func to set error string (R) int *nd; No. of decimal places for printing values when it was recalculated by a program (nvals values) - ignored for integer values (R) int *default_nd; No. of decimal places for printing the default value (nvals values) - ignored for integer values (R) int npr_dflt; No. of values to print when outputting default value (>=1) (R) Return: Error flag = 0 no error; =-1 memory allocation error =-2 a previous memory allocation error had occurred = 1 parameter name or too long = 2 other invalid parameter passed to the routine = 3 'kdm' routines not initialised KDM NAME ALIASES Introduction Routines are available to set an alias or alternative name for a parameter and to select which name to use when the keyword is printed. The following routines are available: Define an alias name - kdm_set_alias Select name for output - kdm_printname Define an alias name - kdm_set_alias The routine kdm_set_alias (kdmf_set_alias) allows an alternative or alias name to be set for a 'kdm' parameter. Either this name or the alias may be used in the input keyworded data. The choice for output is set using the routine kdm_printname (kdmf_printname). Fortran call: CALL KDMF_SET_ALIAS (KDX, KDMSTR(KEYWORD), LENK, KDMSTR(ALIAS), + LENA, MINLEN, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ALIAS c (R) Alias name character string ** Pass address index using the KDMSTR function ** LENA i (R) Length of the alias name (>0) MINLEN i (R) Minimum length of alias name for a valid match IERR i (W) Error flag as returned from kdm_set_alias 'C' call: int kdm_set_alias (int kdx, char * keyword, int lenk, char * alias, int lena, int minlen) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) char * alias; The alias name (R) int lena; Length of alias name string (may be 0 if string is null terminated (R) int minlen; Minimum length of alias name for a valid match Return: Error flag = 0 no error = 1 invalid keyword specification =-100 index does not point to valid KDM dataset Select name for output - kdm_printname The routine kdm_printname (kdmf_printname) selects which keyword name to use on output if an alias has been defined for the keyword. Fortran call: CALL KDMF_PRINTNAME (KDX, KDMSTR(KEYWORD), LENK, USE_ALIAS, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword USE_ALIAS i (R) = 1 use Alias name = 0 use Normal name IERR i (W) Error flag as returned from kdm_printname 'C' call: int kdm_printname (int kdx, char * keyword, int lenk, int use_alias) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int use_alias; Flag =1 use Alias name, =0 use Normal name (R) Return: Error flag = 0 no error = 1 invalid keyword specification =-100 index does not point to valid KDM dataset SET KDM PARAMETER VALUES Introduction Routines are available to set KDM parameter values and to reset default values. The following routines are available: Reset default KDM parameter value(s) - kdm_reset Set a KDM parameter value - kdm_setvalue Set new decimal places flag - kdm_setndvar Reset standard output parameter flag - kdm_resetstd Reset default KDM parameter value(s) - kdm_reset The routine kdm_reset (kdmf_reset) is used to reset the default value for a selected KDM parameter or for all parameters. Values may be reset for single sets/subsets or all sets/subsets as desired. Fortran call: CALL KDMF_RESET (KDX, KDMSTR(KEYWORD), LENK, ISET, ISUBSET, + KDMSTR(ERRSTR), MAXE, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ISET i (R) Set number, 0=all sets - ignored for single value type parameters ISUBSET i (R) Subset number, 0=all subsets - ignored for single value or set type parameters ERRSTR c (W) Returns an error string ** Pass address index using the KDMSTR function ** MAXE i (R) Maximum length allowed for error string (should be >= 80) IERR i (W) Error flag as returned from kdm_reset 'C' call: int kdm_reset (int kdx, char * keyword, int lenk, int iset, int isubset, char * errstr, int maxe) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int iset; Set number, 0=all sets - ignored for single value type parameters (R) int isubset; Subset number, 0=all subsets - ignored for single value or set type parameters (R) char *errstr; Returns an error string (W) int maxe; if >0 Maximum length of returned error string allowed (excluding terminating null - errstr must be at least maxe + 1 characters in length) if <0 abs(maxe) characters will be returned padded with blanks if needed (for 'fortran' use) (should allow 80 chars for error messages) (R) Return: Error flag = 0 no error =-1 invalid set specification =-2 invalid subset specification =-3 invalid keyword specification =-100 index does not point to valid KDM dataset Set a KDM parameter value - kdm_setvalue The routine kdm_setvalue (kdmf_setvalue) 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 floating point 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 floating point 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 floating point variable, the default format for that parameter as defined via kdm_define_float (kdmf_define_float) will be used when the parameter value is printed. Fortran call: Fortran: CALL KDMF_SETVALUE (KDX, KDMSTR(KEYWORD), LENK, ISET, ISUBSET, + KDMSTR(VALSTR), LENV, IVAL, FVAL, IOPT, + KDMSTR(ERRSTR), MAXE, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ISET i (R) Set number, 0=all sets - ignored for single value type parameters ISUBSET i (R) Subset number, 0=all subsets - ignored for single value or set type parameters VALSTR c (R) Value string (-ignored if iopt>0) ** Pass address index using the KDMSTR function ** LENV i (R) Length of value string IVAL() i (R) Integer values for an integer parameter - used if IOPT=1 (NVALS values as defined in KDMF_DEFINE_INT call) FVAL() r (R) Float values for an float value parameter - used if IOPT=1 (NVALS values as defined in KDMF_DEFINE_FLOAT call) IOPT i (R) Flag =0 use value string (for float values the no. of decimal places for printing the values will be determined from this string) =1 use IVAL if an integer parameter and FVAL for a float parameter value (invalid for a string parameter) (for a float value the no. of decimal places for printing the value will be set to use the pre-defined default). Both arrays may be accessed for a variable array type parameter or >0 No. of input values for a variable array of values type parameter using IVAL and FVAL arrays ERRSTR c (W) Returns an error string ** Pass address index using the KDMSTR function ** MAXE i (R) Maximum length allowed for error string (should be >= 80) IERR i (W) Error flag as returned from kdm_setvalue 'C' call: int kdm_setvalue (int kdx, char * keyword, int lenk, int iset, int isubset, char * valstr, int lenv, int * ival, float * fval, int iopt, char * errstr, int maxe) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int iset; Set number, 0=all sets - ignored for single value type parameters (R) int isubset; Subset number, 0=all subsets - ignored for single value or set type parameters (R) char * valstr; Value string (-ignored if iopt=1) (R) int lenv; Length of value string; may be 0 if valstr is null terminated (R) int * ival; Integer values for an integer parameter - used if iopt=1 (nvals values as dedined in kdm_define_int call) (R) float * fval; Float values for an float value parameter - used if iopt=1 (nvals values as dedined in kdm_define_float call)(R) int iopt; Flag =0 use value string (for a float value the no. of decimal places for printing the value will be determined from this string) =1 use ival if an integer parameter and fval for a float parameter value (invalid for a string parameter) (for a float value the no. of decimal places for printing the value will be set to use the pre-defined default) or >0 No. of input values for a variable array of values type parameter using ival and fval arrays (R) char *errstr; Returns an error string (W) int maxe; if >0 Maximum length of returned error string allowed (excluding terminating null - errstr must be at least maxe + 1 characters in length) if <0 abs(maxe) characters will be returned padded with blanks if needed (for 'fortran' use) (should allow 80 chars for error messages) (R) Return: Error flag = 0 no error = 1 syntax error in number = 2 invalid value = -1 invalid set specification = -2 invalid subset specification = -3 invalid keyword = -4 memory allocation error (variable array parameter type only) = -100 index does not point to valid KDM dataset Set new decimal places flag - kdm_setndvar The routine kdm_setndvar (kdmf_setndvar) is a routine which enables the number of decimal places flag for a data item of a variable array keyword parameter to be set to a new value. Fortran call: CALL KDMF_SETNDVAR (KDX, KDMSTR(KEYWORD), LENK, ITM, ND_NEW, + IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ITM i (R) Variable array item no. (from 1 to the maximum defined for the keyword) ND_NEW i (R) The new no. of decimal places for printing the value of a real data value recalculated by the program - ignored for an integer value IERR i (W) Error flag as returned from kdm_setndvar 'C' call: int kdm_setndvar (int kdx, char * keyword, int lenk, int itm, int nd_new) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int itm; Variable array item no. (from 1 to the maximum defined for the keyword) (R) int nd_new; The new no. of decimal places for printing the value of a real data value recalculated by the program - ignored for an integer value (R) Return: Error flag = 0 no error = 1 invalid keyword specification = 2 not a variable array parameter =-100 index does not point to valid KDM dataset Reset standard output parameter flag - kdm_resetstd The routine kdm_resetstd (kdmf_resetstd) is a routine which enables the number 'standard output parameter' flag to be reset for a requested keyword parameter. Fortran call: CALL KDMF_RESETSTD (KDX, KDMSTR(KEYWORD), LENK, IFLAG, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword IFLAG i (R) =1 Set as standard parameter, =0 set as not a standard parameter, =-1 reset default. IERR i (W) Error flag as returned from kdm_resetstd 'C' call: int kdm_resetstd (int kdx, char * keyword, int lenk, int iflag) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int iflag; =1 Set as standard parameter, =0 set as not a standard parameter, =-1 reset default (R) Return: Error flag = 0 no error = 1 invalid keyword specification KDM dataset = 2 invalid value of iflag =-100 index does not point to valid KDM dataset GET KDM PARAMETER VALUES Introduction Routines are avaiable to return the current values of KDM parameters. The following routines are available: Get a KDM parameter value - kdm_getvalue Get a KDM parameter value string - kdm_getvalstr Get a KDM parameter value - kdm_getvalue The routine kdm_getvalue (kdmf_getvalue) is used to get a KDM parameter value for any of the available parameter types. The full keyword string for the parameter must be given. The value will be returned a string and also, in the case of integer or floating point values, in a data item of the corresponding data type. A set and subset value must be given explicitly where relevant. Fortran call: CALL KDMF_GETVALUE (KDX, KDMSTR(KEYWORD), LENK, ISET, ISUBSET, + MAXV, KDMSTR(VALSTR), FVAL, ND, IVAL, + NUM_INP, ISTAT, ITYP, KDMSTR(ERRSTR), + MAXE, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ISET i (R) Set number,(>0) - ignored for single value type parameters ISUBSET i (R) Subset number, (>0) - ignored for single value or set type parameters MAXV i (R) Maximum length allowed for returned value string VALSTR c (W) Returned Value string (must be at least MAXV chars in length ** Pass address index using the KDMSTR function ** FVAL() r (W) Returned float values for a float type parameter (NVALS values as defined in KDMF_DEFINE_FLOAT call) or, in selected elements, for a variable length array parameter (see also NUM_INP) ND() i (W) Returned no. of decimal places flags for a float type parameter (-ve for E format)(NVALS values as defined in KDMF_DEFINE_FLOAT call) or, in selected elements, for a variable length array parameter (see also NUM_INP) IVAL() i (W) Returned integer values for an integer type parameter (NVALS values as dedined in KDMF_DEFINE_INT call) or, in selected elements, for a variable length array parameter (see also NUM_INP) NUM_INP i (W) No. of values presently stored for a a variable length array parameter (otherwise 0). For each array element from 1 to NUM_INP, a value will either be returned in either IVAL or FVAL as defined when the parameter was set up. ISTAT i (W) Parameter value status = 0 default = 1 set explicitly = 2 set globally ITYP i (W) Parameter type = 1 integer (string also returned) = 2 float (string also returned) = 3 string (single token) = 4 string (multiple token) = 5 variable array ERRSTR c (W) Returns an error string ** Pass address index using the KDMSTR function ** MAXE i (R) Maximum length allowed for error string (should be >= 80) IERR i (W) Error flag as returned from kdm_getvalue 'C' call: int kdm_getvalue (int kdx, char * keyword, int lenk, int iset, int isubset, int maxv, char * valstr, float * fval, int * nd, int * ival, int * num_inp, int * istat, int * ityp, char * errstr, int maxe) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int iset; Set number (>0) - ignored for single value type parameters (R) int isubset; Subset number (>0) - ignored for single value or set type parameters (R) int maxv; if >0 Maximum length of returned value string allowed (excluding terminating null - valstr must be at least maxv + 1 characters in length) if <0 abs(maxv) characters will be returned padded with blanks if needed (for 'fortran' use) (R) char * valstr; Returned Value string (must be at least maxval+1 chars in length (W) float * fval; Returned float values for a float type parameter (nvals values as defined in kdm_define_float call) or, in selected elements, for a variable length array parameter (see also num_inp) (W) int * nd; Returned no. of decimal places flags for a float type parameter (-ve for E format) (nvals values as defined in kdm_define_float call) or, in selected elements, for a variable length array parameter (see also num_inp) (W) int * ival; Returned integer values for an integer type parameter (nvals values as dedined in kdm_define_int call) or, in selected elements, for a variable length array parameter (see also num_inp) (W) int * num_inp; Returns no. of values presently stored for a a variable length array parameter (otherwise 0) For each array element from 0 to num_inp-1, a value will either be returned in either ival or fval as defined when the parameter was set up. (W) int *istat; Parameter value status = 0 default = 1 set explicitly = 2 set globally (W) int *ityp; Parameter type = 1 integer (string also returned) = 2 float (string also returned) = 3 string (single token) = 4 string (multiple tokens) = 5 variable array (W) char *errstr; Returns an error string (W) int maxe; if >0 Maximum length of returned error string allowed (excluding terminating null - errstr must be at least maxe + 1 characters in length) if <0 abs(maxe) characters will be returned padded with blanks if needed (for 'fortran' use) (should allow 80 chars for error messages) (R) Return: Error flag = 0 no error = 1 error Get a KDM parameter value string - kdm_getvalstr The routine kdm_getvalstr (kdmf_getvalstr) is used to get a KDM parameter value for any of the available parameter types. The full keyword string for the parameter must be given. The value will be returned a string only (cf kdm_getvalue (kdmf_getvalue)). A set and subset value must be given explicitly where relevant. Fortran call: CALL KDMF_GETVALSTR (KDX, KDMSTR(KEYWORD), LENK, ISET, ISUBSET, + MAXV, KDMSTR(VALSTR), ISTAT, + ITYP, KDMSTR(ERRSTR), MAXE, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ISET i (R) Set number,(>0) - ignored for single value type parameters ISUBSET i (R) Subset number, (>0) - ignored for single value or set type parameters MAXV i (R) Maximum length allowed for returned value string VALSTR c (W) Returned Value string (must be at least MAXV chars in length ** Pass address index using the KDMSTR function ** ISTAT (i W) Parameter value status = 0 default = 1 set explicitly = 2 set globally ITYP i (W) Parameter type = 1 integer (string also returned) = 2 float (string also returned) = 3 string (single token) = 4 string (multiple token) ERRSTR c (W) Returns an error string ** Pass address index using the KDMSTR function ** MAXE i (R) Maximum length allowed for error string (should be >= 80) IERR i (W) Error flag as returned from kdm_setvalue 'C' call: int kdm_getvalstr (int kdx, char * keyword, int lenk, int iset, int isubset, int maxv, char * valstr, int *istat, int *ityp, char * errstr, int maxe) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int iset; Set number (>0) - ignored for single value type parameters (R) int isubset; Subset number (>0) - ignored for single value or set type parameters (R) int maxv; if >0 Maximum length of returned value string allowed (excluding terminating null - valstr must be at least maxv + 1 characters in length) if <0 abs(maxv) characters will be returned padded with blanks if needed (for 'fortran' use) (R) char * valstr; Returned Value string (must be at least maxval+1 chars in length (W) int *istat; Parameter value status = 0 default = 1 set explicitly = 2 set globally (W) int *ityp; Parameter type = 1 integer (string also returned) = 2 float (string also returned) = 3 string (single token) = 4 string (multiple tokens) (W) char *errstr; Returns an error string (W) int maxe; if >0 Maximum length of returned error string allowed (excluding terminating null - errstr must be at least maxe + 1 characters in length) if <0 abs(maxe) characters will be returned padded with blanks if needed (for 'fortran' use) (should allow 80 chars for error messages) (R) Return: Error flag = 0 no error = 1 error OUTPUT KEYWORD AND VALUE STRINGS Introduction A routine enables the formation of output strings for writing KDM data. A user supplied routine does the actual output. The following routines are available: Get output string for a KDM parameter - kdm_output Get output string for a KDM parameter - kdm_output The routine kdm_output (kdmf_output) is used to form 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 routine 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 function is given to do the actual output. Fortran call: CALL KDMF_OUTPUT (KDX, KDMSTR(KEYWORD), LENK, ICHANGED, + IREDUCE, NS, NSS, KDMSTR(OUTSTR), MAXO, + OP_FUNC, KDMSTR(ERRSTR), MAXE, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ICHANGED i (R) If 0 print parameter anyway, if 1-16, only create output parameter value string if parameter changed flag set for that parameter. IREDUCE i (R) =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) NS i (R) Current no. of sets (give -1 if this and the nos. of subsets/set values are to be determined internally from the parameters named via KDMF_INIT) NSS() i (R) Array of current nos. of subsets in each set (at least NS values) - values ignored if NS = -1 OUTSTR c (*) Buffer used in printing output (should be at least 2050 characters in length) ** Pass address index using the KDMSTR function ** MAXO i (R) Maximum length allowed for OUTSTR (should be at least 2050) OP_FUNC s (R) Function to do the actual output. The data to be output by this function will be stored in OUTSTR, The call will be CALL OP_FUNC without any parameters so that the string OUTSTR must be available to the routine op_func via a common block possibly with other parameters such as Fortran unit numbers etc. If any keywords have a large number of values, then the output routine may wish to split the string into more than one record; if the output is to a parameter file which is subsequently to be read then all the records except the last one should be terminated with a '-' or '&' character to indicate continuation. ERRSTR c (W) Returns an error string ** Pass address index using the KDMSTR function ** MAXE i (R) Maximum length allowed for error string (should be >= 80) IERR i (W) Error flag as returned from kdm_output 'C' call: int kdm_output (int kdx, char * keyword, int lenk, int ichanged, int ireduce, int ns, int * nss, char * outstr, int maxo, void (*op_func)(), char * errstr, int maxe) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int ichanged; If 0 print parameter anyway, if 1-16, only create output parameter value string if parameter changed flag set for that parameter. (R) int ireduce; =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) (R) int ns; Current no. of sets (give -1 if this and the nos. of subsets/set values are to be determined internally from the parameters named via kdm_init) (R) int * nss; Array of current nos. of subsets in each set (at least nums values) - values ignored if ns = -1 (R) char * outstr; Returns the output string for printing (W) int maxo; if >0 Maximum length of returned output string allowed (excluding terminating null - outstr must be at least maxo + 1 characters in length); maxo should be at least 2050. if <0 abs(maxo) characters will be returned padded with blanks if needed (for 'fortran' use) (abs(maxo) should be at least 2050) (R) void (*op_func)(); Function to o/p the string; if NULL then o/p will be done to the standard output. If defined then this function will be called without parameters; the string 'outstr' will contain the required o/p and must be globally accessible to the output function together with any other special parameters required. If any keywords have a large number of values, then the output routine may wish to split the string into more than one record; if the output is to a parameter file which is subsequently to be read then all the records except the last one should be terminated with a '-' or '&' character to indicate continuation. (R) char *errstr; Returns an error string (W) int maxe; if >0 Maximum length of returned error string allowed (excluding terminating null - errstr must be at least maxe + 1 characters in length) if <0 abs(maxe) characters will be returned padded with blanks if needed (for 'fortran' use) (should allow 80 chars for error messages) (R) Return: Error flag = 0 no error = 1 error MONITOR KDM PARAMETER CHANGES Introduction Routines are available to assist with the monitoring of changes to KDM parameter values during the running of a program. The kdm_output (kdmf_output) routine, described in the previous section, is used to output such changed values when required. The following routines are available: Reset parameter changed flags - kdm_ch_reset See if any parameter changed - kdm_any_ch See if a KDM parameter changed - kdm_changed Reset parameter changed flags - kdm_ch_reset The routine kdm_ch_reset (kdmf_ch_reset) is used to reset (clear) parameter change monitoring flags for a requested channel or for all channels. Fortran call: CALL KDMF_CH_RESET (KDX, ICHAN, IERR) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT ICHAN i (R) Channel number for reset (1-16), 0 = all channels IERR i (W) Error flag as returned kdm_ch_reset call 'C' call: int kdm_ch_reset (int kdx, int ichan) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) int ichan; Channel number for reset (1-16), 0 = all channels (R) Return: Error flag = 0 no error = 1 error in call parameter See if any parameter changed - kdm_any_ch The routine kdm_any_ch (kdmf_any_ch) is used to test whether any parameter value has been changed for a requested channel or for all channels. Fortran call: CALL KDMF_ANY_CH (KDX, ICHAN, IFLAG) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT. ICHAN i (R) Channel number for test (1-16), 0 = all channels. IFLAG i (W) Flag as returned kdm_any_ch call; 0 = no change or error in call, 1 = parameter changed. 'C' call: int kdm_any_ch (int kdx, int ichan) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) int ichan; Channel number for test (1-16), 0 = all channels (R) Return: Error flag = 0 no change or error in call parameter = 1 parameter changed See if a KDM parameter changed - kdm_changed The routine kdm_changed (kdmf_changed) is used to test whether any parameter value has been changed for a requested channel. Fortran call: CALL KDMF_CHANGED (KDX, KDMSTR(KEYWORD), LENK, ICHAN, ISET, + ISUBSET, IFLAG) Parameters: KDX i (R) Index to keyword set as returned by KDMF_INIT. KEYWORD c (R) Parameter name (full) character string ** Pass address index using the KDMSTR function ** LENK i (R) Length of keyword ICHAN i (R) Channel number for test (1-16) ISET i (R) Set number (from 1 up) - ignored for dataset type parameter ISUBSET i (R) Subset number (from 1 up) - ignored for dataset type or set type parameter IFLAG i (W) Flag as returned kdm_any_ch call; 0 = no change or error in call, 1 = parameter changed. 'C' call: int kdm_changed (int kdx, char * keyword, int lenk, int ichan, int iset, int isubset) Parameters: int kdx; Index to keyword set as returned by kdm_init (R) char * keyword; Parameter keyword string (full) (R) int lenk; Length of keyword string (may be 0 if string is null terminated (R) int ichan; Channel number for test (1-16)(R) int iset; Set number (from 1 up) - ignored for dataset type parameter (R) int isubset; Subset number (from 1 up) - ignored for dataset type or set type parameter (R) Return: Error flag = 0 no change or error in call parameter = 1 parameter changed ROUTINES FOR USER SUPPLIED FUNCTIONS Introduction Some routines are avaiable to enable certain data items to be accessed within user supplied functions for parameter value checking. The following routines are available: Get string parameter value for checking - kdm_strval Set parameter check error string - kdm_set_chkerr Get string parameter value for checking - kdm_strval The routine kdm_strval (kdmf_strval) is used to get the string to be checked from within a user supplied checking function for a string type parameter. Fortran call: CALL KDMF_STRVAL (VALSTR, MAXL) Parameters: VALSTR c (W) Returns the value string ** Pass address index using the KDMSTR function ** MAXL i (R) Maximum length allowed for the string (must be at least MAXLEN characters long) 'C' call: void kdm_strval (char * valstr, int maxl) Parameters: char * valstr; Returns the value string (W) int maxl; if >0 Maximum length of returned string allowed (excluding terminating null - string must be at least maxl + 1 characters in length) if <0 abs(maxl) characters will be returned padded with blanks if needed (for 'fortran' use) (R) Return: None Set parameter check error string - kdm_set_chkerr The routine kdm_set_chkerr (kdmf_set_chkerr) is used to set the error string from within a user supplied parameter value checking routine when an error in the parameter value is found. The error string set will be returned via a kdm_setvalue (kdmf_setvalue) routine call. Fortran call: CALL KDMF_SET_CHKERR (KDMSTR(ERRSTR), LERR) Parameters: ERRSTR c (R) The error string ** Pass address index using the KDMSTR function ** LERR i (R) Length of the string 'C' call: void kdm_set_chkerr (char * errstr, int lerr) Parameters: char * errstr; Error string (R) int lerr; Length of error string; may be 0 if null terminated (R) Return: None FORTRAN CHARACTER STRING PARAMETERS Introduction The routine described in this section must be used when a character string parameter is to be passed to or returned from a KDM routine using its Fortran binding. The following routines are available: Pointers list index of a Fortran character string - kdmstr Pointers list index of a Fortran character string - kdmstr The routine kdmstr is used to return an index to a list of character string pointers held within the 'kdm' routines and used where a Fortran callable routine passes character data to or from the routine. The actual paramter(s) expected by the C routine are machine dependent. The Fortran call is of the form: KDMSTR (CHS) where CHS is a Fortran character variable or string. The function KDMSTR must be declared in the calling Fortran program as an INTEGER FUNCTION. 'C' ROUTINES TO READ KDM 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 - kdm_readline Handle Indirect File References in a String - kdm_readstr Read Line of Data from a File - kdm_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. 'C' call: int kdm_readline (FILE * fp_in, int * indirect, char * line, int maxlen) Parameters: FILE * fp_in; File pointer for file being read (R) int * indirect; 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 kdm+readline is returned as -1 (end of file) or 'indirect' is returned as 0 (otherwise files will be left open) (R/W) char * line; Returns the next logical line with comments removed and with all continuation lines concatenated (null terminated). Length must be at least maxlen+1. (W) int maxlen; Maximum number of characters which may be returned in 'line' (R) Return: Error/End-of-file flag =0 No error, line read; =-1 End of file = 1 'line' too short, data truncated = 2 Error opening indirect file = 3 Maximum allowed level of indirection exceeded = 4 Calling error (invalid 'indirect' value) Handle Indirect File References in a String - kdm_readstr This routine is similar to 'kdm_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. 'C' call: int kdm_readstr (char * line, int maxlen, int *indirect, int *iflag) Parameters: char * line; 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) (R/W) int maxlen; Maximum number of characters which may be returned in 'line' (R) int * indirect; 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 kdm+readline is returned as -1 (end of file) or 'indirect' is returned as 0 (otherwise files will be left open) (R/W) int *iflag 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 (W) Return: Error/End-of-file flag = 0 No error, line read = 1 'line' too short, data truncated = 2 Error opening indirect file = 3 Maximum allowed level of indirection exceeded = 4 Calling error (invalid 'indirect' value) 'C' ROUTINES TO 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 parses the keyword string to determine any set/subset specification. The following routines are available: Parse KDM Data with Checking - kdm_parsekdm Parse a Keyword Item - kdm_parseitem Parse KDM Data with Checking - kdm_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. A user supplied routine may make an additional check on each KDM parameter and disable its update if desired. 'C' call: int kdm_parsekdm (int kdx, char * line, int (*chk_func)(), char * badtok, int maxb, char * errstr, int maxe) Parameters: int kdx; Index to required KDM data set. (R) char * line; Character string containing line to be parsed (Assume comments & continuations already removed) int (*chk_func)(); Function 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: ok = chk_func(keyword) char * keyword; Variable holding the full name of the KDM parameter. Return 1 if parameter may be updated or 0 if it may not. (R) char * badtok; Returns the bad token string - must be at least maxb+1 characters long (W) int maxb; Maximum length for bad token string (R) char * errstr; Error string ( max 80 characters) - must be at least maxe+1 characters long (W) int maxe; Maximum length for error string (R) Return = 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! Parse a Keyword Item - kdm_parseitem This routine is used by the higher level parsing routine 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. 'C' call: int kdm_parseitem (char * str, char * keyword, int * iset, int * isubset, int * iss) Parameters: char * str; String containing the keyword string to be examined (R) char * keyword; Returns the keyword name without any attached set/subset specification (W) int * iset; Returns set specification if present (W) int *isubset; Returns subset specification if present (W) int * iss; =0 keyword only present, =1 keyword + set specification present, =2 keyword + subset specification present (W) Return Error flag = 0 OK = 1 blank keyword =-3 Syntax error in set/subset specification 'C' ROUTINE TO WRITE KDM DATA Introduction A routine is available to write out, with various options, the Keyword Data Module (KDM) keyworded parameter data. The following routines are available: Output a KDM data set - kdm_writekdm Output a KDM data set - kdm_writekdm C This routine is used to output a KDM keyword parameter data set. A number C of options are available to control the amount and style of the output C and there is also an option to output only changed KDM parameter values. 'C' call: int kdm_writekdm (int kdx, FILE * fp, int ioptyp, int ichanged) Parameters: int kdx; Index to required KDM dataset (R) FILE *fp; The output file stream (R) int ioptyp; 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. (R) int ichanged; = 0 Output all parameters = 1-16 Write changed parameter values since last reset of flag for channel 'ichanged' (R) Return 0 OK 1 Invalid KDM index or invalid parameter