MAINSAIL gains control from the host operating system through execution of a “bootstrap”. The bootstrap is an executable file that contains the code needed to start MAINSAIL execution and certain configuration parameters to be used for that execution. It is the only part of MAINSAIL that must be processed by the host operating system linkage editor.

The MAINSAIL configurator MODULE, CONF, lets you create custom bootstraps. It provides an interactive means of restoring configuration parameters from a file, altering the configuration parameters, saving the configuration parameters in a file, and writing a bootstrap file. The bootstrap file is usually an assembly language source file that must be assembled and linked or a link editor file that must be linked.

Custom bootstraps make it possible for each MAINSAIL execution to have a custom-tailored execution environment. For example, the maximum amount of memory used by MAINSAIL is one configuration parameter that can be controlled. Custom bootstraps also make it possible to execute a MODULE directly without entering a dialogue with the MAINSAIL executive, MAINEX.

The configuration is composed of a target-independent set of parameters and, on some operating systems, operating-system-dependent parameters. The target-independent configuration parameters are described herein; the other parameters are described in the appropriate operating-system-specific MAINSAIL user's guides.

6.1. Configuration Files

Example 6–1 shows how to restore configuration values from a configuration file. The RESTORE command causes new configuration values to be restored from the file newconfig. The new bootstrap is written in the file mainsa.s, assuming mainsa.s is the file name specified in the BOOTFILENAME command in the configuration file used to make the current bootstrap. This new configuration file can then be assembled and linked to create an executable bootstrap file. The details of assembling and linking a bootstrap are described in the appropriate operating-system-dependent documentation.

Table 6–2 shows the set of target-independent commands accepted by CONF.

6.2.1. (LONG) INTEGER and (LONG) BITS Command Arguments

The syntax rules for (LONG) INTEGER and (LONG) BITS CONF parameters are as follows:

• An INTEGER CONF parameter must be an INTEGER constant.

• A LONG INTEGER CONF parameter must be an INTEGER or BITS constant.

• A (LONG) BITS CONF parameter must be a sequence of = characters, INTEGER constants, or BITS constants, separated by either ! or -. ! denotes the IOR operator, - denotes CLR (see Section 6.2.3).

• A (LONG) INTEGER or (LONG) BITS CONF parameter may be followed by #, in which case the remainder of the line is ignored. Otherwise, if the parameter is followed by any non-blank characters, an error about unexpected text at the end of the command is reported.

CONF internally maintains (LONG) INTEGER and (LONG) BITS CONF parameters as STRINGs instead of native (LONG) INTEGERs and (LONG) BITS. This means, e.g., that MAXMEMORYSIZE for 64-bit target machines can be set to values larger than 4 Gb even when the host machine on which CONF is being run supports only 32-bit LONG INTEGERs.

(LONG) INTEGER and (LONG) BITS CONF parameter values that are too large to fit in a variable of that type on the target machine elicit an error message to that effect. An exception to this rule is that an out-of-range positive decimal number can be specified for the value of LONG INTEGER CONF parameter, as long as the number would fit in an unsigned LONG INTEGER containing the same total number of bits as a LONG INTEGER on the target machine. For example, for a 32-bit target machine, MAXMEMORYSIZE 4294967295 is equivalent to MAXMEMORYSIZE 'HFFFFFFFF or MAXMEMORYSIZE -1.

6.2.2. Single-Line and Multiline Command Formats for STRING-Valued Command Arguments

For single-line CONF commands, = is also accepted and means leave the current value, though this is less useful.

6.2.3. Commands That Specify (LONG) BITS Values

The values specified for (LONG) BITS configuration parameters may consist of one or more “terms” separated by ! (which denotes “inclusive-OR”) or - (which denotes CLR). A term is either a (LONG) BITS constant or =; = denotes the configuration parameter's current value.

Thus, e.g., you could indicate that the UNIX shared memory functions should be called when object libraries are opened by specifying:

UNIXBITS =!'H100

instead of having to hardwire each bit set in the UNIXBITS parameter. As another example, for MAINSAIL to run as a character-based application on NTPNT, the '1 bit must be cleared in the WIN32BITS parameter. This can be safely done without clobbering other bits that might need to be set by specifying:

WIN32BITS =-'1

In a (LONG) BITS CONF parameter containing a mix of the ! and binary - operators, the operators are evaluated left to right.

When possible, you should use ! and - to set or clear additional bits in (LONG) BITS configuration parameters rather than hardwiring the value of each bit in the new value. For example, the default value of the UNIXBITS parameter for the HPPA platform is (currently) 'H2002. Shared memory is enabled on the HPPA by setting the UNIXBITS bit 'H100. The recommended way to do this is to specify UNIXBITS =!'H100 instead of UNIXBITS 'H2102, since the default value of the UNIXBITS parameter for HPPA may change in future releases.

Similarly, you should not make your own copies of configuration files and then modify them. Instead, you should make separate configuration files that restore from the standard configuration file on the MAINSAIL directory and then specify new values only for those parameters whose values are different from the defaults. The less you duplicate what is already in the standard configuration files, the less likely your own configuration files will become obsolete from release to release.

BOOTFILENAME sets the name of the bootstrap file to s. When CONF is exited with <eol>, the bootstrap is written to this file. On some operating systems, CONF may perform a transformation on the specified boot file name so that it conforms to operating system conventions for assembly language or object files.

6.2.6. COLLECTMEMORYPERCENT n

The parameter n is an INTEGER between 1 and 99 inclusive. MAINSAIL decides to do memory management if it predicts that n percent of memory would be reclaimed by doing a garbage collection. Thus a higher value for COLLECTMEMORYPERCENT, such as 10%, means that MAINSAIL collects garbage less often since more garbage has to build up before a garbage collection occurs. A smaller value, such as 1%, means more garbage collections since only 1% of memory is allowed to be garbage. The heuristic depends on an estimate that MAINSAIL makes of how much of memory is garbage; this estimate changes as garbage collections occur. MAINSAIL may garbage collect regardless of the value of COLLECTMEMORYPERCENT when it cannot get more memory from the operating system.

Large values for COLLECTMEMORYPERCENT may lead to unnecessary paging if a process's virtual size is larger than the physical memory available. Values for COLLECTMEMORYPERCENT larger than about 10% have not been shown to be useful. A value of about 1% may be reasonable for a large batch job.

6.2.7. COMMANDSTRING

COMMANDSTRING permits you to enter a STRING that, when the resulting bootstrap is executed, is treated exactly as if it had been typed to the MAINSAIL executive. It can contain the name of a MODULE to be executed, in which case the MAINSAIL executive dialogue is eliminated and the specified MODULE is executed directly. Subcommands may be specified to the executive by ending the executive command line with a comma. Follow the MODULE name with a comma, list subcommands one per line, then terminate with an extra <eol>. See the description of MAINEX in Chapter 21.

If the command STRING is a single command, it can be specified on the same line with the COMMANDSTRING command. If it consists of multiple lines it must start on the line immediately following the COMMANDSTRING line (COMMANDSTRING must appear alone on a line). In this case, the command STRING is terminated with a blank line (all lines up to the blank line are treated as part of the command STRING).

6.2.8. CONFIGURATIONBITS b

CONFIGURATIONBITS specifies that the bits set in the value b are the new configuration bits. Table 6–3 lists the possible configuration bits and their meanings.

Bit '10 ('H8), $foreignCodeStartsExecution, is for use in conjunction with the Foreign Language Interface (“FLI”). It specifies that foreign language code will gain control before MAINSAIL, and that MAINSAIL is not to initialize itself until the foreign code makes a call into MAINSAIL through the FLI. See Chapter 7 of the MAINSAIL Compiler User's Guide for more information on the FLI.

Bit '100 ('H40), $noAutoCmdFileSwitching, indicates that the exception $cmdFileEofExcpt is not to be raised when end-of-file on cmdFile is reached (as described in Section 22.12 of the MAINSAIL Language Manual); instead, normal end-of-file indicators are returned.

Bit '200 ('H80), $echoIfRedirected, causes input to cmdFile to be echoed to TTY if cmdFile or logFile is not the file TTY, and output to logFile to be echoed to TTY if logFile is not the file TTY.

Bit '400 ('H100), $echoCmdFile, always echoes cmdFile to logFile.

Example 6–4 shows how to use the CONFIGURATIONBITS command. The value '100 specifies that $cmdFileEofExcpt is disabled, and '200 specifies that cmdFile and logFile are to be echoed to TTY when they are redirected to files other than TTY. The = means that other bits have their default values. The new bootstrap is written to the file mainsa.mac. The file mainsa.mac can then be assembled and linked to create the new executable bootstrap.

The names of foreign MODULEs, as produced by the MAINSAIL foreign call FLI compiler, are listed one per line after this subcommand. The list of foreign MODULEs is terminated by a blank line. MAINSAIL does not automatically know about foreign MODULEs linked with the bootstrap; the name of a foreign MODULE must appear in the list in order to be callable from MAINSAIL.

If there is only one foreign MODULE in the list, it may be specified after the keyword FOREIGNMODULES; e.g., FOREIGNMODULES FOO may be used if FOO is the only foreign MODULE.

A line in a FOREIGNMODULES argument beginning with # (the comment character) is ignored, not treated as a foreign MODULE name.

The case of the foreign MODULE names is automatically converted to the case used for labels generated by the FLI compiler.

6.2.9.1. Always Include the Default Foreign MODULEs When Building a Bootstrap

The effect of building a MAINSAIL bootstrap without the default foreign MODULEs is undefined, although on many systems you will get an error when you attempt to link the bootstrap.

6.2.10. INITIALMEMORYSIZE n

The parameter to INITIALMEMORYSIZE is the amount of memory initially allocated by the bootstrap as MAINSAIL comes up. This initial allocation is separate from the allocation done within MAINSAIL (governed by MAXMEMORYSIZE), although the memory allocated is for MAINSAIL's general use in each case.

6.2.11. INITIALSTATICPOOLSIZE n

The parameter to INITIALSTATICPOOLSIZE is the initial size (in storage units) of the static page pool (the pages from which static memory is allocated).

The static pool is made up of multiple extensions, each of which is contiguous, but which is not necessarily adjacent to other extensions. When one extension is exhausted, a new one is allocated elsewhere in memory. The size of extensions allocated after the first one is specified by MINSTATICPOOLEXTENSIONSIZE.

You should be generous in specifying the static pool size. Frequent allocation of small static pool extensions can result in memory fragmentation, which may cause MAINSAIL to exit prematurely if you attempt to allocate a large dynamic ARRAY.

6.2.12. KERMODNAME s

KERMODNAME specifies that the file s contains the MAINSAIL kernel object MODULE, $KERMOD. This name must be changed if the kernel file is moved or renamed. The kernel MODULE cannot reside in the system MODULE library since it must be given control before any MODULE library can be opened.

6.2.13. MAXMEMORYSIZE n

The parameter to MAXMEMORYSIZE is the largest number of storage units MAINSAIL is allowed to ask for from the operating system. On some systems this limit may be approximate.

6.2.14. MAXPERCENTDELAYRIGCHUNKS n

Limits the percentage of allocated memory that can be used for disposed chunks, POINTERs to which need rigging, to n. This parameter is applicable only to SUPERCHECK platforms; see Chapter 18 of the MAINSAIL Language Manual.

6.2.15. MAXSIZEDELAYRIGCHUNKS n]

Limits the number of storage units that can be used for disposed chunks, POINTERs to which need rigging, to n. This parameter is applicable only to SUPERCHECK platforms; see Chapter 18 of the MAINSAIL Language Manual.

6.2.16. MINSIZETOALLOCATE n

The parameter to MINSIZETOALLOCATE is the minimum number of storage units to request from the operating system whenever MAINSAIL needs more memory.

6.2.17. MINSTATICPOOLEXTENSIONSIZE n

The parameter to MINSTATICPOOLEXTENSIONSIZE is the minimum size in bytes of each static pool extension except for the first; see Section 6.2.11 for a description of the static pool mechanism.

6.2.18. OSMEMORYPOOLSIZE n

The parameter to OSMEMORYPOOLSIZE is the number of storage units to reserve for allocation by operating system or FLI routines. The memory is requested from the OS, then released, when MAINSAIL initializes itself. The purpose is to avoid the appearance of static pages allocated by operating system or FLI routines in the middle of the MAINSAIL address space, acting as “firewalls” that prevent the efficient use of memory. This parameter has no effect on many operating systems; the operating-system-specific MAINSAIL documentation describes its effect on those systems where it is implemented.

6.2.19. PLATFORM s

PLATFORM s writes a bootstrap for the named target platform. s is an platform name abbreviation. PLATFORM ? shows a list of possible target platform name abbreviations. The default target is the host platform.

If PLATFORM is not the first command specified in a CONF session, previously specified configuration values may be lost.

If a platform is specified for which no cross-CONF MODULE is available, MAINSAIL complains that it is unable to find a target-dependent CONF MODULE. Cross-CONF MODULEs are shipped with cross-compilers, which must be purchased separately from XIDAK.

6.2.20. QUIT

QUIT causes CONF to exit without writing a bootstrap file.

6.2.21. RESTORE s

RESTORE causes CONF to read commands from the configuration file s. s must contain only valid CONF command lines. The configuration parameter values specified in s supersede the current values. All other parameters retain their previous values.

6.2.22. RUNTIMERESTORE s

RUNTIMERESTORE s causes the values of configuration parameters to be set at runtime from a file named s when you execute the bootstrap to which the command applies. To change most parameters used by a bootstrap, you need only edit a text file; you do not actually have to remake the bootstrap. This avoids the need for an assembler and linker to make simple changes to configuration parameters.

The RUNTIMERESTORE command is ignored when s is the empty STRING.

6.2.22.1. Sample Use of RUNTIMERESTORE

Users of these programs still run them by typing bigp or littlep to the UNIX shell prompt, but updating the configuration parameters is as simple as editing the files /xyz/bigp.cnf and /xyz/littlep.cnf.

6.2.22.2. How RUNTIMERESTORE Works

It is an error if the bootstrap cannot open f, if there are syntactic errors in the CONF commands in f, or if f contains any of the CONF commands that cannot be issued at runtime.

6.2.22.3. Runtime Restore of Configuration Parameters from a C Program

On UNIX and Windows NT, the MAINSAIL bootstrap contains an external C function, readMslConfFile, that reads CONF commands from a runtime configuration file and sets the parameters as specified. User programs may call readMslConfFile, but must do so before MAINSAIL is initialized (i.e., before the first call from C to MAINSAIL). Thus, it makes sense to call readMslConfFile only in programs where foreign code starts execution. If readMslConfFile is called after MAINSAIL is initialized, the effect is undefined.

The interface to readMslConfFile is:

int readMslConfFile (char *fileName, char **errStr)

This interface is subject to change, although XIDAK currently has no plans to change it. The fileName argument is a NUL-terminated string denoting the name of the CONF file to be read. The file name may contain environment variables and, on UNIX, may begin with ~ or ~userName. If a CONF command is specified more than once, then the last specification of the command takes effect. Commands specified at CONF-time are applied first, followed by those specified by user calls to readMslConfFile, and then those specified at MAINSAIL's initialization (when the first MAINSAIL PROCEDURE is called from the foreign language).

If readMslConfFile is successful, it returns 1. Otherwise, it sets errStr to a string denoting the reason for failure and returns 0.

6.2.23. SAVE s

SAVE causes CONF to create a configuration file s and then save the current set of configuration parameters in it. The parameters are saved as commands to CONF, exactly as they are entered from cmdFile.

6.2.24. SHOW

SHOW causes CONF to display the current values of all configuration parameters. STRING parameters with empty value are displayed as "".

6.2.25. STACKSIZE n

The STACKSIZE command specifies the number of storage units to allocate for the stack of each new coroutine. On some operating systems, the stack of the initial coroutine ("MAINSAIL") is not affected by the STACKSIZE parameter; if this is the case, the system-specific MAINSAIL documentation explains in further detail.

6.2.26. SUBCOMMANDS

SUBCOMMANDS is followed by a list of MAINEX subcommands that are executed before any commands or subcommands specified to the MAINEX * prompt (either typed in directly or specified in the COMMANDSTRING command). All valid MAINEX subcommands are allowed. Subcommands are given one per line, the last one followed by a blank line.

This command provides an alternative to COMMANDSTRING for entering subcommands. The subcommands specified in the standard MAINSAIL configuration and subcommands files are needed by MAINSAIL and must not be deleted. Subcommands can, however, be added to the SUBCOMMANDS section of the system configuration file.

6.2.27. SYSTEMLIBNAME s

SYSTEMLIBNAME specifies that the file s is the objmod library that contains the MAINSAIL runtime system MODULEs. This name must be changed from the default if the system MODULE library is moved or renamed.

6.2.28. System-Specific CONF Commands

Various operating systems provide target-specific commands. These commands include INITIALWORKINGDIR (MPNT only), MAXFOREIGNMEMORYSIZE (UIRS and UPA only), FOREIGNSTACKSIZE (UPA and UPA64 only), UNIXBITS (UNIX systems only), VIRTUALALLOCMEMSIZE (MPNT only), and WIN32BITS (MPNT only). Consult the appropriate operating-system-specific MAINSAIL user's guide for descriptions of these commands.