Operation of parameter files


User Information

FTOOLS makes use of parameter files, or pfiles, to provide flexibility and customization to users. A pfile defines all the parameters the user can specify to affect the operation of an ftool. Common parameters include the input and output file names, the rows and columns of a table on which to operate, and a flag determining whether or not to overwrite existing files. The parameters available for each FTOOL can be found either by reading the tool's help file (e.g., fhelp fverify) or by listing the parameter file itself (e.g., plist fverify) which produces the following output:
    Parameters for /home/wilson/pfiles/fverify.par
           infile = table2.fits      Name of FITS file to verify
          outfile = STDOUT           Name of optional output file
          (prhead = no)              Print header keywords?
        (testdata = yes)             Test every data value?
         (clobber = no)              Overwrite existing output file?
            (mode = ql)              
The first two parameters are "required" parameters; the user must specify their value every time the tool is run. The rest are "hidden" parameters and identified by their being located within parentheses. If the user does not explicitly tell the ftool to use a different value, hidden parameters will be assigned their default values. (mode is a special parameter in all the parameter files and is used by the pfile mechanism, not the ftool.) Values can be assigned to parameters either on the command line or by being queried by the program itself. On the command line, values to be assigned to required parameters can be simply listed in the same order as present in the pfile. To assign values to hidden parameters, you must specify a value on the command line, preceding the value with the parameter name and an equals sign. One example of a complete command line function call is:
    > fverify spectrum.fits output.file testdata=no
In this case the tool will run without any further input from the user, sending all output to the file output.file. If you do not specify all the required parameters on the command line, the program will ask you to supply values for them, like this:
    > fverify<cr>
    Name of FITS file to verify[table2.fits] spectrum.fits<cr>
    Name of optional output file[STDOUT] <cr>
The string within the square brackets is the default value which will be used if the user simply hits return (<cr>). If you have run this ftool before, the default value will normally be the value you used the last time. You will not be queried for hidden parameters.

There are two sets of parameter files. System pfiles, normally located in the same directory as the FTOOLS binaries, are the original parameter files shipped with FTOOLS. Many of the parameters have undefined default values. User pfiles, normally located in a directory called pfiles in the user's home directory, are modified after each use of an ftool such that the parameter values used by the user this time become the default values next time.

The actual locations of the parameter files are determined by the environment variable PFILES defined as a pair of paths separated by a semicolon with the user pfile location given first. It will look something like this:

    /home/wilson/pfiles;/local/ftools/SunOS_4.1_sparc/bin
When the user runs a given ftool, the user's pfile directory is checked for a pfile for that tool, named ftool.par. If one is found, its modification date is compared to the system pfile. If the system pfile is more up-to-date (e.g., a new version of FTOOLS has been installed), it is copied to the user's pfile directory, overwriting the old version. (This behavior can be overriden by unsetting the PFCLOBBER variable--unsetenv PFCLOBBER--in which case the user's pfile is always used if present.) If the user does not have a pfile for the ftool in the directory, a copy of the system pfile is placed there.

Several ftools are available for the manipulation of pfiles and their default values.

Developer Information

Every FTOOL must have a corresponding parameter file. The following lines specify the single parameter, "dummy", used by the task cdummyftool:

    # cdummyftool.par
    dummy,s,a,"Hello, World",,,"Enter a string"
    mode,s,h,"ql",,,
Any line which starts with a # is a comment. Otherwise, lines in the parameter file must follow this format:

    name, type, parameter mode, default value, lower limit, upper limit, prompt
The meanings of these seven fields is as follows. The name is obviously the name of the parameter. The type is the data type: either b for boolean, i for integer, r for real, or s for string. There are routines in the Xanadu Parameter Interface (XPI) library designed to read each of these data types, e.g. Uclgst for strings, Uclgsi for integers, etc. The rest of the line governs how a value for the parameter is obtained by the XPI at run time, and is most easily explained through examples. First, suppose the following line were in the parameter file:

    month,i,q,7,1,12,"Enter the number of the current month:"
Because the second field is "i", this parameter is of integer type. To read the parameter "month", an appropriate C XPI call would be:
    Uclgsi("month", &mnum, &status);
where mnum and status are both declared as int. For Fortran, the call would be:
    call uclgsi('month', mnum, status)
with mnum and status both declared as integer. Because the third field, the parameter mode, is "q", which stands for "query", when Uclgsi, or uclgsi, is called, the user would be prompted with the following:
    Enter the number of the current month:[7]
Note that "7", the default value specified in the fourth field, is displayed in brackets in addition to the prompt string specified in the last field. (The value of 7 is reasonable, since most users learn about FTOOLS during the slower summer months...) Should the user enter an illegal value for the month number, like 14, the value will not be accepted, because it is out of the range specified by the lower and upper limits, 1 and 12, given in the fifth and sixth fields. The user will be prompted repeatedly until a value which is between the limits is entered.

Next, consider how Uclgsi handles this line if the parameter mode is not "q" but "h":

    month,i,h,7,1,12,"Enter the number of the current month:"
            ^
The letter "h" stands for "hidden", and is interpreted by the routine Uclgsi to mean that the user will not be prompted at all for this parameter! The default value will be used without comment unless the user explicitly enters, for example, the string "month=9" on the command line.

The mode may optionally contain a second character, "l", which stands for "learned":

    month,i,ql,7,1,12,"Enter the number of the current month:"
             ^
This instructs the XPI to save whatever value is ultimately used in the current run of the FTOOL and use it as the default value in subsequent runs. For example, suppose the user runs the FTOOL twice using this last parameter line, and the first time, enters the value 9:

    Enter the number of the current month:[7] 9
                                              ^
The second time the FTOOL is run, the prompt would be:

    Enter the number of the current month:[9]
                                           ^
If the mode did not contain the "l", the default value would remain 7 no matter how many times the FTOOL was run.

The last possibility for the mode is the single letter "a", which stands for "automatic":

    month,i,a,7,1,12,"Enter the number of the current month:"
            ^
This sets the mode to assume a default value, which is most frequently "ql", just like the previous example. Even this default parameter mode can be set in the parameter file. Every FTOOL parameter file includes an extra parameter, named "mode". This parameter chooses the default mode, that is, the mode used by parameters whose mode is "a":

    mode,s,h,"ql",,,
In other words, the two lines:

    month,i,a,7,1,12,"Enter the number of the current month:"
    mode,s,h,"ql",,,
are equivalent to the one line:

    month,i,ql,7,1,12,"Enter the number of the current month:"
The advantage of using the automatic mode becomes clear if one wants to switch a large number of parameters between different modes. For instance, when one is working with a new FTOOL, or a new group of data, one may wish to use the mode "ql", which forces the user to enter the parameters, and remembers values, thus saving one some typing. Once a routine is established and parameter values are not changing much from one run to the next, however, it may be more convenient to use the mode "h", thus tacitly using the same values on every run. This is more easily accomplished using "a" for the parameters one wishes to change and changing "ql" to "h" once for the parameter named "mode", than it is to change "ql" to "h" for each parameter individually.

Lastly, as mentioned above, any value the user gives on the command line is used no matter what is in the parameter file. This makes it possible to write scripts which will work for ANY user of the FTOOLS, regardless of how that individual has tailored his or her particular set of parameter files.

In summary, parameter files, together with the XPI, form an elegant and flexible interface which permits users of the FTOOLS to provide values to the FTOOL at run time, either on the command line, in the parameter file, or in response to prompts. Each parameter is described by a seven field line in the parameter file, delimited by commas. The first three fields, the name, data type and parameter mode, are required. Names must be no longer than eight characters, data types must be either "b", "i", "r" or "s", and valid parameter modes are "a", "q", "h", "ql" or "hl". The last four fields, the default value, lower limit, upper limit and prompt string, are optional, and the lower limit and upper limit are only relevant for numerical data types.


FTOOLS HELP DESK

If FTOOLS has been useful in your research, please reference this site (http://heasarc.gsfc.nasa.gov/ftools) and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

Web page maintained by: Bryan K. Irby