Passing Collections

Rewritten December 2017

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(), ...

xgetarg 1, $m()

As with other DIMX array passing, the compiler does not attempt to determine if the source and destination array formats are compatible, but the runtime system enforces a degree of sanity, in this case, complaining if you attempt to pass an ordmap(varstr;varx) to an ordmap(varstr;varstr) or vice versa.

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.