Liren Large Software Subsidy 9/09.iso/l/l076/1.ddi/README.TRU

Text File | 1988-12-13 | 9.4 KB | 316 lines

This file contains a few last minute notes concerning True BASIC
version 2.1 for the IBM PC.

1) Note that using the INSTALL file to copy files from the
   release disk to your hard disk can cause a bit of confusion
   if you use it while in a directory other than the root.  INSTALL
   creates subdirectories below the current directory to contain
   HELP, DO and LIBRARY files.  Since True BASIC normally looks
   for the these files in \TBHELP\, \TBDO\, and \TBLIBS\, it won't
   find them if they wind up in \XXX\TBHELP\, etc.  In this case
   you should change the aliases for these directories to point at
   the right place.  You also might want to set up a startup file
   so that these aliases are set up automatically.  Check the user
   guide for information on aliases and startup scripts.

2) A note on the ALIAS command.  The users guide gives examples
   an alias commands:

      alias library,a:,b:,c:
      alias library,c:mylibs,c:util\libs

   Any name given in an ALIAS command should contain a complete
   pathname that ends in a \.  So the examples should read:

      alias library,a:\,b:\,c:\
      alias library,c:\mylibs\,c:\util\libs\

3) The 'DO TRACE' program has a few new features.

      It can now trace line-numbered programs.

      It traces module initialization sections.

      It can now handle 'OPEN #1: SCREEN ...' followed by
      'PRINT #1: ...'.  This is done by changing the open
      screen window coordinates to match those of the output
      window used by the trace package.  This has a side
      effect of clearing the trace output window.  It also
      has a stranger side effect... since each screen that
      is opened on top of the trace output window maintains
      its own x,y coordinates for printing, programs that
      open multiple screens can print over each others output.

      There are now facilities for saving the trace output
      to a file.  For details see the end of this file.

4) A note for assembly programmers.

   The technique for creating routine headers for assembly language
   programs described in the True BASIC Users Guide doesn't work with
   the Microsoft Macro Assembler version 5.1.  This version doesn't
   allow the 'bswap' macro to be used with an address constant.

   One way to deal with this problem is to subtract an address constant
   of zero from that value - then bswap works ok.

   What follows is a copy of an example from the Users Guide, and
   a version changed so that it works with the new assembler.  The
   changed lines are marked by '***'.

;
; Demo program from IBM PC users guide
;
; Bswap inverts the 2 bytes of the argument.
;
; The PC wants 2 byte (word) values inverted so that the low order
; bits come first.  True BASIC wants the high order bits first.
;
bswap    macro    word
         db       high word, low word
endm

arg1     equ      dword ptr 0
arg2     equ      dword ptr 4

code     segment
         assume   cs:code
         org      0
;
; Routine preface
;
         db       0d4h,043h
         dw       0
         bswap    <offset tlen>   ; 'tlen' is the routines' size
         db       0,61h
         bswap    2               ; size of the name
         db       "in"
         bswap    3               ; size of the argument description
         db       "fn,"
;
; Routine starts here
;
input    proc     far
         lds      bx,[bp+arg1]
         mov      dx,word ptr[bx-2]
         in       al,dx
         xor      ah,ah
         lds      bx,[bp+arg2]
         mov      word ptr[bx],-1
         mov      word ptr[bx-2],ax
         ret
input    endp
tlen:

code     ends
         end

;
; Here's the same routine with the changes marked with '***'
;
bswap    macro    word
         db       high word, low word
endm

arg1     equ      dword ptr 0
arg2     equ      dword ptr 4

code     segment
         assume   cs:code
         org      0
rstart   equ      $               ; define beginning ***
;
; Routine preface
;
         db       0d4h,043h
         dw       0
         bswap    <offset tlen>   ; 'tlen' is the routines' size
         db       0,61h
         bswap    2               ; size of the name
         db       "in"
         bswap    3               ; size of the argument description
         db       "fn,"
;
; Routine starts here
;
input    proc     far

codestart equ     $

         lds      bx,[bp+arg1]
         mov      dx,word ptr[bx-2]
         in       al,dx
         xor      ah,ah
         lds      bx,[bp+arg2]
         mov      word ptr[bx],-1
         mov      word ptr[bx-2],ax
         ret
input    endp

rend     equ      $                   ; routine ends   ***
tlen     equ      rend-rstart         ; routine length ***

code     ends
         end

5) Trace log feature...

The DO TRACE program has been enhanced to allow "logging"
of trace data.  This trace information gives a record of the
line numbers executed, and can show a history of variable
values alongside the line numbers.


Logging All Variables

It's easy to log all line numbers and variable values.
There are three possibilities:

      DO TRACE,LOG           log everything to the screen
      DO TRACE,PLOG          log everything to printer
      DO TRACE,LOG TO file   log everything to text file


Logging Selected Variables

To log selected variable values, list those variables after
the keyword LOG.  To refer to variables in external routines,
precede the variable name with the routine name and a colon (:).
The examples below trace the variables A and S$ in the main
program, X in subroutine SUB, and Y in function FN$.

      DO TRACE,LOG(a,s$,sub:x,fn$:y)
      DO TRACE,LOG(a,s$,sub:x,fn$:y) TO file


Logging Only Line Numbers

To log only line numbers -- no variables -- use the keyword
LOG(#) instead of LOG.  For instance:

      DO TRACE,LOG(#)
      DO TRACE,PLOG(#)
      DO TRACE,LOG(#) TO file


Logging until a BREAK Condition

You may also ask the the trace stop when some condition becomes
true.  This makes it easy to pinpoint an error, and then backtrack
to find its causes.  Use the LOGBREAK or PLOGBREAK keywords,
and give the break condition first in the list of trace variables.
You may create compound conditions by using AND, OR, parentheses,
etc, as in True BASIC conditions.

      DO TRACE,LOGBREAK(i=0 or j=0,j,k)
      DO TRACE,PLOGBREAK(x^2+y^2<1)
      DO TRACE,LOGBREAK(name$="Hals") TO file


Turning TRACE On and Off

Your program can turn tracing on/off.  If you have a program
that runs for a long time, you can turn tracing on for only
the part of the program that interests you.  This avoids
enormous logging files.

To turn tracing on, CALL SetTrace(f) with f<>0.  To turn it
off, use f=0.  You can also CALL AskTrace(f) to find the current
value of the tracing flag.

SetTrace and AskTrace are part of the TRACE package.  You can
leave them in your program permanently if you LOAD the trace
package before you run your program.  Otherwise you must remove
them before you RUN your program.

Example:

     for i = 1 to 1000
         if i>995 then call SetTrace(1)
         let x = 1/(i-1000)
     next i
     end

Note:  Since SetTrace and AskTrace use numbers as flags -- not
logical values -- you can construct "levels" of tracing.  For
instance, to have 5 trace levels, where trace flag N always
shows all levels <= N, you could use:

     call SetTrace(3)        !trace levels <= 3
     call A
     call B
     end

     sub A                   !runs at trace level 2
        call AskTrace(lev)
        if lev<2 then call SetTrace(0)
        ....
        call SetTrace(lev)
     end sub

     sub B                   !runs at trace level 4
        call AskTrace(lev)
        if lev<4 then call SetTrace(0)
        ....
        call SetTrace(lev)
     end sub


Format of the LOG Output

The LOG output has the same format, whether it goes to the
screen, printer, or disk.  Each line executed is logged
on a new line by an asterisk and the line number: "*15"
for example.

If that line assigns a value to a traced variable, the
variable's uppercase name and value appears on that line.
Only the first 50 characters of a string's value are shown;
if the string is longer than 50 characters, the logged
value ends with "..." to show that some has been omitted.

If the line assigns to multiple variables, each variable
is logged on its own line.  Only the first line contains
the line number.

Finally, CALL and DRAW statements are logged twice: once
when the statement is executed, and once when control
returns from the called routine.  This makes it clear that
the routine has returned to its caller, and also gives a
place to record the (new) values of the parameters -- which
may have been changed by the CALL or DRAW.

Example Program:

 1    for i = 1 to 2
 2        call sub(a,b)
 3    next i
 4    end
 5
 6    sub sub(x,y)
 7        let x = x+1
 8    end sub

Output from DO TRACE,LOG:

      *1       I = 1
      *2
      *6       X = 0
               Y = 0
      *7       X = 1
      *8
      *2       A = 1
               B = 0
      *3       I = 2
      *2
      *6       X = 1
               Y = 0
      *7       X = 2
      *8
      *2       A = 2
               B = 0
      *3       I = 3
      *4