Variable Load/Save (VLS)
========================
S*BASIC commands to fast save and load assorted arrays and scalar variables
Compatible with all systems, though probably not with Turbo-compiled tasks
due to return values being stuffed into parameters (VLOAD).
VLS basics
==========
VSAVE - save a list of variables in internal format to a file
VLOAD - load them back in again
key: < > => entity, | => or, [ ] => optional, .. => repeated
<filename> can be specified as a string or a <name>
Variables to save/load can be of two kinds and three types.
The kinds are: A) scalars, B) arrays.
The types are: 1) string, 2) float, 3) integer.
A certain amount of coersion is performed at the VSAVE stage in an
attempt to anticipate the wishes of the user:
An expression is interpreted as a variables of the same type.
FOR and REPeat indices are similarly treated as normal variables.
Unset variables are treated as variables containing zero or a nul
string.
A single array element is treated as a scalar variable.
A substring and a single dimension string are treated as a string
variable: eg DIM a$(10) is a single dimension array and the slice of
that a$(2 to 3) is a sub-string. (This is not the same as: b$ = 'abc';
in this case b$(2 to 3) is NOT a sub-string but an expession).
Sub-arrays are treated as any other array and complete arrays may be
reloaded into sub-arrays. (See examples.)
VSAVE
=====
er = VSAVE( <filename> \ | , array1 | var1 [, array2 | var2, ..] )
Save a list of variables to file which can again be loaded back into
variables of the same kind using VLOAD.
If the \ parameter is used after <filename>, any file with the same
name as <filename> is overwritten.
VLOAD
=====
er = VLOAD( <filename>, array1 | var1 [, array2 | var2 ..] )
Load a list of values from file and stuff them into the list of parameters
on a first-come-first-served basis. The parameters neednt be the same as
those used in VSAVE, however if a variable overflows during coercion,
parsing of the file stops at that point and an overflow error is returned
in the variable er.
If an expression is encountered it is simply ignored and the value
skipped.
Sub-strings and single dimension arrays are treated as variables
Sub-arrays may be filled by array values provided the dimensions are
the same. If they are not an Out of Range error will be returned.
It is possible to skip values in the parameter list by using null
parameters, eg er = VLOAD(fnm$; a,, c) will skip the saved value b and
load in a and c in their correct places.
If the parameters to skip are at the end of the list they may simply
be omitted. The error Not Complete is then returned after the values
corresponding to those parameters supplied have been read in, unless
any other errors were encountered first.
If more parameters are found than there are values in the file an End
of File error is returned after reading in all the values that have
corresponding parameters.
Tips
====
It is not too hard to create a VSAVE file from S*BASIC. You might want to
do this particularly for arrays where only a subset or a selection of
elements are wanted to be saved for fast-loading later. See VLSbas_txt for
examples.
VSAVE file structure
====================
dc.l 'VS01' ; header flag & version number
dc.w count ; number of parameters (excl filename)
Then repeat count times:
dc.l skiplength ; offset to next parameter (or 0)
either:
dc.w $30x ; array (string, integer or float)
dc.w nodims ; number of dimensions
repeat nodims times:
dc.w highest_index ; highest index number
dc.w multiplier ; multiplier for this dimension
followed by the data:
data ; array data in internal format
or:
dc.w $20x ; scalar variable, types as above
data ; value of variable
Programming notes
=================
Most of these routines were started in the early 1990's, when I was just
getting to grips with MC68 assembler, so the code may not be very efficient
or pretty. However, it has been totally reliable for the things I have used
it for!
V0.03: This new assembly, with a new library arrangement, has not been as
thoroughly tried and tested as V0.02. Very few people are happy to beta
test for free these days, so it has to be done like this or we'll never
get ahead.
V0.04: There was a wee bug in the routine to load arrays when the array data
was larger than 32k. This had gone undetected for all these years, presumably
because I never had cause to load arrays of that size. Rather than patch
the code with new conditionals I lazily just added a new piece.
On testing some of the more esoteric capabilites (coersion (in some cases),
skipping missing parameters, etc) the code didnt always work as advertised!
In one case the code to do the trick was not present (skipping missing
parameters) so I added that in now. Coersion now relies on the newly re-
arranged libraries, so that may have caused things not to work which
previously did work (or perhaps I wrote the manual before writing the code!
Sadly, I dont remember.)
Used conservatively these commands are useful and safe to use, so dont be
put off, but let me know if you discover any problems and Ill try to put
them right!
My contact details can be found at Knoware.no.
Program status
==============
V0.04, pjw, 2022 Jun 16, Fixed bug in routine to load arrays > 32k
Added test for overflow on massive arrays
Implemented skip parameter feature as advertised
Conditions of use and DISCLAIMER as per Knoware.no
QL Software
