





                SOME PDP-11 BASIC-11
                 EXTENSION ROUTINES


                N. A. Bourgeois, Jr.
                Sandia Laboratories
                  Albuquerque, NM




                      ABSTRACT

     Some extension routines  to  Digital  Equipment
Corporation's  BASIC-11 V2 interpreter running under
RT-11 V03 are described.  They provide the means for
reading  (GET,  GETB,  TBIT) and writing (PUT, PUTB,
SBIT) words,  bytes  and  bits  at  any  implemented
UNIBUS  address,  identifying  (IDEN)  the  extended
BASIC-11 interpreter and zeroing (NULL) arrays.





                INTRODUCTION


     BASIC-11   allows   the   addition   of
assembly   language   routines   to   expand
BASIC-11's  capabilities.   Once  added   to
BASIC-11,  such  routines can be executed in
immediate mode or in programs, by  means  of
the CALL statement.

     The routines described  in  this  paper
permit access to any address on DEC's PDP-11
UNIBUS.  This is useful for  exercising  any
peripheral    connected    to   the   UNIBUS
especially if a handler is  not  present  in
the  operating  system.  In fact, it is even
possible  to  write  entire   handlers   for
non-standard  peripherals  such  as  digital
voltmeters and point plotters using BASIC-11
and  the  CALL  statement  with the routines
described in this paper.  These routines are
designed for use on any of the PDP-11 family
of computers running the RT-11 V03 operating
system.  [1,2,3,4,5]

     The  extension  routines   incorporated
within the file DATBAS.MAC provide the means
for reading and  writing  words,  bytes  and
bits  at  any  implemented  UNIBUS  address,
identifying    the     extended     BASIC-11
interpreter,  and zeroing or nulling arrays.
The values of the arguments may be expressed
in  either  decimal  or octal.  The routines
included are listed in Table 1.



           THE EXTENSION ROUTINES


     The   "BASIC-11   Language    Reference
Manual"  [1]  and the "BASIC-11/RT-11 User's
Guide"  [2]  describe  the  general  use  of
BASIC-11   and  the  CALL  statement.   This
section describes the use of the  extensions
of  DATBAS.MAC  and  their  associated error
messages.





  GET(ARG1,ARG2)  Input  a  word  from   a
  UNIBUS address
          ARG1 UNIBUS word address
          ARG2 Word value returned

  GETB(ARG1,ARG2)  Input  a  byte  from  a
  UNIBUS address
          ARG1 UNIBUS byte address
          ARG2 Byte value returned

  IDEN Output identification message

  NULL(ARG1(),ARG2(),...) Zero array(s)
          ARG()'s Name(s) of array(s)

  PUT(ARG1,ARG2) Output a word to a UNIBUS
  address
          ARG1 Word value delivered
          ARG2 UNIBUS word address

  PUTB(ARG1,ARG2)  Output  a  byte  to   a
  UNIBUS address
          ARG1 Byte value delivered
          ARG2 UNIBUS byte address

  SBIT(ARG1,ARG2,ARG3) Set or clear a  bit
  at a UNIBUS address
          ARG1 Bit number
          ARG2 UNIBUS word address
          ARG2 Bit value set

  TBIT(ARG1,ARG2,ARG3) Test  a  bit  at  a
  UNIBUS address
          ARG1 Bit number
          ARG2 UNIBUS word address
          ARG3 Bit value returned

                  TABLE 1.
           THE EXTENSION ROUTINES


     The arguments for GET, GETB, PUT, PUTB,
SBIT and TBIT may be constants, expressions,
variables  and/or  array  elements.    These
arguments  may  also  be  either  decimal or
octal.  A decimal  argument  may  be  either
numeric   (real)   or   integer.   An  octal
argument must be a string.  A numeric is one
or  more  decimal digits, either positive or





negative, in  which  the  decimal  point  is
optional.  An integer is one or more decimal
digits, either positive or negative, with no
decimal  point.   An  octal string is one or
more of the numeric characters excluding the
"8" and "9".  [1]

     No arguments are required with the IDEN
routine.

     The  NULL  routine  requires  only  the
name(s) of the argument(s).  The argument(s)
may be  the  name(s)  of  numeric  array(s),
integer array(s) and/or string array(s).

     Null arguments are not allowed.

     Descriptions of  the  routines  follow.
The   descriptions   include   the   calling
sequences, and where applicable  the  ranges
of the arguments.


     GET    Deliver  the  contents  of   the
UNIBUS word address of argument one into the
BASIC-11 variable named in argument two.

 Calling sequence:
  CALL GET(ARG1,ARG2)

              Octal             Decimal
  ARG1 Range: 0 to 77776        0 to 32766
              100000 to 177776  -32768 to -2
  ARG2 Range: 100000 to 177777  -32768 to -1
              0 to 77777        0 to 32767


     GETB    Deliver  the  contents  of  the
UNIBUS byte address of argument one into the
BASIC-11 variable named in argument two.

 Calling sequence:
  CALL GETB(ARG1,ARG2)

              Octal             Decimal
  ARG1 Range: 0 to 77777        0 to 32767
              100000 t0 177777  -32768 to -1
  ARG2 Range: 200 to 377        -128 to -1
              0 to 177          0 to 127


     IDEN    Output  a  message  identifying
the   extended   BASIC-11  interpreter.   No
arguments are required.

 Calling sequence:
  CALL IDEN


     NULL    Null or zero the array(s) named
in the argument(s).  The argument(s) must be
the  name(s)  of  either  numeric  array(s),
integer  array(s)  and/or  string  array(s).
Any  number  of  arguments  may  be   given,
subject   only   to   normal   line   length
limitations.

 Calling sequence:
  CALL NULL(ARG1(),ARG2(),...)






     PUT    Deposit the  value  of  argument
one  at  the UNIBUS word address of argument
two.

 Calling sequence:
  CALL PUT(ARG1,ARG2)

              Octal             Decimal
  ARG1 Range: 100000 to 177777  -32768 to -1
              0 to 77777        0 to 32767
  ARG2 Range: 0 to 77776        0 to 32766
              100000 to 177776  -32768 to -2


     PUTB    Deposit the value  of  argument
one  at  the UNIBUS byte address of argument
two.

 Calling sequence:
  CALL PUTB(ARG1,ARG2)

              Octal             Decimal
  ARG1 Range: 200 to 377        -128 to -1
              0 to 177          0 to 127
  ARG2 Range: 0 to 77777        0 to 32767
              00000 to 177777   -32768 to -1


     SBIT    Set the bit named  in  argument
one  at  the UNIBUS word address of argument
two to the value given in argument three.

 Calling sequence:
  CALL SBIT(ARG1,ARG2,ARG3)

              Octal             Decimal
  ARG1 Range: 0 to 17           0 to 15
  ARG2 Range: 0 to 77776        0 to 32766
              100000 to 177776  -32768 to -2
  ARG3 Range: 0 or 1            0 or 1


     TBIT    Test the bit named in  argument
one  at  the UNIBUS word address of argument
two.  The result is returned in the variable
named  in argument three.  If the bit tested
is clear then ARG3=0, and if set ARG3=1.

 Calling sequence:
  CALL TBIT(ARG1,ARG2,ARG3)

              Octal             Decimal
  ARG1 Range: 0 to 17           0 to 15
  ARG2 Range: 0 to 77776        0 to 32766
              100000 to 177776  -32768 to -2
  ARG3 Range: 0 or 1            0 or 1


     When  BASIC-11  finds  an  error  in  a
program  line or immediate mode statement it
prints an  error  message.   After  BASIC-11
prints   the  error  message  it  interrupts
execution of the program line  or  immediate
mode  statement  and  then  prints the READY
message.  These routines return three  fatal
error  messages,  one  on an argument error,
one for  lack  of  adequate  string  storage
space  and the other on an attempt to access
an     unimplimented     UNIBUS     address.
Descriptions  of these error messages follow
along   with   some   suggested   corrective
actions.





     ?ARGUMENT   ERROR   [AT   LINE   xxxxx]
Arguments in a CALL do not match in  number,
range or type, the arguments defined for the
CALL.  Ensure that  there  are  the  correct
number  of  arguments, that their values are
in the correct range, and that they  are  of
the correct type.  [1]

     ?NO STRING  SPACE   [AT   LINE   xxxxx]
BASIC-11 was unable to  allocate  space  for
the  output  string.  Reduce the size of the
program or the amount of string utilization.

     ?UNIMPLEMENTED  BUS  ADDRESS  [AT  LINE
xxxxx]    An  attempt  in a CALL was made to
input from or to output to an  unimplemented
UNIBUS  address.   Ensure  that the value of
the UNIBUS address to be accessed is valid.



                INSTALLATION


     The "BASIC-11/RT-11 Installation Guide"
[3]  describes the general technique used to
install assembly language routines into  the
BASIC-11 interpreter.

     Table 2 lists the set  of  files  which
make  up  the  DATBAS  package.   The  files
DATBAS.TEC and DATBAS.MAC are  needed  along
with     DEC's     BASIC-11/RT-11     binary
distribution package to  build  an  extended
BASIC-11 interpreter.  


  FILE NAME   DESCRIPTION

  DATBAS.BAS  BASIC-11 program to test the
              extension     routines    of
              DATBAS.MAC.

  DATBAS.DAT  Resulting    output     from
              execution of DATBAS.BAS.

  DATBAS.DIR  This directory of the DATBAS
              package.

  DATBAS.DOC  Full  description   of   the
              DATBAS     package     (this
              document).

  DATBAS.HLP  Brief description of the use
              of  the DATBAS.MAC extension
              routines.

  DATBAS.MAC  MACRO-11   source   of   the
              extension routines.

  DATBAS.RNO  Source file for DATBAS.DOC.

  DATBAS.TEC  TECO    macro    to     make
              DATCLI.MAC.

                  TABLE 2.
              THE DATBAS FILES


     Installation of these routines requires
five   steps.    They  are  modification  of
BSCLI.MAC, assembly of  the  DATCLI.MAC  and
the  DATBAS.MAC  extension files, generation





of a command file to build the  interpreter,
editing  the  command  file  to provide more
stack  space  and  finally   executing   the
command  file to build the extended BASIC-11
interpreter.

     DATCLI.MAC    is    constructed    from
BSCLI.MAC  by  executing  the TECO [6] macro
file DATBAS.TEC.  It adds  the  globals  and
the  FTBL  entries  required  to  access the
DATBAS.MAC routines.  The following commands
accomplish this.
        .SET EDIT TECO
        .EDIT/EXEC DATBAS

     The following  commands  will  assemble
DATCLI.MAC  and  DATBAS.MAC  to  produce OBJ
files  which  will  be  used  later  by  the
command file to build the interpreter.
        .RUN MACRO
        *DATCLI,LP:<BSMAC,DATCLI/C
        *DATBAS,LP:<DATBAS/C

     Now it is  necessary  to  generate  the
command file which will be used to build the
extended  BASIC-11  interpreter.   This   is
accomplished  by  executing  the single user
configurator   program,    SUCNFG.BAS,    as
described     in     the     "BASIC-11/RT-11
Installation Guide" [3].   During  the  CALL
part  of  the  dialog  answer  yes  for CALL
support and include the following modules in
the order shown.
        DATCLI
        DATBAS
        BSCLLB

                  CAUTION

  Do not use the double  precision  option
  with   these  routines.   They  are  not
  compatible   with    either    four-word
  floating point or two-word integer.

     The  extension  routines  require  some
extra stack space, therefore it is essential
that the  command  file  just  generated  be
edited to add at least 64 extra words to the
available stack space.  The  following  sets
of  command  strings  show both the TECO and
EDIT syntax to accomplish this task.
        .RUN TECO           .RUN EDIT
        *EBDATBAS.COM$      *EBDATBAS.COM$
        S/B:1$DI2$          G/B:1$DI2$
        EX$$                EX$$
        .                   .

     The command file is finally  ready  for
execution  to  build  the  extended BASIC-11
interpreter.  Use the following  command  to
execute the command file.
        .@DATBAS

     At  this  point   the   newly   created
extended  BASIC-11  interpreter is ready for
use.

     Once the extended BASIC-11  interpreter
has  been  built  it  should be tested.  The
program, DATBAS.BAS,  thoroughly  tests  the
extensions.  Messages are output to identify
the particular test being performed.   Fatal
errors,  if  any, are reported in BASIC-11's





normal error message format [1].   Non-fatal
errors   are   reported  with  the  message:
ERROR: xxxxxxxxxxxxxxx.



           MISCELLANEOUS COMMENTS


     The "BASIC-11/RT-11 User's  Guide"  [2]
describes   how  to  add  assembly  language
routines to  BASIC-11.   This  includes  the
general   format   of   the   routine,   the
procedures to access arguments and  the  use
of  some routines provided by BASIC-11.  The
procedure for incorporating  the  additional
routines  into  the  BASIC-11 interpreter is
described     in     the     "BASIC-11/RT-11
Installation  Guide" [3].  This section will
add to the information  contained  in  these
two references.

     It is  convenient  to  use  the  Online
Debugging   Technique   (ODT)  [5]  facility
provided by DEC to debug  assembly  language
extensions  to  BASIC-11.  When this is done
it is necessary to request a load map during
execution of the SUCNFG program.  It is also
necessary to include ODT as the first module
name  during  the  CALL  statement dialogue.
BASIC-11's start address is  then  found  at
the   global   symbol,   STARTI,   which  is
contained in the root PSECT, BASSCD.

     BASIC-11'S I/O is interrupt driven  and
may cause some confusion unless a time delay
subroutine is entered  following  any  PRINT
statement  which  in turn is followed by the
CALL statement  being  debugged.   The  time
delay   subroutine   of  the  test  program,
DATBAS.BAS, is just for this purpose.

     During debugging it is helpful to set a
breakpoint  at  the  entry  to  the assembly
language routine being debugged.  When  this
breakpoint is reached a pointer map may then
be obtained.

     Figure  4-4  of  the  "BASIC-11  User's
Guide"  [2] illustrates an array descriptor.
It identifies the third word as "Array  Size
(bytes)",  the  sixth word as "High limit of
1st subscript" and the eighth word as  "High
limit  of 2nd subscript".  This is true only
if the argument itself points to either  the
array in general or to the zeroth element of
the array.  At other times when the argument
points  to  some  element  beyond the zeroth
element of the array the value of the  third
word   when   added  to  the  value  of  the
corresponding argument list entry equals the
address  of  the  first memory location past
the upper end of the array.   The  value  of
the  sixth  word  when added to the value of
the subscript in  the  argument  equals  the
upper  limit of the subscript.  An identical
relation prevails for the eighth word.

     Some  selected  descriptor  words   are
given in Table 3.







  377   Null argument

  1023  Integer variable

  1100  String variable or array element

  1223  Integer constant

  2041  Numeric variable

  2241  Numeric constant

  21022 Integer array

  21100 String array

  22040 Numeric array

                  TABLE 3.
              DESCRIPTOR WORDS


     Being able to write handlers implies  a
real time capability.  When interacting with
hardware in real time it is not advisable to
use   strings   (octal   values).   BASIC-11
allocates string storage  space  dynamicaly.
In   the   process  of  doing  this  dynamic
allocation  BASIC-11  occasionally  collects
abandoned  string  storage  space.  This may
take some considerable amount  of  time  (as
much as tens of seconds).

     The PUT  and  GET  routines  offer  the
ability  to  perform  integer  arithmetic in
octal.  The actual arithmetic operations are
performed    by    BASIC-11    in   decimal.
Conversions between octal  and  decimal  are
handled  by  the  PUT  and GET routines.  An
unused vector location is a  convenient  bus
address for this purpose.



                 REFERENCES


1.  "BASIC-11  Language  Reference  Manual",
    DEC-11-LIBBB-A-D,    Digital   Equipment
    Corporation, Maynard, MA, Sep-76.

2.  "BASIC-11/RT-11      User's      Guide",
    DEC-11-LIBUA-A-D,    Digital   Equipment
    Corporation, Maynard, MA, Aug-77.

3.  "BASIC-11/RT-11   Installation   Guide",
    DEC-11-LIBTA-A-D,    Digital   Equipment
    Corporation, Maynard, MA, Aug-77.

4.  "PDP-11  MACRO-11   Language   Reference
    Manual",  AA-5075A-TC, Digital Equipment
    Corporation, Maynard, MA, Aug-77.

5.  "RT-11     System     User's     Guide",
    DEC-11-ORGDA-A-D,    Digital   Equipment
    Corporation, Maynard, MA, Aug-77.

6.  "PDP-11     TECO     User's      Guide",
    DEC-11-UTECA-A-D,    Digital   Equipment
    Corporation, Maynard, MA, Sep-77.
                                                                                                                                 