
--------------------------------------
Application : !Throwback  1.1
Author      :  Joe Taylor April 1993
Purpose     : BASIC Error throwback

              RISCOS 3 only

--------------------------------------

----------------
0. INTRODUCTION
----------------

   !Throwback is an application which enables error-throwback for BASIC
   programs.

   I.e. when an error occurs in BASIC a window opens on the desktop
   containing the appropriate error information. Clicking on this window
   causes an editor text window to open up with the cursor placed at
   the appropriate faulty line.

   'C' programmers will already be used to this facility which is part
   of Acorn's Desktop Development Environment (DDE).

   !Throwback has two modes of operation:

   (a) (The 'clean' method)
   
       IF your editor is capable of handling BASIC programs AND 'C'-type
       throwback then !Throwback will use this in preference. (Note that this
       requires a copy of Acorn's DDEUtils module)

   (b) ('Simulated' throwback)

       Even if you don't own such facilities never fear we can still produce
       error throwback by simulation.

       This works perfectly happily with the text editor !Edit in the built-
       in Resource filing system for example and !Throwback will use this
       editor and method as a last resort.
       

    !Throwback has been written to support the writing of BASIC programs,
    without line numbers, using a desktop text editor.Here is a summary of
    !Throwback's use with some well-known text editors

            Editor        'C'-throwback     Simulation     line-numbers
                              
            !Edit                                           normal
            !DeskEdit                                      normal
            !StrongEd                                       logical
            !Zap                                            logical

         N.B.'C'-type throwback for !DeskEdit requires that the text window
          is already open on the desktop otherwise the file is not de-tokenised.

    
     Snag 1 :  In BASIC the line number reported when an error occurs
     ------    (given by the value of the BASIC keyword ERL) is the line-number
               used by the BASIC command-line and is not necessarily the same
               as the "logical" line number.For example the program

                        10 x=1
                        20 PRINT x/0
                        30 END

               has a "division-by-zero "  error at BASIC line 20 but "logical"
               line 2.

              Each editor has a different default when you save a program
              from its text window  without line-numbers.

              !Throwback assumes that lines are numbered "normally" i.e
               starting with line 10 and then in increments of 10. This
               corresponds to !Edit's default

               Technical note
               
               To switch !Throwback to assuming that lines are numbered
               'logically' set the system variable, Basic$Options to the
               value 'l' i.e

                           *Set Basic$Options "l"

               If this system varaiable contains no 'l' then !Throwback
               defaults to 'normal' line numbering.
              
                

--------------
1. SETTING UP
--------------

   Simply double-click the application !Throwback in the usual way.

   This only needs to be done once before each error-throwback session begins.

         ********************************************************************
         *                                                                  *
         *                              SUGGESTION                          *
         *                              ----------                          *
         *                                                                  *
         *                                                                  *
         *     Add a line to your !Boot file                                *
         *                                                                  *
         *            *Filer_Run <PathName>.!Throwback                      *
         *                                                                  *
         *     where <Pathname> is the directory in which you have stored   *
         *     !Throwback on your disc containing the !Boot file.           *
         *                                                                  *
         *                                                                  *
         ********************************************************************

-------------------------------------------------
2. ORGANISING THROWBACK FOR SIMPLE BASIC PROGRAMS
-------------------------------------------------

   A "simple" BASIC program is one which is non-multitasking. (E.g. those
   programs which are run by double-clicking their icon in a Filer window. For
   multi-tasking see below.)

   In BASIC the programmer has to "trap" and deal with errors by using the
   "ON ERROR" command; see the "BASIC PROGRAMMING MANUAL"

   To use the error throwback facilities of !Throwback make the first line
   of your program

               ON ERROR CHAIN "Edit:Throwback"
  
   or even better (if you understand procedures) make your program of the form

               ON ERROR PROCError
               <Your program lines here>
               END
               :
               DEF PROCError
               ON ERROR OFF
               CHAIN "Edit:Throwback"
               ENDPROC

    N.B.  When an error is comitted in BASIC the control is passed to the
    ===   statements following the most recently executed "ON ERROR" command.

          Thus in the second example above the procedure "PROCError" would
          be obeyed on the first occurrence of an error. The first command in
          this procedure turns the error handler off. THIS IS A VERY WISE
          MOVE!!!!!!!!! IF AN ERROR OCCURS IN PROCError AND THE ERROR HANDLER
          IS NOT TURNED OFF THE PROCEDURE WOULD CALL ITSELF AD INFINITUM. THE
          ONLY WAY OUT WILL BE TO REBOOT THE MACHINE SO RESULTING IN A LOSS
          OF DATA - BE WARNED!!!!!!! (Such an error occurs in the above
          example if you haven't run !Throwback and the program "Edit:Throwback"
          cannot be found, or if you mis-type its name, etc.)


------------------------
3. THE THROWBACK WINDOW
------------------------

    If "!Throwback" is used in the manner described in 2 , when an error
    occurs in a program, a window opens on the desktop of the form:
                 _______________________________________
                 |  |  |    Error in Basic Program   |
                 
                 |                                     |
                 |  Error at line # |
                 |  |                                | |
                 |  |       <Error message>          | |
                 |  |                                | |
                 |   |
                 |  line numbers                |
                 |  |                 |                |
                 |  | normal         |       |
                 |  |         redo   |   |Throwback|  |
                 |  | logical        |       |
                 |  |                 |                |
                 |                  |
                 |_____________________________________|

    (N.B. The throwback window stays open on the desktop untl you
    close it - by clicking on its "close" icon.)

    Clicking on the button marked "Throwback" will open a window on the program
    file (if none was already open) and the line containing the error will be
    highlighted and the cursor placed at the beginning of the line ready for
    editing.


    PROBLEMS
    
    
    1. Throwback to WRONG program file.
    
    
       (a) For "simple" BASIC programs this is unlikely to happen.

       In this case the file used for throwback is taken from the value of
       the system variable Basic$File which was set to the pathname
       of the BASIC program file when its icon was double-clicked.

       ( Note for the technically minded:   
         
         When !Throwback is Run the so-called "Run alias" for BASIC files
         [the system variable "Alias$@RunType_FFB"] is changed to include the
         command
                      *Set Basic$File %0

         which sets the value to the file double-clicked. This means that
         for simple programs the user can ignore the setting of this variable.)

        (b) LIBRARIES
            
            Libraries of BASIC procedures are loaded by using the command

                           LIBRARY "<file>"

            from within your program. Any procedure in this library can
            be used in your program. If an error occurs in one of the
            library procedures !Throwback still works provided that the
            first line of the program contains the correct pathname of
            the library. I.e. the library has the form

                         REM > <file>
                         ...
                         ...
                         
                         library procedure definitions
                         
                         ...
                         ...

            

             The use of pseudo-filing system variables is helpful here.


         (c)Multi-tasking Applications
             

             The value of Basic$File is set to the pathname of the last
             BASIC program which was *Run. For multi-tasking programs this
             might not be the program in which the error occurs.

             Standard applications contain a !Run file (of type "Obey")
             which in turn call the BASIC file "!RunImage".

             Writers of multi-tasking programs will be know that when a *Obey
             file is run the system variable Obey$Dir is set to its path. It
             is quite common to store the value of this variable at run time.
             Basic$File is playing the same role for BASIC files as
             Obey$Dir does for Obey files.

             In the !Run file of an application, called !Fred, place a line
             
                        *Set Fred$BasicFile <Obey$Dir>.!RunImage

             which stores the value at run time. Have a PROCError procedure
             as above except include a line which sets the value of
             Edit$BasicFile. E.g.

                         DEF PROCError
                         ON ERROR OFF
                         *Set Basic$File <Fred$BasicFile>
                         CHAIN "Edit:Throwback"
                         ENDPROC

        (d) Programs which are CHAINED
            

            In this case the value of Basic$File has to be set by the
            programmer as in (c).


        (e) DRAGGING
            

            IF a BASIC program or a "standard" application (i.e. with a BASIC
            !RunImage file) is dragged onto the throwback window the pathname
            of the file to throw back to changes appropriately.

            If you need to do this it is because you haven't been observing
            the "rules" in (a)-(d) above!


       2. Throwback to the wrong line (but the correct file)
       

          As a first resort try toggling between "normal" and "logical" line
          numbers. This will probably "cure" your problems.

          (Remember that !Throwback assumes line numbers in increments of 10.
           If, for example, your program actually has logical line numbers
           then an error on line 4 would be shown as "error at line 0.4". The
           remedy in this case is simple - choose logical line numbers.)

          If the line numbers are neither logical nor normal the program has
          to be renumbered. This can be done by clicking on the "redo" button
          on the throwback window. (Alternatively,Enter the BASIC command line,
          loading the program and giving the command RENUMBER followed by a
          SAVE.
           
       
        SUMMARY
        =======

        !Throwback is in effect controlled by two system variables:

        Basic$File  =  pathname of file containing error
        
        Basic$Options  If contains "l" then logical line numbers
                           otherwise normal.
                           If contains "+" the usual error messages will
                           be given before the throwback window is opened.

        Library path names are contained in their first line (as specified
        in BASIC programming manual)
        

             
            
         

        

       

    

   

               
   
