A-Shell Reference

Reviewed and revised April 2024

Syntax one:

.ARGTYP(argno)     or     .ARGSIZ(argno)

Syntax two:

.ARGTYP(@arg)     or     .ARGSIZ(@arg)

These two dot functions return the type and size, respectively, of the specified source argument as passed to the current SBX, function, or procedure. Note that the original source argument types and sizes may be completely different from those received by the SBX or function (see Parameter Types). These functions allow the called routine to see the original passed types and sizes before they were converted by the calling operation.

Parameters

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 format 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).

The return value for .ARGSIZ is the size of the original argument in bytes.

The return value for .ARGTYP is a 16-bit bitmap value based on the following tables: one bit from the first table, zero or more bits from the second table.

 

 

u ARGTYP_READONLY Details

 

Example: SBX

xgetargs color, rvalue, gvalue, bvalue

xgetarg 5, name

...

if .argtyp(@gvalue) and ARGTYP_B then ...  ! if gvalue arg binary

if .argtyp(3) and ARGTYP_B then ...        ! if 3rd arg binary (same as above)

if .argtyp(@name) and ARGTYP_S then ...    ! if name arg string

 

The above example illustrates that in the case of an SBX, the @arg reference is based on the order that the referenced variable appears in the xgetargs statement, or the argument number associated with it in a preceding xgetarg statement. Usually the @arg syntax is preferred, since it self-adjusts if you alter the parameter list, but in some cases it might be preferable to stick with the numeric argument numbering.

Note that .argtyp() returns the type of the argument that was passed in the XCALL, not the type of the variable receiving it in the SBX.

For example, if the gvalue variable inside the SBX was mapped as B,1, but the SBX was called via...

xcall RGB, &h0080ff,  "255", "128", 0, "orange"

then .argtyp(@gvalue) would return &h0422 (ARGTYP_READONLY, _NOSURR, _S), not _B.

Example: Function

map1 lastname$,s,35,"Ryan"

call Fn'MilitaryID(serial=123456789, name=lastname$)

...

 

Function Fn'MilitaryID(name="" as s20, rank="Private" as s15, serial="" as s10)

   map1 ix,i,2

   for ix = 1 to .argcnt

      ? "&h";Fn'Dec2Hex$(.argtyp(ix), .argsiz(ix)

   next ix

EndFunction

 

The above should print out:

&h22     35

&h422    7

&h424    8

 

The .argcnt is 3 even though only two parameters were listed in the call; this is because the default values in the function declaration caused the compiler to add the missing parameter and default value (rank="Private") to the call.

All three of the arguments have the ARGTYP_NOSURR bit set, indicating that the arguments were passed directly without the use of an intermediate surrogate; that typically only affects internal subroutines passing F6 parameters with an IEEE F8 surrogate. The last two have the ARGTYP_READONLY bit set since they were passed as expressions rather than variables and therefore can't be updated.

The first line/argument in the display refers to the name parameter (#1 in the declaration) even though it is passed second in the call. Again, the named parameter mechanism causes the calling statement to be rearranged to match up with the expectation of the target function. Note that its size is 35 (the size of the source variable lastname$) rather than 20 (the size of the local variable name receiving it.) It can be updated via xputarg since a real variable was passed.

The second line refers to the rank parameter (#2 in the declaration); its size is 7 because it is effectively a literal string "Private".

The third line refers to the serial parameter (#3 in the declaration); its size is 8 because the value 12345678 passed in the call was converted to a numeric (F8) expression before being converted to a string during the parameter passing.

See Also

History

2017 September, A-shell 6.5.1616, compiler edit 834:  Add support for .ARGTYP and .ARGSIZ.

2017 July, A-Shell 6.4.1553:  ARGTYP_READONLY added to A-Shell.

2014 September, A-Shell 6.1.1373:  Functions added to A-Shell. Warning: These functions are not recognized by prior runtime versions, and will simply return the value of the argno passed. You could use this fact to test if the feature is supported at runtime by passing an illegal argno, such as 999 or -2, to .ARGTYP(argno). If supported, the return value will be -1 (error); else if will match the argno passed. If developing code that might possibly have to run on such an old version, use MX_GETVER or the wrapper function Fn'MinAshVer() in fnminsasver.bsi in SOSLIB:[907,10] to check the version first.