Please enable JavaScript to view this site.

A-Shell Reference

Parameters used in subroutines and functions are normally passed By Value, which allows ASB to convert between the data types supplied by the caller and those expected by the routine, and vice versa for any parameters passed back. The mechanism is similar to the automatic data type conversion that occurs in assignment statements, where the rvalue is reduced to a string or floating point expression on the stack and then converted to the lvalue type to carry out the assignment. In the parameter passing case, the type conversion involves a matrix of from/to transformations carried out independently from stack.

Overall, this affords the caller considerable—but not unlimited—flexibility in the choice of data types. For example, a subroutine that receives a Centigrade temperature and returns the Fahrenheit equivalent would accept any data type that can represent a number. But unless the type can also accommodate negative and fractional numbers, the accuracy and precision of the result will be compromised. A more extreme case occurs with parameters passed By Reference where the from and to types must match exactly. In an attempt to convey these kinds of requirements in abbreviated form, the subroutine documentation uses the following parameter type names—essentially a superset of Data Types. In all cases, the size of the data type needs to be sufficient for the range of possible values.

Note that for read-only parameters passed by value, you can normally specify a string or numeric expression (of arbitrary complexity) rather than a variable of one of the prescribed data types, as long as the expression result is compatible with the parameter type expected by the subroutine. Actually, variables are only required for return parameters, or for more complex parameter types that can't be represented by an expression value such as arrays, collections, BLOBs, etc.).

Also note that the following table provides brief descriptions while the popups referenced in column one provide, when needed, more details.

Parameter Type

Description and Corresponding Data Type(s)

String

Normally data type S, or possibly X.

Number

Any data type that can represent a number, including string.

Integer

Same range of data types as Number.

Integer - Signed

Same as Integer but excluding the unsigned B types.

Integer - Unsigned

Same as Integer but makes clear that B types are acceptable.

Bitmap

Same as unsigned integer but specifically for values representing collections of bit flags.

Structure

A MAP layout, or preferably, a DEFSTRUCT.

BLOB

A series of raw bytes, typically stored in an X variable.

Array

Several variations. See popup at left and documentation for specific routine.

Collection

ORDMAPs, GRIDMAPs, MLISTs, etc.

<Explicit Data Type>

For parameters passed By Reference (collections, DIMX arrays, some legacy subroutines), the parameter type must precisely match an explicit data type, in which case the routine documentation will specify the data type instead of a more general parameter type.