MAINSAIL Language Manual, Chapter 28

previous   next   top   complete contents   complete index   framed top   this page unframed


28. Generalized Parameter Files

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 files automatically. 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 extension prm. 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.

28.2. Format of a Parameter File

In general, a parameter file consists of a sequence of groups:

$GROUP groupName

firstParameter
...
lastParameter


$ENDGROUP

. . .

$GROUP groupName

firstParameter
...
lastParameter


$ENDGROUP

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:

$INCLUDE fileName

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 parmValue

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 \
firstContinuationLine \
...
lastContinuationLine

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.

28.3. Parameter Groups Used by XIDAK Software

The following groups are used by XIDAK software:

The use of each of these groups is described in the documentation for the relevant application.

28.3.1. The Group $MAINEX

The group $MAINEX can contain any valid MAINEX subcommand as a parameter. 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 automatically).

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 compiler session.

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 EDITORPARMSFILE (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:

Parameter Name Global Option Name
proportionalWindows proportionalWindowsMode
visibleLeftBorder leftBorder
visibleRightBorder rightBorder
autoHorizontalScroll autoHorizontalScroll
maximumProportionalWindows maximumUnanchoredProportionalWindows

28.3.4. The Group $MAINED

The MAINED options stickyTabs and wordWrap are available as parameters. 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
displayCurrentProcFrame F
displayCurrentDataSec D
verbose V
recursiveDebug R

The option is turned on if its argument is the keyword TRUE and turned off if its argument is FALSE.

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

$GROUP $MAINEX

INTFILE
OBJFILE
EXEFILE

$GROUP $MAINEDIT

windowWidth 72
proportionalWindows TRUE
maximumProportionalWindows 3

$GROUP $MAINED

wordWrap FALSE
autoSaveInterval 5000

$GROUP $MAINDEBUG

verbose TRUE

$GROUP $COMPIL

DEBUG
ACHECK
UCHECK

28.4. How to Process Parameters in a Program

Parameters are processed in two steps:

  1. A parameter file is read and the information in it put into a data structure called a group list.

  2. When an application that has parameters wishes to examine them (usually when the application starts up), it traverses the group list(s) that contain the parameters.

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:

POINTER($parmCls$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.

Figure 28–1. PROCEDUREs for Processing Parameters
POINTER($parmCls)
PROCEDURE   $readParms  (STRING filename;
                         
OPTIONAL POINTER($parmCls)
                             
groupList;
                         
OPTIONAL BITS ctrlBits);

POINTER($parmCls)
PROCEDURE   $findGroup  (POINTER($parmClsgroupList;
                         
OPTIONAL STRING name);

POINTER($parmCls)
PROCEDURE   $nextParm   (POINTER($parmClsgroupOrParm;
                         
PRODUCES OPTIONAL STRING
                             
name,value);

$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:

STRING name,value;
POINTER($parmClsp;
...
IF p := $findGroup(gl,"myGroup") THEN
    
WHILE p := $nextParm(p,name,valueDO
        # 
process each possible named parameter
        
IF name = ... THEN ...
        
EF name = ... THEN ...
        ...

28.5. Recommendations for Use of Parameters

Some users may wish to put the parameters for all the programs they use into a single file, the v1630.prm on their home directory. Others may prefer to put the parameters for each application in an application-specific parameter file that is read when the application is started. To allow for both possibilities, it is recommended that general-purpose parameters for all applications be read into the same group list,
$mslParms (which is the group list into which v1630.prmis read), and that application-specific group lists not be maintained for general-purpose parameters.

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:

$GROUP XyzCorp-myApp
myAppCommand1 value1
myAppCommand2 value2
$GROUP $MAINED
windowWidth 50

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.:

$GROUP XyzCorp-applicationOne

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:

UnitedAmalgamatedInc-UniversalSoftwareTool

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:

STRING name,value;
POINTER($parmClsp;
...
$readParms($composeFileName("ust","prm"),$mslParms);
IF p := $findGroup($mslParms,
    "
UnitedAmalgamatedInc-UniversalSoftwareTool") THEN
    
WHILE p := $nextParm(p,name,valueDO
        # 
Process each possible named parameter.
        # 
Note that parameter names are all upper case.
        
IF name = "PARM1THEN process parm1
        
EF name = "PARM2THEN process parm2
        
EF name = "PARM3THEN process parm3;
        # 
Note that no error is given for unrecognized
        # 
parameter names.

previous   next   top   complete contents   complete index   framed top   this page unframed

MAINSAIL Language Manual, Chapter 28