Binary Load/Save via CIO (De Re Atari)
- Type
- Utility
- Category
- Disk utility subroutine
- Author
- Jim Dunion (Section 8 of De Re Atari)
- Published in
- De Re Atari: A Guide to Effective Programming (Atari Program Exchange, APX-90008, 1982), Section 8, "Operating System" (Using CIO from BASIC)
- Year
- 1982
- Language
- Atari BASIC
- Requirements
- Any Atari 8-bit, Atari BASIC, disk drive and DOS
- Tags
- cio, iocb, disk, usr, utility, de-re-atari, jim-dunion, atari-basic
About the program
De Re Atari ("All About Atari") was written by Atari's Software Development Support Group as a training manual for professional programmers. Early versions went to registered developers in 1981, and the 1982 edition was sold through the Atari Program Exchange as APX-90008. Jim Dunion's operating system chapter points out a gap in Atari BASIC. The OS's Central I/O (CIO) can read or write a whole buffer in one call (GET CHARACTERS / PUT CHARACTERS), but BASIC only gives you one byte at a time with GET and PUT. This subroutine fills the gap. It fills in an I/O control block and calls CIO through a 7-byte machine-language string, so that it can load or save any area of memory, such as a machine-language routine, a character set or a picture, as fast as the drive can go.
What you need
- Atari BASIC, a disk drive and DOS 2.0S or similar.
- For the demo as written, a file
D:TESTthat holds the bytes you want to load into page 6 (address 1536).
Typing it in
Line 100 holds the machine code as a seven-character string. It stands for the bytes 104,104,104,170,76,86,228 (PLA PLA PLA TAX JMP $E456). hhh and LV are ordinary letters, but the * and the final d must be in inverse video (170 and 228). In the listing, {inverse}…{/inverse} marks them: press the Atari/inverse key, type the character, and press the key again. If you'd rather not type inverse characters, build the string with CHR$ instead, for example CIO$=CHR$(104):CIO$(2)=CHR$(104):CIO$(3)=CHR$(104):CIO$(4)=CHR$(170):CIO$(5)="LV":CIO$(7)=CHR$(228). The REM lines with _ padding are plain comments.
How to use it
Set the variables, then GOSUB 30000:
CMD=7loads, andCMD=11saves.STADRis the start address, andBYTESis how many bytes to transfer.IOCBis the channel number (1–5 are safe), andFILE$is the file name.
On return, ERROR=1 means success. Any other value is the CIO error code. Note that the demo at lines 100–200 sets neither BYTES nor IOCB, so as printed it relies on their default value of 0. Set IOCB=1 and a byte count (for example BYTES=256) before line 120 for a clean result.
How it works
- Each of the eight IOCBs is 16 bytes long, starting at location 832. Lines 30024–30028 work out the addresses of the command byte (ICCOM, +2), the status byte (+3), the buffer address (+4/+5) and the buffer length (+8/+9).
- The file is OPENed normally from BASIC, with mode 4 to read or 8 to write.
USR(ADR(CIO$),IOCBX)passes the IOCB offset. The routine pulls it into the X register and jumps to CIOV ($E456), and CIO then performs the GET/PUT CHARACTERS command (7 or 11) on the whole buffer.TRAP 30900catches errors and reads the error number from location 195.
Variations to try
- Save the current character set:
STADR=57344:BYTES=1024:CMD=11:FILE$="D:CHARSET". Load it later into RAM that you have reserved. - Save and load GRAPHICS 8 screens (7680 bytes from
PEEK(88)+256*PEEK(89)) as an instant picture viewer.
Listing
30 REM THIS PROGRAM LOADS PAGE 6 FROM THE FILE D:TEST
100 DIM FILE$(20),CIO$(7):CIO$="hhh{inverse}*{/inverse}LV{inverse}d{/inverse}"
106 REM CIO$ IS PLA,PLA,PLA,TAX,JMP $E456 (CIOV)
110 FILE$="D:TEST":REM _ *FILE NAME
120 CMD=7:STADR=1536:GOSUB 30000
130 IF ERROR=1 THEN ? "TRANSFER COMPLETE":STOP
135 ? "ERROR # ";ERROR;" OCCURRED AT LINE # ";PEEK(186)+256*PEEK(187)
200 END
300 REM _ CIO SETUP SUBROUTINE
310 REM
30000 REM
30001 REM
30002 REM THIS ROUTINE LOADS OR SAVES MEMORY FILE FROM BASIC
30003 REM BY SETTING UP AN IOCB AND CALLING CIO DIRECTLY
30004 REM
30006 REM ON ENTRY CMD=7 MEANS LOAD MEMORY
30008 REM _ CMD=11 MEANS SAVE MEMORY
30009 REM _ STADR= THE ADDRESS TO LOAD OR SAVE MEMORY
30010 REM _ BYTES= THE NUMBER OF BYTES TO SAVE OR LOAD
30011 REM _ IOCB= THE IOCB TO USE
30012 REM _ FILE$= DESTINATION FILE NAME
30013 REM _
30014 REM ON EXIT ERROR=1 MEANS SUCCESSFUL COMMAND
30018 REM _ ERROR<>1 THEN ITS AN ERROR STATUS
30019 REM
30020 REM _ *** IOCB EQUATES ***
30022 REM
30024 IOCBX=IOCB*16:ICCOM=834+IOCBX:ICSTA=835+IOCBX
30026 ICBAL=836+IOCBX:ICBAH=837+IOCBX
30028 ICBLL=840+IOCBX:ICBLH=841+IOCBX
30029 REM
30030 AUX1=4:IF CMD=11 THEN AUX1=8
30035 TRAP 30900:OPEN #IOCB,AUX1,0,FILE$
30040 TEMP=STADR:GOSUB 30500
30090 POKE ICBAL,LOW:POKE ICBAH,HIGH
30100 TEMP=BYTES:GOSUB 30500
30130 POKE ICBLL,LOW:POKE ICBLH,HIGH
30140 POKE ICCOM,CMD:ERROR=USR(ADR(CIO$),IOCBX)
30150 ERROR=PEEK(ICSTA):RETURN
30200 REM
30300 REM _ ***ROUTINE RETURNS HIGH,LOW BYTE OF 16 BIT NUMBER
30400 REM
30500 HIGH=INT(TEMP/256):LOW=INT(TEMP-HIGH*256):RETURN
30550 REM
30600 REM ***TRAP HERE IF ERROR OCCURS DURING ROUTINE****
30900 ERROR=PEEK(195)
30920 CLOSE #IOCB:RETURN
Credits
- Program listing: Binary Load/Save via CIO (De Re Atari) — program listing (De Re Atari: A Guide to Effective Programming (Atari Program Exchange, APX-90008, 1982), Section 8, "Operating System" (Using CIO from BASIC)) — Jim Dunion (Section 8 of De Re Atari)
- De Re Atari — Section 8: Operating System (atariarchives.org) — Jim Dunion (Section 8 of De Re Atari)
- De Re Atari — preface (section authors) — AtariArchives.org
- comp.sys.atari.8bit FAQ (De Re Atari editions: C060070 1981 developer versions, APX-90008 1982) — Michael Current (comp.sys.atari.8bit FAQ), 1981
