Loading Binary DOS Files From BASIC

Robert E. Alleger

You can load binary (machine language) files from DOS with selection "L." Here's a machine language program that lets you do it from BASIC.

Introduction

Several months ago, my friend Doug came to me and said, "Hey Bob, I want to show you the nifty menu program I wrote." After he demonstrated his program, I said, "Big deal! You came all the way over here to show me this?" He replied, "Not exactly. There's one slight problem that I don't know how to solve. My menu will not load machine language programs. I thought that you might be able to help me." After some arm twisting, I agreed to write a routine that would allow a BASIC program to load machine language disk files.

DOS 2 LOAD File Format

Before I begin with a step-by-step breakdown of LOADIT, it might be helpful to define the format of a DOS 2 binary load file (see Figure 1). A binary load file begins with a two-byte header id of $FF $FF ($xx indicates hexadecimal numbers), followed by a two-byte start address, a two-byte end address, and the program data (object code).

For programs with multiple ORGs, this pattern may repeat over and over again, beginning with the start address. If the file was created by using the DOS copy ('C') command to append two or more files together, then the pattern may repeat beginning with the header id.

Figure 1.

: $FF $FF : start address : end address : object code : …

On With The Show

LOADIT is designed to be called from BASIC via the USR function. It is ORG'd for page six (1536-1791) so that it is relatively safe, as long as the machine language program that it runs does not load into this area.

Referring to Program 1 (LOADIT. ASM) line numbers 0440-0580 (INIT) is the initialization routine. It calls a subroutine that CLOSEs IOCB (I/O Control Block) number one (in case it was already open), retrieves the address of the file-spec from BASIC, and then OPENs the specified file.

Lines 0620-0810 (RDHDR) read the first two bytes of a block of object code from the input file. If both bytes are an $FF (header id), then the program loops back to get the next two. Together, these bytes form the address into which to start loading the object code. An end of file error ($88) at this point indicates that the whole file has been loaded, and therefore execution branches to the DONE routine.

Lines 0850-0930 (CONT) read the next two bytes, which form the ending address for the current block of object code. Any error returned in the Y-register by CIO at this point either indicates that the file is bad (i.e., "File Number Mismatch," etc.) or that the file is not in binary load format (see Figure 1).

Lines 0970-1040 (HDROK) check to see if this is the first block of object code that has been read from this file. If it is, then the address of the first instruction is used as the default run address, in case none is specified. In assembly language, the run address is specified by storing the address of the entry point to your program in locations $02E0-02E1.

Lines 1080-1270 (RDBLOK) read the object code from the file and store it in memory, from start address through end address. The number of bytes to be read is calculated by taking the ending address, subtracting the start address, and adding one. The only non-fatal error code that CIO could return at this point is $03, which indicates that an end of file error will be encountered on the next read.

After loading the entire block of object code, the program loops back to the RDHDR routine.

Lines 1340-1350 (DONE) are executed on an end of file error in the RDHDR routine. The input file is CLOSEd and execution is transferred to the loaded program via the vector at address $02E0-02E1.

Does It Really Work?

I will use a very simple, no frills menu program (see Program 2) to demonstrate that LOADIT really does work. Although LOADIT might be useful in other applications, I chose this menu because it illustrates the most common usage.

The subroutine starting at line number 5000 is responsible for placing LOADIT at its proper location in memory. A FOR/NEXT loop reads the decimal equivalent of the machine language instructions and POKEs them into page six of memory.

LOADIT is only called when a machine language program is chosen from the screen menu. I chose to indicate a machine language load-and-go file by using the file extension ".CMD" (from my old TRS-80 days). Of course you can use anything you like, just change line number 480.

LOADIT is called by the statement in line number 550. The parameters specified in the USR function are LOADIT's starting address (1536 = $0600) and the address of the string variable which contains a complete file-spec (i.e., Dn:name.ext).

BASIC should never fall through to line number 570, because LOADIT only returns to BASIC if an error is encountered.

Did I Really Type All Those DATA Statements?

In case you were wondering, I did not type in the DATA statements on line numbers 5001-5008. Instead, I used a handy BASIC utility program that I wrote called DATAGEN (see Program 3). It is included as a bonus.

DATAGEN reads a binary load format file, such as LOADIT.OBJ, and produces a file that can be appended to your BASIC program with the ENTER command (see page 25 of the ATARI "BASIC REFERENCE MANUAL"). This file will contain one FOR/NEXT loop and a number of DATA statements for each block of object code in the file.

Upon startup, DATAGEN requests a complete file-spec for the input and output files. It also asks for the starting line number that will be used to begin numbering the subroutine that is being written to the output file.

And That's Not All, Folks

Program 4 is another utility program which can be used to find out the load parameters of a binary load format file. DPSLOAD reads a binary file and displays the starting and ending address of each block of object code, the auto run, and init addresses, if present (see pages 41-44 of the Atari Disk Operating System II Reference Manual).

The input requested by DSPLOAD is a complete file-spec of the input file. The information will be displayed on the screen when each block of object code is encountered.

To some, it may seem that DATAGEN and DSPLOAD have nothing to do with my intended topic, but I hope that they prove to be educational as well as useful aids to programming.

PROGRAM 1. Loading Binary DOS Files From BASIC.

10 .TITLE "LOADIT 1.1 02/24/82"
20 ;Author : Robert E. Alleger
30 ;
40 ;This program allows a BASIC
50 ;program to LOAD a machine
60 ;language program and execute it.
70 ;
80 ;
90 ;
0100 IOCB1 = 1 * 16 ;IOCB #1 (D : )
0110 ;IOCB (8 * 16 bytes)
0120 ICHID = $0340 ;handler ID
0130 ICDNO = ICHID + 1 ;device #
0140 ICCOM = ICDNO + 1 ;command
0150 ICSTA = ICCOM + 1 ;status
0160 ICBAL = ICSTA + 1 ;buffer address
0170 ICPTL = ICBAL + 2 ;PUT routine addr - 1
0180 ICBLL = ICPTL + 2 ;buffer length
0190 ICAX1 = ICBLL + 2 ;AUX 1
0200 ICAX2 = ICAX1 + 1 ;AUX 2
0210 ICAX3 = ICAX2 + 1 ;AUX 3
0220 ICAX4 = ICAX3 + 1 ;AUX 4
0230 ICAX5 = ICAX4 + 1 ;AUX 5
0240 ICAX6 = ICAX5 + 1 ;AUX 6
0250 ;
0260 CIO = $E456 ;CIO entry point
0270 ENR = $03 ;EOF on next read
0280 EOF = $88 ;EOF status
0290 OPEN = $03 ;OPEN command
0300 GETCHR = $07 ;GET CHARACTERS command
0310 CLOSE = $0C ;CLOSE command
0320 OREAD = $04 ;OPEN direction = READ
0330 ;
0340 RUNLOC = $02E0 ;auto run vector
0350 FREE0 = $00CB ;free 0 page RAM (to $00D1)
0360 HEADER = FREE0 ;block header buffer
0370 FLAB = HEADER + 4 ;1st block flag
0380 ;
0390 ;
0400 * = $0600
0410 ;
0420 ;Initialization
0430 ;
0440 INIT LDX #IOCB1
0450 JSR CLOSEIT ;in case IOCB was in use
0460 STX FLAG
0470 PLA ;get rid of # of args on stack
0480 PLA ;MSB of file spec location
0490 STA ICBAL + 1, X
0500 PLA ;LSB
0510 STA ICBAL, X
0520 LDA #OREAD
0530 STA ICAX1, X
0540 LDA #OPEN
0550 STA ICCOM, X
0560 JSR CIO ;open file
0570 BPL RDHDR
0580 JMP ERROR ;file not found
0590 ;
0600 ;Read header id or start address
0610 ;
0620 RDHDR LDA #HEADER&255
0630 STA ICBAL, X
0640 LDA #HEADER/256
0650 STA ICBAL + 1, X
0660 LDA #2
0670 STA ICBLL, X
0680 LDA #0
0690 STA ICBLL + 1, X
0700 LDA #GETCHR
0710 STA ICCOM, X
0720 JSR CIO ;get id or start addr
0730 BPL CHKID
0740 CPY #EOF ;end of file?
0741 BEQ DONE ; - yes
0742 BNE ERROR ; - no, bad file
0750 ;
0760 CHKID LDA #$FF
0770 CMP HEADER
0780 BNE CONT
0800 CMP HEADER + 1
0810 BEQ RDHDR ;ignore $FF, $FF id code
0820 ;
0830 ;Read end address
0840 ;
0850 CONT LDA #HEADER + 2&255
0860 STA ICBAL, X
0870 LDA #HEADER + 2/256
0880 STA ICBAL + 1, X
0890 JSR CIO ;get end address
0900 BPL HDROK
0930 BMI ERROR ;bad file
0940 ;
0950 ;Store program start address
0960 ;
0970 HDROK LDA FLAG
0980 BEQ RDBLOK ;skip if not 1st block
0990 LDA HEADER ;use start of program
1000 STA RUNLOC ; as default run adr
1010 LDA HEADER + 1
1020 STA RUNLOC + 1
1030 LDA #0
1040 STA FLAG ;clear 1st block flag
1050 ;
1060 ;Read a block of object code
1070 ;
1080 RDBLOK LDA HEADER ;load address
1090 STA ICBAL, X
1100 LDA HEADER + 1
1110 STA ICBAL + 1, X
1120 LDA HEADER + 2 ;end address
1130 SEC
1140 SBC HEADER ;length = end - start
1150 STA ICBLL, X
1160 LDA HEADER + 3
1170 SBC HEADER + 1
1180 STA ICBLL + 1, X
1190 INC ICBLL, X ;adjust length by 1
1200 BNE * + 5
1210 INC ICBLL + 1, X
1220 ;
1230 JSR CIO ;read block
1240 BPL RDHDR ;get next block
1250 CPY #ENR
1260 BEQ RDHDR ;this is also OK
1270 JMP ERROR ;bed file
1280 ;
1290 ;Subroutines follow
1300 ;
1310 ; **********************
1320 ;Start selected program
1330 ; **********************
1340 DONE JSR CLOSEIT
1350 JMP (RUNLOC) ;start program
1360 ; **************************
1370 ;Return error code to BASIC
1380 ; **************************
1390 ERROR TYA
1400 STA 212 ;tell BASIC what's wrong
1410 LDA #0
1420 STA 213
1430 ;now fall through to CLOSEIT
1440 ;then return to BASIC
1450 ; **************
1460 ;Close the IOCB
1470 ; **************
1480 CLOSEIT LDA #CLOSE
1490 STA ICCOM, X
1500 JSR CIO ;close file
1510 RTS

PROGRAM 2. Loading Binary DOS Files From BASIC.

10 REM LOADIT demo menu
20 REM by Robert E. Alleger
30 DIM LINE$(13), DIR$(12 * 64), DRIVE$(3)
40 REM * Initialization *
50 GRAPHICS 0 : POKE 752, 1
60 DRIVE$ = "D1 :"
70 PRINT, "MENU for Drive ";DRIVE$ : PRINT
80 GOSUB 5000 : REM store LOADIT.OBJ
90 LINE$ = DRIVE$ : LINE$(4) = " * . * "
100 DIR$(1, 1) = " " : DIR$(12 * 64) = " "
110 DIR$(2) = DIR$
120 CLOSE #1 : OPEN #1, 6, 0, LINE$
130 TRAP 380 : ENTRY = 1 : LINEFLAG = 1
140 REM * Read the directory *
150 FOR FILENUMBER = 1 TO 64
160 INPUT #1, LINE$
170 IF LINE$(2, 2) < > " " THEN 380
180 PD = ENTRY
190 REM * Scan file name *
200 FOR PS = 3 TO 10
210 IF LINE$(PS, PS) = " " THEN 240
220 DIR$(PD, PD) = LINE$(PS, PS)
230 PD = PD + 1 : NEXT PS
240 REM * Check for extension *
250 IF LINE$(11, 11) = " " THEN 320 : REM no extension
260 DIR$(PD, PD) = "." : REM append dot
270 PD = PD + 1
280 REM * Scan file extension *
290 FOR PS = 11 TO 13
300 DIR$(PD, PD) = LINE$(PS, PS)
310 PD = PD + 1 : NEXT PS
320 REM * Display file name.ext *
330 IF LINEFLAG = 3 THEN PRINT : LINEFLAG = 1
340 IF FILENUMBER < 10 THEN PRINT " ";
350 PRINT FILENUMBER;" ";DIR$(ENTRY, ENTRY + 11); " ";
360 LINEFLAG = LINEFLAG + 1
370 ENTRY = ENTRY + 12 : NEXT FILENUMBER
380 REM * Choose one *
390 PRINT : PRINT "Enter number of file to load : ";
400 TRAP 390 : INPUT N
410 IF N < 1 OR N > FILENUMBER - 1 THEN 390
420 LINE$ = DRIVE$
430 LINE$(4) = DIR$(N * 12 - 11, N * 12)
440 GRAPHICS 0 : POSITION 2, 10
450 PRINT "{6 SPACES}LOADING ";LINE$
460 REM * See if machine language *
470 FOR PS = 4 TO 12
480 IF LINE$(PS, PS + 3) = ".CMD" THEN 540
490 NEXT PS
500 REM * Load BASIC program *
510 TRAP 530
520 RUN LINE *
530 ERROR = PEEK(195) : GOTO 560
540 REM * Load M.L. program *
550 ERROR = USR(1536, ADR(LINE$))
560 REM * Shouldn't be here! *
570 PRINT "ERROR #";ERROR;" encountered during load"
580 END
5000 FOR A = 1536 TO 1717 : READ B : POKE A, B : NEXT A
5001 DATA 162, 16, 32, 173, 6, 134, 207, 104, 104, 157, 69, 3, 104, 157, 68, 3, 169, 4, 157, 74, 3, 169, 3, 157, 66
5002 DATA 3, 32, 86, 228, 16, 3, 76, 166, 6, 169, 203, 157, 68, 3, 169, 0, 157, 69, 3, 169, 2, 157, 72, 3, 169
5003 DATA 0, 157, 73, 3, 169, 7, 157, 66, 3, 32, 86, 228, 16, 6, 192, 136, 240, 92, 208, 96, 169, 255, 197, 203, 208
5004 DATA 4, 197, 204, 240, 210, 169, 205, 157, 68, 3, 169, 0, 157, 69, 3, 32, 86, 228, 16, 2, 48, 69, 165, 207, 240
5005 DATA 14, 165, 203, 141, 224, 2, 165, 204, 141, 225, 2, 169, 0, 133, 207, 165, 203, 157, 68, 3, 165, 204, 157, 69, 3
5006 DATA 165, 205, 56, 229, 203, 157, 72, 3, 165, 206, 229, 204, 157, 73, 3, 254, 72, 3, 208, 3, 254, 73, 3, 32, 86
5007 DATA 228, 16, 137, 192, 3, 240, 133, 76, 166, 6, 32, 173, 6, 108, 224, 2, 152, 133, 212, 169, 0, 133, 213, 169, 12
5008 DATA 157, 66, 3, 32, 86, 228, 96
5009 RETURN

PROGRAM 3. Loading Binary DOS Files From BASIC.

10 REM DATAGEN
20 REM Translates DOS LOAD files
30 REM to BASIC DATA statements
40 REM (C) 1981 by Robert E. Alleger
50 REM * Initialization *
60 DIM FI$(15), FO$(15)
70 ERRSAV = 195 : MAX = 25
80 REM * ask for file specs *
90 GRAPHICS 0
100 PRINT, "DATAGEN" : PRINT
110 TRAP 120
120 PRINT "Input file spec : ";
130 INPUT FI$
140 TRAP 150
150 PRINT "Output file spec : ";
160 INPUT FO$
170 TRAP 610 : CLOSE #1 : CLOSE #2
180 OPEN #1, 4, 0, FI$
190 OPEN #2, 8, 0, FO$
200 REM * Get header ID (2 bytes) *
210 GET #1, B1 : GET #1, B2
220 IF (B1 = 132 AND B2 = 152) OR (B1 = 255 AND B2 = 255) THEN 260
230 PRINT "{BELL}Not LOAD format" : GOTO 620
240 REM * Ask for starting line *
250 TRAP 260
260 PRINT "Starting line number : ";
270 INPUT LNBR
280 REM * Get START & END addresses *
290 TRAP 560 : REM trap normal EOF
300 GET #1, B1 : GET #1, B2
310 ADRSTART = B1 + B2 * 256
320 IF ADRSTART = 65535 THEN 300
330 GET #1, B1 : GET #1, B2
340 ADREND = B1 + B2 * 256
350 TRAP 540 : REM trap premature EOF
360 REM * Build FOR/NEXT loop *
370 PRINT #2; STR$(LNBR);
380 PRINT #2; "FOR A = ";STR$(ADRSTART); " TO ";STR$(ADREND);
390 PRINT #2; " : READ B : POKE A, B : NEXT A"
400 A = ADRSTART - 1
410 REM * Build DATA statements *
420 LNBR = LNBR + 1
430 IF A + 1 > ADREND THEN 520
440 IF LNBR > 32765 THEN PRINT "{BELL}Line number too large" : GOTO 620
450 PRINT #2; STR$(LNBR); "DATA ";
460 FOR N = 1 TO MAX : A = A + 1
470 IF A > ADREND THEN 520
480 IF N > 1 THEN PRINT #2; ",";
490 GET #1, B1 : PRINT #2; STR$(B1);
500 IF N = MAX THEN PRINT #2
510 NEXT N : GOTO 410
520 PRINT #2 : LNBR = LNBR + 1
530 GOTO 290
540 IF PEEK(ERRSAV) = 136 THEN PRINT "Premature EOF on input file" : GOTO 620
550 GOTO 610
560 REM * Error TRAP *
570 IF PEEK(ERRSAV)< >136 THEN 610
580 PRINT #2; STR$(LNBR); "RETURN"
590 PRINT " < < < DONE > > > "
600 GOTO 620
610 PRINT : PRINT "{BELL} ERROR #";PEEK(ERRSAV)
620 CLOSE #1 : CLOSE #2 : TRAP 65535

PROGRAM 4. Loading Binary DOS Files From BASIC.

10 REM DSPLOAD
20 REM Display DOS LOAD
30 REM format information
40 REM (C) 1981 by Robert E. Alleger
50 REM * Initialization *
60 DIM F$(15), HEX$(4)
70 GRAPHICS 0
80 PRINT, "DSPLOAD" : PRINT : PRINT
90 PRINT "This program will print information"
100 PRINT "for DOS LOAD format files."
110 TRAP 110 : CLOSE #1
120 PRINT : PRINT "File spec :";
130 INPUT F$
140 OPEN #1, 4, 0, F$
150 PRINT "{CLEAR}", "LOAD Display" : PRINT : PRINT
160 PRINT "File name", F$
170 PRINT "Format",,
180 REM * GET header ID *
190 TRAP 530
200 GET #1, B1 : GET #1, B2
210 IF B1 = 132 AND B2 = 9 THEN PRINT "DOS 1 LOAD" : GOTO 240
220 IF B1 = 255 AND B2 = 255 THEN PRINT "DOS 2 LOAD" : GOTO 240
230 PRINT "{BELL} Not LOAD format {DOWN}" : GOTO 730
240 REM * Get START & END Addresses *
250 TRAP 590 : GET #1, B1
260 TRAP 530 : GET #1, B2
270 NBR = B1 + B2 * 256
280 IF NBR = 65535 THEN 310
290 ADRSTART = NBR : GOSUB 460
300 PRINT "Start - End Address ";HEX$; " - ";
310 GET #1, B1 : GET #1, B2
320 NBR = B1 + B2 * 256
330 ADREND = NBR : GOSUB 460
340 PRINT HEX$
350 IF ADREND < ADRSTART THEN 710
360 REM * Read LOAD file *
370 TRAP 560
380 FOR N = ADRSTART TO ADREND
390 GET #1, B1 : BYTES = BYTES + 1
400 IF N = 736 THEN ADRAUTOL = B1
410 IF N = 737 THEN ADRAUTOH = B1
420 IF N = 738 THEN ADRINITL = B1
430 IF N = 739 THEN ADRINITH = B1
440 NEXT N
450 GOTO 240 : REM get next LOAD block
460 REM * Convert decimal to hex *
470 I = 4 : HEX$ = "0000"
480 T = NBR : NBR = INT(NBR/16) : T = T - NBR * 16
490 IF T < 10 THEN HEX$(I, I) = STR$(T) : GOTO 510
500 HEX$(I, I) = CHR$(T + 55)
510 IF NBR< >0 THEN I = I - 1 : GOTO 480
520 RETURN
530 REM * ERROR #1 *
540 PRINT : PRINT "{BELL} Premature EOF while reading HEADER"
550 GOTO 730
560 REM * ERROR #2 *
570 PRINT : PRINT "{BELL} Premature EOF while reading DATA"
580 GOTO 730
590 REM * ERROR #3 *
600 IF ADRAUTOL = 0 AND ADRAUTOH = 0 THEN 640
610 NBR = ADRAUTOL + ADRAUTOH * 256
620 GOSUB 460
630 PRINT "Auto Run Address", HEX$
640 IF ADRINITL = 0 AND ADRINITH = 0 THEN 680
650 NBR = ADRINITL + ADRINITH * 256
660 GOSUB 460
670 PRINT "Init Address", HEX$
680 PRINT "Program size", INT(BYTES/1024 * 100)/100; "K BYTES"
690 PRINT : PRINT "{BELL}---EOF---"
700 GOTO 730
710 REM * ERROR #4 *
720 PRINT : PRINT "{BELL} END Address less than START Address"
730 REM * Exit *
740 TRAP 65535 : CLOSE #1 : END

Return to Table of Contents | Previous Section | Next Section