• Antelope Release 5.5 Linux 2.6.32-220.el6.x86_64 2015-04-21

 

NAME

check_required_pf - prescan parameter files for critical parameters

SYNOPSIS

#include "glputil.h"
void check_required_pf(Pf *pf);

SUPPORT


Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

Programs can use parameter files to pass around large trees of parameters as an inefficient, but simple mechanism for data encapsulation. The problem with this, however, is that a program must be certain these parameters are defined early in execution. Otherwise program could run for hours before dying on a trial error caused by a missing parameter. This function uses options defined in the pf itself to state what parameters need to be checked. The program will die immediately inside this function when a required parameter is not found in pf. The function also allows range checking on numerical parameters. This is a potentially useful sanity check on input that might be useful in some applications.

PARAMETER FILE

This function is driven by a pf description that is assumed to be embedded in the same pf space that is to be checked. The simplest way to define what is required is to give an example from dbpmel:

require &Arr{
    boolean     &Tbl{
        use_all_stations
        use_dnorth_deast
        pmel_autodelete_high_rms
        pmel_cluster_mode
    }
    double      &Tbl{
        pmel_initial_error_scale
        pmel_minimum_error_scale
        pmel_minimum_sswrodgf
        pmel_F_test_critical_value 0.9 1.0
        pmel_svd_relative_cutoff 0.0000000001 1.0
        pmel_sc_fraction_convergence_error 0.0000001 0.1
    }
    int &Tbl{
        pmel_maximum_sc_iterations 1 100
    }
    string      &Tbl{
        3Dreference_model
        travel_time_model
        pmel_run_name
        gridname
        pmelrun_archive_directory
        author
    }
}

Note how the definitions are keyed by the require parameter and the related curly brackets. Within the outer brackets the lines are broken into type segments defined by the keywords: boolean, double, int, and string. This is followed by a list of required parameter names. For numerical fields this is (optionally) followed by a range of valid values. For example, the above requires the parameter pmel_F_test_critical_value to be between 0.9 and 1.0. When used the actual value will extracted and elog_die is called if the parameter read is outside this range.

LIBRARY

$(STOCKLIBS) -lglputil

DIAGNOSTICS

Announces offending parameters and dies on all errors.

SEE ALSO

pf(3)

BUGS AND CAVEATS

Should probably also allow Arr and Tbl parameters in require list, but this has not been implemented. The function should probably scan the entire list listing all errors and then terminating. Instead it dies on each error which may require multiple false starts to get a program running.

AUTHOR

Gary L. Pavlis
Indiana Univesity
pavlis@indiana.edu

Antelope User Group Contributed Software
Printer icon