Compiler (edit 465) and corresponding runtime enhancement: Add support for a new "dynamic overlay" mechanism. This is similar to the standard static overlay mechanism supported since "the beginning", except that the overlay is activated at runtime. Its primary initial use to be able to overlay a dynamic array with an X variable so that it can be passed as a parameter to subroutines. Eventually it might also be incorporated into a "pass by reference" capability.
There are two steps involved in creating a dynamic overlay:
Step 1: Declare the Overlay
Declare the overlay variable using the special ,@0 overlay syntax, e.g.:
MAP1 OVERLAY,X,@0
Note that the size field is optional but ignored, and only S and X variables are allowed. (In most cases, only X makes sense; use S-type overlays only when you are sure that the target variable contains no embedded null bytes.)
Step 2: Assign the Overlay
Assign the overlay at runtime using the "=@" operator, e.g.:
OVERLAY =@ VAR ! or, OVERLAY = @VAR (spaces are not significant)
This effectively gives the OVERLAY variable the same data storage location and size as the VAR variable. AS mentioned above, the main motivation is to do this with dynamic arrays, e.g.:
DIMX DYNARY(x,y,z),S,n
...
OVERLAY =@ DYNARY()
Note that you may NOT specify any array subscripts for the array on the right side of the @= operator, since this technique is currently only supported to overlay the ENTIRE array.
There is currently no corresponding operation to overlay a dynamic array on top of an X variable (which admittedly might be handy when passing such an array between routines via parameter lists). But you can get around that limitation using the technique in the following example, which passes a dynamic array to a procedure for processing:
DIMX ARY(X),S,Y
MAP1 OVL,X,@0
...
<load the array with some data>
...
OVL = @ARY() ! overlay the array with the XARY variable
CALL MYPROC(OVL,X,Y) ! pass array plus its dimensions to a function
...
! (our ARY() may have been updated by the MYPROC() procedure)
END
!----------------
PROCEDURE MYPROC(XXARY AS X0, ELEMENTS AS F, WIDTH AS F)
DIMX LOCARY(ELEMENTS),S,WIDTH ! allocate local array to match array passed in
MAP1 LOCOVL,X,@0
MAP1 I,F
LOCOVL =@ LOCARY() ! overlay the local (currently empty) array
LOCOVL = XXARY ! now copy the data on top of that
FOR I = 1 TO ELEMENTS
<perform operations on LOCARY(I)>
NEXT I
XPUTARG 1,LOCOVL ! update caller's overlay (which is the same as
! caller's actual array) with the local array data
ENDPROCEDURE
