Added February 2025
Syntax one:
.ARG_READONLY(argno) or .ARG_READONLY(@arg)
Syntax two:
.ARG_PASSED(argno) or .ARG_PASSED(@arg)
These two dot functions indicate whether the specified argument is read-only, or was even passed to the current SBX, function, or procedure.
Warning: It is easy to accidentally specify arg when you meant @arg, both of which are syntactically correct (assuming arg is the name of an argument in the current context) but have vastly different meaning. To help avoid this mistake, the compiler (as of edit 1065) will treat arg as an error if it matches a current argument name; if you really meant to reference the argument by number, use a literal number or a variable that isn't a current argument.
Parameters
Note that these parameters apply to all of the .ARG... functions.
argno (Unsigned int) [in]
The ordinal number of the argument being queried, starting from 1. Note that in the case of Named Parameters, the parameter numbers are determined by the function declaration or subroutine DEFXCALL directive, not necessarily by the order specified in the calling statement. If the argno passed is invalid, the return value of the function will be -1.
@arg (Literal parameter name) [in]
This syntax provides an alternate way to reference the parameter of interest by its name rather than its ordinal number. The concept is similar to that used for XPUTARG @arg : @arg is treated by the compiler as a macro for the argument number corresponding to the argument arg as defined in the function/procedure definition or as retrieved in an SBX using XGETARG(S).
Comments
The return value is a BOOLEAN.
.ARG_READONLY() is logically equivalent to testing the ARGTYP_READONLY bit in the value returned by .ARGTYP().
.ARG_PASSED() returns .TRUE if the argument was actually passed by the caller, rather than auto-set via the default value specification in the function declaration. Note that although this function is fully resolved by the compiler, making it at least nominally backwards compatible, on runtime versions prior to 7.0.1767 it acts as the inverse of .ARGTYP_READONLY().
Also note that as of compiler edit 1065 (A-Shell 7.0.1770), the .ARG_PASSED status is inherited; see Example 2 below.
Example 1
call fn'foo(arg=9)
...
function fn'foo(arg=1 as b2)
? .ARG_READONLY(@arg) ! .TRUE in all cases
? .ARG_PASSED(@arg) ! .TRUE if > 7.0.1766, else FALSE
endfunction
The argument is readonly because it was passed as a literal value. The function could try to update it using XPUTARG(@arg1) but it would have no effect, since the value is on the stack.
But readonly or not, it was actually passed, which might be meaningful to the called function. However, prior to 7.0.1767, the runtime is unable to determine that, so it will the readonly status instead. From 1767 forward, the two flags are independent.
Example 2
call fn'foo() ! no arg passed
end
function fn'foo(argx=0 as b2:outputonly)
? "argx=";argx; .ifelse$(not .ARG_PASSED(@argx),"NOT ",""); "passed"
call fn'nested'foo(argy=argx)
endfunction
function fn'nested'foo(argy=1 as b2:outputonly)
? "argy=";argy; .ifelse$(not .ARG_PASSED(@argy),"NOT ",""); "passed"
endfunction
The above program will display...
argx= 0 NOT passed
argy= 1 NOT passed
... even though the call from fn'foo() to fn'foo'nested() actually does specify the argy=argx parameter, since the inheritance of the argument passed status carries down to the nested function. The fn'foo'nested() function could still pass an updated argument back to its immediate parent fn'foo(), but that value would not ever make it back to the top level since it wasn't passed from there. (If fn'foo() really wanted the value passed back from fn'foo'nested(), it might want to use a different variable to eliminate the potential ambiguity over whether fn'foo'nested() needed to update that argument.)
Note that this applies to both normal static function calls and dynamic (DYNFUNC) calls.
History
2025 March, A-Shell 7.0.1770, compiler edit 1065: ARGTYPE_PASSED status now inherited.
2025 January, A-Shell 7.0.1767, compiler edit 1051: Add support for .ARGTYP_READONLY and .ARGTYP_PASSED.
