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: