|Temporary feature: subject to change|
Most nontrivial applications need a way to customize their initialization, typically by specifying commands to be executed when the application starts up or initial values of symbols used by the application. Until now, each application has had to do this customization in its own way, usually by creating a special-purpose file with its own syntax and reading the file in as the application started. This led to an abundance of special-purpose initialization files with different formats. The new facilities provide a simpler, more uniform way of specifying and processing initialization files, as well as a way for all the initializations to reside in a single file.
Because these facilities are relatively new, they are subject to improvement. The format of parameter files, the names and values of parameters for individual XIDAK applications, and the PROCEDUREs used to process parameters within a program are all subject to change.
28.1. The v1630.prm File
When MAINSAIL starts up, it tries to open and read two parameter
First it tries to read a file on the home directory, and then
(if the current directory is not the home directory) it
tries to read one on the current directory,
so that if both files exist the parameters in the current directory
are read in after those in the home directory (in many cases, this
will mean that parameters in the current directory override those
from the home directory).
The name of the file is the same in both directories;
it is formed from the letter v, the current major version number
of MAINSAIL, the current minor version of MAINSAIL, and the
Thus, in version 16.30,
the name of the file is v1630.prm.
These files may contain initialization parameters for any number of applications, including the initial subcommands for MAINEX.
Applications may have parameter files in addition to the default v1630.prm files, but either the application must arrange to read the parameters from such files explicitly, or the v1630.prm files themselves must contain directives to read such files; the v1630.prm files are the only ones that are read automatically by MAINSAIL when MAINSAIL initializes itself. Section 28.2 describes the $INCLUDE command that may appear in a parameter file to direct MAINSAIL to read another file; Section 28.4 tells how a program can read a parameter file explicitly.
. . .
Blank lines, page marks, and comment lines are discarded on input. A comment line has # as the first nonblank character and continues to the end of the line.
A group is a named grouping of parameters. The writer of the application that uses a group decides what parameters constitute a group. A parameter file may contain the parameters for a single application, with just one group, or may hold the parameters for many different applications, with each application constituting a group. For example, the standard parameter file for MAINSAIL may contain groups for MAINEX, MAINEDIT, MAINDEBUG, and so forth, in addition to any other application that reads parameters from the default group list, $mslParms (see Section 28.4).
Each group name is converted to upper case on input. The $ENDGROUP directive marks the end of a group. It is optional; i.e., the keyword $GROUP automatically terminates the preceding group, if any.
Group names need not be identifiers; however, they may not contain white space characters (blanks, tabs, or end-of-line characters). A groupName that starts with $ should not be chosen by the user; such names are reserved for XIDAK use.
The same group can occur several times in a file. The parameters in the various occurrences of the same group are concatenated together in the order encountered.
groupName may be omitted, in which case it defaults to $DEFAULT. If a parameter is encountered outside of any $GROUP ... $ENDGROUP pair, it is added to the $DEFAULT group.
An $INCLUDE directive can occur on any line in a parms file:
The specified file must be a valid parameter file. The contents of each group in the file fileName are processed as if they occurred in the current file.
Each parameter has the following format:
parmName is converted to upper case on input. A parmName that starts with $ should not be chosen by the user; such names are reserved for XIDAK use.
The characters that make up the parameter value retain their original case. Continuation lines are indicated by a trailing \ character. A parameter with continuation lines has the following format:
parmName parmValue \
The resulting parameter value is:
parmValue & firstContinuationLine & ... & lastContinuationLine
Leading whitespace (space or tab characters) is
discarded from each line; extra whitespace between parmName and
parmValue is also discarded.
Thus the final parameter value cannot
contain leading or trailing whitespace or end-of-line characters.
The use of each of these groups is described in the documentation
for the relevant application.
28.3. Parameter Groups Used by XIDAK Software
The following groups are used by XIDAK software:
28.3.1. The Group $MAINEX
The group $MAINEX can contain any valid MAINEX subcommand as a
These commands are processed when MAINSAIL is initialized (but
not in subsequent recursively invoked MAINEX sessions, so
that only subcommands specified in the
v1630.prm ever take effect; any commands
that appear in the group $MAINEX
in subsequently read parameter files are not processed
28.3.2. The Group $COMPIL
The group $COMPIL can contain any compiler subcommand, as documented
in Section 4.1 of the MAINSAIL Compiler User's Guide.
The subcommands specified become the initial defaults for each
28.3.3. The Group $MAINEDIT
The group $MAINEDIT can have any of the previously documented
eparms keywords (see Chapter 2 of the MAINEDIT User's Guide) as a parameter
except for the CONTEXT, MACRO, NAMEDMACRO, and
(these keywords reside in the file eparms).
In addition, several global options (see Chapter 16 of the MAINED User's Guide)
can be set as parameters,
although the parameter names and option names are not always the same;
the correspondence is as follows:
The use of each of these groups is described in the documentation for the relevant application.
|Parameter Name||Global Option Name|
28.3.4. The Group $MAINED
The MAINED options stickyTabs and wordWrap are available as
In addition, the insertModeDefault option can be set by giving
the parameter defaultModule the value insert,
and the overstrikeModeDefault option can be set by giving
the parameter defaultModule the value overstrike.
The parameter autoSaveInterval is used to set the initial
value of autoSaveLimit.
The parameter tabStops is used to set tab stops, as if its value
were given as an argument to the Qtab command.
28.3.5. The Group $MAINDEBUG
The following options can be set as parameters:
|Parameter Name||Argument to OP Command|
The option is turned on if its argument is the keyword TRUE
and turned off if its argument is FALSE.
Group lists, groups, and individual parameter values are all represented
by the CLASS $parmCls, which has no user-visible fields:
28.3.6. Sample Parameter File
The following is a sample parameter file that contains groups
used by XIDAK software:
# This is a comment at the start of the file
28.4. How to Process Parameters in a Program
Parameters are processed in two steps:
Group lists, groups, and individual parameter values are all represented by the CLASS $parmCls, which has no user-visible fields:
CLASS $parmCls ( );
The v1630.prm file is read automatically when MAINSAIL starts up. The group list into which the v1630.prm file is read is called $mslParms:
Parameter files are read with the system PROCEDURE $readParms. A parameter file may be read either into the $mslParms group list or into a group list created by an application.
When an application processes group lists, it calls the PROCEDURE $findGroup to find a given group in a given group list. It then uses the PROCEDURE $nextParm to traverse the list of parameters in the group and retrieve the parameters' values.
The headers of the PROCEDUREs $readParms, $findGroup, and $nextParm are shown in Figure 28–1.
PROCEDURE $readParms (STRING filename;
OPTIONAL BITS ctrlBits);
PROCEDURE $findGroup (POINTER($parmCls) groupList;
OPTIONAL STRING name);
PROCEDURE $nextParm (POINTER($parmCls) groupOrParm;
PRODUCES OPTIONAL STRING
$readParms reads the groups from the file named fileName (if it exists) into the group list groupList. If groupList is not specified, a new group list is created; otherwise, information from the file is added to the existing group list groupList. The only valid ctrlBits bit is $dontTryHomeDir. If set, the fileName is opened exactly as specified. Otherwise, the fileName is assumed to be a simple (leaf) file name, and $readParms attempts to open the named file first on the current user's home directory, and then (if the current directory is not the home directory) on the current directory (this is the same behavior as with v1630.prm). Whether $dontTryHomeDir is set or not, no error is given if the file does not exist. $readParms returns a POINTER to the group list into which it read.
$findGroup finds the group named name in the group list groupList. If name is not specified, it defaults to $DEFAULT. If the named group is found, $findGroup returns a POINTER to it; otherwise, it returns NULLPOINTER.
$nextParm takes a POINTER to a group or to an individual parameter value. If groupOrParm is a group, it returns the first individual parameter value in the group; otherwise, it returns the individual parameter value following groupOrParm within the same group. In any case, $nextParm sets name to the name of the returned parameter and value to its value. $nextParm returns NULLPOINTER when groupOrParm is the last parameter in the group.
If gl is a group list in which you want to process parameters in the group myGroup, the code to do so would look something like:
IF p := $findGroup(gl,"myGroup") THEN
WHILE p := $nextParm(p,name,value) DO
# process each possible named parameter
IF name = ... THEN ...
EF name = ... THEN ...
Some applications with few parameters of their own may not need an application-specific parameter file. However, if your application does define an application-specific parameter file, it may be possible that the user will want to configure other applications that are used in conjunction with that application. Thus, it is best not to use the $DEFAULT group for general-purpose parameters, but to require that the parameter file contain $GROUP commands that specify particular groups.
For example, suppose that you have an application myApp that has a group named XyzCorp-myApp. It may be that myApp invokes the MAINSAIL editor, and that you want to configure the editor in a particular way when myApp invokes it (say, by setting the windowWidth parameter to 50). Then the contents of a parameter file specific to myApp might look like:
If this file is read into the general-purpose group list $mslParms, then when MAINEDIT is initialized, it will find the specified value for windowWidth.
A group name that starts with $ should not be chosen by the user; such names are reserved for XIDAK programs. Group names should be chosen so as not to conflict with other group names. Group names created by companies other than XIDAK should contain, at the least, the name of the company and the name of the application to which the group is relevant, e.g.:
When processing parameters, it is best to ignore unrecognized parameter names rather than issue an error message for them. This permits newer versions of parameter files to be used with older versions of an application.
As an example of an application that follows the above recommendation, suppose that United Amalgamated Inc. has an application named Universal Software Tool. This application reads parameters from a group named:
The application recognizes three parameters in this group: parm1, parm2, and parm3.
When the application starts up, it reads parameters from a file called ust.prm. This file can appear either on the home directory or the current directory or both, just like v1630.prm. The file can contain parameters for applications other than Universal Software Tool.
To allow the parameters in the application's group to appear either in v1630.prm or in ust.prm, the application reads the ust.prm file into the group list $mslParms. The code to process parameters in Universal Software Tool thus looks something like:
IF p := $findGroup($mslParms,
WHILE p := $nextParm(p,name,value) DO
# Process each possible named parameter.
# Note that parameter names are all upper case.
IF name = "PARM1" THEN process parm1
EF name = "PARM2" THEN process parm2
EF name = "PARM3" THEN process parm3;
# Note that no error is given for unrecognized
# parameter names.