SBYTES

Syntax

SBYTES device_file,start,length or

SBYTES device_file,start[,length[,data[,extra[,type]]] (Minerva v1.80+) or

SBYTES [device_]file,start,length(Toolkit II) or

SBYTES #channel,start,length(SMS only)

Location

QL ROM, Toolkit II

It can sometimes be useful to save part of the QL’s memory to a file so that it can be loaded back into the computer at a later date. The area of memory saved may for example, contain a program, some machine code or some data.

The command SBYTES allows you to save length number of bytes from the QL’s memory, starting from the specified start address. The area of memory is saved to the specified file which must include the name of the device to be used, unless Toolkit II is present, in which case the default data device is supported. The Toolkit II variant will also provide you with the option of overwriting the file if it already exists.

Example

To save the currently displayed screen on a standard QL, use the command:

SBYTES flp1_Example_scr,SCREEN,32768

Or under SMS, you can save any size screen using:

SBYTES flp1_Example_scr, SCR_BASE, SCR_LLEN * SCR_YLIM

The start of a program which was protected by a password could be written along the lines of this:

100 a=ALCHP(100)
110 IF FTEST(flp1_pass)=0
120   LBYTES flp1_pass,a
130 END IF
140 pass$=''
150 PAPER#0,0:CLS#0:INK#0,7
160 PRINT #0,'Enter Password :';
170 FOR letter=1 TO 4
180   pass$=pass$&INKEY$(-1)
190   PRINT#0,'*';
200 END FOR letter
210 PRINT #0
220 IF PEEK(a)=0
230   offset=RND(1 TO 50)
240   POKE a,offset
250   FOR i=1 TO 4
260     POKE a+i,CODE(pass$(i))+i+offset
270   END FOR i
280   FOR i=5 TO 100:POKE a+i,RND(100)
290   SBYTES flp1_pass,a,100
300 ELSE
310   offset=PEEK(a)
320   FOR i=1 TO 4
330     IF CODE(pass$(i))<>PEEK(a+i)-i-offset
340       PRINT 'Access Denied':RECHP a:STOP
350     END IF
360   END FOR i
370 END IF
380 PRINT 'Access Granted' 390 RECHP a

NOTE 1

On Minerva ROMs (pre v1.80), if SBYTES was aborted for some reason whilst writing to a file, the file would be deleted. On later versions of Minerva and all other QL ROMs, the incomplete file is kept and on Toolkit II, the error ‘Medium Full’ is reported.

NOTE 2

On Minerva ROMs (pre v1.83) SBYTES set the wrong file type.

NOTE 3

The Minerva variant is unfortunately overwritten by the Toolkit II version of this command.

MINERVA NOTES

On Minerva v1.80 (or later) the commands SBYTES and SEXEC have practically become interchangeable, as both support exactly the same parameters. All of the parameters except for the start address and device_file where the data is to be stored, are optional and will default to 0 if not specified.

These additional parameters have the following uses:

  • Extra This sets the value which is normally returned with FXTRA (which would normally have to be altered with SetHEAD).

  • Type This allows you to set two file attributes:

    • the file type - this is normally 0 for data, or 1 for executable programs. This is calculated by PRINT type && 255.

    • the file access key - it is generally used by Toolkits such as QL-System to store various file attributes (such as whether a file is read-only). This is calculated by PRINT type DIV 256.

The only problem with using this extended version of SBYTES instead of using SEXEC is that you must remember to specify a file type of 1 if the file is later to be EXECuted (as this defaults to 0 in the case of SBYTES!).

For example, both of these are the same:

SBYTES ram1_test_exe, code_start, 20000, 500, 0, 1
SEXEC ram1_test_exe, code_start, 20000, 500

SMS NOTE

The fourth variant of the command allows you to save the bytes to an existing channel which is already OPEN to a file, thus allowing you to work more efficiently. You can use the following to error trap the saving routine:

100 REPeat loop
110   ch=FOP_NEW (ram1_test_bin)
120   IF ch<0
130     REPORT ch
140     PRINT "Press <y> to retry, <n> to stop"
150     REPeat kLoop
160       key$=INKEY$(-1)
170       IF key$ INSTR 'yn':EXIT kLoop
180     END REPeat kLoop
190     IF key$=='y':NEXT loop
200     STOP
210   END IF
220   SBYTES #ch,131072,32768
230   EXIT loop
240 END REPeat loop
250 CLOSE #ch

CROSS-REFERENCE

SBYTES_O and SEXEC are very similar. DATA_USE allows you to alter the current default data device. LBYTES allows you to load in a block of code which has been saved with SBYTES or SEXEC.