Table of Contents

Name

getXparam, hasvalue, isaparam, initparam, finiparam, stop - main startup and command line processing.

Synopsis


#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";
string cvsid="$Id: $";
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

Description

These functions provide a simple and uniform mechanism for command line processing (see also nemomain(3NEMO) for an even simpler approach). Input as well as output (storage) of selected parameters can be controlled via command line parameters. First, initparam is called to set up values associated with a set of possible keyword names; after this getparam and any of its relatives may be called to access and/or parse the value associated with a specified keyword. finiparam should be called before the program ends, to ensure any outstanding requests are dealt with (e.g. writing updated keyword files, see HELP and DEBUG below), or optionally complain about unprocessed command line arguments. Output of parameters is described in outparam(3NEMO) .

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.

Required Arguments

Arguments with default values (as listed in defv) of "???" are required; initparam will print an informative message and quit if no value for such an argument can be obtained from argv. This feature is handy for things which must be specified or for which no reasonable default exists.

Version

It is good (NEMO) programming practice to give your program a VERSION id. We refer to this as the internal VERSION id. The NEMO technique has historically been by adding it as the last keyword, VERSION, in upper case. Its value should be of the form x.y, where x is the major version number, and y the minor version number. Sometimes a subversion labeled a, b, c, ... has been added.

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.

Indexed Keywords

The indexparam and getparam_idx family provides one way of access to indexed keywords. Indexed keywords are defined in the defv vector by a basename that ends in with the # symbol, which can at runtime be replaced by any set of non-negative integers, e.g. naxis# can be used to for example define naxis1=10, naxis4=4 (note the index is actually 0 based). It is up to the programmer to decipher missing elements (e.g. using isaparam or indexparam).

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 Functions

Besides interpreting the command line, initparam provides some assistance to the user via an additional argument (in addition to those defined in defv), namely


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

a
- print program name and command line arguments,
p,k
- print program name and all parameter values,
d,v
- print program name and default values,
n
- print newlines after every parameter/default values,
o
- show output keywords (see outparam(3NEMO) )
c
- show CPU usage: clock, user, system, child-user, child-system and cpu-tick-0
q
- exit after other help requests.
u
- show usage string
h
- show key and help strings
t
- show help as MIRIAD doc file (expert mode)
t
- show help as KHOROS pane file (expert mode)
i
- show some internal variables of the user interface (expert mode)

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.

Output Keys

The system keyword outkeys=key1,key2,... controls which pre-defined output keys (see outparam(3NEMO) ) are going to output to NEMO’s persistent global keyword database.

Debugging

The system keyword debug=debug_level is checked for by the initparam call. It sets the debug_level to the requested value. Any calls to dprintf(3NEMO) will only be send to the standard error output device,(stderr), if debug is less or equal than debug_level. Any initial setting of debug_level is also done through an environment variable DEBUG, but overriden by the debug= keyword.

Files


~/src/kernel/io       getparam.c 
~/src/kernel/cores    error.c (stop)

See Also

environ(5) , dprintf(3NEMO) , error(3NEMO) , nemoinp(3NEMO) , nemomain(3NEMO) , outparam(3NEMO)

Diagnostics

Complains via error(3NEMO) or the local_error() function about extra arguments, unknown arguments, etc. This will generally result in a stopped program.

Bugs

The code to access environ has only been implemented for the system environment variables DEBUG, YAPP, HISTORY, BELL, REVIEW, ERROR, ARGV and HELP.

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.

Examples

Here are some examples of usage of such a user interface. Assume we have a program p, which has keywords a, b and c, of which c is an indexed keyword
% 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

Author

Joshua Barnes, Peter Teuben

Update History


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


Table of Contents