6.2.2 getparam.h

The command line syntax described earlier in Chapter  is implemented by a small set of functions used by all conforming NEMO programs. A few function calls generally suffice to get the values of the input parameters. A number of more complex parsing routines are also available, to be discussed in the next subsection.

First of all, a NEMO program must define which program keywords it will recognize. For this purpose it must define an array of strings with the names and the default values for the keywords, and optionally, but STRONGLY recommended, a one line help string for that keyword:

    #include <stdinc.h>     /*   every NEMO module needs this  */
    #include <getparam.h>   /* needed when user interface used */

    string defv[] = {       /* definitions of the keywords */
        "in=???\n          Input file (a snapshot)",
        "n=10\n            Number of particles to view",
        "VERSION=1.1\n     14-jul-89 - 200th Bastille Day - PJT",
        NULL,
    };

    string usage = "example program";   /* def. of the usage line */

The ``keyword=value'' and ``help'' part of the string must be separated by a newline symbol ($\backslash$n). If no newline is present, as was the case in earlier releases, no help string is available.^6.3 The 'help=h' command line option displays the ``help'' part of string during execution of the program for quick inline reference. The ``usage'' part defines a string that is used as a one line reminder what the program does. It's used by the various invocations of the user interface.

The first thing a NEMO program does, is comparing the command line arguments of the program (commonly called string argv[] in a C program) with this default vector of ``keyword=value'' strings (string defv[]), and replace appropriate reset values for later retrieval. This is done by calling initparam^6.4 as the first step in your MAIN program:

    main (argc, argv)
    int argc;
    string argv[];
    {
        initparam(argv,defv);
        . . .

It also checks if keywords which do not have a default value (i.e. were given ``???'') have really been given a proper value on the command line, if keywords are not specified twice, enters values of the system keywords etc.

There is a better alternative to define the main part of a NEMO program: by renaming the main entry point main() to nemo_main() , without any arguments, and calling the array of strings with default 'key=val's string defv[], the linker will automatically include the proper startup code (initparam(argv,defv)), the worker routine nemo_main() itself, and the stop code (finiparam()). The above section of code would then be replaced by a mere:

    nemo_main()
    {
        . . .

This has the obvious advantage that various NEMO related administrative details are now hidden from the application programmers, and occur automatically. Remember that standard main() already shields the application programmer from a number of tedious setups (e.g. stdio etc.). Within NEMO we have taken this one step further. The example given later in Section  also uses the technique of calling the main entry point nemo_main().

Once the user interface has been initialized, keyword values may be obtained at any point during execution of the program by calling getparam(), which returns a string^6.5:

    if (streq(getparam("n"),"0")
        printf(" You really mean zero or octal?\n");

There is a whole family of getXparam() functions which parse^6.6 the string in a value of one of the basic C types int, long, bool, and real. It returns that value in that type:

    #include <getparam.h>     /* defines ``int getiparam()'' */
    . . .
    int nbody;
    . . .
    if ( (nbody = getiparam("n")) <= 0) {
        printf("Cannot handle %d particles\n",nbody);
        exit(0);
    }

Finally, there is a macro called getargv0(), which returns the name of the calling program, mostly used for identification:

    if (getbparam("quit"))
        error("%s: early quit", getargv0());

This is very useful in library routines, who normally would not be able to know who called them. Actually, NEMO's error function already uses this technique, since it cannot know the name of the program by whom it was called. The error function prints a message, and exits the program.

More detailed information can also be found in the appropriate manual page: getparam(3NEMO) and error(3NEMO).