

                    THE MODULA-2 POST-MORTEM DEBUGGER


        This file contains information on the new release of the
        post-mortem debugger. It should be read in conjunction
        with section J.2 in the Modula-2/ST version 2.00a manual.

        J.2.2  Starting the debugger

        To run the debugger double-click on the "DEBUG.PRG" icon.
        When the debugger has loaded it will look for the dump file
        "DUMP.COR". If this file cannot be found it will prompt you
        for it. Selecting the "CANCEL" button will stop the debug
        session. When the dump file has been successfully read the
        debugger will prompt for the failed program. Select the
        program that crashed and produced the dump file. Clicking
        "CANCEL" will again stop the debug session.

        The debugger will then set up the chain of procedure calls
        immediately before the crash. While doing this the debugger
        will search for reference files of some modules. If they cannot
        be found it will prompt you for them. Clicking "CANCEL" informs
        the debugger that no reference file exists. Selecting a reference
        file and clicking "OK" will allow the debugger to show information
        about the data and procedure names of a module. If no reference file
        exists, no data will be shown and only procedure numbers of the
        module will be displayed. The procedure numbers correspond the
        the ones output by the compiler to the listing file. See Chapter
        12 for more information on this.

        If the message "P-chain too long" appears, more than 23 procedure
        calls were executed. Only the last 23 calls will be shown.

        J.2.3   Debugging errors

        See section J.2.3 of the manual.

        J.2.4   Windows of the debugger

        See section J.2.4 of the manual.

        J.2.5   Debugger commands

        The debugger windows may be manipulated as any normal GEM
        window. They can be sized, closed, moved and fulled.

        The currently selected item in a window is shown in reverse
        video (i.e. white on black). This cursor can be moved up
        and down through keyboard and mouse commands.

        J.2.5.1 Universal window commands

        Full box in window
          -  Toggle the window between full size and normal size
        Close box in window
          -  Close the window and make the last topped window active
        Size box in window
          -  Resize the window
        Move bar in window
          -  Move the window to a new place
        P -  Switch to the process window
        D -  Switch to the data window
        T -  Switch to the text window
        M -  Switch to the memory window

        J.2.5.2 Universal cursor movement commands

        Up arrow box in scroll bar or cursor up key
          -  Move the cursor up one line if not at top
        Down arrow box in scroll bar or cursor Down key
          -  Move the cursor down one line if not at bottom
        Shift cursor up key or "last page" region of scroll bar
          -  Move the cursor up one page
        Shift cursor down key or "next page" region of scroll bar
          -  Move the cursor down one page

        The cursor position may also be moved with the mouse. Simply
        point to the required line and click the left mouse button.
        Alternatively, press the left mouse button and drag the cursor
        to the required line.

        J.2.5.3 Process window commands

        @  -  Regenerate the p-chain of the process which was running
              when the program was aborted. This command should be used
              after examining the p-chain of a PROCESS when you wich
              wish to see the main program process p-chain.

        J.2.5.4 Data window commands

        Cursor right key or right arrow in window
          -  Go into a structured variable
        Cursor left key or left arrow in window
          -  Pop out of a structured variable
        V -  Go back to the last level with variables
        C -  Display the global variables of a compilation unit
        @ -  Generate the p-chain of the currently selected variable
             of type PROCESS or POINTER TO PROCESS.

        J.2.5.5 Text window commands

        C -  Display the source of a given compilation unit.

        J.2.5.6 Memory window commands

        @ -  take the currently selected longword as the new address
             (indirect addressing). Used to skip down linked lists.
        #C  - show data as CHAR
        #B  - show data as bytes (8-bit hexadecimal)
        #W  - show data as words (16-bit hexadecimal, default)
        #I  - show data as integers (16-bit signed decimals)
        #U  - show data as cardinals (16-bit unsigned decimals)
        #A  - show data as addresses (16-bit hexadecimal)
        #LI - show data as long integers (32-bit signed decimals)
        #LU - show data as long cardinals (32-bit unsigned decimals)
        #R  - show data as reals

        J.2.6   View through the process window

        This window shows the procedure chain leading up to the crash.
        The items on each line are:

        -  The module the call was made from
        -  The procedure that made the call
        -  The module that was called
        -  The offset of the call relative to the beginning of the module

        If "(initialisation)" occurs in the second column, the
        initialisation code of the module specified in the first column
        made a procedure call.

        To view the local data of a procedure, simply select the
        procedure that you wish to view from the second column and
        select the data window (by pressing the "d" key or pointing
        to the d window and clicking).

        J.2.7   View through the Data window

        The data window shows the local variables and parameters
        of the current procedure selected in the process window or
        global variables of a compilation unit.

        When there is no reference file for a module the debugger
        will show no data for any selected procedure of that module,
        nor the global data of the module.

        Variables are displayed as follows:

        INTEGER  - shown as 16-bit signed decimal number
        CARDINAL - shown as 16-bit unsigned decimal number
        LONGINT  - shown as 32-bit signed decimal number
        LONGCARD - shown as 32-bit unsigned decimal number
        BYTE     - shown as 8-bit hexadecimal number
        WORD     - shown as 16-bit hexadecimal number
        ADDRESS  - shown as 32-bit hexadecimal number
        CHAR     - shown as character if printable, octal otherwise
        PROCESS  - shown as 32-bit hexadecimal address of process descriptor
        POINTER  - shown as 32-bit hexadecimal address (where pointer points)
        BITSET   - shown as 16-bit binary, bit 15=leftmost
        BOOLEAN  - shown as TRUE or FALSE

        Enumerations are shown as the enumerated element.

        To enter a structured variable (RECORD, POINTER, ARRAY, large set)
        press the right arrow key or click the right arrow button in
        the window. This will display the RECORD fields, dereference the
        pointer, display the array elements, or display the members in
        the set. To pop out of a structured variable, press the left arrow
        key or click the left arrow button in the window.

        To view the global data of a separately compiled module, press
        the C key (for "compilation unit"). You will be presented with
        a selection of modules that were used by the program. Position the
        cursor over the one you wish to view and press the return key.
        Alteratively, double click the left mouse button over the required
        module.

        Before viewing the data of a compilation unit using the above
        sequence the debugger may need the reference file. It will prompt
        you as in section J.2.2.


        J.2.8   View through the Text window

        The text window shows the text of the currently selected
        procedure in the process window. To view a different separately
        compiled module press the C key and select the module as with
        the data window.

        The debugger automatically looks for the source file to a module.
        If it cannot find the source file it will prompt you for it.
        clicking the "CANCEL" button informs the debugger that there
        is no source file. Selecting "OK" will show the source file
        for that module.

        To view the text of a procedure without searching through a
        large source file, go to the process window, select the required
        procedure from the second column and switch to the text window.
        The cursor will then be positioned at the procedure heading.

        J.2.8   View through the Memory window

        The memory window displays the memory image held on the dump
        file at the moment of the crash. The representation of the
        data may be changed as described in section J.2.5.6, and will
        not change when leaving and re-entering the memory window.

        The base address of local data for the currently selected
        procedure or module in the process window is shown by a ">"
        sign. When the memory window is entered, the cursor is placed
        at this position. Note that it may not be displayed when ADDRESS,
        LONGCARD, LONGINT or REAL numbers are shown. Select the BYTE
        representation and the maker will appear.
