The default return value is 0 for numeric functions and "" (null) for string functions. To set another return value, assign it to the variable matching the function name (e.g. FN'name = -1). Note that this is similar in concept to the RETURN(<expression>) statement in an SBX, except that it doesn't end the function.
The return variable otherwise functions as a standard variable and can be used in expressions and be assigned a value multiple times (only the last one will matter at the time the function returns). As an example of one possibility, in the Fn'Dec2Hex$ sample function above, the return variable Fn'Dec'Hex$ receives its value by being passed as a parameter to a subroutine:
xcall MIAMEX, MX_OCVT, decval, width, OT_MEM or flags, Fn'Dec2Hex$
A special case occurs when the function returns a defined structure. In this case, in order to obey the naming rules, the function name must end with a $. But the $ is dropped when referencing members of the structure. Consider this example of a function which returns an item structure when passed an item ID.
defstruct ST_ITEM
map2 id,s,10
map2 descr,s,30
map2 price,f
endstruct
map1 item,ST_ITEM
item = Fn'Item$("A12345")
end
Function Fn'Item$(itemid as s10) as ST_ITEM
Fn'Item.id = itemid
Fn'Item.descr = "some description"
Fn'Item.price = 7.99
End Function
Note that the name of the function has a $ on the end (Fn'Item$), but when referring to the individual fields within the structure, the $ is dropped (Fn'Item.id = itemid).
Also note that the return value of the function is a copy of the entire ST_ITEM structure as it exists at the end of the function, even though there is no explicit reference to the structure as a whole. Any members of the structure which are not assigned would simply default to zeros or nulls, just as they would for a traditional unformatted MAP1/MAP2 structure.+
The alias .fn (or .FN or .Fn, i.e. case insensitive) may be used in place of the actual function name for the return value variable. This typically makes for easier-to-read code, and simplifies the process of changing the name of a function. Note that the alias does not take a $ suffix, regardless of whether the function returns a number, string, or structure. For example:
function Fn'Bracket$(arg1 as f6) as s20
.fn = "[" + arg1 + "]" ! equivalent to Fn'Bracket$ = ...
endfunction
History
2018 September, A-Shell 6.5.1647: FN alias introduced
