;
; load.sh
;
; Loading and importing of files
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  load
;  load_initBuf
;  load_killBuf
;  load_extendBuf
;  load_doneBuf
;  load_file

		[	:LNOT::DEF:load__dfn
		GBLL	load__dfn

; --- load ---
;
; On entry:	R0 == pointer to entry point block
;		R1 == value of R10 to pass to entry points
;		R2 == value of R12 to pass to entry points
;
; On exit:	--
;
; Use:		Attempts to load a file after receipt of a Message_DataSave,
;		Message_DataLoad or Message_DataOpen.  If user entries for
;		RAM transfer are provided, this is attempted, although the
;		entries must also be aware that file transfer may be
;		required.

		IMPORT	load

; --- load_initBuf ---
;
; On entry:	R1 == estimated file size
;		R2 == pointer to flex anchor (unallocated)
;
; On exit:	R0 == pointer to buffer start
;		R1 == buffer size
;		May return an error
;
; Use:		Initialises a flex block for use as a RAM transfer buffer.
;		This routine is suitable for use as the initBuf routine for
;		RAM transfer loading.

		IMPORT	load_initBuf

; --- load_killBuf ---
;
; On entry:	R2 == pointer to flex anchor
;
; On exit:	--
;
; Use:		Frees a flex block.  This routine should be used to free
;		the buffer used for RAM transfer.

		IMPORT	load_killBuf

; --- load_extendBuf ---
;
; On entry:	R0 == pointer to previous buffer
;		R1 == size of previous buffer
;		R2 == pointer to flex anchor
;
; On exit:	R0 == pointer to a new buffer
;		R1 == size of the new buffer
;		May return an error
;
; Use:		Extends the flex block if it was initially too small.
;		This routine is designed to be used as the extend routine
;		during RAM transfer.

		IMPORT	load_extendBuf

; --- load_doneBuf ---
;
; On entry:	R1 == actual size of data
;		R2 == pointer to flex anchor
;
; On exit:	--
;
; Use:		Sets the block into which the data has been loaded to the
;		correct exact size.

		IMPORT	load_doneBuf

; --- load_file ---
;
; On entry:	R1 == pointer to filename to load
;		R2 == pointer to flex anchor
;
; On exit:	R0 == size of file loaded
;		May return an error
;
; Use:		Loads a named file into a flex block for your delectation.

		IMPORT	load_file

;----- User entry points ----------------------------------------------------

		^	0

lEntry__initBuf	#	4			;Create a load buffer
						;On entry:
						;  R0 == ptr to `filename'
						;  R1 == estimated file size
						;  R2 == 0
						;On exit:
						;  R0 == ptr to buffer start
						;  R1 == ptr to buffer end
						;  R2 == buffer `handle'
						;  R10 may be updated

lEntry__killBuf	#	4			;Destroy the load buffer
						;On entry:
						;  R0 == ptr to buffer start
						;  R1 == ptr to buffer end
						;  R2 == buffer `handle'
						;On exit:
						;  --

lEntry__extend	#	4			;Extend the load buffer
						;On entry:
						;  R0 == ptr to buffer start
						;  R1 == ptr to buffer end
						;  R2 == buffer `handle'
						;On exit:
						;  R0-R2 updated

lEntry__doneBuf	#	4			;All data is now loaded
						;On entry:
						;  R0 == ptr to `filename'
						;  R1 == total size of data
						;  R2 == buffer `handle'
						;On exit:
						;  --

lEntry__file	#	4			;Load data from a file
						;On entry:
						;  R0 == ptr to `filename'
						;  R1 == file to load
						;  R2 == 0 if file unsafe
						;On exit:
						;  R10 may be updated

lEntry__done	#	4			;Completed loading
						;On entry:
						;  R0 == ptr to `filename'
						;  R1 == safeness indicator
						;On exit:
						;  --

lEntry__failed	#	4			;Failed to load file
						;On entry:
						;  R0 == pointer to error
						;  R1 == 1
						;On exit:
						;  --

		]

;----- That's all, folks ----------------------------------------------------

		END