The BBC and Master Computer Public Domain Library

99FE Get address of the specified Array element

Submitted by Steve Fewell

Routine:ArrayElemAddr
Name: Get address of the specified Array element
Starting Address: &99FE
Entry criteria: &37 and &38 point to the start of the variable name.
Y = length of the variable name (Y points to the '(' character of the variable name.
&2C contains the return type of the variable.
Exit: (&2A, &2B) = the address of the required data element (&2A = LSB).

Description:

Increment the X and Y pointers to point to after the '(' character of the variable name.
Call routine &8085 to get the address of the variable block (stored in (&2A, &2B).
If the variable was not found (Zero flag set), then the variable hasn't been defined
so, generate 'Array' error.
Update the Text Pointer B offset value (&1B) with X.

Push the variable return type, the variable pointer LSB and variable pointer MSB to the stack.
Load the first byte from the variable pointer address (&2A, &2B). This value is
the pointer to position after the last dimension.
If the pointer to position after the last dimension is 4 (indicating 1 dimension) then goto &9A85 to
handle a 1 dimensional-array.

[&9A16] Handle Multiple Array dimensions
Clear the IWA and set byte &2D of the IWA to 1. [Bytes &2A and &2B is the requested element
value. Byte &2D is the pointer to the dimension subscript (max value)].
[&9A1D] Push the IWA value to the stack. This is the current subscript value & pointer to max subscript.
Call routine &96AF to evaluate the expression after the '(' character, and convert the
expression result to an Integer (if it was a Float). A Type Mismatch error is generated
if the result is a String. Now the IWA contains the requested element.
If the next character is not a comma then generate an Array error, as the declared Array
is a multi-dimensional array, but the array usage does not specify a second dimension, so
the array the text pointer is refering to does not exist!
Increment the Text pointer B offset (to point to after the comma character).

Set (&37,&38) to Variable block pointer & retrieve current subscript from stack to &39-&3C
Pop the Integer value stored to the stack to locations &39 to &3C.
Set Y = the current dimension offset in the variable block (the 4th byte of the Integer variable).
Store the Variable block pointer MSB in &38 (keeping the value on the stack).
Store the Variable block pointer LSB in &37 (keeping the value on the stack).

Check subscript value in the IWA & get next dimension's max subscript value
[&9A3A] Call routine &9AD3 to check the dimension subscript.
Update &2D with the value returned by the check subscript routine. This value now points
to the Dimensioned subscript value for the next dimension in the variable parameter block
[each 2-byte dimensioned subscript value is stored, one after the other, after the pointer to
the position after the last dimension (1-byte) value in the variable parameter block].
Load the second dimension's subscript (maximum element number) and store this 2-byte value in
locations &3F-&40.

Add the current subscript value (in the IWA) to the previous subscript value (&39-&3A)
and store the result in &2A-&2B, as the current subscript value now takes into account
any previous dimensions that have been specified.
The previous subscript value is the previous IWA value (before the current element subscript) was
obtained. This value is the total of all previous subscript values.
Call routine &9508 to multiply the current subscript value (&2A, &2B)
(or "the Upper limit", as it is the total element value from all earlier elements) by the
Lower Limit (&3F-&40). The lower limit is the maximum number of elements in the next dimension.
We need to multiply the current subscript by the lower limit (of the next element) in
order to take into account the relative position of the element we require within the
Array as a whole.
E.g. "DIM r(100,100):r(37, 50)=1" will return the element value for r as: 37 * 100 (= 3700) + 50 = 3750.
The 37 * 100 part is the value that is calculated by the section of the routine described above.

Load the pointer to the position after the last dimension of the array (the first byte of the
variable parameter block). Subtract the current dimension maximim subscript pointer (&2D) from
the pointer to the position after the last dimension.
If this value is >&eq;3 then there is more than 1 more dimension to process, so goto &9A1D
to handle the other dimensions.

One more element left to process - obtain details for last element
Push the IWA to the Stack, the IWA contains the current element location )&2A-&2B) and a
pointer to the next element details in the Variable Parameter block (&2D).
Call routine &96A7 to evaluate the next expression pointed to by Text pointer B.Convert the
[&ADAC] If the next character after the expression is not an ")" then generate a Missing ) error.
Convert the expression result to an Integer (if it was a Float). A Type Mismatch error is generated
if the result is a String. Now the IWA contains the requested element value of the last element.

Pop the Array variable parameter block pointer address from the Stack (and place it in &37-&38).
Pop the Integer value from the stack to locations &39-&3C (this is the current element location).
Set Y = the Dimension offset in the variable paremeter block (?&3C).
Call routine &9AD3 to check the dimension subscript.
Add the current subscript value (in the IWA) to the previous subscript value (&39-&3A)
and store the result in &2A-&2B, as the current subscript value now takes into account
any previous dimensions that have been specified. Now IWA bytes &2A-&2B contain
the required element position within the array.
Jump to &9A96 to calculate the address of the element's value.

[&9A85] Handle Single/Last dimension of array
Call routine &ADAC to evaluate the next expression pointed to by Text pointer B.Convert the
If the next character after the expression is not an ")" then generate a Missing ) error.
Convert the expression result to an Integer (if it was a Float). A Type Mismatch error is generated
if the result is a String. Now the IWA contains the requested element value.

Pop the Array variable parameter block pointer address from the Stack (and place it in &37-&38).
Set Y = 1 (the Dimension offset in the variable paremeter block).
Call routine &9AD3 to check the dimension subscript.
Continue to &9A96 to calculate the address of the element's value.

&9A96 Calculate the address of the element's value.
Pop the variable return type from the Stack.
If the variable return type = 5 (Floating-Point value) then Store the original element
position (&2A-&2B) in A and X and Multiply the element position by 4 and then
add the original element position to the result. This will have multiplied the value by 5 in total.
Each Floating-Point value is 5-bytes in length, so now bytes &2A-&2B contain the
address of the required value. Jump to &9ABC to finish off and tweek this value to the correct address.

If the variable return type is either Integer or String (both values are 4-bytes long), then
Multiply the element position by 4, so that bytes &2A-&2B now point to the required value.

[&9ABC] However, as the values are offset from the variable paremeter block, we need to add the
length of the array parameter block to the address we generated. This is because, depending on the
number of dimensions, the parameter block could be different lengths for each array - not a fixed length.
Add Y (Byte &2D of the IWA value), which is the offset of the last dimension in the parameter block,
to &2A, and increment byte &2B if an overflow occurred.
Now, to obtain the direct address of the specified value we need to add the value we calculated
in &2A-&2B to the base address of our variable paremeter block (&37-&38). This will
give us the exact memory start address for the first byte of our value.
Exit with &2A-&2B = The value address and &2C = value type.

[&9AD3] Check the dimension subscript
Load byte 2 of the Integer subscript value in the IWA & 'AND' the value with #&C0,
then 'ORA' the result with &2C and &2D. This checks the subscript value, if the value
is > 8392 or < 0 (&2C or &2D contain a value or one of the top 2 bits of &2B are set).
then generate a Subscript error, as the subscript value is too large or negative.
Compare the first byte (&2A) of the subscript value with the dimension subscript LSB value
in the variable parameter block.]. Increment Y.
Compare the second byte (&2B) of the subscript value with
the dimension subscript MSB value (maximum size of subscript, MSB).
If either of the compares exceed the maximum subscript value for that dimension then
generate Subscript error. Increment Y to point to the next byte of the variable block.
The subscript is ok, so return to the calling routine.

[&9508] Multiply specified upper dimension by the lower dinension
(&2A, &2B) return the specified upper dimension adjusted to take into account the lower elements.
Multiplies &2A, &2B by &3F-&40.
Firstly: zero X and Y.
[&950C] Divide copy of 2nd dimension's max subscript (&3F-&40) by 2 (shift right).
Next, if the lost bit (from the right-hand end) was 0 then multiply &2A,&2B by 2 and
if &3F and &40 are not zero then loop again [&950C].
Otherwise: clear carry flag, add &2A to Y & add &2B to X. If the addition
     overflowed, then generate a Bad Dim error, as the element value is >&FFFF)
     (this should only occur during the DIM statement, and not during access to
     the array - as the DIM would have already generated the error).
     Multiply &2A-&2B by 2.
     If &3F-&40 is not zero then loop again [&950C].
Now, the second value (&3F-&40) is zero, and X & Y contain the result of
the first value (&2A-&2B) multiplied by the second value (&3F-&40).
Set &2A = Y and &2B = X and return with the updated element location.

Disassembly for the Get address of specified Array element routine

Disassembly for the Check Dimension Subscript routine

Multiply specified upper dimension by the lower dimenson subscript (2-byte multiplication)