Updated October 2011
See History at the bottom of this topic.
These statements may be used (in place of the MX_XCBDATA calls) to retrieve and return values within an SBX routine:
XGETARGS ARG1{,ARG2,...{ARGN}}
XGETARG ARGNO, ARG
XPUTARG ARGNO, ARG
XPUTARGSBX <argno>,<expr>
XGETARGSBX <argno>,<expr>
XPUTARGSBX <argno>,<expr>
XGETARGSBX <argno>,<expr>
XGETARGS retrieves the XCALL arguments into the corresponding variables. The first argument is returned in ARG1, the second in ARG2, etc. If more arguments were passed than you specify variables for, the extra arguments are ignored. Conversely, if you specify more ARG variables in the XGETARGS statement then were passed by the caller, the excess ARG variables are ignored. In either case, the operation is non-destructive to the original argument list, so you can later go back and retrieve (or re-retrieve) parameters using XGETARGS, XGETARG, or the original MX_XCBDATA statements.
XGETARG ARGNO,ARG performs the same function as XGETARGS except that it retrieves only the one argument (whose number is specified in ARGNO).
XPUTARG ARGNO,ARG is the reverse of XGETARG. It returns the value of the argument ARG into the caller's argument number ARGNO.
Note that in the case of XPUTARG, the ARG can be a variable or an expression, whereas in the case of XGETARGS or XGETARG, the arguments must be variables. (You can't retrieve an argument into an expression, but you can use an expression to return an argument.)
As with XGETARG, attempting to return an argument beyond the number of arguments passed is just ignored.
Type conversions will be made as appropriate if the variable types do not match the types passed to the routine (but it behooves you to use "appropriate" data types for the circumstances).
The following examples may clarify the equivalencies between the new statements and the old MX_XCBDATA calls:
XGETARGS P1,P2,P3,P4
is equivalent to:
xcall MIAMEX, MX_XCBDATA, XCBADR, XCBGET,1,P1
xcall MIAMEX, MX_XCBDATA, XCBADR, XCBGET,2,P2
xcall MIAMEX, MX_XCBDATA, XCBADR, XCBGET,3,P3
xcall MIAMEX, MX_XCBDATA, XCBADR, XCBGET,4,P4
and is also equivalent to:
XGETARG 1,P1
XGETARG 2,P2
XGETARG 3,P3
XGETARG 4,P4
For returning arguments,
xcall MIAMEX, MX_XCBDATA, XCBADR, XCBPUT,1,A+B/C
is equivalent to:
XPUTARG 1,A+B/C
The main advantage of the new statements is just efficiency, both for the programmer and for the computer. (This is especially true if you use XGETARGS to retrieve all arguments in one statement.)
Note that these new statements do not require XCBADR or any of the other variables set up by ASHINC:XCALL.BSI. However, you may still want to continue including XCALL.BSI at the start of your SBX modules since it does set the variable XCBCNT to the number of parameters passed, and the XCBSTRUCT() array to the types and sizes, and this information can be useful in determining how to interpret the passed parameters. (XGETARGS and XGETARG do not give you any obvious indication when fewer parameters were passed to the subroutine than the subroutine is expecting, so a well-written subroutine should, at a minimum, check XCBCNT to see how many parameters were passed.)
You do need to compile with the /X:2 (A-Shell extensions) switch (but this is true for all SBX modules anyway).
History
2011 October, A-Shell 5.1.1235: XGETARG now supports AUTO_EXTEND. Previously you needed to do a dummy assignment to the array variable prior to the XGETARG in order to trigger the auto extension.
2010 January, A-Shell 5.1.1173: Added the following new statements:
XPUTARGSBX <argno>,<expr>
XGETARGSBX <argno>,<expr>
XPUTARGSBX acts just like XPUTARG except that it references <argno> in the current SBX context, even if it occurs inside a function or procedure. PUTARG continues to act as before, referencing the function or procedure argument if inside a function or procedure, else the SBX argument if not.
Note that using XPUTARGSBX in a program will set the "5.1 extensions" flag in the header, which will can be seen by VERSYS, and which will cause a runtime error in versions of A-Shell prior to 1160, but it will not provide any warning in versions 1160-1172. In those versions, the runtime system will generate an illegal syntax code when hitting such a statement.