System Functions


Classification of System Functions

Although they are listed alphabetically by English name in this chapter, for convenient reference, the A+ system functions can be grouped, among many other ways, in ten categories, dealing with:

Querying Syntax

To inquire about the syntax of a system function or external function in an A+ session, enter its name alone on a line. For example:
     _nl
 _nl{any;any} returns any
Because some of the system functions take more than two arguments, they are all shown here in general form, for uniformity, and that is how a syntax query is answered. Nevertheless, infix notation can also, of course, be used to invoke the monadic and dyadic system functions.

Common Error Reports

Multiple errors elicit but one report. If an error report in the following list is issued, then the ones preceding it do not apply. Seven reports are common to all system functions:

Definitions of System Functions

The Name Argument

Several system functions take names as arguments. A name argument is one of the following:

These names always refer to global objects. See "
Symbols and Symbol Constants".

The definition of a system function refers to this section if it has an argument that conforms to this definition.

Abort Loading of Script _abortload{}

   Definition

This system function allows the user to terminate the $loading of a file. Executed in a script, it will terminate that script after the current line is processed. If one script loads a second, and the second script calls _abortload{}, the second script ends immediately, but the first script is not aborted, and continues to be loaded. While the loading of a script is suspended - by an interrupt, error, Stop, or Signal, for example -, entering _abortload{} in the (Emacs or XTerm) session log for execution will terminate its loading, without affecting the suspension.

All Attributes _atts{y;x}

   Argument and Result
The arguments x and y are described in "The Name Argument". The result is a vector of symbols.

   Definition
Lists all attributes set by _set on y with prefix x. E.g., _atts{`a;`appl} lists all attributes of the form `appl.* set on a. If x is Null, lists all attributes set by _set on y. The attributes are listed in random order. If the variable y does not exist, the result is empty. For a list of attributes set by s (which does not currently use _set), i.e., display attributes, use the settings attribute.

All Dependent Object Names _alldep{x}

   Argument and Result
The argument x is described in "The Name Argument". The result is a vector of symbols.

   Definition
The result is the transitive closure of _dep{x} (Dependent Object Names): it returns the dependency set of x, to wit, a list containing _dep{x}, _dep_dep{x}, etc., with duplicates removed.

Note that if f is a dependency and `f is contained in the vector _alldep{`f}, then the dependency set _alldep{`f} is cyclic. See "Cyclic Dependencies".

Association List to Slotfiller _alsf{x}

   Argument and Result
The argument is an association list or a slotfiller. The result is a slotfiller (but see below).

   Definition
This function converts an association list to the equivalent slotfiller. It also accepts slotfillers and returns them unchanged, so that it can be used to obtain a slotfiller from an array that might be either an association list or a slotfiller; no checking is necessary.

An argument that is an association list whose length is odd is accepted in two cases. If the last element is a symbol, a Null is appended before conversion. If the last element is a Null, it is dropped.

In one case the result is not actually a slotfiller: if there are duplicates among the symbols that are to be the elements of the first item of the result, the argument is nevertheless accepted and the duplicates are retained.

   Example
     _alsf(`a;1;`b;2;`c;3 4 5)
< `a `b `c
< < 1
  < 2
  < 3 4 5

Change Directory _cd{x}

   Argument and Result
The argument x is a symbol or character vector. The result is a nested vector with either one or two elements.

   Definition
_cd{x} provides the same function as the $cd command. The argument x specifies the new current directory in Unix format. If the change to the new current directory is successful, the result is 1<`ok; otherwise it is a two-element array of the form (`error;"error message"),  for example if there is no such directory. The PWD environment variable is set.

After a file is loaded, the current directory is the same as it was when the Load function or command was initiated: it is automatically restored if it was changed during execution of the lines of the file.

Comma Fix Input _cfi{y;x}

   Arguments and Result
y is a simple character array of rank less than or equal to two, and x is a scalar restricted whole number. The result is a two-element nested array of the form (bool;data), where #bool equals #data if y is a matrix and equals 1 otherwise, and bool is an integer array of rank 0Ӣ1+y, and data is a numeric array of rank 1y with 1data equal to x0.

   Definition
See "Fix Input" (_fi). The definition of _cfi is the same as Fix Input, except that _cfi permits additional representations (and misrepresentations) of numbers. Specifically, commas and parentheses are permitted in number representations, as well as minus signs, low and the A+ high (). In producing the numeric values, commas are ignored no matter where they appear, and high and low minus signs and each set of enclosing parentheses is replaced by a high minus sign. In other words, commas are not treated as "thousands" separators (although they can be playing that role), and all parentheses and - and are treated as signifiers of negative quantities. For each result number, there can be at most one indication that it is negative: '-16', '(-16)', and the like are not accepted. The parentheses that indicate a number is negative must surround the entire number, those that indicate an exponent (in e-notation) is negative just the exponent itself. A left parenthesis may be followed by blanks.  Note: blanks between numbers are not required, although their absence is obviously inadvisable;  in other words, missing blanks are not used as an indication of possible error any more than missing or extraneous commas are'1e-3.5-7.6.5' is translated as 1e-3 0.5 7.6 0.5.

Scalar Comma Fix Input, _scfi, is expected to be used in `in functions, validating user input. _cfi, on the other hand, is designed for larger arrays, such as text files; the assumption is that the data argument is likely to have been machine generated.

   Additional Error Reports
   Example
     _cfi{'(1,200)';1}
<  1
<  1200.

Debug _dbg{x}

   Argument and Result
This function takes essentially the same arguments as $dbg and returns essentially the results displayed by it.
   Definition
Provides the functionality of $dbg with different syntax: e.g., _dbg{`cxt;(`only;`)} to trace only the root context. Additionally:

(1) _dbg{`display;`beam} returns a slotfiller with information about all files currently beamed in. The six fields of the slot filler contain entries for each file:
`mode - 0, 1, or 2: the file is copy-on-write, read/write, or local write.
`arg - the righthand argument given to .
`fname - the actual file name `arg was turned into.
`addr - the memory address where the file was mapped.
`refcnt - reference count: how many A-objects point to the file.
`bytes - the size of the file in bytes.

(2) _dbg allows for callbacks at the points where a tracing or tracking message would be displayed. Executing _dbg{`cb;(fn;cd)} sets up the callback function with its client data (static). This function must take five arguments: fn{cd;event;arg1;arg2;arg3}. The events are `func, `xfs, `sfs, `load, `beam, and so on; arg1 is the name of the function, file, or whatever involved; the possible values of arg2 are `enter, `exit, `abort, `in, `out, `unmap, `dep, `func, and how many Infs and how many NaNs; and arg3 is usually null, but for beaming in it is the left argument of .

(3) In the event callback for `inv events, the second argument is null for normal invalidation, and equals `cycle if the `inv event is the detection of a cyclic dependency.

Dependency Definition _def{x}

   Argument and Result
The argument x is described in "The Name Argument". The result is a character vector.

   Definition
The result holds the definition of the dependency named in x. See "Dependencies". If x does not name a dependency, the result is Null.

Dependent Object Names _dep{x}

   Argument and Result
The argument x is described in "The Name Argument". The result is a vector of symbols.

   Definition
The result contains the names of all dependencies whose definitions explicitly reference the object named in x. See "Dependencies".

Dynamic Load _dyld{x;y}

   Arguments and Result
The argument x is a character vector and the argument y is a nested vector. The result is a scalar integer.

   Definition
The effect of this system function is to load C functions into A+ so that they can be used like ordinary user functions. (But the fixed number of arguments for a C function being _dylded cannot exceed 8.) The details can be found in "Calling C Subroutines from A+". System error messages are also displayed. If this function is not available, the Dynamic Environment system variable, `dyme, has the value -1. It is safe to _dyld an object already _dylded.

Warning!  A cover function that takes care of the requirements of different architectures should be used rather than a direct invocation of _dyld, except when "hacking".

Warning! If the A+ name used in _dyld (in its right argument) begins with an underscore, then the function will be installed in the root context, no matter what the current context, and it will be listed by $sfs but not by $xfs.

Execution Profile _profile{x}

   Argument and Result
A meaningful argument is a scalar symbol, one of `on `off `report `reset. If the argument does not cause an error - i.e., if it is a one-element array - then the explicit result is the scalar integer 0.

   Definition
This facility is enabled by executing _profile `on and disabled by _profile `off.  When not enabled, it adds absolutely no overhead to primitive function calls.

When it is enabled, executing _profile `report causes a report to be displayed that gives the number of primitive function executions by function, data type, and array size range (number of elements) since the last time _profile `on or _profile `reset was executed.

Exit _exit{x}

   Argument and Result
The argument x is a scalar integer. There is no result.
   Definition
The expression _exit{x} provides a similar function to the system command $off. The argument x is the value returned when the A+ process terminates. Proper values for x are 0 through 255, although any integer is accepted; by convention, the value 0 means success. Since execution of this system function causes the A+ process to exit, it has no meaningful result. See "Invoking A+".

Expunge _ex{x}

   Argument and Result
The argument x is described in "The Name Argument". The result is an integer scalar.

   Definition
_ex provides the same function as $ex. The object named in x is removed and its associated memory is freed. The result is 0 if the removal is successful, and 1 otherwise. In particular, the result is 1 if the object does not exist. It is also 1 if x is an object bound to a display class (see "is" and "free"); i.e., a bound object cannot be expunged.

Expunge Context _excxt{x}

   Argument and Result
The argument x is described in "The Name Argument". The result is an integer scalar.

   Definition
The context named in x must be empty. If it is, _excxt{x} removes it from the active workspace and returns 0. If the context is not empty, _excxt returns 1. The Name List system function with arguments x and `globs can be used to list all objects that would prevent the expunging of a context. See the "Name List" (_nl{y;x}) function. See also "Expunge Context" ($excxt).

The root context cannot be expunged; an attempt to expunge it yields a result of 1. For a nonexistent context, the result is 1.

Fix Input _fi{y;x}

   Arguments and Result
y is a simple character array of rank less than or equal to two, and x is a scalar restricted whole number. The result is a two-element nested array of the form (bool;data), where #bool equals #data if y is a matrix and equals 1 otherwise, and bool is an integer array of rank 0Ӣ1+y, and data is a numeric array of rank 1y with 1data equal to x0.

   Definition
This function creates a numeric array with x0 elements derived from each row of y (or from y itself, if it is a scalar or vector). If a valid vector is created for the row i#y, it becomes i#data, and i#bool is assigned 1. If i#y does not contain the representations of exactly x0 numbers, then i#bool is assigned 0, and i#data is created by using the first x0 valid nonblank sequences in i#y, and using zeros as fillers if there are not enough valid nonblank sequences. (The term nonblank suggests how you should use the function, with blanks as separators, but see the note with which this definition ends.) If there is a nonblank sequence in i#y that does not represent a number, then i#data contains zeros from the point of invalidity on.

Each row of the argument y for which a valid numeric vector can be created must consist of x common representations of numbers. A common representation is one of the three general forms produced by the Default Format monadic primitive function , namely integer, fixed-point, and exponential, except that low and high minuses are accepted indifferently: a low minus is accepted at the beginning of any number and in exponential form a high minus is accepted in the exponent. The expression

     bool/#y
yields the row indices of y for which a valid numeric vector was created. Note: blanks between numbers are not required. 1e-3.5 7.6.5-2 is translated as 1e-3 0.5 7.6 0.5 2.
   Additional Error Reports
   Examples
     a3 5'1.34 2 3  2x50 '
1.34
2 3
2x50
     a _fi 1
< 1 0 0
<  1.34
   2
   2
     a _fi 2
< 0 1 0
<  1.34 0
   2    3
   2    0

Flatten _flat{x}

   Argument and Result
The argument x is any array whose simple components are of one type, except that symbols and functions may be mixed and nulls are essentially ignored. The result is a simple vector whose length is the total number of elements in all the simple components of x and whose type is that of the first nonempty simple component of x, if x is not empty.

   Definition
The simple components of x are all those simple objects obtainable by repeated selection and disclosure. If they are all empty, the result is an empty vector whose type is that of the nonnull ones; if they are all null, the result is the Null. If x is simple, the result is the ravel of x. Otherwise, the result is the catenation of the ravels of all the simple components of x.

   Additional Error Report
   Examples
    _flat (3 5;23 34 42;0;0;;<<(<1 2),<1 27 8)
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 23 34 42 0 1 2 7 8
    _flat `a,<2 2`b`c`d`e
 `a `b `c `d `e
    (`a,<{+})_flat(`a;+)
1

Format _fmt{y;x}

   Arguments and Result
y is a character vector or scalar, and x is a simple character or numeric array or a nested array. The result is a simple character array of rank less than or equal to 2.
   Definition
The function _fmt transforms character and numeric data in x into a character table according to specification y, which consist of a series of format phrases - see the "Format Phrases" table - separated by commas. For example, the string 'i6,f8.2,f6.1' contains three phrases. Each phrase governs the appearance of a column in the result. The number of phrases need not match the number of items in x, the phrases being repeated cyclically as needed; furthermore, tab and constant specifications are in separate phrases.

Each phrase has a type, indicated by a letter, such as the letters i and f in the above example. A tab or constant field in y does not correspond to anything in x. A tab field merely contributes to the positioning of the next part of the output, and a constant field is reproduced in the output exactly as shown.

Within each format phrase, to the left of the letter that identifies its type, qualifiers or decorators may be inserted. A qualifier provides additional rules, such as "insert commas between triplets of digits" or "leave this field blank for zero". See the "Qualifiers" table. A decorator is a code letter immediately followed by a piece of text enclosed in angle brackets or whatnot; the text is to be attached to the representation of a number, usually to indicate its sign. See the "Decorators" table.

When rounding is required, IEEE rules are used: see "Format". When a number cannot be formatted in the specified manner, its field is filled with asterisks. A field whose format is valid but for a different type from the data is filled with question marks. In particular, symbols in x do not cause an error message, but the field in which a symbol is to be formatted is filled with question marks.

Normally, x is a matrix, and the application of the formatting phrases is straightforward. It can be of other ranks and of any depth, however. In that case, the columns to be formatted are obtained, conceptually, by the following process. When a nested array is encountered, it is ravelled, and its elements are successively disclosed and treated in the manner being described. When a simple array is encountered, it is transformed into a matrix if it is not already one: a scalar becomes a 1 by 1 matrix, an n-element vector becomes an n by 1 matrix, and any other array a is reshaped as ((/1a),1a)a.  This produces a series of matrices, and thus a series of columns, to which the formatting phrases are applied as stated above. Each formatted column can be viewed as a character matrix; the result has the same number of rows as the one with the most rows. Conceptually, blank rows are appended as necessary to each of these matrices to make them the same length as the result, and they are catenated side by side (,@0) to form the result.

In the "Format Phrases" table, j is an optional repetition factor; q represents an optional qualifier and decorators; w is field width; d denotes significant digits or decimal digits; p is displacement; a, e, f, i, t, and x are literals giving phrase types.

Format Phrases
PhraseApplicationDescription
jaw Character Display each character in a field w positions wide. A w greater than 1 produces blanks between adjacent characters.
jqew.d Exponential Display each number in a field w positions wide, with d significant digits. Align E's and decimal points in fields that are not left justified.
jqfw.d Fixed point Display in a field w positions wide, with d decimal digits, including trailing zeros. Leading zeros are shown as blanks unless the z qualifier is used.
jqiwInteger Display in a field w positions wide. Leading zeros are shown as blanks unless the z qualifier is used.
jqg<txt> Picture Format, rounding arguments to integers In txt, 9 and z are "special characters"; the rest are "ordinary." Round each number to an integer, after scaling if k is present. If s is present, modify txt as required. Then format each number with as many digits as there are special characters in txt, so each digit corresponds to a special character. Display a digit corresponding to a 9 unconditionally. If a digit corresponding to a z is in a sequence of leading or trailing zeros, display a blank; otherwise, display the digit. Display ordinary characters as is, with one exception, intended to exclude superfluous thousands separators but include decimal points: any ordinary character surrounded by special characters is displayed as blank if in the display a blank is next to it, unless it is the last ordinary character and is followed by at most two characters. The only valid decorators and qualifiers are m and p (but only the first character of the text of each), s, and k.
jtpAbsolute tab Start the next field at position p+1. If p is too small, the next field may overwrite earlier ones.
jxpRelative tab Start the next field at a position displaced p positions from the end of the preceding field. If p is negative, the next field may overwrite earlier ones.
<text>Constant: for all Insert text in every row of the result.

Qualifiers
QualifierSummaryDescription
bblanks Make the entire field blank when the value is zero.
ccommas Insert commas between successive triplets of digits in integer and (before the decimal point) fixed-point fields.
kescale Scale the result by displaying a value that is 10e times the value.
ljustify Left justify. The default is right justification.
zzeros Display leading zeroes in integer and fixed-point fields.

In the "Decorators" table, text may also be delimited by , , , //, , .

Decorators
DecoratorSummaryDescription
m<text>Negative-Left Insert text to the left of a negative value, not APL high minus. text can be empty. m and n can be used together.
n<text>Negative-Right Insert text to the right of a negative value rather than use APL high minus. text can be empty. m and n can be used together.
o<text>Zero replacement When the data as formatted is zero, replace the result by text. Valid for the e, f, and i phrase types.
p<text>Positive-Left Insert text to the left of a positive value. p and q can be used together.
q<text>Positive-Right Insert text to the right of a positive value. p and q can be used together.
r<text>Background Fill the field cyclically with text where normally blanks would appear, including blanks from a b qualifier. For e, f, and i phrase types.
s<text>Symbol Substitution For each pair of characters in text, the second indicates a character to replace the first. In e, f, and i phrase types, punctuation, sign, and error characters in the result can be replaced; in a g phrase type, any characters in the picture text and error characters in the result can be replaced; no other replacements can be made. For example, s<,..,> in an f phrase type produces periods where commas usually appear and commas where periods usually appear.

   Examples
     'e9.4' _fmt 200 .987
 2.000E 2                Internal blank used to align decimal points and E's.
 9.870E1


     n123456789 0 123456789 123456
     'bcm<->k-2f13.2' _fmt n
 1,234,567.89

-1,234,567.89
     1,234.56


     'm<(> n<)> q< > b c k-2 f16.2' _fmt n
   1,234,567.89                 Blanks are okay in the left argument.

  (1,234,567.89)
       1,234.56


     'i 6' _fmt `wrong `type
??????
??????


     'g<99:99:99>' _fmt 10033sys.ts{}
07:19:30


     'g<zz9>' _fmt .49 .51 99.47
  0
  1
 99


     rfnd 1.23 10.00 12345.67 332 1234.56
     'k2 g<Your refund is: $z,zz9.99>' _fmt rfnd
Your refund is: $    1.23  k2 applied to 1.23 is 123, and the
Your refund is: $   10.00  decimal point in 1.23 is from g.
*************************  12,345.67 is too long; if we had s<*?>
Your refund is: $  332.00  in the left arg, *...* would be ?...?.
Your refund is: $1,234.56  The comma is needed here, and it appears.


     'k2 g<Your refund is: $z,zz9.zz>' _fmt 1.23 10.00
Your refund is: $    1.23
Your refund is: $   10.    The decimal point is the last ordinary
                           character and it has only two characters
                           after it,so it's shown even when the
                           trailing zeros are dropped.

     's<9#z$>g<$$$# units of product z9>' _fmt 73
  73 units of product z9   s allows 9 and z to be included literally
                           in the output.

General Search and Replace _gsr{y;x;r;n}

   Arguments and Result
y, x, r, and n are all simple character arrays, normally vectors, except that r and n can also be null. The result is either a simple character array or an integer vector or matrix.

   Definition
If x, r, or n is not a vector, its ravel is used. There are eight cases, as determined by n and r:
   Examples
Name delimiters are okay within target and replacement:
     _gsr{'IO1';'IO';'IO';''}
IO1

     _gsr{'IO1,IO2,BIO3';'IO';'IO';''}
IO1,IO2,BIO3

     _gsr{'IO1,IO2,BIO3';'IO';'IO';''}
IO1,IO2,BIO3


     _gsr{'Mississippi is';'is';'IS';''}
Mississippi IS

     _gsr{'Mississippi is';'is';'IS';}
MISsISsippi IS

Get Attribute _get{y;x}

   Argument and Result
The arguments x and y are described in "The Name Argument". The result is an array.

   Definition
If _set{y;(x;z)} (Set Attribute) has been executed previously, then the result of this function is z, the value for attribute x on variable y. Otherwise, the result is Null, including the case when y does not exist.

Get Callback _gcb{y}

   Argument and Result
The argument y is described in "The Name Argument". The result is a two-element nested array.

   Definition
If _scb{y;x} (Set Callback) has been executed previously, then the value of _gcb{y} is the value of x in the last such setting: function scalar, static data. Although the name displayed for the callback function may now have a new reference, 0_gcb{y} gives the definition of the callback function. Otherwise the value is Null.

Get Client Data _gcd{y}

   Argument and Result
The argument y is described in "The Name Argument". The result is an array.

   Definition
This function is like _get (Get Attribute), but for an implicit, unnamed attribute. It gets the value that was set by the last execution of _scd{y} (Set Client Data); if none was set, it returns the Null. It has been superseded by Get Attribute and is retained only for compatibility.

Get Format Symbols _gfmtsym{}

   Result
The result is a vector of symbols.

   Definition
This function lists the symbols acceptable as values for the out attribute. See the "out Attribute Format Samples" table.

Get Preset Callback _gpcb{y}

   Argument and Result
The argument y is described in "The Name Argument". The result is a two-element nested array.

   Definition
If _spcb{y;x} (Set Preset Callback) has been executed previously, then the value of _gpcb{y} is the value of x in the last such setting: function scalar, static data. Although the name displayed for the preset callback function may now have a new reference, you can obtain the definition of the preset callback function by entering 0_gpcb{y}.

Otherwise the value is Null.

Get System Variable _gsv{x}

   Argument
The argument x is a symbol scalar or a quoted string naming a system variable whose value the user is allowed to access. The result is the value of that system variable.

   Definition
The value is the current value of the system variable named in x. A domain error is reported if x does not name a system variable or access to the system variable named in x is forbidden, as it is for `rl. See "System Variables" for descriptions of the system variables and their values and interdictions.

   Additional Error Report

Hash Table Statistics _hashstat{x}

   Argument and Result
The argument is Null or a symbol naming a context. The result is an integer vector.

   Definition
The result gives the number of entries in each bucket of a hash table. If the argument is Null, the statistics are for the symbol table and the result length is 1024. If the argument names a context, the statistics are for the hash table for that context and the result length is 512. The function +/ applied to the result indicates the number of names that have ever been defined, while / gives a rough indication of collisions and hence possibly reduced execution speed (although for this purpose the whole vector should be examined for clumping).

Index of _index_of{y;x}

   Arguments and Result
y and x must be nested vectors of the same length. For each of them, its elements must all be nested vectors of the same length, or all be enclosed scalars. For y, a scalar is treated as a one-element vector. The result is a simple integer vector or scalar whose shape is the same as an element of x.

   Definition
Call y's contained vectors y1...yn and x's contained vectors x1...xn. The result r is an integer vector of length x1; r[i] is the least j for which xk[i] is equal to yk[j] for all k; if there is no such j, then r[i] is y1. This function is a high performance version of the expression (>yɡy)>yɡx.

Regarding the arguments as matrices whose columns are the contained vectors, so that the matrices have the same number of columns, _index_of yields a vector that gives, for each row of the right argument, the index of the first row of the left argument that it matches; for any row of the right argument that does not have a matching row in the left argument, the corresponding element of the result is the number of rows in the left argument, i.e., the common length of its contained vectors.

   Example
Consider a tiny table with three fields: styles, colors, and prices. The style and color fields can be used as key fields with _index_of to find row indices of the table, and these can be used with Pick to give prices:
   Inventory(("Oxford";"Oxford";"Loafer";"Loafer");
*             ("Brown"; "Tan";   "Black"; "Brown" );
*             (128.98;  175.98;  112.50;  112.50))
   (Inventory[0 1]_index_of(<"Oxford";<"Tan"))2Inventory
 175.98
   Additional Error Reports

Is a Slotfiller _issf{x}

   Argument and Result
x is any array. The result is a scalar boolean integer.

   Definition
If x is a slotfiller, the result is 1. Otherwise the result is 0, e.g., if there are repetitions among the items of 0x.

Items of a Mapped File _items{y;x}

   Arguments and Result
The argument y is a one-element numeric array whose element is a restricted whole number, while the argument x is a symbol or character scalar or character vector. The result is a scalar integer.

   Definition
The argument x holds the name of a mapped file (see "Mapped Files"). A mapped file can be processed within A+ as if it were an ordinary array. In particular, it makes sense to speak of the items of a mapped file. If y is -1, the result is the number of currently allocated items. If y is nonnegative and less than the current number of items, then the effect is to truncate the file. Otherwise, if y is nonnegative the effect of this function is to allocate space (if necessary) on the end of the file so that the file can hold y items. See "Work Area" (_wa) regarding units of storage allocation. The result is the current number of items before the new allocation. See "Examples", and note that the "Operation would block" message and the delay caused by trying to avoid that message can occur for _items.

When a file is written out as a mapped file, the file is made only large enough to hold the actual data.

After a file length is changed by _items, any variables that were associated with it (by Map or Map In) must be remapped (by a new application of Map or Map In), because _items has rewritten the file.

Load _load{x}

   Argument and Result
The argument x is a symbol scalar or a character vector. The result is a two-element nested array.

   Definition
The expression _load{x} provides the same function as $load x (Load command). The argument x names the A+ script file to be loaded. The result is (`ok;file) if the file is found and can be read, where file is a character vector giving the fully qualified name of the file that is loaded, i.e., path/filename. After a file is loaded, the current context and the current directory are the same as they were when the Load function was invoked: each is automatically restored if it was changed during execution of the lines of the file.

If the file is not found the result has the form (`error;"error message"). Note that a result (`ok;file does not mean that the file was loaded without error, just that it was found and can be read.

   Example
     _load 's'
< `ok
< /usr/local/lib/s.+

Load and Remove _loadrm{`delete;x}

   Argument and Result
The right argument x is a symbol scalar or a character vector. The result is a two-element nested array.

   Definition
_loadrm{`delete;x} provides the same function as $loadrm x (Load and Remove command).  The argument x holds the name of the file to be loaded. The file is loaded and then deleted (this is a special function for the Emacs environment). The result is the same as that of _load. The left argument must be `delete or 'delete' or an error message is issued.

Locals _locals{x}

   Argument and Result
x is a symbol, function expression, or function scalar representing a defined or external function; it cannot be a primitive or derived function. The result is a three-element nested array.

   Definition
The first element of the result is the name of the function, as a symbol. If x represents a defined function, the second element is a vector of the names of the arguments to the function and the third element lists its local variables. If x represents an external function, the second element is an integer vector of its argument types (see table in "Calling C Subroutines from A+"), and the third element is null.

Name _name{x}

   Argument and Result
The argument x is a function scalar. The result is a scalar symbol.

   Definition
x is of the form <{fn},  where fn is a defined, primitive, or system function. For a defined function, the only case that really makes sense, the result holds the fully qualified name of fn, i.e., the name of the current context, which will be empty for the root context, followed by a dot as separator, followed by fn. If fn is a system or primitive function, the result is just fn preceded by a backquote.

The expression _name<{&},  either inside the definition of a function fn or entered when a defined function fn is suspended, will produce the fully qualified name of fn.

If in context cx you enter, literally, _name<{f},  you will get either the uninteresting result `cx.f or a value error: the only unqualified name you can use in the argument is one defined in the current context. A more useful case is when you have an expression that yields a function that may or may not be in the current context, an expression that uses _gcb or of or the like.

   Additional Error Report
   Example
     $cx sys
     _name <{import}
 `sys.import

Name Class _nc{y;x}

   Arguments and Result
Both arguments and the result are symbol scalars; y can also be Null.

   Definition
If the symbol x holds an unqualified user name, i.e., a name without an explicit reference to its context, and if the symbol y holds a context name, the result is the symbol form of the name class of the user name x, in the context y (see the "Name Classes" table). If x holds a fully qualified name of the form cxt.nm,  the result refers to nm in the context cxt, and the value of y is ignored.

The root context is denoted by the empty symbol (`). The current context is denoted by Null: if _nc is referenced in the form _nc{;x}, the current context is assumed.

Name Classes
Name ClassDescription
`varsUser variables
`fnsDefined functions
`xfsExternal functions
`globsGlobal objects
`depsDependencies
`opsDefined operators
`nullNot in use, not a valid name, or not one of the above

Name List _nl{y;x}

   Arguments and Result
Both y and x are symbols, except that x can be and y can be Null. The result is a vector of symbols.
   Definition
The result is a vector of symbols holding the names of objects of class x (see the "Name Classes" table) in the context identified by y. The empty symbol (`) denotes the root context, and Null denotes the current context. Dependencies are listed only when they have saved values, which need not be valid. See the table "Name List Expressions vs. The Kind of Objects in the Result" for examples of these and other uses of Name List. For the arguments `apl `ascii, and `uni, the order of the symbols is consistent between them (the symbols in the same positions representing the same primitive) within the same version of A+, but the order may change from version to version, and new functions may cause insertion of symbols; any such changes will not be considered upwardly incompatible.
Name List Expressions vs. The Kind of Objects in the Result
Expression (see Note below) Kind of Object Named in the Result
_nl{`ctx;`vars}Variables in the context `ctx
_nl{`ctx;`fns}Functions in the context `ctx
_nl{`ctx;`deps}Dependencies in the context `ctx
_nl{`ctx;`ops}Operators in the context `ctx
_nl{`ctx;`globs} Global objects in the context `ctx
_nl{`ctx;`xfs} External functions in the context `ctx
_nl{`;`cxs}Contexts
_nl{`;`svs}System variables
_nl{`;`sfs}System functions
_nl{`;`cmds}System commands
_nl{`;`apl}All keywords and primitive symbols in APL mode
_nl{`;`ascii}All keywords and primitive symbols in ASCII mode
_nl{`;`uni}All keywords and primitive symbols in UNI mode
_nl{`;`circle} or
_nl{;}
List of symbolic left arguments for Circle function. (Although ` _nl `circle works fine, the parser is confused by ` _nl .  Left arg can be null, with correct result in any current context.)
_nl{`;`errors}Names (as symbols) of errors defined in A+
_nl{`;`nl}Valid right arguments to _nl
_nl{`;`wa}Valid symbol arguments to _wa

Note:

Name Search _ns{y;x}

   Arguments and Result
Both y and x are character arrays, normally vectors. The result is an integer vector or matrix.

   Definition
If x is not a vector, its ravel is used. If y is a vector, the result is a vector of indices of nonoverlapping namelike occurrences of the vector x in y. Each index marks the beginning of an occurrence in y. An empty result signifies that there are no occurrences. A namelike occurrence is one that satisfies the following restrictions:

If y is a matrix or higher-rank array, then an occurrence is required to be entirely on one line; occurrences spanning rows are not accepted. (An unbalanced quotation mark, perhaps intended as an apostrophe, will block name recognition in later lines, however.) The result is an r by n matrix, where r is the rank of y and n is the number of occurrences found. A column of the result gives the indices of the corresponding occurrence, with the highest-order index at the top and the column index at the bottom. Thus 0# applied to the result gives a list of the items in which occurrences were found.
   Examples
      _ns{'This is ''is''';'is'}
 5
     4 3'abc abc  abc'
abc
 ab
c
abc
     _ns{4 3'abc abc  abc';'abc'}
 0 3
 0 0

Name Search and Replace _nsr{y;x;r}

   Arguments and Result
y, x, r, and the result are all character arrays, normally vectors.

   Definition
If x or r is not a vector, its ravel is used. Occurrences of x are sought in exactly the same way as they are in Name Search, _ns{y;x}, but in two different objects, depending upon y, x, and r: See also the examples in "String Search and Replace".
   Example
     _nsr{'This is ''is''';'is';'are'}
This are 'is'

NaN Find _nanfind{x}

   Argument and Result
The argument is any array. The result is an integer vector.

   Definition
If the type of x is floating point (so x is simple), then the result is a vector consisting of the indices of those elements of the ravel of x that are NaN's. Otherwise the result is 0.

NaN's are used in some systems to represent indeterminate numbers. They are like Infs, but more general. This function can be used to locate NaN's occurring in loaded files or resulting from dynamically loaded code. The nan subcommand of the $dbg command can be used to screen files being beamed in for NaN's. (NaN's are not generated by A+ primitive functions.)

Permissive Indexing _index{i;x;d}

   Arguments and Result
i is a simple array of restricted whole numbers, x is any array, and d conforms to the items of x, i.e., its general type is the same as theirs, and either it is a scalar or its shape is the same as theirs.

   Definition
This function is like i#x, with three exceptions: (1) Only a simple i is allowed, so only items of x are chosen. (2) If i is Null, the result is no items of x, not all items of x. (3) If an element of i is out of range, no index error is reported; instead, d is placed in the corresponding position in the result, replicated if necessary so that it matches the items of x.
   Examples
     _index{2 19 14 1;
        ('Mar 06';'Jul 18';'May 15';'Nov 26');<'n.a.'}
< May 15
< n.a.
< n.a.
< Jul 18

     _index{10 11;11 4;1}
 40 41 42 43
 1 1 1 1

Remove Dependency Definition _undef{name}

   Argument and Result
The argument name is described in "The Name Argument". The result is a boolean integer.

   Definition
The function removes the dependency definition for name, if any, and leaves everything else, such as value and callback function, unchanged. After this function is executed, name is an ordinary, not a dependent, variable. It may not have a value, since Remove Dependency Definition does not cause an evaluation. You may sometimes want to force an evaluation before invoking this function. The result is 0 if a definition was removed, and 1 otherwise - name does not name a dependency. Cf. "Remove Dependency Definition" ($undef).

Scalar Comma Fix Input _scfi{s}

   Argument and Result
The argument s is a character array, normally a vector, and the result is a numeric scalar.

   Definition
This function is like Comma Fix Input (_cfi), except that:  it handles only a single number (so there must be no internal blanks);  it has a simple scalar result;  it has no boolean part to its result, an invalidity being reported as an error instead;  and it treats commas properly, requiring that they be internal to the integer portion of the number, properly placed every three digits leftward from the decimal point (or right end, if there is no decimal point), and that there be either no commas or the full set.  I.e., if s is a valid argument for _scfi, _scfi{s} is exactly equivalent to ''1_cfi{s;1}.

   Additional Error Report

Scalar Fix Input _sfi{s}

   Argument and Result
The argument s is a character array, normally a vector, and the result is a numeric scalar.

   Definition
This function is like Fix Input (_fi), except that it handles only a single number, has a scalar result, and has no boolean part to its result, an invalidity being reported as an error instead. I.e., if s is a valid argument, _sfi{s} is exactly equivalent to ''1_fi{s;1}.

   Additional Error Report

Screen Format _sfmt{f;d}

   Arguments and Result
The left argument is a format specification, either one shown in the "out Attribute Format Samples" table, or one acceptable as a left argument for _fmt (Format), or (Format). The right argument is a simple numeric scalar. The result is a character vector.

   Definition
If the left argument is a symbol, then it and the result are as described in the "out Attribute Format Samples" table. If the left argument is character, then it and the result are as described for _fmt (Format). Otherwise, the left argument is numeric and the result is as described for (Format).

Formats containing y2 are restricted to the years 1950 through 2049, errors in dates return 0's except that an erroneous `y2 is set to "**", and the length of the result returned for a bad date is the same as for a good date.

Warning! If the right argument is numeric but nonscalar, only the first element is used.

Set Attribute _set{y;x}

   Argument and Result
The argument x is a nested vector (w;z),  where z is any array. Both w and the argument y are described in "The Name Argument". The result is a scalar integer.

   Definition
Sets the value for attribute w on global variable y to the value z. If z is Null the attribute is removed. The result is 1 if the value was not previously set or the attribute was removed or y does not exist, and 0 otherwise. The attribute w, which is commonly a name, can be whatever you want; it simply allows you to associate data with y in an easily retrievable way.

Set Callback _scb{y;x}

   Arguments and Result
The argument y is described in "The Name Argument". The argument x is a two-element nested array. The result is Null.

   Definition
The argument x is a pair of the form (f;s),  where s is any array and f is a function expression. Thus the first element of x is a function scalar and not the name of a function, so this assignment is unaffected by any later changes to the meaning of the name of the function f. Executing _scb{y;x} causes the "callback" function f to be called each time the value of the global variable (or, indeed, function) named in y is modified through certain assignments, after the modification has been made. The array s is known as the static data, and is passed as a parameter to f on every call that results from an assignment to the global variable named in y.

If s is omitted the static data is Null. If f is omitted then any callback previously established for the global variable named in y is removed.

The general form of the syntax of f is
f{s;d;i;p;c;v} where

s is the static data
d is the new value
i is an index, nested if for y and simple if for ,y
p is a path
c is a symbol naming the context in which y is defined, and
v is `y
such that

  (i#pc%v)d  if i is nested
  (i#,pc%v)d if i is simple
     or
  (pc%v)[,]d if i is out of range for c%v before this assignment

describes the change that caused f to be called.

A callback function can have any number of arguments from to zero to six, but the meaning of the arguments is always as above, reading from the left. For example, if it has three arguments then the first is static data, the second is new data, and the third is an index. Any explicit result of a callback function is ignored by A+.

Dependencies are global variables, and callbacks can be set on them. However, such a callback function is called only when the dependent variable is explicitly specified using ordinary or selective assignment, and in the latter case only as described above. A callback does not occur when a dependency is marked for evaluation, or when an evaluation occurs (although a preset callback is called in this latter case). Furthermore, during a callback on a dependency, the dependency's value is not marked invalid by any change the function makes in a variable on which it depends. (Cf. "Set Preset Callback".)

Only one callback can be set on a global variable. For example, if _scb{`a;(fn;)} is executed, and then _scb{`a;(gn;)},  the first callback function fn is removed when the second one gn is established. Since it is the callback function itself, and not a name, that is given to _scb, if you redefine the function and want the new definition to apply to the callback, you must call _scb again to set it.

For examples and more detail, see "Callback Functions".

Set Client Data _scd{y;x}

   Arguments and Result
The argument x is any array. The argument y is described in "The Name Argument". The result is an array.

   Definition
This function is like _set (Set Attribute), except that there is no explicit, named attribute and the result is the previous client data, i.e., what the result of _gcd{y}, Get Client Data, would be if it were executed immediately before _scd{y}. This function has been superseded by Set Attribute and is retained only for compatibility.

Set Preset Callback _spcb{y;x}

   Arguments and Result
The argument y is described in "The Name Argument". The argument x is a two-element nested array, as described for Set Callback. The result is Null.

   Definition
The differences between callback functions established by _spcb and _scb are: Since preset callbacks are used for validating new values of global variables, the following rules should be followed in their definitions:

For examples and more detail, see "Callback Functions".

Set System Variable _ssv{y;x}

   Arguments and Result
The argument y is a symbol scalar or a quoted string. The result is always Null.

   Definition
This function sets the value of the system variable named in y to the value of the right argument x. A domain error is reported or a correction made (e.g., 100x for `pp) if the right argument is not a valid value of the system variable named in y or if that system variable is not allowed to be set. See "System Variables" for descriptions of the various system variables and their values and interdictions.

   Additional Error Report

Stack Information _doErrorStack{}

Returns the stack information for the last error that occurred under a Protected Execute while `doErrorStack was enabled (1).

This facility should enable developers to mail error information without having to exit the application.

String Search _ss{y;x}

   Arguments and Result
Both y and x are character arrays, normally vectors. The result is an integer vector or matrix.

   Definition
If x is not a vector, its ravel is used. If y is a vector, the result is a vector of indices of nonoverlapping occurrences of x in y. Each index marks the beginning of an occurrence.

If y is a matrix or higher-rank array, then an occurrence is required to be entirely on one line; occurrences spanning rows are not accepted. The result is an r by n matrix, where r is the rank of y and n is the number of occurrences found. A column of the result gives the indices of the corresponding occurrence, with the highest-order index at the top and the column index at the bottom. Applying 0# to the result gives the indices of the items in which occurrences were found. See also the examples for Name Search.

   Examples
     _ss{'Mississippi';'is'}
 1 4
     _ss{'Mississippi';'issi'}
 1      The instances must be nonoverlapping.

String Search and Replace _ssr{y;x;r}

   Arguments and Result
y, x, r and the result are all character arrays, normally vectors.
   Definition
If x or r is not a vector, its ravel is used. Occurrences of x are sought in exactly the same way as they are in String Search, _ss{y;x}, but in two different objects, depending upon y, x, and r:
Examples
     _ssr{'Mississippi';'is';'IS'}
MISsISsippi
     3 6'abc abc defgh abcd'
abc ab
c defg
h abcd
     _ssr{3 6'abc abc defgh abcd';'abc';'xyz'}
xyz ab
c defg
h xyzd
     _ssr{3 6'abc abc defgh abcd';'abc';'wxyz'}
wxyz wxyz defgh wxyzd

Valence _valence{x}

   Argument and Result
The argument x is either the name of a defined or external function, as described in "The Name Argument", or a function expression or scalar holding a defined, external, or system function. The result is an integer scalar.

   Definition
The result is the number of arguments taken by the function specified in the argument x.

   Additional Error Reports

Work Area _wa{x}

   Argument and Result
The argument x is a symbol or integer scalar.

   Definition
The expression _wa n,  for n greater than or equal to 1, increases the workspace size by approximately n megabytes; see the first table entry regarding IBM machines. Other values of the argument x will produce information about the amount of available storage in the workspace, as well as the amount and distribution of storage in use, and in one case cause the areas of unused storage to be coalesced. See the "_wa Arguments and Results" table.

Memory allocation for A+ objects is based on an increasing set of integers called fragment sizes. The storage area for a particular object will be a fragment of sufficiently large fragment size to hold the object, but perhaps with extra, unused room. (It always uses a fragment of smallest possible size. Fragments can be split off larger ones as needed.) As noted in "_wa Arguments and Results", _wa can be employed to find out how many fragments of each size are currently in use.

_wa Arguments and Results
ArgumentEffect and Result
n,  for n1 The effect is to increase the workspace size, `size,  by n megabytes (a megabyte is 220 bytes). The effect of giving a noninteger argument is undefined. The result is 0 if successful.

On IBM machines, the workspace size cannot be increased when a mapped file exists for an A+ process, because A+ requires that the entire workspace be contiguous and AIX requires that all space be taken from one end of the address space; thus, the mapped file blocks enlargement of the workspace.

`fragsizes The result is a vector of integers of fragment sizes, in words. This vector is fixed for every A+ session, but may vary with the release number and the machine on which you are running.
`fragcounts or 0 The result is a vector of integers giving the number of free, or available, storage fragments of each fragment size. (Note that these numbers are computed after the argument to _wa is allocated.)
`coalesce or 1 The effect is to combine contiguous free fragments into larger fragments. The result is a vector of the new fragment counts. If there is no writable /var/atmp (see the -m invocation flag, below) nothing is done and the result is all zeros.
`size The result is the workspace size, i.e., its current maximum permitted size, in bytes. It can be increased by _wa n, or by a naked left arrow (, indicating resumption) with a pending wsfull error.
`avail The result is the amount of available storage in the workspace. (Note that the amount is computed after the argument to _wa is allocated.) It is the difference between the workspace size, `size, and the space actually being used, and is almost equal to the result of the command $wa. Usually, some of `avail is in `atmp and some is not.
`atmp The result is the current total size of the files used to hold the workspace. It includes both space that is in use and space that is available. See `avail.
$df /var/atmp tells more about available atmp.
`info The result is a combination of the above information in the following arrangement:
(`size `atmp `avail; `fragcounts; `fragsizes).

A+ data objects (including function arrays but not functions) are stored as 56-byte headers and bodies of varying size. If the number of elements of an object is n, then its body will take, in bytes, depending on its type:
`char     n+1
`int      4n1
`float    8n1
`sym      4n1
`box      4n1
plus the storage for each of its elements
`func     4n1
`null     
usually no space, but sometimes the same formula as `box.

A+ looks for its atmp space in /var/atmp/*. If several A+ processes are running on the same machine, they will compete for the same atmp space. The atmp space is used as both workspace area and mapped file area, so if large mapped files are used it may even be necessary to reduce the workspace size to get an application to work. Usually, it is best to keep the workspace about twice as large as the amount of memory you expect to use; 256Meg is the recommended safe limit, beyond which you may run out of address space.

Modifying Memory Mapping Characteristics

The memory mapping characteristics of atmp can be modified by means of the invocation flag -m with the value ws_atmp_shared, ws_atmp_noreserve, ws_atmp_private, ws_atmp_heap, or ws_malloc. The same settings can be given to APLUS_ATMP_MODEL, an environment variable, with the same effect.

ws_atmp_shared, ws_atmp_noreserve, and ws_atmp_private control the flags used for mmap and atmp (see the man page for mmap); ws_atmp_noreserve is implemented as MAP_AUTORESRV on sgi. ws_atmp_heap will put atmp in memory. ws_malloc will just use malloc and free as needed.  If there is no /var/atmp then the default will be ws_malloc. When /var/atmp does exist, the default is ws_atmp_shared except on UltraSparc and all Solaris machines, which have a default of ws_atmp_noreserve.  Alternatively and temporarily, the memory mapping characteristics of atmp can be modified by setting the environment variable APLUS_ATMP.  This variable is intended for use by system administrators to configure new architectures.  The possible settings for APLUS_ATMP are: MAP_PRIVATE, MAP_NORESERVE, and FROM_HEAP.

The Heap

There is another area of storage in A+, aside from atmp space, namely, the heap. The heap is used for A+ internal memory needs, either temporary or permanent, such as in creating contexts or global names, parsing nested arrays, and buffering outgoing messages in adap. Subsequent uses of a symbol or name within a process do not use more memory, because expunging a name does not free the heap space used for it.

A long-running A+ process can eventually use up its heap, although the heap is pretty large and A+'s demands on it are fairly small. A brealloc() error can then occur. The obvious way of controlling this potential problem is to not use a tremendous number of names. The heap size can be changed at A+ invocation by using the -h flag;  caution: do not use this flag unless it is specifically needed to solve a memory-related problem. The size can be measured using pmon, remotely, from an XTerm, but not from within an A+ process, since pmon is interactive, so $pmon cannot be used.

Another way to monitor heap space use is to run in an XTerm, while A+ is running,
while [ true ]; do pstat -s; sleep 1; done

Handling of Symbols

Memory allocation and hashing algorithms are intended to provide high performance even for applications using 10,000 or more symbols. Symbols are kept in the atmp area rather than in the heap, preventing the bus errors that could occur when an application used hundreds of thousands of symbols, exhausting the heap. Such an application may need a relatively large _wa allocation.

The address space for an A+ process is fixed at two gigabytes. Four things use address space:

See also "Memory Allocation - What to Do and What Not to Do" and "Memory Allocation in A+ - a Closer Look" in "Calling C Subroutines from A+".


doc@aplusdev.org© Copyright 1995–2008 Morgan Stanley Dean Witter & Co. All rights reserved.