MAINSAIL Utilities User's Guide, Chapter 1

previous   next   top   contents   index   framed top   this page unframed


1. Introduction

This guide contains documentation for a number of MAINSAIL utility MODULEs. These MODULEs are included as part of the runtime system on every MAINSAIL release.

Some of the utilities are interactive programs meant to be invoked by a human user. Other utilities are program utilities that can be invoked only from a MAINSAIL program. Still others are basically interactive utilities that also provide a program interface.

1.1. Version

This version of the MAINSAIL Utilities User's Guide is current as of the proposed Version 16.30.1 of MAINSAIL (which has not yet been released).

This document is preliminary. Its contents have been updated to include information about the proposed 16.30.1 release, but the document has not been thoroughly proofread. Please contact XIDAK if you have any questions concerning this document or if you find any errors in it.

1.2. Command Syntax for Line-Oriented Utilities: File Names Containing Spaces

Many MAINSAIL utility commands use space as a separator between arguments, including file name arguments. This poses a problem for file names that contain spaces. Such file names are uncommon on UNIX but frequently used on Windows NT.

Most MAINSAIL utility commands that permit file names as arguments allow the file names to be enclosed in double quotes. For example, the MODLIB command ADD can add the MODULEs X, Y, and Z to a library file named My Library as follows:

ADD "My Libraryx y z

It is necessary to enclose a file name in double quotes only when the file name contains a space; quoting is optional otherwise. In fact, many commands where a file name cannot be followed by other arguments do not actually require that the file name containing spaces be quoted, because such commands treat all trailing characters as the file name. However, even in such cases, the commands permit file name arguments to be quoted; when in doubt, you should always quote a file name containing spaces.

1.2.1. Trailing Commas

Several MAINSAIL utilities (e.g., MAINEX and the MAINSAIL compiler) allow you to end an argument with a trailing comma to indicate that you will provide subcommands. In general, when commas follow quoted arguments, they may fall either inside the quotes or outside, so that:

"argument",

is equivalent to:

"argument,"

1.3. Changes to Utility Programs

XIDAK reserves the right to change the syntax of commands and arguments to its utility programs and the format of output from these programs. An effort will be made to keep command and output formats reasonably compatible with previous versions; however, if such compatibility would prevent XIDAK from implementing an increase in functionality, command and/or output formats will be altered.

XIDAK may eliminate some utility programs if they are obsolete or if their functionality is subsumed by some other program.

XIDAK reserves the right to create programs and commands for XIDAK internal use only. Such programs and commands are not documented in this manual and are subject to change or removal without notice.

1.4. Command Line Arguments

Only those utilities documented as accepting command line arguments do so; command line arguments are ignored by other programs.

Command line argument formats are subject to change.

In all cases, if no arguments are specified, the utilities prompt for any information needed. If arguments are specified, the program executes with prompting, then exits, unless documented otherwise.

When arguments are specified to MAINEX, the comma used to enter subcommand mode must follow the MODULE name, not the arguments. Thus, to enter subcommand mode following an invocation of DIR, do:

*dir, foo bar<eol>     —right

not:

*dir foo bar,<eol>     —wrong!


previous   next   top   contents   index   framed top   this page unframed

MAINSAIL Utilities User's Guide, Chapter 1