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.
See Also
History
2017 June, A-Shell 6.5.160?, compiler edit 825: XPUTARG{SBX} @var{=<expr>} added. Note that it is purely handled by the compiler and requires no update to the run-time.
Subtopics
