previous next top contents index framed top this page unframed
17.1. Executing a MAINSAIL Module
Any MAINSAIL module can be executed
from MAINED. The command QEm
executes a module, where m is either
the name of the module or the
name of the file that contains the module.
MAINED prompts for m
on the message line, offering as a default the last executed
module, if any. Terminal I/O for the module is directed to the
buffer CMDLOG.
CMDLOG is a buffer that can be altered by normal
MAINED commands. It differs from other buffers in that:
The use of CMDLOG is invisible to user modules. Thus, modules do not have to be modified to take advantage of MAINED's terminal I/O redirection feature. CMDLOG can be used to keep a log of a display-oriented MAINSAIL session. This log can be saved on a file by renaming the buffer CMDLOG, then saving it with the F command.
If you create a buffer named CMDLOG, subsequent
output from MAINSAIL
programs appears in that buffer, regardless of how the
buffer was originally created.
17.2. Escaping to Caller
When a QE command has been performed and the MAINSAIL module so
executing has been suspended (presumably by typing <ecm> in
CMDLOG while the module is waiting for input),
the E command is used to return to the suspended module.
If the module has a special display-oriented interface,
MAINED sets the mode letter to E (Escape mode).
MAINED commands are not available in escape mode.
If the module performs standard terminal I/O through CMDLOG,
MAINED positions the cursor on the last line of CMDLOG and
enters insert mode to allow you to respond to the suspended
module's prompt. If the prompt to which you typed <ecm>
to suspend the module is no longer present on the last line
of CMDLOG, MAINED rewrites it.
If there is no suspended module, MAINED rejects the E command with the message Nothing to escape to.
The .E command dislays the name of the module most recently invoked and still pending. Q.E shows all pending invoked modules (most recently to least recently invoked). See Table 17–1.
Table 17–1. Commands to Invoke Modules
| Command | Effect |
|---|---|
| E | Escape to caller, if any |
| QEs | Execute module s ($invokeModule) |
| .E | Show name of currently executing module |
| Q.E | Show names of all executing modules |
Any amount of editing activity can take place before typing the <eol> at the end of CMDLOG, which allows the suspended module to resume control. You can view and edit any number of other files or buffers before returning to CMDLOG and typing in the response. For example, you may want to view another file to help decide what response to type into CMDLOG. You can even execute other modules, by means of the QEm command, before responding.
When you return control to a suspended module by typing <eol> on the last line of CMDLOG, MAINED verifies that the prompt to which you typed <ecm> still appears as the first part of that last line. If not, MAINED reprompts. If so, MAINED takes the remainder of the line as the line of terminal input.
The -QF editor command, if available, may be used to exit MAINSAIL even while MAINED is awaiting an <eol> from the last line of CMDLOG. As always, it prompts to save each altered buffer. Use of the QF command in this situation, however, raises the exception $abortProgramExcpt, which usually aborts the executing program. If you wish to exit MAINED, you may have to type QF more than once.
The MAINSAIL compiler is described in the MAINSAIL Compiler User's Guide.
Assume the initial screen configuration is as shown in Example 17–2.
Type QEcompil<eol>; the resulting configuration is shown
in Example 17–3. The mode character in CMDLOG is set
to I because the module COMPIL is waiting for input to the
“compile (? for help):” prompt. There is no mode character
in the buffer POEM because the cursor is not located there.
Example 17–2. Initial Screen Configuration
Example 17–3. After Issuing the Command QEcompil<eol>
Assume there exist two files, one called poem with the
contents shown in the POEM buffer in the example, and one
called poet, which is a short MAINSAIL program. If
you type poem<eol> instead of poet<eol> to the
compiler prompt, the compiler attempts to compile the file
poem and gets an error, as shown in Example 17–4.
Example 17–4. After Typing poem<eol>
In Example 17–4, the compiler is prompting for an error
response. Part of the compiler's output to CMDLOG has been
scrolled out of the CMDLOG window. You can
enter command mode and view more
of the error message in
CMDLOG by typing <ecm>QY-4W, with the result shown
in Example 17–5. The QY command makes CMDLOG occupy
the entire screen, so the POEM buffer is no longer visible,
and the -4W scrolls four lines farther back.
Example 17–5. After Typing <ecm>QY-4W in CMDLOG
If you now wish to take a look at the file poet (to verify that
it is the file you really wanted to compile), issue the command
.Fpoet<eol><eol>, with the result shown in Example 17–6.
The second <eol> is required to answer the Initial page.line
prompt.
Example 17–6. Examining the File poet with .Fpoet<eol><eol>
You may now resume the suspended execution of COMPIL by means
of the E command. Since CMDLOG is not present on the screen,
it is placed in a new window, as shown in Example 17–7.
Example 17–7. After Returning to COMPIL with the E Command
First, enlarge the CMDLOG window by typing <ecm>Q+2Y.
Then type I to return to insert mode.
Then
type a c<eol> (an abbreviation for MAINSAIL compiler:
Abort compilation) to terminate the erroneous compilation.
See Example 17–8.
Example 17–8. Terminating the Compilation with a c<eol>
Type in the correct file name, poet<eol>. The result is
shown in Example 17–9.
Example 17–9. Compiling the Correct File
Finally, type <eol> to the compiler's prompt to end the
compiler session. The result is shown in Example 17–10. The
CMDLOG mode character becomes C, since the module is no
longer waiting for input. Typing the E command at this
point produces the message Nothing to escape to, since
there is no longer a pending compiler prompt.
17.3. Sample Invocation of the MAINSAIL Compiler from MAINED
This example shows the invocation of the MAINSAIL compiler from
MAINED on a screen 58 characters wide by 11 characters high.
A caret (^) is shown beneath the character at the cursor
position.
You may find it instructive to perform the steps shown,
making the changes required by a larger screen.
Initial page.line for poem (1.1): 1
-MAINED--1.1------------C----POEM-------------------------
: :
^
:Nvnc est bibendvm, nvnc pede libero :
:Pvlsanda tellvs, nvnc Saliaribvs :
:Ornare pvlvinar deorvm :
: Tempvs erat dapibvs, sodales. :
: :
: -- Horativs :
: :
E
Module or file name: compil
-MAINED--1.3------------I----CMDLOG-----------------------
:MAINSAIL (R) Compiler :
:Copyright (c) 1984-2002 by XIDAK, Inc., Point Arena, Cal*
: :
:compile (? for help): :
^
-MAINED--1.1-----------------POEM-------------------------
: :
:Nvnc est bibendvm, nvnc pede libero :
:Pvlsanda tellvs, nvnc Saliaribvs :
:Ornare pvlvinar deorvm :
Module or file name: compil
-MAINED--1.15-----------I----CMDLOG-----------------------
:Expected BEGIN :
:Error Response: :
^
E
E
-MAINED--1.1-----------------POEM-------------------------
: :
:Nvnc est bibendvm, nvnc pede libero :
:Pvlsanda tellvs, nvnc Saliaribvs :
:Ornare pvlvinar deorvm :
Module or file name: compil
-MAINED--1.11-----------C----CMDLOG-----------------------
:poem 1 :
: :
:ERROR: file poem page.line 1.2 (absLine 2) at ## :
:Nvnc## est bibendvm, nvnc pede libero :
:Expected BEGIN :
:Error Response: :
^
E
E
E
Initial page.line for poet (1.1):
-MAINED--1.1------------C----POET-------------------------
:BEGIN "poet" :
: :
:INITIAL PROCEDURE; :
:IF confirm("Would you like me to write a poem?") THEN :
: write(logFile,"Sorry, my Muse is on a break." & eol):
:EL write(logFile,"OK, I won't." & eol); :
: :
:END "poet" :
^
E
Initial page.line for poet (1.1):
-MAINED--1.14-----------I----CMDLOG-----------------------
:Nvnc## est bibendvm, nvnc pede libero :
:Expected BEGIN :
:Error Response: :
^
E
-MAINED--1.7-----------------POET-------------------------
: :
:END "poet" :
E
E
Initial page.line for poet (1.1):
-MAINED--1.20-----------I----CMDLOG-----------------------
:Intmod not stored :
: :
:compile (? for help): :
^
E
-MAINED--1.7-----------------POET-------------------------
: :
:END "poet" :
E
E
Initial page.line for poet (1.8):
-MAINED--1.28-----------I----CMDLOG-----------------------
:Objmod for POET stored on poet-usp.obj :
:Intmod for POET not stored :
: :
:compile (? for help): :
^
-MAINED--1.7-----------------POET-------------------------
: :
:END "poet" :
E
E
17.4. Simultaneous File Access Caveat
While a module is suspended, it is possible to
attempt to edit a file that the module currently
has open. This can lead to
problems on operating systems that do not support file locking or
multiple versions of files.
For example, suppose that while running the compiler from MAINED with an input file foo, a syntax error has been reported and the “Error response:” prompt displayed. At this point, you may type <ecm> and edit a buffer associated with the file foo. If you try to save the buffer before the compiler has gotten back to its “compile (? for help):” prompt, one of three things may happen: