Command line syntax: {modName {args}}, or see Section 21.1.1

MAINEX is the MODULE that invokes user MODULEs. Subcommands that govern the execution of the user MODULE may be specified to MAINEX when a user MODULE is invoked.

If the MAINSAIL bootstrap does not specify a MODULE to execute (see Section 6.2.7) and no command line is given, MAINEX prints a herald and an asterisk prompt when MAINSAIL is invoked. You may then specify the name of a MAINSAIL MODULE or the name of a file containing a MAINSAIL object MODULE (or a comment if the line begins with the pound sign (#) character). The specified MODULE is executed if it is found; otherwise, MAINEX informs you that the MODULE cannot be found and returns to the asterisk prompt.

If the bootstrap command STRING or command line is not null, the command line is appended to the command STRING, and MODULE names and their arguments are read, one MODULE per line of the resulting STRING, until the STRING is exhausted. MAINEX examines the command line only when the executive starts execution; it does not examine the command line value resulting from each MODULE's execution, so it is not possible for a MODULE to cause another MODULE to be executed by MAINEX by setting the command line and then returning to MAINEX.

MAINEX executes a MODULE by calling the MAINSAIL system PROCEDURE $invokeModule, which binds the MODULE. Binding a MODULE has the side effect of executing its INITIAL PROCEDURE, which functions as the “main body” of the program. After execution of the MODULE, MAINEX disposes the MODULE's bound data section (but not the control section). MAINEX then prompts for the next MODULE to be executed. Other MODULE(s) brought into memory as a result of execution of the MODULE specified to MAINEX are not automatically disposed. When MAINSAIL exits to the host operating system, the FINAL PROCEDURE of each MODULE that has not been disposed is executed.

If the MODULE to be executed already has a bound data section, and has not been compiled with the subcommand UNBOUND (see Section 4.45 of the MAINSAIL Compiler User's Guide), then MAINSAIL issues a message that the MODULE could not be invoked.

21.1. MAINEX Executive Dialogue

Whenever MAINEX gains control, it identifies itself and prints a * prompt to the file logFile (initially directed to your terminal) indicating that it is waiting for input. MAINEX reads its input from the file cmdFile, which is initially directed to the operating system's primary input medium (usually your terminal). Table 21–1 shows possible responses to the prompt (these responses are displayed when ? is typed).

If <eol> is typed in response to the MAINEX * prompt, control is returned to the calling program, which is usually the host operating system command interpreter.

Example 21–2 shows how to execute a MODULE MYMOD. MYMOD is typed in response to the MAINEX * prompt. Case is ignored when a MODULE name (but not a file name) is entered at the * prompt. MYMOD is typically contained in an open MODULE library (see Section 21.2.29) or in a file of which the name is derived from the MODULE name in an operating-system-dependent manner. The search rules for object MODULEs are described in Chapter 14 of the MAINSAIL Language Manual.

If the input to MAINEX is not a valid MODULE name, MAINEX assumes that it is a file name. For example, if you type mymod.xxx, MAINEX assumes this is a file name since it is not a valid MODULE name (it contains a period). In this case, MAINEX attempts to execute the object MODULE contained in the file mymod.xxx, as shown in Example 21–3.

21.1.1. Using MAINEX to Invoke MAINSAIL Programs with a Single Command Line

MAINEX supports a syntax that allows you to use a single command line to invoke line-oriented utilities that would normally go into a multiline dialog. This capability may be useful in programs like make that would like to invoke MAINSAIL utilities with a single operating system command.

The command line syntax allows you to specify a single line that expands internally into the series of lines that you would normally type in a dialog with a line-oriented utility.

The one-line command syntax uses two special characters, + and -. + is intended to mark the start of a normal line of input, and - is intended to mark the start of a subcommand line.

21.1.1.1. Examples

Here are the rules for replacing the characters + and - within the line given to MAINEX to produce the contents of the MEM file to which cmdFile is redirected:

• For the purposes of these rules, a “word” is delimited by whitespace.

• + and - are treated specially only if they appear at the start of a word; they are not replaced if they occur in the middle or at the end of a word.

• + and - are the only characters treated specially by these rules.

• The algorithm remembers which character it last replaced: +, -, or (at the start of the line) neither.

• ++ at the start of a word is replaced with +, and -- at the start of a word is replaced with -. These replacements do not alter the remembered last replaced character. This rule allows you to specify a command argument beginning with + or -.

• Otherwise, whitespace immediately before and after a + or - is discarded, and the + or - replaced according to the following table:

  Character to Replace	Last Replaced +	Last Replaced -	Last Replaced Neither
  +	eol	eol & eol	""
  -	eol & "," & eol	eol	"," & eol

  These replacements alter the remembered last replaced character.

• The line given to MAINEX has had its trailing eol removed at the time of processing.

  If, at the end of the line given to MAINEX, the last character replaced is -, two eols are appended to the result; otherwise, one eol is appended.

cmdFile's previous value is also restored when the system procedure errMsg issues an Error response prompt. Thus, MAINEX lines beginning with + or - cannot contain responses to the Error response prompt.

21.2. MAINEX Subcommands

MAINEX subcommand mode is entered by ending a line with a comma (“,”). MAINEX prompts with > and waits for input. Table 21–4 lists the available MAINEX subcommands; a list similar to this is printed when ? is typed to the > prompt.

Except in file names, case is ignored by MAINEX when interpreting subcommand input. In addition, only as much as is necessary to uniquely identify a subcommand need be typed. Subcommand mode is exited by typing <eol> to the > prompt.

Mixed case is used in the subcommands to show the minimum permitted abbreviation of MAINEX subcommands. The uppercase portion of each MAINEX subcommand in mixed case is a sufficient abbreviation for that subcommand (as if the upperCase bit were given to cmdMatch).

21.2.1. Long Subcommand Lines

MAINEX allows long subcommand lines to be broken by terminating them with the continuation character (\ on all currently supported systems). If a subcommand line ends with the continuation character, the next line is treated as part of this line and the continuation character is subsequently discarded.

The continuation character and the immediately following eol cancel each other out; they are not replaced with a blank or any other character. This allows single words to be split across more than one line; e.g.:

search\
path

would be equivalent to the single line:

searchpath

Typically, lines are split at word boundaries, in which case users should be careful to include the space that separates the words where the split was made either right before the continuation character in the first line or as the first character of the second line.

21.2.2. Search Rule Manipulation Subcommands

The subcommands listed in Table 21–5 govern searches for intmods, non-executable objmods, and executable objmods. The terms “intSearch”, “objSearch”, “exeSearch”, “intList”, “objList”, and “exeList” are defined and explained in Chapter 14 of the MAINSAIL Language Manual.

Any of the MODULE arguments m shown in Table 21–5 may consist of a MODULE name optionally followed by a dash and a target system abbreviation (e.g., FOO-USPA, BAR-MPNT). The initial default target for each subcommand is the host system. When a target appears in a subcommand argument list, it changes the default target to that system for the current MODULE and the remainder of the argument list. A null target system abbreviation specifies the host system (e.g., BAZ-).

In the search rule subcommands, the prefix determines the type of search or list to which the subcommand applies: INT subcommands govern intSearches (or the intList), OBJ subcommands objSearches (or the objList), and EXE subcommands exeSearches (or the exeList).

21.2.2.1. [INT|OBJ|EXE][FILE|LIB] m₁{=f₁} ... m_n{=f_n}

The CHECKCONSISTENCY subcommand turns on interface consistency checking (as described in Section 11.10 of the MAINSAIL Language Manual) when subsequent MODULEs are bound. Interface consistency checking is on by default.

The NOCHECKCONSISTENCY subcommand turns off interface consistency checking. Interface consistency checking remains off until the CHECKCONSISTENCY subcommand is given. Being able to turn off consistency checking is useful for a system that is “known” to be consistent (i.e., has been run many times) because it saves runtime, especially when MODULEs have been swapped out since the consistency check must swap in all involved MODULEs. If interface consistency checking is turned off, difficult-to-track errors may occur if MODULE interfaces are actually inconsistent.

21.2.4. CLoseexelib fn

The "CLOSEEXELIB" subcommand closes the object MODULE library file named fn for execution access (the list of objlibs open for execution is distinct from the list open for read/write access; both are global to the entire MAINSAIL session). fn may have been opened by a previous OPENLIBRARY subcommand or by the system PROCEDURE openLibrary.

CL is a sufficient abbreviation of CLOSEEXELIB.

21.2.5. CLOSEINTLIB fn

The CLOSEINTLIB subcommand closes the intmod library file named fn, so that it no longer plays a role in intmod searches conducted by the compiler, debugger, etc. fn may have been opened by a previous OPENINTLIB subcommand or by another program; the open intmod library list is global to the entire MAINSAIL session.

21.2.6. CLOSEOBJLIB fn

The CLOSEOBJLIB subcommand closes the object MODULE library file named fn for read/write access (the list of objlibs open for execution is distinct from the list open for read/write access; both are global to the entire MAINSAIL session). fn may have been opened by a previous OPENOBJLIB subcommand or by a MAINSAIL system program (e.g., the compiler).

21.2.7. CMDFILE fn

The CMDFILE subcommand allows you to redirect cmdFile. fn is the name of the file that is to become cmdFile. The CMDFILE subcommand takes effect as soon as subcommand mode is exited. Once in effect, a new line is read from fn whenever a MODULE (including MAINEX) requests input from cmdFile.

Example 21–6 shows an example command file and how the CMDFILE subcommand is used. MAINSAIL is invoked and cmdFile is redirected to the file commands. When subcommand mode is exited, input to the compiler is taken from commands. The MODULE MOD1 is compiled with the DEBUG compiler option (consult the “MAINSAIL Compiler User's Guide” for a description of compiler options). The first blank line exits the compiler subcommand mode; the second exits the compiler. Note that a third blank line may be included to exit MAINSAIL, but this is not necessary. If input is requested from cmdFile but the end of cmdFile has been reached, then (unless the $noAutoCmdFileSwitching configuration bit is set) the message WARNING: Unexpected <eol> on cmdFile, switching to TTY is displayed and cmdFile is automatically redirected to primary input.

The subcommand CONTROLINFO causes messages to be written to TTY whenever a coroutine resumes or kills another, or whenever an exception is raised, propagated, or handled, or whenever a handler is invoked. NOCONTROLINFO cancels CONTROLINFO.

21.2.9. CSUBCOMMANDS fn

The CSUBCOMMANDS fn subcommand works just like the SUBCOMMANDS fn subcommand, except that if the file named named fn does not exist, no error message is given. The C stands for “conditional”; the subcommand file is read only if it is present.

21.2.10. DEFine name body

The DEFINE subcommand allows a MAINEX command to be defined as a macro. The syntax of the subcommand is:

DEFINE identifier macroBody

Whenever the identifier is encountered as the first word of a MAINEX command line, the macro body is substituted for it. For example:

DEFINE xxx compil

allows the MAINSAIL compiler to be invoked as xxx. The MAINEX command line:

xxx foo.msl

invokes the compiler on the source file foo.msl.

Since the macro body is just arbitrary text, it can include parameters in addition to the actual MODULE name; e.g.:

DEFINE foo edit foo.msl

would edit the file foo.msl whenever foo was typed to the MAINEX * prompt. The macro body (with leading and trailing blank space removed) is substituted in place of the macro name in the original command line (separated from the rest of the command line by a single space if the command line contains text after the macro name).

For example, with the above definition, the command line foo wy43 expands to edit foo.msl wy43. Macro substitution is recursive, so that if you issue DEFINE foo bar and DEFINE bar baz, then the command line foo ultimately expands to baz. There is a recursion depth limit (its exact value is subject to change), so that an error message is issued if an infinite recursion occurs.

The reason for the existence of the DEFINE command is that there are some XIDAK MODULE names that have a leading $, and yet are documented for invocation by users: $DEBUG, $INTCOM, $MM, $OBJCOM, $STAMP, $STRTXT, etc. Without the DEFINE mechanism, you would have to type the full name, including the dollar sign, to the MAINEX prompt in order to invoke one of these MODULEs. The DEFINE subcommand allows users to use more convenient names without dollar signs. By default, XIDAK includes the subcommands:

DEFINE debug $debug
DEFINE intcom $intcom
DEFINE mm $mm
DEFINE objcom $objcom
DEFINE stamp $stamp
DEFINE strtxt $strtxt

in the system subcommand file created during standard installation of MAINSAIL.

21.2.11. DEFINETIMEZONE s n

Define the time zone abbreviation s as representing n seconds west of Greenwich; in other words, n is the number of seconds to be added to the standard time in the local time zone to get Greenwich Mean Time. If s (which may be either one or two words) is also the name of the local standard or daylight time zone, then the DEFINETIMEZONE information is ignored. Use of this subcommand, unlike the other date and time MAINEX subcommands, does not cause $timeSubcommandsSet to become TRUE. The time zone abbreviation is recognized by $dateAndTimeToStr.

If no argument is given, all the currently defined time zones are displayed.

21.2.12. DELAYRIGPTRS

Delay rigging POINTERs until enough chunks have been disposed. This subcommand has an effect only on SUPERCHECK platforms; see Chapter 18 of the MAINSAIL Language Manual.

21.2.13. DSTENDRULE s

DSTOFFSET n, where n is a LONG INTEGER (without trailing L) informs MAINSAIL:

• If n is zero, that daylight savings time does not affect the local time zone. The DSTSTARTRULE and DSTENDRULE commands are ignored.

• If n is non-zero, that n is the offset, in seconds, to be added to standard time to get daylight savings time when daylight savings time is in effect. In the United States, n is 3600L (one hour) in areas that have daylight savings time.

If no DSTOFFSET command is specified, n is assumed to be zero.

If this subcommand is specified with no argument, the current value of the DST offset is displayed.

21.2.16. DSTSTARTRULE s and DSTENDRULE s

The start and stop rules handled by the standard algorithm allow the starting and stopping times and dates for daylight savings time to be expressed as:

• A month,

• a day of the month expressed either as a numeric date or as a day of the week and the number of its occurrence, and

• a time of day.

In DSTSTARTRULE s and DSTENDRULE s, s is a STRING containing the above information in the format:

monthName weekdayName occurrence timeOfDay

or:

monthName dateOfMonth timeOfDay

monthName is an unambiguous prefix of one of the twelve month names. weekdayName is an unambiguous prefix of one the names of the seven days of the week. occurrence is 1 for the first occurrence of the named weekday in the month, 2 for the second, etc.; 5 or any greater number may be used for the last occurrence, since any given weekday never occurs more than five times in a single month. dateOfMonth is the day of the month; any number greater than the number of days in the month is treated as the last day of the month. timeOfDay is a time of day in any format acceptable to the MAINSAIL system PROCEDURE $strToTime.

Some sample values of s and their interpretations are:

DSTSTARTRULE s and DSTENDRULE s specify the rule for the starting and ending dates and times, respectively, of daylight savings time. DSTSTARTRULE specifies the time in standard time, and DSTENDRULE in daylight savings time; i.e., they are specified using the kind of time in effect before the time change. In northern hemisphere locations that adjust standard time in the winter (calling it “winter time”), or southern hemisphere locations adjusting standard time in the summer, the month in DSTSTARTRULE will be later in the year than in DSTENDRULE. The algorithm deals with this situation correctly, applying the adjustment from late in one year through the early part of the next.

If DSTOFFSET is zero, DSTSTARTRULE and DSTENDRULE are ignored; otherwise, if DSTSTARTRULE and DSTENDRULE are not both specified, daylight savings time is assumed to apply throughout the year.

If no argument is given to one of these subcommands, the current value of the corresponding rule is displayed.

21.2.17. ECHOCMDFILE/NOECHOCMDFILE

The subcommand ECHOCMDFILE tells MAINSAIL to echo the contents of cmdFile to logFile (regardless of whether either is redirected). NOECHOCMDFILE turns off ECHOCMDFILE.

21.2.18. ECHOifredirected/NOECHOifredirected

The subcommand ECHOIFREDIRECTED echoes logFile to TTY if logFile is not TTY, and cmdFile to logFile if cmdFile or logFile is not TTY. ECHOIFREDIRECTED may be abbreviated to ECHO. NOECHOIFREDIRECTED turns off ECHOIFREDIRECTED.

21.2.19. ENTER ln fn

The ENTER subcommand associates the logical name ln with the file name fn. Whenever a file open is performed using the name ln, the name fn is used instead. If fn is not specified, any previous association for ln is broken.

In Example 21–7, whenever (data file) or eparms is opened, the file name data1 or realEparms is used. Note that fn is taken to be the last sequence of characters that does not contain any blanks so that any sequence of characters, including blanks, can be associated with a file name. Here, (data file) is associated with file name data1, and eparms is associated with the file name realEparms.

This command allows flexibility in file names without modification of source code. For example, a given MODULE can run on several machines without modification even though file name formats across those machines may differ if a logical name is used in the call to open and an ENTER is used to associate that logical name with the actual file name. XIDAK logical names are surrounded by parentheses. It is suggested that users adopt a different convention for logical names, so as to avoid conflict with XIDAK logical names.

A logical file name with embedded blanks cannot be used as arguments of commands to some MAINSAIL utilities (e.g., a library file name in a MODLIB command).

21.2.20. FILEINFO/NOFILEINFO

The FILEINFO subcommand causes a message to be written to TTY each time a file is opened, closed, deleted, or renamed. It may be useful for debugging. NOFILEINFO turns off FILEINFO.

21.2.21. GLOBALREMOVE r and GLOBALSYMBOL r s

These subcommands manipulate the global symbol table. The global symbol table allows programs to communicate with each other and allows parameters to programs to be set with MAINEX subcommands. The global symbol table is described in detail in Section 16.7 of the MAINSAIL Language Manual.

GLOBALSYMBOL r s calls the system PROCEDURE $stringGlobalEnter(r,s). r must be quoted using the double quote character if it contains spaces or tabs; s must be quoted if it contains trailing spaces or tabs or if it is the empty STRING. To include a double quote character in a quoted STRING, double it, as in a MAINSAIL STRING constant.

GLOBALSYMBOL r displays the value returned by the system PROCEDURE $stringGlobalLookUp(r).

GLOBALSYMBOL (with no arguments) displays all global symbols. STRING global symbols (those of the system CLASS $stringGlobalSymbol) are displayed with their values; others are displayed with a note that they are not $stringGlobalSymbol records.

GLOBALREMOVE r removes the symbol r from the global symbol table by calling the system PROCEDURE $globalRemove(r).

21.2.22. GMTOFFSET n

GMTOFFSET n, where n is a LONG INTEGER (without trailing L) informs MAINSAIL that n is the number of seconds to be added to the standard time in the local time zone to get Greenwich Mean Time. For example, in the Pacific Time Zone, GMTOFFSET 28800 would be appropriate, since 28800 = 7 * 3600, and Pacific Standard Time is seven hours behind Greenwich Mean Time. Standard time zones east of Greenwich should express n as a negative number; e.g., in France use GMTOFFSET -3600.

If no GMTOFFSET command is specified, n is assumed to be zero.

If this subcommand is specified with no argument, the current value of the GMT offset is displayed.

21.2.23. LOGFILE fn

The LOGFILE subcommand allows you to redirect logFile. fn is the name of the file that is to become logFile. The LOGFILE subcommand takes effect as soon as subcommand mode is exited. Once in effect, all output to logFile is redirected to fn.

Example 21–8 shows how the LOGFILE subcommand is used. MAINSAIL is invoked and logFile is redirected to the file log. When subcommand mode is exited, the compiler writes its prompt to the file log and reads its input from cmdFile. If cmdFile is primary input (usually the terminal), as in this example, you must enter commands, but no prompts are displayed. sample<eol> tells the compiler which MODULE to compile, and <eol> exits the compiler. The second <eol> is needed to return to the operating system.

The LOOKUP subcommand causes the association for logical name ln to be displayed if there is one. If ln is not specified, the values of all logical names are specified.

21.2.25. MAP n/NOMAP

The MAP n subcommand causes a memory usage map to be displayed periodically. The map consists of one or more lines, each consisting of a hexadecimal number followed by sequence of characters. Each character corresponds to a MAINSAIL memory page, and the hexadecimal number at the beginning of the line is the first ADDRESS of the page corresponding to the first map character of the line. The INTEGER n governs the frequency with which the map is displayed. The larger n the less frequently the memory map is displayed (an n of 1 produces the maximum display frequency). Table 21–9 lists the characters displayed in a memory map and their meaning.

The MAP subcommand allows you to evaluate a program's memory consumption. This is most useful on computers with a small address space where memory is at a premium, or in programs where memory fragmentation (perhaps due to scattered foreign pages) is a problem.

The MAP subcommand with no argument produces a memory map of the same format as produced by the other form of the MAP subcommand. However, maps are printed only immediately before and after each event printed out by the MEMINFO subcommand. This subcommand automatically turns on the MEMINFO subcommand.

NOMAP turns off a previous MAP command.

The utility MM also provides a command to display a memory map just once, immediately. The Motif-based MAINSAIL tools provide a map that is automatically updated each time memory changes.

21.2.26. MEMINFO/NOMEMINFO

This subcommand causes a message to be printed when various memory management events occur: garbage collections, asking the operating system for more memory, and so forth. The messages produced are either self-explanatory or of interest only to XIDAK personnel. The information printed may vary from release to release. NOMEMINFO turns off MEMINFO.

21.2.27. OPenexelib fn

The OPENEXELIB subcommand opens the object MODULE library file named fn for execution (the list of objlibs open for execution is distinct from the list open for read/write access; both are global to the entire MAINSAIL session).

If fn is already on the list of objlibs open for execution (which is determined by comparing it with the fns previously given to OPENEXELIB; the file name must match exactly), then it is moved to the head of the list. This affects the search order, but does not open a new library or close and reopen the existing library.

OP is a sufficient abbreviation of OPENEXELIB.

21.2.28. OPENINTLIB fn

The OPENINTLIB subcommand opens the intmod library file named fn, so that it plays a role in intmod searches conducted by the compiler, debugger, etc. The open intmod library list is global to the entire MAINSAIL session.

If fn is already on the list of open intlibs (which is determined by comparing it with the fns previously given to OPENINTLIB; the file name must match exactly), then it is moved to the head of the list. This affects the search order, but does not open a new library or close and reopen the existing library.

21.2.29. OPENLIBRARY fn

OPENLIBRARY is equivalent to OPENEXELIB.

21.2.30. OPENOBJLIB fn

The OPENOBJLIB subcommand opens the object MODULE library file named fn for read/write access (the list of objlibs open for execution is distinct from the list open for read/write access; both are global to the entire MAINSAIL session).

If fn is already on the list of objlibs open for read/write access (which is determined by comparing it with the fns previously given to OPENOBJLIB; the file name must match exactly), then it is moved to the head of the list. This affects the search order, but does not open a new library or close and reopen the existing library.

21.2.31. RELEASE

The RELEASE subcommand displays the release number (minor minor version number) of the MAINSAIL system currently running.

21.2.32. RESPONSE/NORESPONSE

When RESPONSE is in effect (the default), errMsg prompts for a user response if the raised $systemExcpt is not handled (except when the warning bit is set in ctrlBits). When NORESPONSE is in effect, errMsg never prompts; it writes the message to logFile and continues execution (unless the fatal bit was set in ctrlBits).

21.2.33. REVISION

The REVISION subcommand displays the revision time of the MAINSAIL system currently running.

21.2.34. RIGGINGPTRBADADDR, RIGGINGSTRBADCHAR, RIGPTRS, and RIGSTRS

The SEARCHPATH command has the form:

SEARCHPATH f f₁ f₂ ... f_n

where f is a pattern to be matched to a file name, and the f_i are file name specifications which are to be used in place of the original file name. Whenever a file is opened, MAINSAIL looks through the list of current searchpath specifications (from most recently added to least recently added), and if the file name matches the pattern f, then it processes each f_i in the sequence given by substituting the wildcard characters in f_i and attempting to open an existing file named by the resulting STRING. If such an open succeeds, the PROCEDURE open returns the file so opened; if no such open succeeds, the PROCEDURE open returns FALSE (if errorOK is set) or prompts for a new file name (if errorOK is not set).

If a file name matches more than one pattern in the list, the most recently added matching pattern is checked first, then older matching patterns.

If the f part of a pattern is the same as a pattern already on the list, then the entry for that pattern is removed from the list, and the new entry added to the head of the list.

f may contain any number of asterisks as wild card characters. * matches any sequence of zero or more characters. The f_i may contain any number of replacement specifiers of the form *n, where n is a positive integer, e.g., *1, *10. A replacement specifier *n is replaced with the STRING that matched the nth * in f (numbered from the left as 1, 2, ...; if n is greater than the number of wildcards in f, *n is replaced with the empty STRING). * in an f_i not followed by a digit is treated as *1, which is a useful short form since there is often just one * in f.

If no f_i are specified, the searchpath associated with the pattern f is removed.

A system-dependent escape character (\ on UNIX, ^ on Windows) may be used in f or an f_i as an escape character to indicate that the next character is not to be treated specially (such escape characters are discarded). For example, if * is to appear as a normal character in a searchpath on UNIX, it must be written as \*; *2 followed by 34 must be written on Windows as *2^34 since *234 means that the 234th wildcard match is to be substituted. On UNIX, \ must be written as \\, and on Windows, ^ as ^^. The escape character as the last character in f or an f_i is treated as itself; i.e., the escape character may not be used to escape a space or tab character.

For example, if the command:

SEARCHPATH msl:* *.msl /usr/john/*.msl /x/*.msl

is given, open attempts to open every file whose name starts with “msl:” using the searchpath. For example, it first tries to open msl:abc as abc.msl; then, if it could not open abc.msl, as /usr/john/abc.msl; then, if it could not open /usr/john/abc.msl, as /x/abc.msl; and then if that fails, the PROCEDURE open fails altogether (issues a message or returns FALSE, depending on the setting of errorOK).

If the command:

SEARCHPATH *-before-*.* *1-after-*2.*3

is given, then open replaces the file name foo-before-upgrade.txt with foo-after-upgrade.txt.

The command:

SEARCHPATH \*-\*.txt star-star.txt

is equivalent (on a UNIX system) to:

ENTER *-*.txt star-star.txt

assuming there are no other searchpaths that would match the file name *-*.txt.

A structured use of searchpaths is to choose prefixes to represent searchpath names; e.g., one might use prefixes of the form “identifier:” (any identifier would do). For example, one could use “source:” as a source searchpath prefix, and “intmod:” for an intmod searchpath prefix. Then, in a portable way, source:foo could be used to open a source file foo, and intmod:baz-upa to open an intmod file baz-upa. The searchpaths must first be set up with MAINEX subcommands:

>SEARCHPATH source:* *.msl /16.20/*.msl<eol>
>SEARCHPATH intmod:* *.int /16.20/*.int<eol>

In this way, MAINSAIL appends the extension, and at the same time tries various directories, so that the source file can use portable file names (i.e., there is no need to put the extension into source code for file name constants).

21.2.35.1. Searchpaths Beginning with * *

When the open routine tries to open the various file names formed from the f_i, it uses the errorOK bit and goes on to the next one if it cannot be opened. Thus even if the incoming file name is something like source:foobar.lib, it would try foobar.lib.msl, but that is OK since it will fail (assuming there is no foobar.lib.msl).

Searchpaths are case-sensitive.

The searchpath syntax may change in future releases.

21.2.36. SETFILE tmn fn

The SETFILE subcommand associates the name of the actual MODULE tmn with the file fn. MAINSAIL then accesses the MODULE in the file fn when the actual MODULE is referenced. The association made by the most recent SETFILE subcommand is the one that is used.

If fn is omitted, any file association for tmn is removed. If tmn is omitted, all current MODULE-file associations are listed (as by EXESHOW).

SETFILE m f is equivalent to EXEFILE m=f. SETFILE m is equivalent to EXEDEFAULT m.

21.2.37. SETMODULE dmn tmn

The SETMODULE subcommand associates the dummy MODULE name dmn with the true MODULE name tmn. All subsequent references to the dummy MODULE are redirected to the actual MODULE tmn. The association made by the most recent SETMODULE subcommand is the one that is used.

If tmn is omitted, any MODULE association for dmn is removed. If dmn is omitted, all current MODULE-MODULE associations are listed.

In STDNAME s and DSTNAME s, s is the commonly used name (usually abbreviated) of the local time zone. The STDNAME value is used if standard time is in effect, the DSTNAME if daylight savings time is in effect. For example, for the Eastern Time Zone of the United States, specify the commands:

STDNAME EST
DSTNAME EDT

If DSTOFFSET is zero, DSTNAME is ignored, and STDNAME always used for the name of the current time zone.

If one of these subcommands is given with no argument, the current value of the corresponding parameter is displayed.

21.2.39. SUBCOMMANDS fn

This subcommand indicates that further MAINEX subcommands are to be read from the file fn. When end-of-file is reached on that file, MAINEX resumes reading from the file containing the SUBCOMMANDS subcommand. This subcommand is useful if a series of subcommands is frequently executed or executed by a number of different MAINSAIL bootstraps.

21.2.40. SWAPINFO/NOSWAPINFO

The SWAPINFO subcommand is used to monitor MODULE swapping. When specified, messages are written to TTY when a MODULE is brought into memory and when a MODULE is discarded from memory, as described in Section 11.14 of the MAINSAIL Language Manual. NOSWAPINFO turns off SWAPINFO.

MODULEs in an open mapped library are never removed from memory.

21.2.41. # s

The # character in MAINEX subcommand mode introduces a comment. It is especially useful in command files.

21.3. Initialization Parameters for MAINEX in the Parameter File

The parameter file contains settings of parameters that you specify in the file. In Version 16.20 of MAINSAIL, the parameter file is called v1620.prm (in general, the name of the file depends on the version of MAINSAIL; it consists of the letter v followed by the major and minor version numbers followed by .prm). This file may reside on your home directory, the directory on which you are editing, or in both places (if it exists in both places, the one on the home directory is read first, and then the one on the current directory, which means that settings specified in the current directory override those in the home directory if the same parameter is specified in both).

Chapter 28 of the MAINSAIL Language Manual contains more information on parameter files.

The parameter group $MAINEX in the parameter file is headed by the line $GROUP $MAINEX. Subsequent lines in this group can contain any valid MAINEX subcommand as a parameter. These subcommands are executed when MAINSAIL is initialized. The subcommands are not processed in subsequent recursively invoked MAINEX sessions, so that only subcommands specified in the v1620.prm ever take effect; any commands that appear in the group $MAINEX in subsequently read parameter files are ignored.

For example, a parameter file containing the subcommands EXEFILE, INTFILE, and OBJFILE would contain the lines:

$GROUP $MAINEX
EXEFILE
INTFILE
OBJFILE

These subcommands specify that MAINSAIL should search for MODULEs first in individual files in the current directory instead of in open libraries.

21.4. $mainsailExec

$mainsailExec recursively invokes the MAINSAIL executive. The current command line (as would be returned by $getCommandLine) is appended to s. If the resulting s is non-Zero, each line read from s is interpreted as the name of a MODULE (possibly followed by arguments) and executed; $mainsailExec returns when the STRING is exhausted. If s is Zero, the recursively invoked executive functions as MAINEX normally does: it repeatedly prompts with the asterisk prompt for a MODULE name and arguments, then executes the named MODULE, until a bare <eol> is read from cmdFile, at which point it returns to its caller.

21.5. $getSubcommands

The PROCEDURE $getSubcommands may be used to enter MAINEX subcommands from a program. The accepted subcommands are the same ones that are valid in the usual MAINEX subcommand mode.

If both cmdStr and theCmdFile are Zero, prompts are written to logFile and subcommands read from cmdFile. If cmdStr is not Zero, the subcommands are read from cmdStr, and no prompts are written to logFile. If cmdStr is Zero and theCmdFile is not Zero, commands are read from theCmdFile, and prompts are written to logFile only if theCmdFile equals cmdFile.

Subcommand names spelled out in full (not abbreviated) are more likely to be compatible with future releases, since abbreviations may conflict if another subcommand with the same prefix is created. Since all subcommands are subject to change from release to release, however, compatibility is never guaranteed. Programmers making use of $getSubcommands may have to change the value of cmdStr or the contents of theCmdFile if MAINEX subcommands change.