The BBC and Master Computer Public Domain Library

9534 DIM

Submitted by Steve Fewell

Description:

Get the next non-space character pointed to by BASIC Text pointer A.
Subtract 1 from address pointed to by Text pointer A (plus Pointer A offset) and store
the new address in location &37-&38.
Store 5 in &3F (variable trype), as the default variable type (unless a % or $ is specified
at the end of the variable name) is a 5-byte Floating-Point value.

Backup the current PTR Offset value in X (to preserve the pointer to the start of the variable name).
Call routine &9AF6 to Check the variable name. This routine does the following:
1* Set Y = 1
2* Read next character from address pointed to by &37-&38.
3* If the next character is < "0" then exit.
4* If the next character is >= ":" and less then "@" then exit.
5* If the next character is "0" to "9" and Y = 1 then exit (variable cannot start with a digit).
6* If the next character is >= "[" and < "_" then exit.
7* If the next character is > "z" then exit.
8* Otherwise, the character is valid for the variable name, so increment Y & X (Ptr A offset)
and check next character (2*).

If Y is still 1 then no valid characters were found, so a variable name was not specified
after the DIM keyword, so issue a Bad DIM error.

if A (the Character after the last valid character of the variable name) is "(" (open bracket)
then jump to &9570 to dimension an Array variable.
If A is "$" or "%" then we have either a String or an Integer variable type, as both of
these has a parameter block size of 4 bytes, then decrement &3F (size of the variable
parameter block) from 5 (default - Float) to 4. Also, check the next charater pointed to
by &37-&38. If this character is "(" then jump to &9570 todimension an Array variable.
If the next character is not "(", or the variable was a Floating-Point value (no "%" or "$" after name),
then jump to &94BC to dimension a memory area.

&9570 - DIM Array variable
Increment Y to point to after bracket character (this is the variable name length we will pass to &8085).
Store back X to the PTR A offset (pointer to start of variable name).
Call routine &8085 to get the variable return address details.
If A is not 0 then an array with that name already exists, so issue a Bad Dim error as
we cannot have two arrays with the same name. &8085 sets &39 to the length of the variable name.

Call routine &9854 to add the new array name to the variable parameter block.
Set X to 1 (Number of bytes to reserve for the variable parameter block) and call routine &9883 to Allocate
variable parameter block space for the variable.

Store &3F to the stack (Variable type length - 5 for float, 4 for Integer/String).
Store 1 to the stack (this is the next Dimension subscript position in the variable parameter block).
Call &AE18 to set the IWA to 1.

[9589]
Push the current IWA value to the BASIC stack.
Call routine &926F to get the result of the expression pointed to by BASIC text pointer A
and convert the result to an Integer value (or issue Type Mismatch error if String value).
If any of the bytes &2C or &2D, or either of the top 2 bits of Byte &2B, are set
then the value is either negative or too large for an array subscript (>&3FFF (16383 in decimal)).
Increment the IWA value (routine &BEEF), we we need to define 1 more position that the value stated, in order
to make space for element 0 of the array.

Retrieve the "next Dimension subscript position in the variable parameter block" from the stack
and store &2A and &2B (the next dimension subscript value) to VARTOP + next subscript position in
parameter block value.
Increment the next subscript position by 2 (to obtain the next dimensions (if any) position
and store this value back on the stack.

Call routine &9503 to Multiply the specified subscript by any lower subscript values (the IWA value on the
Stack). This routine issues a Bad DIM error if the total number of elements is >FFFF.
Now, the IWA contains the current total number of elements in the array.
Check the next non-space character at BASIC Text Pointer A (&8CE5) and if the character is
a comma (','), thengo back to &9589, to store the current number of elements (IWA) on the Stack
and process the next dimension subscript in the array.

Otherwise, if the next non-space character is not a comma, then it needs to be a close bracket ')',
if it isn't a close bracket then there is an error with the structure of the DIM statement,
so issue a Bad DIM error.

Retrieve the Variable return type value, and store this value in location &3F.
[To do this the variable block offset (pointer to next free location in the Array's variable block header)
is temporarily retrieved, and stored back to the stack again, after we have retrieved the variable type.]
Set location &40 to zero. Now &3F-&40 contain the number of bytes required by the variable
return type [that is 4 for String/Integer and 5 for Floating-Point].
Multiply the number of elements by the number of bytes required by the variable return type.
This will set the IWA to the total number of bytes required for the array variable data.
Retrieve the Variable parameter block offset value (which points to the location after the last Subscript value)
from the stack, and add this to the IWA.
Now the IWA contains the total number of bytes required for the array storage (including the storage
required to hold the maximum subscript values for each dimension).

Copy the current VARTOP address to &37-&38.
Add the total number of bytes required for ther array's storage (&2A-&2B) to the
address pointed to by VARTOP. If this value exceeds &FFFF then issue a DIM space error.
If the new VARTOP value would run into the BASIC Stack then issue
the DIM space error, as there is not enough variable storage space left for the array.

Update VARTOP to point to the next free location after the array storage space.
Retrieve the offset to the next dimension in the variable parameter block (which actually
is a pointer to the first value, as there are no more dimensions to add) in the first
byte of the variable parameter block (pointed to by &37-&38 - the old VARTOP value!).
This byte specifies how many dimensions the array has.

Next, store zero in the array's element value locations to initialise all elements to blank.
[To get the value of the first element to byte, we set Y to &37 (Old VARTOP LSB value) + offset
to the first value, so that Y contains the LSB pointer to the first value in the array,
and clear &37, so now (&37),Y will return the first byte of the first array value].
[Keep storing zero until (&37), Y reaches the new value of VARTOP.]

Jump to &94FB to check for a comma at BASIC Text pointer A location, if there is a comma
there we have more arrays to define, so jump back to &9534.
Otherwise, jump to &9000 to continue processing the current BASIC command/program line.

&94BC - DIM Memory area
Decrement &0A (the BASIC Text pointer A), to disregard the last character we read (we needed to check
whether it was a '(' or not in order to know whether to DIM an array or memory).

Call routine &98AE to check for the variable's existence (and create a new variable if it doesn't
already exist).
If the variable name was not valid (zero flag set) then issue a Bad DIM error.
If the variable is a String variable (carry flag set), then issue a Bad DIM error,
as we need a variable that can hold the address value of the dimensioned memory space.

Call &BC43 to Push &2A, &2B and &2C to the 6502 stack (&2A-&2B is the
address of the variable's value, and &2C is the variable's type).
Call &96AF to get the result of the expression and convert the result to an Integer
if it was a Floating-Point value, or issue Type Mismatch error is a string value was returned.
Increment the IWA value (&BEEF), as we need to account for the 0th byte (i.e. DIM a% 0 - reserves
1-byte of storage). Now the IWA contains the number of bytes of memory to reserve.

If &2C or &2D contain a value then the amount of memory to reserve is either negative
or >FFFF, so issue a Bad DIM error.

Add the required number of bytes to reserve (IWA) to the current VARTOP address
(but dont update VARTOP value yet).
If the new VARTOP would run into the Stack then there is not enough room for the
required number of bytes of memory to be reserved, so issue a DIM Space error.
[Note: The variable is still defined even if there is not enough room to reserve the required memory!].

Set &2A-&2B to the previous VARTOP address (the start of the reserved memory).
Update VARTOP to point to the new VARTOP value.
Set &27 and A to #&40 (Integer result value), and call &B32B to set the
variable (whose value address and type are stored on the Stack) to the current result value
(in this case the value of the IWA, as the result type (&27) is Integer).
Call &9275 to reset BASIC Text Pointer A offset (&0A) to the BASIC Text Pointer B offset (&1B).

Continue to &94FB to check for a comma at BASIC Text pointer A location, if there is a comma
there we have more arrays to define, so jump back to &9534.
Otherwise, jump to &9000 to continue processing the current BASIC command/program line.

Disassembly for the DIM routine