Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/paramio_pquery.html
AHELP for CIAO 4.2

pquery

Context: paramio

Synopsis

Query a parameter value from S-Lang.

Syntax

String_Type pquery( paramfile, param )

Description

This function is essentially the same as the command-line version (see "ahelp tools pquery"), although only one parameter - the param value above - can be queried at a time. The parameter value is always returned as a string by this function.

The paramio module is not available by default; to use it in a S-Lang program, it must be loaded using the S-Lang require() function:

  require("paramio");

paramfile is a string

If called with the name of the parameter file then the function will, if it is not a hidden parameter, prompt the user and then return the selected value.

paramfile is a Param_File_Type variable

The behaviour is the same if the paramopen() call was made without supplying the optional third argument. If the third argument was given then, before querying the user, the routine searches for the parameter value among these values. If the parameter is found in this list then the user will not be queried for the value. This behaviour is useful when writing S-Lang scripts that use a parameter file; see the examples below and those in "ahelp paramio" for more information.

Error handling

As with all the paramio routines, the PF_Errno variable is set to 0 on success, or on error it is set to one of the error codes listed in the paramio documentation.

Example 1

slsh> require("paramio");
slsh> punlearn("dmcopy");
slsh> pset( "dmcopy", "infile", "in.fits" );
slsh> ifile = pquery( "dmcopy", "infile" );
slsh> ifile;
in.fits
slsh> clval = pquery("dmcopy","clobber");
slsh> clval;
no

The pset() call sets the value for the infile parameter of dmcopy to "in.fits". We then call pquery() to find its value and - since it is not a hidden parameter - we are prompted for a value. In this example we accept the default value, and so the contents of ifile are "in.fits".

The query of the "clobber" parameter does not result in an interactive query since it is a hidden parameter.

Example 2

slsh> punlearn("dmcopy");
slsh> fp = paramopen("dmcopy","rw");
slsh> pset( fp, "infile", "in.fits" );
slsh> ifile = pquery( fp, "infile" );
Input dataset/block specification (in.fits): test.fits
slsh> ifile;
test.fits
slsh> pget( fp, "infile" );
test.fits
slsh> paramclose(fp);
slsh> pget( "dmcopy", "infile" );
test.fits

In this example, since we explicitly open the parameter file as read-write, the pquery() call results in the parameter file being changed.

Example 3

slsh> args = [ "dmcopy", "test.fits", "out=out.fits", "cl+" ];
slsh> fp = paramopen("dmcopy","rw", args );
slsh> ifile = pquery( fp, "infile" );
slsh> ifile;
test.fits
slsh> ofile = pquery( fp, "outfile" );
slsh> ofile;
out.fits
slsh> clval = pquery( fp, "clobber" );
slsh> clval;
yes
slsh> paramclose( fp );
slsh> pget( "dmcopy", "outfile" );
out.fits
slsh> pget( "dmcopy", "clobber" );
no

Here we use the three-argument form of paramopen() to set parameter values as if the command had been run from the command-line. Since the parameter values for "infile" and "outfile" are contained in the parameter list (the args array here), the pquery() calls do not need to ask the user what the value is. And, as the parameter file was opened with a mode of "rw", these new parameter settings are written to the parameter file if the parameter mode is not "hidden".

Although this example was run within Slsh, it is more likely to be useful when run from a S-Lang script executed by slsh; see "ahelp paramio" for an example of this.

Bugs

See the bugs page for the paramio module on the CIAO website for an up-to-date listing of known bugs.

See Also

concept
parameter
modules
paramio
paramio
paccess, paramclose, paramopen, pget, pgets, plist_names, pset, punlearn
tools
dmhistory, dmkeypar, dmmakepar, dmreadpar, paccess, pdump, pget, pline, plist, pquery, pset, punlearn

Last modified: December 2009