diff options
Diffstat (limited to 'doc/pset.ms')
| -rw-r--r-- | doc/pset.ms | 433 |
1 files changed, 433 insertions, 0 deletions
diff --git a/doc/pset.ms b/doc/pset.ms new file mode 100644 index 00000000..b7193a08 --- /dev/null +++ b/doc/pset.ms @@ -0,0 +1,433 @@ +.LP +.ps +1 +.ce +\fBNamed External Parameter Sets in the CL\fR +.ps +.ce +\fIand related revisions\fR +.ce +Doug Tody +.ce +October 1986 +.sp 2 + +.NH +Introduction +.PP +The CL has recently been modified or extended in a number of areas to support +named, shareable parameter sets. The purpose of this memo is to document the +changes and the new facilities. All revisions are upwards compatible with +previous versions of the CL. + +.NH +Parameter Set Extensions +.PP +The major modification to the CL was the addition of support for named external +parameter sets, breaking the one-to-one relationship between tasks and what +were formerly called parameter files. This was done to make it possible to +better structure the parameter sets of tasks with very large numbers of +parameters, and to make it possible for tasks which use the same piece of +code to share a common parameter set. +.PP +It should be emphasized that most tasks are not expected to need the new pset +facilities, and the use of a single main task parameter set should prove the +simplest and best approach for most tasks. Tasks which would otherwise have +very large parameter sets, subsets of which would appear in the parameter sets +of other tasks in the same package, are most likely to benefit from the use of +the new pset facilities. + +.NH 2 +Conceptual Model +.NH 3 +Pset Tasks +.PP +A \fIpset-task\fR is an object whose function is to maintain a global set of +parameters for access by other tasks or by the user. Pset tasks may be either +visible or hidden, but normally they serve an important role in describing +some data object or controlling some algorithm, hence they should be a visible +and well documented part of the user interface to a package. One of the main +reasons for implementing a named pset as a type of task is this desire to have +them be a visible part of the user interface. They appear in the package menu, +have on-line manual pages, can be run as tasks (\fIeparam\fR is called up to +edit the pset), and their contents (the pset parameters) can be accessed using +the facilities already provided for accessing the parameters of an ordinary +executable task or package. +.PP +A named pset is very similar to a global (external) data structure in C. +Psets and tasks are two different but equally viable classes of objects from +which packages are constructed. In a sense it is not correct to think of +a pset as a type of task, rather, psets and tasks are instances of some more +abstract type of object, and a package is a collection of objects of various +types which operate upon a particular kind of data. +.PP +Examples of psets are the control parameters for a sky fitting or centering +algorithm, the control parameters for a graphics plotting utility (e.g., an +axis drawing and labelling routine), or a set of parameters describing the +characteristics of a particular type of data. The conceptual basis of a pset +should be obvious to the user, else the use of a pset is probably not justified. +.PP +By concentrating the information pertaining to a particular object in one place, +a pset can significantly reduce the complexity of a large package without loss +of flexibility or control. The information hiding capability of a pset can +reduce the coupling between the modules of a large package or task, much as +the use of an opaque external data structure (descriptor or handle) can reduce +the coupling between the procedures in a large program. +.NH 3 +Pset Parameters +.PP +A pset parameter serves as a pointer to an external parameter set. A pset +parameter is a string valued parameter of datatype \fIpset\fR. The string +value of the parameter is the filename or taskname of the pset to be used +when the task is run. If the value of the pset parameter is the null string, +the parameter set of a pset-task with the same name as the pset parameter +will be used. All pset parameters in a package that refer to the same type +of pset should have the same name, and a pset-task of the same name should +be defined in the package to define the contents of the parameter set and +to supply default values (if appropriate) for the parameters. +.PP +Whereas a pset-task is a named, statically allocated instance of some data +structure, much like a C external data structure, a pset parameter is like +a C structure pointer. Imagine a C function which takes a pointer to an +external structure as an argument. If the value of the pointer is null +the function references a particular default global structure, otherwise the +referenced structure is used. Within the program the external structure is +always referred to via the pointer, regardless of the name or storage class +of the particular external data structure being referenced. This is very +similar to the way psets are used in CL programs. +.NH 3 +Relationship to other Data Structuring Facilities +.PP +The main parameter set of a CL task is very similar to the arguments and local +variables of a conventional compiled procedure. The pset construct adds a +basic data structuring capability to the CL. It is not surprising that, +just as data structuring becomes increasingly important as the size of a +compiled program or package increases, we should start to experience the +need for it in our large CL tasks and packages. Part of the need can and +should be met by non-CL data structures, e.g., image structures and various +kinds of database facilities, but the CL pset mechanism offers unique +facilities for queries and command line parameter assignments which are not +provided by these other, more lower level facilities. In general, the pset +mechanism should be used for high level interactive control, and the lower +level data structures should be used to access and store large quantities +of data. + +.NH 2 +Implementation of Psets +.PP +A pset-task is declared with the \fItask\fR or \fIredefine\fR statements +in much the same way that a CL script task is declared, except that the +filename extension of the referenced file is \fL.par\fR rather than \fL.cl\fR. +For example, +.DS +\fLtask skypars = "mypkg$skypars.par"\fR +.DE +adds the new pset-task \fIskypars\fR to the current package. The parameter +set of a pset-task is initially read from the named file in the package +directory and is updated in the the users \fLUPARM\fR directory, just as +for a conventional task. For those who prefer to have their parameter +declarations parsed, the actual declarations file may be a \fL.cl\fR file, +e.g., \fLskypars.cl\fR, but the extension \fI.par\fR must still be used in +the \fItask\fR statement. A pset-task may be called like any other task, +with or without arguments on the command line; the function of a pset-task +is to call up \fIeparam\fR to edit and update the parameter set. +.PP +A pset parameter is declared like any other parameter except that the +datatype is specified as \fIpset\fR. For example, either +.sp +.nf +\fL skypars,pset,h,,,,"sky fitting parameters"\fR +or +\fL pset skypars { prompt = "sky fitting parameters" }\fR +.fi +.sp +would suffice to declare the pset parameter \fIskypars\fR in the parameter +set for some task. +.PP +Binding of a pset parameter to a particular instance of the referenced +parameter set occurs when a task is \fIexecuted\fR. This means that the +pset parameter must be set to point to the pset to be used either before +the task is called, or on the command line when the task is called. +The pset parameter should not be changed to point to a different pset while +a task is executing. +.PP +When a task is invoked the main task parameter set and all external psets are +loaded into memory and the names and values of all the non-query parameters +therein are passed via IPC to the CLIO cache in the subprocess. The query +mechanism works exactly the same for pset parameters as for the main task +parameters. For example, if a parameter does not have a valid value or the +effective mode is something other than hidden, the parameter is not cached +in the subprocess during task startup, and a query will result if the parameter +is referenced at runtime. The values of pset parameters may be set with +\fIclput\fR calls and the parameter set will be updated if the task exits +normally, just as for the main task parameter set. +.PP +The runtime context of a task which has a parameter set has always included +three different psets, the main task pset, the pset of the package in which +the task is defined, and the global CL pset; runtime parameter references +are resolved by searching the three psets in the order \fItask-pkg-cl\fR. +This mechanism has been extended to include any psets referenced in the +main task pset. For example, if the task references the two psets A and B, +the search path for a parameter is \fItask-A-B-pkg-cl\fR. If the package +itself references psets they will be loaded when the package is loaded, +since a package is a type of task, however the use of psets in the parameter +set of a package is not recommended (cacheing frequently used psets at package +load time may be desirable, however). +.PP +Since the psets are included in the search path for a runtime parameter +reference, the pset name is optional when specifying a parameter. +This has two major implications: first, the parameters to a task may be +organized into psets without the applications code having to know about +the existence of the psets, and second, the user may override the values +of pset parameters on the command line when a task is invoked, without +having to specify the pset name., i.e., \fIparam=value\fR rather than +\fIpset.param=value\fR. The full syntax is however supported for both +command line and runtime parameter references, and should be used in +applications code to eliminate the possibility of name collisions, +to improve error detection, and to speed searches. +.PP +In the current implementation of the CL, psets may not reference other psets. +There is nothing in the conceptual model of a pset which excludes this, +but it would complicate the implementation considerably and the use of such +a feature would probably be undesirable in any case. +.NH 3 +Example +.PP +A brief example may help to clarify the discussion presented in the last +section. Assume we have a task \fIcenter\fR with the following parameters +(a real task would have lots more): +.DS +\fLimage,s,a,,,,"image name" +objlist,*imcur,a,,,,"list of initial object centers" +cenpars,pset,h,,,,"centering algorithm parameters" +skypars,pset,h,,,,"sky fitting algorithm parameters"\fR +.DE +Assume further that the \fIskypars\fR parameter set contains a parameter +\fIksigma\fR defining the k-sigma cutoff level for some iterative rejection +feature of the sky-fitting algorithm. +.LP +The task would normally be called as follows when working interactively: +.DS +\fLcl> center pix\fR +.DE +This would run the task, taking cursor input interactively from the image +display, using the default centering and sky fitting parameter sets. +To use a different set of centering algorithm parameters, stored in the +file \fLcen1.par\fR in the current directory: +.DS +\fLcl> center pix cen=cen1.par\fR +.DE +To use the default parameter sets, but override the value of the \fIksigma\fR +parameter in the \fIskypars\fR parameter set: +.DS +\fLcl> center pix sky.ksigma=3.5\fR +.DE +Assuming that the \fIcenpars\fR parameter set does not also contain a +\fIksigma\fR parameter, this could be shortened to: +.DS +\fLcl> center pix ksigma=3.5\fR +.DE +The default \fIcenpars\fR and \fIskypars\fR parameter sets would be stored +in the files \fLcenpars.par\fR and \fLskypars.par\fR (or in equivalent \fL.cl\fR +files) in the package source directory. + +.NH 2 +CLIO Pset Extensions +.PP +The CLIO package has been modified to support the new CL pset facilities. +The major modification was the addition of a subpackage of get/put routines +to be used to access parameters in named psets. These are very simple +routines, provided to avoid having programs explicitly reference the pset +name in every \fIclget\fR or \fIclput\fR call, and to eliminate the need +for string concatenation to construct the \fIpset.param\fR parameter name +if the pset name is parameterized. The new routines are summarized below. +.sp +.TS +center; +n l. +pp = \fLclopset\fR (\&psetname) open pset +\fLclcpset\fR (\&pp) close pset +pval = \fLclgpset\fR[\fLbcsilrdx\fR] (\&pp, param) get parameter +\fLclppset\fR[\fLbcsilrdx\fR] (\&pp, param, pval) put parameter +\fLclgpset\fR (\&pp, param, sval, maxch) get string parameter +\fLclppset\fR (\&pp, param, sval) put string parameter +.TE +.LP +The CLIO pset routines are functionally equivalent to the corresponding +\fIclget\fR and \fIclput\fR routines except that ``\fIpsetname.\fR'' is +prefixed to the given parameter name to form the full parameter name +before the parameter value is retrieved or updated. The string \fIpsetname\fR +is the name of the pset parameter (pset pointer) in the main parameter set +of the calling task. +.PP +Continuing with the example presented in \(sc2.2.1, we would open the pset +and fetch the \fIksigma\fR parameter as follows: +.DS +\fLpp = clopset ("skypars") +ksigma = clgpsetr (pp, "ksigma")\fR +.DE +.LP +A conventional \fLksigma = clgetr ("ksigma")\fR statement could also have +been used, in which case the CL would search for the named parameter using +the search path described in \(sc2.2, referencing the first parameter found. +Use of the CLIO pset routines will be preferable in most applications since +they eliminate the possibility of the wrong parameter being referenced. + +.NH +Eparam and Lparam Extensions +.PP +The \fIeparam\fR and \fIlparam\fR tasks have been modified to work upon either +the main parameter sets of tasks (as before), or upon named parameter files. +The presence or absence of a \fL.par\fR filename extension is used to +determine whether an operand is a taskname or a filename. For example, +.DS +\fLcl> eparam skypars.par\fR +.DE +will edit the parameter \fIfile\fR \fLskypars.par\fR in the current directory, +whereas +.DS +\fLcl> eparam skypars\fR +.DE +will edit the parameter set for the pset-task \fIskypars\fR. +Lastly, since \fIspypars\fR is a pset-task, we could just type +.DS +\fLcl> skypars\fR +.DE +to edit or review the contents of the pset. +.PP +The parameter file \fLskypars.par\fR in the above example would probably be +created using the new colon-command extensions to eparam. The original +eparam supported only single keystroke editing commands. The new colon +commands are used to enter command lines of arbitrary length to be processed +by eparam. +.PP +A colon command is entered by typing the colon character (`\fL:\fR') while +the cursor is positioned to the starting column of any value field of the +parameter set being edited. The colon character is not recognized as a +special character beyond column one, e.g., when entering the string value +of a parameter. When colon command mode is entered, the colon character +will be echoed at the start of the bottom line on the screen, and the cursor +will move to the character following the colon, waiting for the command to +be entered. The command is read in raw mode, but the usual delete, +<ctrl/c>, <ctrl/u>, etc. sequences are recognized. +.PP +The following eparam colon commands are currently supported. All commands +are carefully error checked before being executed to avoid having eparam +abort with a stack trace. An illegal operation causes colon command entry +mode to be exited, leaving an error message on the command entry line. +All commands which cause editing of the current pset to terminate may include +the \fL!\fR character to avoid updating the current pset before reading in +the new one or exiting eparam. The default is to update the current pset. +In all cases, \fIpset\fR may be either the name of a task or the name of a +parameter file. Parameter files are always indicated by a \fL.par\fR +extension, even though the actual file may be a \fL.cl\fR file: +only \fL.par\fR files will be written, although either type of file may be read. +.sp +.RS +.IP \fB:e\fR[\fL!\fR]\ [\fIpset\fR] +.br +Edit a new pset. If \fIpset\fR is omitted and the cursor was positioned to +a pset parameter when the colon command was entered then eparam descends into +the referenced pset; when editing of the sub-pset is complete eparam returns +to editing the higher level pset at the point at which the ``\fL:e\fR'' +command was entered. If a pset is named the editor context is switched to +the new pset, updating the current pset first unless the ``\fL:e!\fR'' command +was given. +.sp +.IP \fB:q\fR[\fL!\fR] +.br +Exit eparam for the current pset; equivalent to a <ctrl/z>. The variant +``\fL:q!\fR'' causes eparam to be exited without updating the current pset. +Entering this command when editing a sub-pset causes an exit to the higher +level pset. To abort eparam entirely without updating anything, <ctrl/c> +should be used. +.sp +.IP \fB:r\fR[\fL!\fR]\ [\fIpset\fR] +.br +Read in a new pset. If the command is ``\fL:r\fR'', an error message is +printed. If the command is ``\fL:r!\fR'' the pset currently being edited +is reread, cancelling any modifications made since the last update. +If a pset is specified the contents of the named pset are merged into the +current pset, i.e., the named pset is loaded into the current pset, +overwriting the contents of the current pset. +The command ``\fL:r pfile.par\fR'' is commonly used to load a pset formerly +saved in a user file with ``\fL:w pfile.par\fR'' into the UPARM version of +the parameter set for a task. +.sp +.IP \fB:w\fR[\fL!\fR]\ [\fIpset\fR] +.br +Write or update a pset. If \fIpset\fR is omitted the pset currently being +edited is updated on disk. If \fIpset\fR is given it should normally be the +name of a parameter file to be written. If the file exists an error message +will be printed unless the command ``\fL:w! pfile.par\fR'' is given to force +the file to be overwritten. +.sp +.IP \fB:g\fR[\fBo\fR][\fL!\fR] +.br +Run the task. Eparam exits, updating the pset and running the task whose pset +was being edited. This is implemented by pushing a command back into the input +stream of the task which called eparam, hence if eparam was called in a script +or with other commands on the same line, execution may be delayed until these +other commands have been edited. The feature works as expected when used +interactively. Since the run command is pushed back into the command input +stream it will appear in the history record and in any log files. +.RE + +.LP +To get out of colon command mode without doing anything, simply type delete +until the colon prompt is deleted and the cursor returns to the parameter +it was positioned to when colon command entry mode was entered. + +.NH 2 +New Task Dparam +.PP +A new builtin task \fIdparam\fR (dump-parmeters) has been added to the +\fIlanguage\fR package. This task is similar to \fIlparam\fR except that the +output is formatted in a way which is more convenient for use in scripts +or as input a program, whereas \fIlparam\fR output is intended more for the +user. The \fIdparam\fR task dumps the parameters for the named psets, +one parameter per line, in the format \fItask.param\ =\ value\fR. Nothing +is abbreviated or truncated. The value string will be absent if the value +of the parameter is undefined. Array valued parameters are not supported. + +.NH +Pfile Access Semantics +.PP +The code which reads and writes parameter files had to be almost completely +rewritten to accomodate the above features. In the process several other +improvements were made. +.IP \(bu +The old "Warning: pfile X is out of date" message will no longer be seen. +If the package pfile is newer than the user copy of the pfile, the package +pfile will be read and the parameter values from the old user pfile will +be merged into the new pfile. This preserves the learned parameter values +but allows the master pfile to change, e.g., new fields can be added, old +fields deleted, or the names of parameters may be changed. If an old parameter +cannot be found in the new pfile the old value is simply discarded. +.IP \(bu +Zero length \fLUPARM\fR pfiles are now detected, causing the package pfile +to silently be read. +.IP \(bu +A bug was fixed which would sometimes cause \fIunlearn\fR to fail. +.IP \(bu +The low level CL procedure which reads a pfile will look for a \fL.par\fR +file followed by a \fL.cl\fR file with the same root name, allowing either +type of pfile to be used virtually anywhere. + +.NH +Showtype Option in Package Menus +.PP +A new boolean parameter \fLshowtype\fR has been added to the set of global +CL parameters. If this option is enabled the special tasks will be flagged +in package menus by appending a character to the end of the taskname. +Currently, two types of special tasks are recognized thusly: package script +tasks are marked with a trailing `\fL.\fR', and pset-tasks are marked with +a trailing `\fL@\fR'. The default value of this switch is currently \fLno\fR +for compatibility with previous versions of the CL. +.PP +In order for the \fIshowtype\fR option to work properly for package script +tasks, the CL must be informed that the script will define a new package +when executed. This was done by extending the syntax recognized by the +\fItask\fR statement to permit a \fL.pkg\fR extension on the taskname. +For example, \fLtask plot.pkg = "plot$plot.cl"\fR defines the new +package-task \fIplot\fR. The \fL.pkg\fR is optional and it is harmless if +it is omitted, but the \fIshowtype\fR option will not work properly without it. |