Basic-11 V2 - Source File Assembling and Linking

Lou Ernst lfernst@alumni.princeton.edu 5/8/2007


References: (available from Bitsavers.org)

	DEC-11-LIBTA  Basic-RT V2 Installation Manual
	DEC-11-LIBUA  Basic-11 Users Guide

Files:	DISK1.DSK (RT-11 logical disk image of the first floppy - Basic-11)
	DISK2.DSK (RT-11 logical disk image of the second floppy - Basic-11)
	DISK3.DSK (RT-11 logical disk image of the third floppy - MU Basic)
	BASIC.DSK (a single RT-11 logical disk image of files from the first and second disk that has been cleaned up - extraneous/redundant files removed. Use this disk image for best results for generating Basic-11) 

Background:

	Basic-11 V2 is a basic language package for RT-11. It can be customized to run in as little as 8kw of core (by way of overlays) and make use of EIS, FIS, or an FPU if available.

	The collection of files here was extracted from three RX02s that Tom Ponsford had in his collection. He purchased some binders with Basic-11 documentation in them with three RX02 floppies at a University of Arizona auction in 2005. Tom never read the disks, but correctly assumed that they would eventually be readable by someone with an RX02 or compatible drive. 

	I read the disks on my 11/23+ and found what you now see. Two of the disks had the complete source code for Basic-11 V2 as .MAC files, the SUCNFG.BAS and related configuration files, and a series of .BAT files for patching assembled code with various fixes. The .MAC files are fully commented and can be amusing to simply read by themselves. The comments can give insights into the personalities of the programmers in the early/mid seventies when this code was written.

	The third disk contained assembled and linked .SAV files for Multi-User Basic (mubas.sav) and the version of MU Basic optimized to take advantage of the XM monitor (mubasx.sav). MU Basic ran on RT-11 systems sysgened for multi-terminal support. Each terminal would appear to the operator to be connected to its own dedicated machine running basic. Only some of the MU Basic source files are present, there is not enough here to run mucnfg.bas and assemble and link custom versions of MU Basic. Perhaps the rest will turn up eventually. I have not gone to the trouble to install the hardware and sysgen my system for multi-user support to verify that the MU Basic .sav files work. However, there is no reason not to believe that they do.

	I extracted these .DSK files from my 11/23+ (and sent them to an IBM PC) via ethernet/ftp with a DELQA and the Kent State University RT-11 TCP/IP package. The .dsk images can be manipulated on a PC with PUTR (be sure to use the /rt11 so that putr knows the filesystem). I did this (with "set copy binary" in PUTR), and put the files in the directories (disk1, disk2, disk3, basic) that you also see. 

	Most, if not all of the manuals required to get started with Basic-11 (and MU Basic) are on Bitsavers and should be reviewed.

	However, the dec manuals all appear to assume that the user who is building his own custom version of Basic already has assembled .OBJ files. In this archive there are the original source .MAC files, which need to be assembled before they can be linked as illustrated in the manual.

	In the paragraphs that follow, the instuctions to assemble and link custom versions of Basic-11 are detailed.


Procedure:

	It is assumed that the user has a sizeable mass storage device, like an RK05 or RL01 or RDxx. If that is not the case (a system with no fixed disks and limited removable storage) the user is not out of luck. They will instead however, need to be more careful, planning to put only the needed files on the working disks.

	Transfer the logical disk image with the source files (basic.dsk is suggested - see "Notes about basic.dsk" at the end of this file) to your machine and mount the logical disk. Assign the logical disk to DK:. There is already a basic.sav on the logical disk. This is needed to run the sucnfg.bas configuration file. This basic, as stated in the installation guide has type 3 overlay and no math hardware support. The manual also mentions bas8k and basicd. A user can make his own basicd from selecting the right options in sucnfg. Bas8k is only needed if the user's machine only has 8k (overlay 5). The sucnfg basic program generates an indirect file that when run will link the necessary pre-assembled .OBJ files. Again though, the necessary .OBJ may not be present here, they need to be assembled from the .MAC files. Sucnfg.bas will chain to other small sucnfg#.bas files as it runs. Assumedly this was done for users with only 8kw. Sucnfg1.bas does most of the work populating the indirect file with most of the appropriate routines to be linked based on the question responses. One of the sucnfg2 through 6 files adds the remaining entries depending on the overlay structure requested. Sucnfg7 cleans up and finishes off the job.

	To determine what source files need to be assembled, run the sucnfg.bas as detailed in the Basic-11 Instalaltion Guide. The user will be prompted to answer questions about the his custom basic should be built, reminescent of a simplified rt-11 sysgen. Next, examine the indirect file that was generated - it contains the list of .OBJ files that need to be assembled. 

	For each .OBJ to be assembled, there are three .MAC files required. These are BSMAC.MAC, BSASM.MAC, and the .MAC that has/almost has the name of the finished .OBJ required. The BSMAC.MAC contains some common routines used by every .OBJ the user will be creating. BSASM.MAC contains definitions that will be looked for by assembler directives in the third .MAC file mentioned above. The user should examine the BSASM.MAC and edit it so that it agrees with the choices made when sucnfg.bas was run (for example, double or single precision, subroutine support, resequencing, etc.) Various versions of BSASM.MAC that were present on the source floppies have been left here. They have filenames like BSASM*.mac, where * is some other letter.

	There is often not a .MAC file with exactly the name of the .OBJ file referenced in the indirect file generated by sucnfg.bas. Often the difference is a missing last letter. For example, the indirect file shows BSR0D while only BSR0.MAC is found. I have found that depending on the definition found in the BSASM.MAC, the BSR0 can complile with double or single precision support, hence the D or S at the end of the compiled BSR0D or BSR0S that came from BSR0.MAC.

	So, to create BSR0D.OBJ, the user edits BSASM.MAC to enable the definition for double precision support then does:

.R MACRO
*BSR0D=BSMAC,BSASM,BSR0

and gets BSROD.OBJ as output. Other files this is true for are BSSUB (BSSUB and BSSUBN for subroutine and no subroutine support) and slightly more complicated BSERML (long err msg) or BSERMS (short err msg), which are generated from BSERMD (double precision) and BSERMS.MAC (single precision).

	BSCLI is also tricky. If the user is not linking other outside routines that will need call support, then assemble this file to BSCLIN.OBJ. If they will, follow the instructions in the users guide in the chapter entitled "Using Assembly Language Routines with Basic."

	Some files are straightforward, as with SUDTCM. It assembles to SUDTCM.OBJ. In all cases, always assemble all three files. Again for example: 


.R MACRO
*SUDTCM=BSMAC,BSASM,SUDTCM

	Some files do not have to be assembled, they already have been. These are BSOT0 and 1, D and S .EAE, .EIS, .FIS, .FPU. These routines contain the transindental function support using optional math hardware, if so selected for incorporation by sucnfg. The unassembled source files are not here (and I don't know where they would be.)

	Once all the files have been assembled, then the indirect file generated by SUCNFG.BAS can be executed as illustrated in the installation guide.


Notes about linking Basic-11 with assembly routines provided with hardware (drivers):

	If the user has assembly routines to link with Basic (as described in the installation manual and users guide) they may also need to link a library called BSCLLB if requested by the instructions that came with the hardware. I have a National Instruments GPIB11V-2 interface card for which that is the case. BSCLLB.MAC or .OBJ was not found with this distribution, however a series of other files that appear to contain the routines that would otherwise have been in BSCLLB were found. The user should assemble BSMAC and BSASM with each of the following: BSCLAE, BSCLAL, BSCLBM, BSCLCH, BSCLCK, BSCLMS, BSCLPL, and BSCLRT. Then when answering the question in SUCNFG concerning user provided files to be linked, instead of entering BSCLLB, instead enter each of the individual files assembled above.

Notes about basic.dsk:

	This logical disk file is 3000 blocks long, unlike the other disk?.dsk files that are exactly as long as an RX02. In this file I put all the necessary files in one logical disk. The reader will need 3000 blocks open on his hard disk, but they aren't all used. I went through all this trouble of building basic from the source files so that I could use my National Instruments GPIB11V2 Q-bus GPIB card. The files needed to link with Basic-11 for this board are on this logical disk also. The file basica.sav is the end result, compiled to work with the NI card. Manuals for the NI GPIB11 cards are on Bitsavers. 


	Good Luck. If you get stuck, you are welcome to send me an e-mail for help.
