Passing Collections II
Added February 2018
Beginning with A-Shell 6.5.1623 and compiler edit 844 of December 2017, collections can be passed by reference in a subroutine to an SBX. On the calling side, the syntax is the same as for passing a DIMX array of structures, i.e. just specify the collection name with an empty set of parentheses, e.g.:
dimx $coll, ordmap(varstr;varstr)
...
xcall MYSBX, $coll(), ...
The receiving side is also similar to that for receiving a DIMX array of structures, i.e. you must first declare the receiving array with a variation of the DIMX statement including the BYREF clause, e.g.
dimx $locoll, ordmap(varstr;varstr), byref
Then use XGETARG or XGETARGS to receive the collection...
xgetargs $locoll(), ...
or
xgetarg 2,$locoll()
See MAPDIR.SBX and associated TSTMAPDIR in SOSLIB:[907,45] for a useful working example.
Ordered map parameters are passed by reference, allowing the called routine to operate directly on the caller's copy of the ordered map (inputting and/or outputting, clearing or extending). As there are multiple variations of ordered maps, it is usually necessary that the variation passed matches the expectation of the receiving routine—which hopefully spells out the requirements in its documentation.
History
2017 December, A-Shell 6.5.1623: Add capability to A-Shell.
