#include <stdinc.h>#include <getparam.h>string defv[]={
"key1=val1\n Example help for key1",
"key2=val2\n Example help for key2",
"VERSION=1.0\n 30-apr-2002 pjt",
NULL,
};
string usage="Example usage for program";
void initparam(string *argv, string *defv)void finiparam(void)
void stop(int
level)
string getparam(string name)int getiparam(string name)long getlparam(string
name)double getdparam(string name)bool getbparam(string name)
string *getargv(int
*argc)
int indexparam(string basename, int idx)string getparam_idx(string
basename,int idx)int getiparam_idx(string basename,int idx)long getlparam_idx(string
basename,int idx)double getdparam_idx(string basename,int idx)bool getbparam_idx(string
basename,int idx)
void putparam(string name,string value)void promptparam(string
name,string prompt)
bool hasvalue(string name)bool isaparam(string name)bool
updparam(string name)int getparamstat(string);extern int error_level;extern
int debug_level;extern int yapp_level;extern int help_level;
undocumented:
_bell_level_history_review_flag_yapp_dev_yapp_string_help_string_argv_string
initparam is called with two arguments: the argument vector argv which is passed to main, and a similar vector defv which determines the set of legal keyword names and their default values. More precisely, defv is of the form
string defv[] = { "name=value\nhelp", . . ., "VERSION=x.y", NULL };
initparam determines a value for each name in defv by scanning the command line arguments in argv, any values supplied in a keyword file (see below) and finally adopting the value supplied by defv if no other value can be found. Note the recommended (but not enforced) usage of the VERSION keyword; this version ID will be used to tag the history of datafiles which were created by programs, and will also warn users when outdated keyword files are used (see below).
Arguments specified in argv are matched with names specified in defv either one of two ways. Those appearing to the left of the first argument containing an embedded "=" sign are matched by position: the first such argument is associated with the first name listed in defv, and so on; it is an error if more arguments are supplied in argv than names are supplied in defv. The remaining arguments must all be of the form "name=value", and are matched by keyword: name must appear in defv, and value is associated with name. It is an error to specify more than one value for a given name. If getparam is compiled with MINMATCH, keyword names are also matched in minimum match mode.
An exception to commandline parsing is made for any arguments that follow the standalone command line argument "--". The function getargv() can be used to get access to any arguments that follow (and including) "--". The returned array simply points into the original char **argv, but starts at the location of "--". The returned argc therefore only counts the number of arguments after (and including) "--", and thus making argv[0] be "--".
Depending on a user specified help_level (see below) parameters may also be set by reading them from a keyword file. The keyword file is unique for each program, and has the name "program.def". Although there is some control over the directory in which these keyword files should be located ($NEMODEF, but more on that later), it is dangerous to use keyword files during multiple sessions since NEMO does not use a file locking mechanism. Command line keyword values are always favored over values from a keyword file.
Once initparam has returned, the value associated with a name may be obtained (as a string) by getparam, or directly converted to an int, long, double, or bool by the functions getiparam, getlparam, getdparam, and getbparam respectively. The latter recognizes the digit "1" or any string starting with one of "tTyY" as TRUE, and "0" or any string starting with one of "fFnN" as FALSE. All the getXparam function can do simple parsing of expressions, see nemoinp(3NEMO) for some extended rules. Also note that getparam returns a string into private space, that should not be modified or freed! An single parameter integer that starts with the 0x string, can also be parsed as a hexdecimal value (see strtol(3) ).
getparamstat is currently only available to provide ZENO compatibility, it currently triggers a call to error(3NEMO) when called.
As a special case, the contents of argv[0], which is the name used to invoke the process, are associated with the keyword name argv0. This is useful when reporting errors from library routines which may have no other way of determining what program called them; for example,
printf("sqrt in %s: negative arg\n", getparam("argv0"));
could be used to print an error message from a square-root procedure, giving the name of the program in which the error occured. The macro getargv0(), defined in getparam.h, can also be used for this, instead of called getparam(). This technique is used by the routine, error(3NEMO) ; it reports the program name in square brackets before the string is output.
The optional usage and cvsid strings, that will need to be defined by the user, can be queried with the help=u and help=I options.
Not only does this enable the running task to warn users if outdated keyword files are used, but also it provides an automated way to label the data history with the version of the program used to generate that data. A minor version number conflict will result in a warning message, but a major one will result in a fatal error message. If your program has changed data format, or keywords have changed meaning or name, it is adviced to change the major version number.
The external VERSION id is the id stored in some external keyword database, (such as the commandline or a keyword file), that is supplied to the running task. This would make it possible for programs to refuse execution if the internal and external VERSION id do not match. We do not currently employ this technique. Most NEMO programs have a section labeled UPDATE HISTORY in which old version ID’s are labeled by time, comment and author.
indexparam(basename,-1) returns the largest index that was found, indexparam(basename,-2) returns 0 if the keyword is not an indexed keyword, and indexparam(basename,idx), for idx >= 0, will check existence (1=true) for a specific index.
help=option,option,...
If this argument, which must be specified by name, appears in argv, initparam will generate some helpful information before returning. Possible options include
These options must be abbreviated to one character. For example,
help=d,q
will print defaults and then quit (actually, the comma is not needed).
This feature may be disabled by including an entry for help in defv, in which case help processing is left to the applications program (not recommended).
An environment variable HELP or the system keyword help= can be set to a non-zero number to change to various levels of interactive input if implemented.
~/src/kernel/io getparam.c ~/src/kernel/cores error.c (stop)
Some undocumented features. The NEMO Users Guide is often more complete.
A key-less parameter that contains an ’=’ sign confuses the parser and will most likely complain about an unknown parameter. E.g. "i%%128==0" will return Parameter "i%128" unknown.
% p help= p a=1 b=2 c#= VERSION=0.1 % p help=h a : keyword a [1] b : keyword b [2] c# : indexed keyword c [] VERSION : PJT [0.1] % p a=2 % p c2=1 c0=1.2 % mkplummer . 1000000 help=c CPU_USAGE mkplummer : 7.84 6.99 0.42 0.00 0.00 6202936
xx-nov-86 created Joshua Barnes 16-oct-87 add system keyword host= Peter Teuben 9-mar-88 add system keyword debug= PJT 21-apr-88 interactive input PJT 24-nov-88 editor mode in help= PJT 6-mar-89 added nemoinp parsing of getXparam PJT 28-nov-94 V3 rewrite, many new features, deleted some others PJT 12-feb-95 added updparam 20-jan-02 re-implemented indexed keywords PJT 12-jul03 added getargv() PJT 13-may-04 added help=c PJT 29-dec-04 added help=I and documented CVSID PJT