Modified March 2016; minor edits

XTREE enhancement: array descriptors. Provides an alternate method of specifying the answer and data arrays, using the following structure as defined in XTREE.SDF in SOSLIB:[907,16]:

DEFSTRUCT ST_XTRARYDESC    ! [136] array descriptor

    map2 BASEADDR64             ! [136] address of base of array

        map3 BASEADDR'LO,B,4    ! [136] low 32 bits

        map3 BASEADDR'HI,B,4    ! [136] hi 32 bits (for 64 bit mode future)

    map2 LOADFROM,B,4           ! [136] element # to start loading from (base 1)

    map2 FLAGS,B,4              ! [136] misc flags

    map2 WIDTH,B,4              ! [136] array width

    map2 TOTROWS,B,4            ! [136] total rows in ENTIRE array

ENDSTRUCT

To retrieve the address of the base of the array (and for convenience, the width as well), use XCALL GETADR as follows:

MAP1 xtary'desc,ST_XTRARYDESC

MAP1 xtary(5000),S,99

xcall GETADR, xtary(1), xtary'desc.BASEADDR64, xtary'desc.WIDTH

That would load the BASEADDR64 and WIDTH members of the structure. You can get the total number of elements using the .EXTENT() function:

xtary'desc.TOTROWS = .EXTENT(xtary())

Then just specify the desired starting row with an assignment:

xtary'desc.LOADFROM = 1     ! start loading from 1st element

This descriptor structure can then be used in place of the data or answer array, e.g.:

XCALL XTREE, srow, scol, answer, xtary'desc, itemcount, coldef, ...

Note that you still need to set the ITEMCOUNT parameter to the number of rows to be loaded, just as you normally would. (The TOTROWS member of the descriptor is just there as a safety check against accidentally trying to load more rows than exist. (Either way, XTREE has to trust you on the total size of the array, but if you use the .EXTENT() function as shown above, it should be easy to avoid mistakes there.)

The ST_XTRARYDESC structure definition has been added to ASHINC:XTREE.SDF

History

2012 June, A-Shell 6.1.1307:  XTREE Array descriptors added to A-Shell.