36.4. $getCommandLine

Many operating systems allow the user to invoke a program using a command line, which can specify information other than just the program name. For example, a command line foo a b c could mean to execute the program foo with arguments a, b, and c. $getCommandLine gives a program access to command arguments, which may have been set by the operating system or by a MAINSAIL program.

A command line can be specified in the following ways:

• At the operating system level, when MAINSAIL is invoked.

• At the MAINEX * prompt.

• During program execution, in a call to $invokeModule.

• During program execution, using $setCommandLine.

In the case of a command specified at the operating system level, MAINSAIL alters the command line if necessary to put it into a more portable form:

• On some operating systems, the program name is part of the command line, i.e., foo in the example above. In this case, MAINSAIL removes the program name (and any blank space after it) from the command line. In the example, the command line would be altered to be just a b c. Thus the name of the program is not available in the command line formed by MAINSAIL (it may be available as $programName).

• On some operating systems, the command line is parsed and broken into a sequence of arguments before MAINSAIL has access to it. In this case, MAINSAIL concatenates the arguments, separated by a single blank, into a STRING that becomes the command line. For example, if the command line typed to the operating system were foo  a   b  c, i.e., with several blanks separating the arguments, and the operating system broke this into a program name and three arguments a, b, and c, MAINSAIL would form the STRING "a b c" as the command line.

• The exact rules for the formation of the command line information provided by the operating system into a single command line STRING by MAINSAIL is provided in each system-specific MAINSAIL user's guide if not covered by the above points.

• The resulting command line is concatenated onto the end of the COMMANDSTRING value specified in the MAINSAIL bootstrap file. This value is the null STRING unless a value was specified for the COMMANDSTRING command when CONF was used to make the bootstrap. If the resulting concatenated STRING is non-Zero, MAINEX executes MODULE(s), one for each line in the command STRING (interpreting the first word of the line as the MODULE name, and the rest of the line as the MODULE's arguments), until the command STRING is exhausted and then returns to the operating system. In this case, the MAINSAIL banner and the MAINEX * prompt are not displayed.

In the case of arguments specified at the MAINEX * prompt, MAINSAIL removes the first word (presumably the MODULE or file name to be invoked), as if with $removeWord, and sets the command line to what remains. This means that the user cannot specify to the * prompt an initial file name containing embedded blanks, since the components of the file name after the first word would be treated as part of the command line rather than as part of the file name.

The MAINSAIL runtime system makes the operating system's command line arguments visible to a MAINSAIL program by calling the system PROCEDURE $setCommandLine. $setCommandLine sets the command line to its argument (which may be the null STRING), with leading and trailing blanks, tabs, and end-of-line and end-of-page characters removed, and also sets an internal BOOLEAN variable to TRUE to indicate that the command line is set.

$getCommandLine is used by a program to examine the command line. $getCommandLine examines the internal BOOLEAN variable maintained by $setCommandLine. If it is TRUE, then $getCommandLine sets its argument to the command line, sets the BOOLEAN variable to FALSE to indicate that the command line is no longer set, and returns TRUE. If the BOOLEAN variable is FALSE, then $getCommandLine sets its argument to the null STRING and returns FALSE.

The PROCEDURE $nextCommandLineArg is intended to be used to parse command lines. It divides a command line into arguments and supports syntax to allow empty arguments or arguments with embedded blank space; see Section 42.12.

If several calls are made to $getCommandLine without any intervening calls to $setCommandLine, the first one will obtain the command line, and subsequent ones will not. If a particular access to the command line does not need to process all of it, call $setCommandLine with the unprocessed part to make it available to the next call to $getCommandLine.

$getCommandLine should be called before any other PROCEDUREs in a MODULE's INITIAL PROCEDURE. MAINSAIL system calls may cause an arbitrary amount of work to be done, possibly including the invocation of other MODULEs that change the remembered command line.

For example, each of the following invocations of the bootstrap mainsa is treated as described:

1. mainsa foo<eol>

   MAINSAIL is invoked and executes the MODULE FOO. The command line is the null STRING. The MAINSAIL herald is not displayed. When FOO terminates, MAINSAIL exits to the operating system.

2. mainsa foo a b c<eol>

   Same as (1), except that the command line is a b c.

3. mainsa<eol> followed by *foo a b c<eol>.

   Same as (2) except that the MAINSAIL herald is displayed and MAINSAIL returns to the * prompt if FOO terminates normally.

$invokeModule uses only the first word of its STRING argument as the name of the MODULE to invoke; the remainder of the STRING is used to set the command line.

The definition of $getCommandLine is intended to allow a program to distinguish between an operating system that does not support command line arguments (the first call to $getCommandLine returns FALSE) and an operating system that does support command line arguments, but where no arguments were provided for the current program ($getCommandLine returns TRUE but sets its argument to the null STRING).

Several XIDAK utility programs examine the command line, as described in the MAINSAIL Utilities User's Guide and MAINSAIL Compiler User's Guide. The command line syntaxes described therein are subject to change.