+IV Issuing Commands to MEND
+===========================
+
+IV.1 Types of Commands
+----------------------
+
+There is a need in debugging systems similar to MEND for two types of
+commands for controlling operation. One type is a set of short,
+immediate-action commands that the user of the debugging system may
+issue at any time, such as a command to completely stop all activities
+of the debugging system and to exit. The other type is the set of all
+commands not belonging to the first set. This includes commands that
+take arguments and those that can only be given while the application
+program is suspended from execution.
+
+IV.2 Immediate Interrupt-Level Commands
+---------------------------------------
+
+In MEND's normal mode, various actions occur automatically. Most
+importantly, the application program is executing and the displayed
+representation of the MSTACK is being updated correspondingly. During
+this time the programmer may type ahead to the application program,
+but, since there is only one physical cursor that is used by both
+MEND's display and typein echoing that must therefore jump back and
+forth between the two text entry positions, a large amount of typein
+is awkward. Therefore, all immediate action commands that the user can
+issue while MEND is in automatic mode are single characters. To
+minimize the chance of conflict with typein that the executing
+application program might read, MEND immediate action commands are
+invoked by typing certain ASCII control characters. Furthermore typing
+one of these control characters causes an interrupt to occur which is
+handled by MEND and allows immediate response.
+
+Note that this arrangement requires that there be certain reserved
+characters, as listed below, that cannot be used to communicate with
+the application program. Normally this presents no difficulty. An
+alternative method was considered that required the reservation of
+only one control character. However, the user would be required to
+type an additional character as an argument signifying what function
+is intended. There did not seem to be a great advantage to this scheme
+and it was considered after the first scheme had been implemented. For
+this and other reasons stated later in this section, the alternative
+scheme was discarded.
+
+From the user's viewpoint, the currently implemented interrupt-level
+commands are as follows. (ASCII control characters are represented by
+"↑" followed by the corresponding letter.)
+
+ ---- ------------------------------------------------
+ ↑L clear screen, reprint stack and input
+ ↑Q Quit from current MEND
+ ↑E End automatic mode
+ ↑B Begin automatic mode
+ ↑U Unprint (stop displaying stack)
+ ↑P Print (start displaying stack)
+ ↑O skip Over (completely evaluate) current object
+ ↑N Next step (used when not in automatic mode)
+ ---- ------------------------------------------------
+
+The command invoked by typing ↑L is for housekeeping purposes. It
+causes extraneous information (e.g., old program output) to be cleared
+from the screen and all MEND-related constantly-displayed information
+to be reprinted. Unread input is also reprinted.
+
+The command invoked by typing ↑Q is used to exit from an invocation of
+MEND. It has the effect of stopping all actions related to monitoring
+the application program and allowing the program to continue normally.
+In this way a programmer may discard MEND and continue running the
+application program without the need for restarting it at the
+beginning.
+
+The two commands invoked by typing ↑E and ↑B switch MEND between
+automatic mode, the only one described thus far, and non-automatic
+(command) mode. Command mode will be described in the next section.
+
+Sometimes it is desirable for the sake of saving both computer time
+and the application programmer's time to turn off printing of the
+MSTACK. MEND will continue to monitor program execution and store the
+appropriate information but it does not display it. Nor does it pause
+between steps in the normal manner. This is mainly useful when
+breakpoints are present to turn on printing or switch to command mode.
+At that time MEND will know how it got to the current level and will
+be able to display the MSTACK as usual. Two commands invoked by typing
+↑U and ↑P toggle the state of printing.
+
+Whenever the programmer is satisfied that a particular call of a
+function is working properly or for some reason he or she is not
+interested in seeing the details of evaluation of some object, typing
+↑O just before the object's evaluation invokes a command that causes
+MEND to skip over that evaluation and continue normal monitoring and
+display immediately after a value is returned. Unlike turning off the
+printing, no monitoring is performed here at all so the evaluation
+proceeds as fast as it would without MEND. This is actually handled by
+causing Muddle to leave single-stepping mode during the evaluation of
+the object.
+
+The last command, invoked by typing ↑N, is special in that it is
+ignored in automatic mode. Its actions in command mode will be
+described in the next section. It is an interrupt-level command mainly
+for convenience and compatibility with DEBUGR.
+
+Bruce Daniels' DEBUGR is the prototype Muddle multiprocessing
+debugging system. It provides a simple user interface to Muddle's
+single-stepping functions that makes single-stepping through a Muddle
+program appear similar to single-stepping through an assembly-language
+program with DDT[^18][^19]. The choices of characters for invoking
+many of the MEND functions were based upon the characters used to
+invoke similar functions in DEBUGR. Many of DEBUGR's command
+invocation characters were in turn based upon those in DDT. The object
+of all of this is to build character/command associations in the
+user's mind that may be carried over from one system to the next.
+
+Several other control-character commands are handled by MEND
+invisibly. That is, the user may not be aware that they are being
+handled. Most of these are commands that are already being handled by
+other subsystems but must be intercepted by MEND to maintain
+consistency in its environment. Two of this type, invoked by typing ↑S
+and ↑G, are already set up in an initial Muddle and a third, invoked
+by typing ↑F , is set up by the subsystem EDIT, which is called by
+MEND as described in the next section. All three of these are used to
+escape to various command levels. MEND has its own command level (see
+next section) and must in many cases escape to that one instead to
+maintain control. Until a method was discovered for having ITS section
+the screen, it was necessary to also interrupt on carriage-returns
+(↑M, the new-line character) on input to insure that typein was kept
+in the proper section.
+
+IV.3 MEND's Command Level
+-------------------------
+
+Sometimes the user may wish to stop the application program at some
+point to examine it in more detail or to alter it or its environment
+in some way. Alternatively the user may want to issue commands to MEND
+that require arguments. A command level is provided for both of these
+activities.
+
+The command level differs from the automatic mode described in the
+last section in two ways. First, the application program is not
+continually executing. It runs one step at a time under the direct
+control of the user rather than automatically. Second, in
+non-automatic mode typein is normally passed to MEND instead of the
+application program, even that class of typein which does not produce
+immediate action.
+
+When the application program is stopped, the user may either request a
+service from the debugging system or examine and/or modify the program
+and/or its environment. Since editing functions form a large part of
+the latter class of actions, it was decided that instead of requiring
+the user to "import" an editor, MEND should provide an editor by
+making one available at command level.
+
+It is generally believed and empirical evidence indicates, that
+creating a new editor is "the kiss of death" for a Muddle subsystem. A
+number of Muddle editors have been tried over the years and the only
+one that finally became generally accepted (and is now pre-loaded in
+Muddle) is EDIT[^20] . Members of the Muddle community will tolerate
+minor changes to EDIT, but they will not accept a new editing system.
+The situation is analogous to one of the major obstacles blocking the
+acceptance of ESP. Programmers were accustomed to using DDT to examine
+and modify their machine-language programs. ESP was not compatible
+with DDT and therefore did not provide the familiar interface desired.
+
+In view of the situation, it seemed desirable to incorporate EDIT into
+the command level, essentially unaltered. EDIT uses a special reader
+that either interprets input as a command to it or passes input on to
+the normal Muddle reader. At first the task of superimposing a MEND
+reader on top of both of these appeared difficult. After much
+discussion with the current maintainer of EDIT, a very satisfactory
+solution was arrived at.
+
+A general capability was added to EDIT allowing the specification at
+runtime of a table of EDIT-like commands to be handled by
+programmer-defined functions. This table is searched before EDIT's
+command table and thereby provides a capability to override standard
+EDIT commands. MEND basically uses an invocation of EDIT as its
+command level with all MEND commands included in a table as described.
+EDIT-format commands are all one or two letters and may take suffix
+arguments. Currently the MEND table includes the following commands.
+(FIX here means a Muddle object of type FIX, i.e., a fixed-point
+number. FLOAT means a floating-point number. PPRINT[^21] is a function
+that prints a Muddle object in a format which indicates the positions
+of its elements and sub-elements in the tree hierarchy.)
+
+ NAME ARG TYPE MEANING
+ ------ ---------- --------------------------------------------------
+ ? none type out short summary of MEND commands
+ ?? none type out complete summary of all commands
+ O any Open object or MCSTACK level n (if arg n is FIX)
+ V none toggle Verbosity
+ N FIX do Next n steps (like ↑N)
+ OV none skip OVer current object (like ↑O)
+ Q none Quit EDIT & return to automatic mode (like ↑B)
+ QM none Quit MEND (like ↑Q)
+ SN FIX Set number of lines used for stack display
+ SV FIX Set leVel below which MEND will not 1STEP
+ SD number Set Delay time (FIX or FLOAT) between steps
+ PD FIX Pprint Displayed object in level n
+ PO FIX Pprint Original (actual) object in level n
+ AI any Add an Item to the list being monitored
+ DI FIX Delete Item number n from the list
+ PI FIX Pprint Item number n
+
+What the user types to the command level is inspected by EDIT. If it
+looks like an EDIT command, it is looked-up in the MEND command table
+or the EDIT one and handled as appropriate. Otherwise it is passed to
+the Muddle reader. In general any interesting (useful) input that
+Muddle should read and evaluate will not look like an EDIT command, so
+there is no confusion.
+
+As can be seen from the table, the MEND commands include general
+information retrieval ones (? and ??), system tailoring ones (V, SN,
+SV, and SD), and commends that allow objects to be accessed in special
+MEND locations (O, PD, PO, AI, DI, and PI. The O command is special in
+that it allows an object known only by its location in the MSTACK to
+be opened for examination and alteration by the normal EDIT commands.
+The remaining commands duplicate control-character commands except
+that they are read at normal input level rather than at interrupt
+level.
+
+The most powerful feature of this command level is seen when Muddle
+objects are evaluated. This level, and therefore the evaluation, uses
+stack space below the application program and in the same process. All
+bindings and pending evaluations of the program are above the command
+level where they may be examined and modified at will. Most of what
+constitutes MEND is in another process safely removed and hidden from
+the user. Even the small amount of overhead constituting the command
+level function is hidden from functions such as FRAMES[^22], which may
+be used to view the levels of the application program's current
+control stack. The effect is much the same as that of Muddle's
+listening loop which is invoked at the current bottom of the stack in
+case of error, to allow the programmer to run any program (evaluate
+any object) to find and correct the problem.
+
+Note that for critical examination of the program, the user may
+request that it be continued for a limited number of steps (usually
+one) with control then being returned to him or her at the command
+level. One normally would employ such a feature when the program is
+executing statements near the area of suspected trouble but it is not
+entirely clear how or why the program is misbehaving.
+
+IV.4 Breakpoints
+----------------
+
+Normally MEND operates in automatic mode where the application program
+is running continuously. If one is aware of a particular area of
+concern, one cannot and should not have to see that area as it is
+reached and quickly type ↑E in order to stop the program. One may have
+the program running with a very small delay time or have the printing
+turned off.
+
+In their simplest form, MEND breakpoints stop the program when
+evaluated, putting the user in command mode if she or he was not
+already in it. This is the Muddle equivalent of DDT breakpoints, which
+stop a program at a certain instruction. The breakpoints can also be
+conditional, where the evaluation of an arbitrary object determines
+whether or not to actually break at that point.
+
+The breakpoints as so far described are very much like the breakpoints
+that can be set by EDIT. As a matter of fact, EDIT is used to set and
+clear these breakpoints just as it would be in the absence of MEND.
+The only real difference is that, when MEND is present, a MEND
+function is called to handle the break instead of an EDIT function.
+
+MEND breakpoints would be useful even if they only did what was just
+described. However they are more powerful. A standard EDIT-style
+breakpoint is a call to the break function with a number of arguments.
+The first of these is the object at which the breakpoint is set, which
+will be evaluated when the user returns from the breakpoint and whose
+value will be returned by the break function to the application
+program. The next is the conditional object and the rest are objects
+to be evaluated and printed at each break. MEND's break function
+handles these as EDIT's does but also looks for a recognized ATOM
+(variable name), which may come after or replace the conditional. If
+such an ATOM is found, it will cause a special action to occur instead
+of stopping the program:
+
+ ------- ---------------------------------------
+ ON printing will be turned on (like ↑P)
+ OFF printing will be turned off (like ↑U)
+ GO free-run the object (like ↑O)
+ PRINT just print arguments & continue
+ ------- ---------------------------------------
+
+Other arguments will still be printed and all actions are still
+predicated upon the value of the conditional.
+
+The first two special ATOMs (ON and OFF), perhaps coupled with manual
+control, are used to allow the MSTACK to be viewed only during areas
+of interest while maintaining maximum speed in other places. The next
+one (GO) is used to avoid wasting time examining the details of a
+functional call that is known to be working and is probably evaluated
+repeatedly. When the break function returns, single-stepping resumes
+as before the break. The last special ATOM (PRINT) is used to give
+information at key places that might not otherwise be seen.
+
+One thing that was considered extremely important was to make MEND's
+breakpoints compatible with those of EDIT. The problem is that a
+breakpoint inserted outside of MEND might still be present when MEND
+is started and vice versa. As has been stated EDIT breakpoints work
+almost exactly as usual when handled by MEND's break function. The
+converse is not quite true. EDITs break function will ignore the
+significance of a special ATOM end simply print it as a normal
+argument. Fortunately, an ATOM evaluates to itself. If it is in the
+conditional position it will always be considered "true" and no harm
+will be done.
+
+It would be easy to extend this arrangement to other special ATOMs if
+other functions were considered useful. The above seem to form a basic
+set in this system. At least they are useful and no one has yet
+suggested another type of breakpoint that would also prove useful.
+
projects / mudman.git / commitdiff