Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileBLOAD name$[,addr]
BSAVE name$,addr,count
BGET #n,addr,count
BPUT #n,addr,count

name$: sexp
n, addr, count: aexp

With BSAVE an area of memory can be stored on disk (or RAM-disk, hard disk
drive etc.), and loaded again e.g. with BLOAD. The numerical expression addr
specifies the address of the first byte of the area to be saved, or, with
BLOAD, the address where the data from disk is to be put. If no address is
specified with BLOAD, the address that was specified with BSAVE when the area
was saved will be used. BSAVE must also specify the number of bytes to be
saved. The parameter name$ is the file specification of the file to which the
area is to be saved, or from which it is to be loaded. See the beginning of
"File Management" for details of the specification. BSAVE and BLOAD always use
a whole file.

BGET reads from channel 'n', the number of bytes 'count', and places the data
at address 'addr'.  BPUT writes to channel 'n', the number of bytes 'count',
starting at address 'addr'. BGET and BPUT access a file via its channel number
n, so it is possible to use BGET and BPUT to save or load parts of a file.

Examples:

    DEFFILL 1,2,4
    PBOX 100,100,200,200
    BSAVE "RECTANG.PIC",XBIOS(2),32000 !XBIOS(2) gives screen address
    CLS
    PRINT AT(4,20);"Picture stored. Press a key"
    ~INP(2)
    CLS
    BLOAD "RECTANG.PIC"

--> Draws a rectangle and stores the screen under the name "RECTANG.PIC". An
    appropriate message is displayed, and, after a key has been pressed, the
    file is re-loaded, again to the screen memory area.

    DEFFILL 1,2,4
    PBOX 0,0,639,199
    DEFFILL 1,2,2
    PBOX 0,200,639,399
    DEFTEXT 1,0,0,32
    TEXT 10,115,"the upper half"
    TEXT 10,315,"the lower half"
    '
    OPEN "o", #1,"SCREEN.PIC"
    BPUT #1,XBIOS(2),32000
    CLOSE #1
    PAUSE 25
    CLS
    '
    OPEN "i",#1,"SCREEN.PIC"
    BGET #1,XBIOS(2)+16000,16000
    BGET #1,XBIOS(2),16000
    CLOSE #1

--> The upper half of the screen is filled with one pattern, the lower half
    with another, and appropriate messages are put in each half. Then the
    entire screen is saved into the file SCREEN.PIC. After a pause, the first
    half of the file is loaded into the bottom half of the screen, and the
    second half of the file is loaded into the top half of the screen.

Fread()+, Fwrite()+

Memo: BSAVE does not actually save the address of the memory block into
      the file. BLOAD attempts to load the block at the last address used in
      the last BSAVE command that was executed with in the same program if no
      address is specified. BLOAD "path" (with no address) will crash if used
      without first using BSAVE. This is because the last used address = 0.

      Internally GFA uses channel #89 to perform BSAVE/BLOAD. Conflicts can
      occur if you use this channel and leave it open and then call BSAVE or
      BLOAD.  The result is an error #22.

      BLOAD is not allowed on devices. The result is an error #-1.