The BBC and Master Computer Public Domain Library

90AB Set String variable

Submitted by Steve Fewell

Routine:setstringvar
Name: Store string value in the specified Variable
Starting Address: &90AB
Entry criteria: The SWA contains the String value &
the variable address and type details are stored in the Integer value on the BASIC stack.
Exit: The specified variable has been set to the value in the SWA.

Description:

Pop the Integer from the BASIC Stack. Now &2A-&2B will contain the address of the variable's value,
and &2C will contain the variable's return type.

If the variable's return type is #&80 then we are not setting a variable, but a direct memory access
via a statement such as: LET $&0F55="HELLO"; so, as we are not dealing with a variable we can skip the
checking of the variable's existing length and go directly to storing the value.
To store the value of a non-variable String, we first store a carriage return as the next free position in the
SWA (as String values must terminate with a carriage return character). If SWA length (&36) is zero then
store the carriage return character at the Direct Memory address given and exit; otherwise, copy the SWA value
to the Direct Memory address (and subsequent bytes, as necessary) and exit.
Note: The SWA value is stored last character first, and first character last.

Otherwise we are dealing with a String variable (as the return type is probably #&81).
The String variable's address points to a 4-byte parameter block, this parameter
block contains the following: A 2-byte pointer to the current value of the String,
followed by the maximum size allocated for the String variable value (1 byte),
followed by the current size of the String value.

Compare the maximum length assigned for the String Variable value (the 3rd byte in the
variable's parameter block) with the length of the SWA (&36).
if the current Maximum length is >&eq; the SWA length then we do not need to allocate
more space for the variable, so [&910E] Store the SWA value in variable location.

Otherwise we need to allocate more space, as follows:
Store VARTOP address (the next free Variable storage address) in &2C-&2D, this
will be the location of the variable's new String value.
If the new String length is less than 8 and the new string length + 8 is less then #&FF
then set the new String length to #&FF. [This will resolve possible problems with String values
more than #&F7 characters long]. Otherwise set the new string length to &36 (SWA length).
Push the new String length to the Stack.

If the current VARTOP value is equal to the Variable value address (first 2 bytes of
variable's parameter block) plus the variable length (4th byte of the variable parameter
block) then the Variable's current value was the last item added to VARTOP, so
Store zero in location &2D (this will tell the allocate space routine not to
change the current Variable value address) and Subtract the old String length from the
new String length (in X), so that we only allocate the remaining number of bytes required!

Add the new string length (in X) to VARTOP address (store result in X & Y).
This will be the new VARTOP value, but first check whether this value would overlap with
the BASIC Stack, if it would then there is no more variable storage space, so issue a No Room
error.
Otherwise, update VARTOP (&02-&03) to the new VARTOP value (in X and Y).

Next, we need to set up the Variable's parameter block with the newly allocated information.
Retrieve the new variable length from the Stack.
Store the new variable length in the Max Size Allocated byte of the variable's parameter
block (the 3rd byte).
Check location &2D, if it is zero then we do not need to change the address of the variable's
value, as the last location (which was at the top of the BASIC variable Heap) has been extended.
Otherwise, store the new located (in &2C-&2D) as the address of the variable's value
in the first 2 bytes of the variable's parameter block.
Now, that we have the required space, continue to &910E to store the SWA value.

[&910E] Store the String SWA value in the variable location
Firstly, store the SWA length (&36) in byte 4 of the String variable's parameter block, this is the
1-byte which represents the current length of the String variable.
If the String is blank (SWA length is 0) then exit.

Store the variable's address (the first 2 bytes of the variable's parameter block)
in locations &2C-&2D.
Store the SWA value to the memory location pointed to by &2C-&2D. [Note: The SWA
value is stored first character first, last character last].
When we have stored all characters of the SWA's String value then exit, as the variable's
value is now complete.

Disassembly for the Set String variable routine