Dynamic tailoring of the Newstar program-parameter interface ------------------------------------------------------------ Contributed by Johan Hamaker, 940916 Statement of the problem ======================== The DWARF parameter interface and the way it is harnessed in the Newstar programs is plagued by several problems that confuse the user: - many keywords are used in multiple places serving multiple, often quite different, functions ("keyword overloading"); - since DWARF allows only static definitions of keyword prompt, options and help text, the information provided to the user in a prompt is either too generic (in order to cover all functions for which the keyword is used) or confusing (when a keyword is re-used in a context that differs from the one it was designed for); - the logic underlying the order in which prompts are presented is in many places different from a user's natural expectations. Following the DWARF design philosophy a proper solution would be to split overloaded keywords into multiple ones; in addition the order of the prompts could be made more natural to the uninitiated user. Both of these options are unacceptable because of their pervasive impact on existing batch procedures. In trying out various ways to patch the situation I noticed that the only information that a user can hardly avoid noticing is that provided in the prompts (and in the help texts if he consults these). Everything else is very easily overlooked. The problem, then, is to provide prompts, options and help texts specific to each of the quite different contexts in which a keyword may be used, without resorting to changing the keywords themselves. In other words, we want a method enabling programs to set these prompt components dynamically. As a practical matter, the method should have a minimal impact on the existing programs. The new subroutine WNDPOH ========================= A new routine WNDPOH has been created that accepts dynamic Prompt, Options and Help strings. These will be used in the subsequent parameter prompt (directly through WNDPAR or indirectly through WNDNOD, NSCHAS etc.). The prompt and options strings replace those in the .ppd file; the help text may either be inserted in front of the .pps text or replace it. Thus, the call sequence is simply CALL WNDPOH (, , ) CALL WNDPAR (... or CALL WNDPOH (, , ) CALL NSCHAS (... etc. There is no need to clear the strings later, this is done automatically once an answer from the user has been accepted. Details on the call arguments ----------------------------- The help text may contain newline directives in the WNCTXT format: !/. It is recommended to format help text in lines that will fit in single 80-character Fortran lines and extend the quoted string over as many continuation lines as are necessary, e.g. CALL WNDPOH( 1'Target node to which to write corrections',' ', 3'SET COPY copies the average telescope corrections from 1 complete!/ 3input sector to selected parts of any number of output sectors.') A help text ending in a line '#-' signals that the text OVERRIDES the .ppd help text rather than being prepended to it (so the .ppd text will not be shown). The and strings are limited to 128 characters, the text to 512 (or a few less). Blank arguments to WNDPOH are ignored, i.e. they leave the corresponding dynamic text unaltered. Where to program dynamic prompting ---------------------------------- The following is a list (possibly still incomplete) of keywords and subroutine calls that may need dynamic prompting. A complete example of how I envisage the use of WNDPOH is in ncadat.for. all _NODE keywords (WNDNOD) all _SETS keywords (WNDST) all _LOOPS keywords (WNDXLP) in those cases where the loop controls more than one ,xxx>_SETS stream SELECT_XYX (NSCPL) when used to select telescope rather than interferometer polarisations. In this case the dynamic options are 'X,Y,XY', and the subsequent NSCPLS call must read CALL NSCPLS(XY_P,) where XY_P is defined in CBITS_DEF SELECT_IFRS (NSCIF), SELECT_TELS (NSCTL) in those cases where it is not obvious to which stream (input or output) the selection pertains. Limitations =========== 1. The dynamic information is not included in the hypertext display for the keyword, because the hypertext source file is a static derivate of the .psc or .pef file. For this reason the dynamic information is always shown on the terminal for all forms of on-line help requests. 2. As stated before, the method can not change the order in which prompts appear. 3. Since the dynamic texts are provided by the program, they are not available to dwspecify. I consider this a minor disadvantage since dwspecify is a primitive program in other ways as well. For interactively setting up parameter values dwexe/norun is a much better alternative that does have access to the dynamic texts. APPENDIX: Implementation ======================== WNDPAR through GET_PARM calls on routines PPD_PRSTR_GET, PPD_OPSTR_GET and PPD_HSTR_GET to fetch the prompt, options and help strings from the .ppd file. To allow a program to modify e.g. the prompt dynamically, a new entry point PPD_PRSTR_LSET was created. It takes a prompt string as argument and stores it in an internal buffer. When PPD_PRSTR_GET is called later, it checks this buffer and if it finds anything there, uses it instead of the .ppd prompt. The same method is used to allow dynamic options and help texts; a dynamic help text may either override the static text or be inserted in front of it. A terminating line '#-' is inter[reted as an 'override' flag. For the programmer's convenience, a single routine is available to set dynamic information pertaining to the subsequent direct or indirect (through another routine such as WNDSTA) WNDPAR call. The dynamic information will be used in the prompt and any automatic repeat of it; it will then automatically be cleared. Automatic clearing ================== Subroutines like WNDNOD, WNDSTA, NSCIFS are called in various contexts, so the use of WNDPOH with them is desirable. Internally, these routines call WNDPAR and may do so repeatedly in case of an incorrect reply. For this reason WNDPAR can not automatically clear the dynamic strings. The solution is for the calling subroutines to set an 'inhibit clearing' flag. WNDPAR will only clear the dynamic strings if this flag is clear. Any routine that sets the flag is responsible for clearing both the falg and the strings, through a call to WNDPOHC. The flag must be accessible to several routines and must therefore reside in a COMMON block. At present the location A_J(0) defined by WNG_DEF is used because it was available. This solution is sound except that it is invisible outside the routines that use the flag; an unexpected conflict could arise later when someone decides that he may use this location for another purpose.