|AHELP for CIAO 4.2||
Query a parameter value from S-Lang.
String_Type pquery( paramfile, param )
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:
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.
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.
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.
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.
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.
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.
See the bugs page for the paramio module on the CIAO website for an up-to-date listing of known bugs.