Updated June 2023; see History
An entire ordered map may be passed by reference to functions, procedures, and subroutines. Conceptually and syntactically this is very similar to passing other kinds of DIMX arrays by reference. On the calling side, you specify the array in the parameter list using an empty set of parentheses, for example...
dimx $mymap, ordmap(varstr;varstr)
...
call MyProc($mymap()) ! pass $mymap() ordered map by reference to procedure
xcall MYSBX, $mymap(), ... ! pass $mymap() ordered map by reference to SBX
On the receiving side, the syntax is somewhat different between functions/procedures, on the one hand, and SBX routines on the other. In the case of functions and procedures, you declare the local name for the array in the parameter definition also with an empty set of parentheses, with the "as clause" specifying the ordered map type, e.g.
Procedure MyProc($m() as ordmap(varstr;varstr))
$m("foo") = "bar" ! updating m$() updates $mymap() directly
In the case of an SBX, you must use a special variation of the DIMX statement, with the BYREF clause, to declare the local copy of the map, and then use XGETARG{S} to set up the connection to the calling map:
dimx $m ordmap(varstr;varstr), byref ! declare surrogate local version of map
...
xgetargs $m(), ...
or
xgetarg 1, $m()
See the following subtopic for information on Mismatched Collection Arrays.
Note that once the ordered map passed by the caller is linked to the local surrogate ordered map using one of the above schemes, from that point on, the local and remote arrays are the same, i.e. their names are aliases for the same ordered map, and any changes made within the function or SBX will directly affect the caller's copy of the map.
Do not use XPUTARG to try to pass back the updated local array, as this is both superfluous and senseless.
In addition to passing ordered maps by reference to any SBX written to receive them, there may be specific built-in subroutines which are capable of handling ordered maps passed by reference in very specific cases, in which case it will be explicitly so noted in the documentation for that subroutine. For example, see the CGIUTL opcode CGIOP_GETPARRAY.
See Also
| • | MAPDIR.BP (SBX) and the corresponding TSTMAPDIR in SOSLIB:[907,45] which illustrate passing an ordmap to an SBX by reference. |
History
2023 June, A-Shell 6.5.1731, compiler edit 1022: Compiler now complains about mismatched collection arrays passed by reference to functions.
2017 December, A-Shell 6.5.1623: Add ability to pass ordered maps by reference to functions and procedures.
2016 August, A-Shell 6.3.1520: Add capability to A-Shell.
Subtopics
