X-ARGs

Revised June 2017

The peculiar term "X-ARGS" is used to apply to the family of statements listed below.

See History at the bottom of this topic.

These statements may be used (in place of the MX_XCBDATAX calls) to retrieve and return values within an SBX routine:

XGETARGS var1{,var2,... varN}

XGETARG <argno>, var

XPUTARG <argno>, <expr>

XPUTARG @var {=<expr>)

XGETARGSBX <argno>, var

XPUTARGSBX <argno>, <expr>

XPUTARGSBX @var {=<expr>)

These statements transfer arguments between callers and SBX modules, functions, and procedures. The XGET* variations receive arguments from the caller into local variables within the called routine, while the XPUT* variations send values back to the caller. XGETARGS is equivalent to a series of individual XGETARG statements referencing the variables in order, i.e. the nth argument passed by the caller is returned in the nth argument in the XGETARGS statement. Any additional arguments passed by the caller are ignored, as are any additional variables on the XGETARGS statement beyond the number passed by the caller. Likewise, any PUT operation for a parameter beyond the number of parameters passed by the caller will be ignored. The GET operations are non-destructive to the original argument list, allowing you to later retrieve (or re-retrieve) the same parameters with other XGETARG* statements.

The *SBX variations are specific to SBX parameters, eliminating confusion when an SBX also contains function/procedure calls. The non-*SBX variations always refer to the current function/procedure/SBX, whereas the *SBX variations only refer to the current SBX, so they could be used within a function within an SBX.

XGETARG argno,var performs the same function as XGETARGS except that it retrieves only the one argument, whose number is specified in argno.

XPUTARG argno,var is the reverse of XGETARG. It returns the value of the argument var into the caller's argument number ARGNO.

Note that in the case of XPUTARG, the second argument (value to return) can be a variable or an expression, whereas in the case of XGETARGS or XGETARG, the second argument must be a variable. You can't retrieve an argument into an expression, but you can use an expression to return an argument.

XPUTARG @var{=<expr>} is a newer convenience form (see History below) which eliminates the possibility of a mismatch between the argument number and the value by having the compiler automatically determine the argument number which matches the specified var, based on a prior XGETARG{S} statement referencing the same var. In the absence of the =<expr> clause, XPUTARG @var returns the current value of var. Otherwise it returns the value of the expression, using @var only to determine which parameter the expression is returned to (without modifying the value of var itself). For example:

XGETARGS vx,vy,vz

vy = 77

XPUTARG @vy ! same as XPUTARG 2,vy

XPUTARG @vz=vx+88 ! same as XPUTARG 3,vx+88s

Type conversions will be made as appropriate if the variable types do not match the types passed to the routine, although it behooves you to use "appropriate" data types for the circumstances.