This page has been reproduced from original A+ documentation provided by Morgan Stanley at www.aplusdev.org. Copyright remains with the authors.

Classification of System Functions
Querying Syntax
Common Error Reports
Definitions of System Functions

The Name Argument
Abort Loading of Script _abortload{}
All Attributes _atts{y;x}
All Dependent Object Names _alldep{x}
Association List to Slotfiller _alsf{x}
Change Directory _cd{x}
Comma Fix Input _cfi{y;x}
Debug _dbg{x}
Dependency Definition _def{x}
Dependent Object Names _dep{x}
Dynamic Load _dyld{x;y}
Execution Profile _profile{x}
Exit _exit{x}
Expunge _ex{x}
Expunge Context _excxt{x}
Fix Input _fi{y;x}
Flatten _flat{x}
Format _fmt{y;x}

Table:  Format Phrases
Table:  Qualifiers
Table:  Decorators

General Search and Replace _gsr{y;x;r;n}
Get Attribute _get{y;x}
Get Callback _gcb{y}
Get Client Data _gcd{y}
Get Format Symbols _gfmtsym{}
Get Preset Callback _gpcb{y}
Get System Variable _gsv{x}
Hash Table Statistics _hashstat{x}
Index of _index_of{y;x}
Is a Slotfiller _issf{x}
Items of a Mapped File _items{y;x}
Load _load{x}
Load and Remove _loadrm{`delete;x}
Locals _locals{x}
Name _name{x}
Name Class _nc{y;x}

Table:  Name Classes

Name List _nl{y;x}

Table:  Name List Expressions vs. The Kind of Objects in the Result

Name Search _ns{y;x}
Name Search and Replace _nsr{y;x;r}
NaN Find _nanfind{x}
Permissive Indexing _index{i;x;d}
Remove Dependency Definition _undef{name}
Scalar Comma Fix Input _scfi{s}
Scalar Fix Input _sfi{s}
Screen Format _sfmt{f;d}
Set Attribute _set{y;x}
Set Callback _scb{y;x}
Set Client Data _scd{y;x}
Set Preset Callback _spcb{y;x}
Set System Variable _ssv{y;x}
Stack Information _doErrorStack{}
String Search _ss{y;x}
String Search and Replace _ssr{y;x;r}
Valence _valence{x}
Work Area _wa{x}

Table:  Arguments and Results for Work Area

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:

• system variables:   Get System Variable, Set System Variable;

• names and references:   Expunge, Expunge Context, Locals, Name, Name Class, Name List, Valence;

• attributes:   All Attributes, Get Attribute, Set Attribute, Get Client Data, Set Client Data;

• dependencies:   All Dependent Object Names, Dependency Definition, Dependent Object Names, Remove Dependency Definition;

• callbacks:   Get Callback, Get Preset Callback, Set Callback, Set Preset Callback;

• files:   Abort Loading of Script, Change Directory, Dynamic Load, Items of a Mapped File, Load a File, Load and Remove a File;

• format changes:   Association List to Slotfiller, Comma Fix Input, Fix Input, Flatten, Format, Scalar Comma Fix Input, Scalar Fix Input, Screen Format, Get Format Symbols, Is a Slotfiller;

• text functions:   General Search and Replace, Index Of, Name Search, Name Search and Replace, String Search, String Search and Replace;

• indexing:   Permissive Indexing;

• debugging:   Debug, NaN Find, Stack Information;

• A+ operation and space:   Execution Profile, Exit, Hash Table Statistics, Work Area.

Common Error Reports

The Name Argument

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

• a symbol holding a valid A+ name, e.g., `var or `ctx.var;

• a pair of symbols holding a valid A+ context name and a valid name, e.g., `ctx `var.

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.

All Attributes _atts{y;x}

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

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}

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

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}

Change Directory _cd{x}

_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}

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.

• Nonce error if x is greater than 1000.
• Rank error if the rank of y exceeds two.

     _cfi{'(1,200)';1}
<  1
<  ¢1200.

Debug _dbg{x}

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}

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

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}

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

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

Dynamic Load _dyld{x;y}

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}

Exit _exit{x}

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}

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

_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}

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

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}

This function creates a numeric array with xÓ0 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 xÓ0 numbers, then i#bool is assigned 0, and i#data is created by using the first xÓ0 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.

• Nonce error if x is greater than 1000.
• Rank error if the rank of y exceeds two.

     Õaû3 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}

Format _fmt{y;x}

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 ((«/¢1ÕÒa),¢1ÙÒa)Ò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

Phrase	Application	Description
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.
jqiw	Integer	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.
jtp	Absolute tab	Start the next field at position p+1. If p is too small, the next field may overwrite earlier ones.
jxp	Relative 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

Qualifier	Summary	Description
b	blanks	Make the entire field blank when the value is zero.
c	commas	Insert commas between successive triplets of digits in integer and (before the decimal point) fixed-point fields.
ke	scale	Scale the result by displaying a value that is 10e times the value.
l	justify	Left justify. The default is right justification.
z	zeros	Display leading zeroes in integer and fixed-point fields.

In the "Decorators" table, text may also be delimited by ¤¦, ÚØ, ¡¡, //, ÌÌ, ìì.

Decorators

Decorator	Summary	Description
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.

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

If x, r, or n is not a vector, its ravel is used. There are eight cases, as determined by n and r:

• If r is Null, then:
  • If n is Null, then the function is the same as String Search (_ss).
  • If n is not Null, then the function is the same as Name Search (_ns), except that n affects the definition of "namelike" as follows:
    • if n is the empty character vector (''), then the definition is exactly the same as for _ns;
    • if n is nonempty and 0#n is not 'þ', then n replaces '._', and '`¢' are not considered;
    • if n is 'þ',c, then c replaces the alphabetic characters, digits, and '._', and '`¢' are not considered.

• if r is not Null (but possibly ''), then:
  • If n is Null, then the function is the same as String Search and Replace (_ssr).
  • If n is not Null, then the function is the same as Name Search and Replace (_nsr), except that n affects the definition of "namelike" as follows:
    • if n is the empty character vector (''), then the definition is exactly the same as for _nsr;
    • if n is nonempty and 0#n is not 'þ', then n replaces '._', and '`¢' are not considered;
    • if n is 'þ',c, then c replaces the alphabetic characters, digits, and '._', and '`¢' are not considered.

Name delimiters are okay within target and replacement:

     _gsr{'ÌIOû1';'ÌIO';'ÈIO';'ÌÈü'}
ÈIOû1

     _gsr{'ÌÌIOû1,ÌIOû2,BÌIOû3';'ÌIO';'ÈIO';'ÌÈü'}
ÌÌIOû1,ÈIOû2,BÌIOû3

     _gsr{'ÌÌIOû1,ÌIOû2,BÌIOû3';'ÌIO';'ÈIO';'þÌÈü'}
ÌÌIOû1,ÈIOû2,BÈIOû3


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

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

Get Attribute _get{y;x}

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

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}

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

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}

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

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{}

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

Get Preset Callback _gpcb{y}

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

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}

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.

• A domain error is reported if x does not name a system variable whose value is accessible.

Hash Table Statistics _hashstat{x}

Index of _index_of{y;x}

   Inventoryû(("Oxford";"Oxford";"Loafer";"Loafer");
*             ("Brown"; "Tan";   "Black"; "Brown" );
*             (128.98;  175.98;  112.50;  112.50))
   (Inventory[0 1]_index_of(<"Oxford";<"Tan"))Ø2ØInventory
 175.98

Is a Slotfiller _issf{x}

Items of a Mapped File _items{y;x}

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}

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.

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

Load and Remove _loadrm{`delete;x}

_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}

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}

Name Class _nc{y;x}

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 Class	Description
`vars	User variables
`fns	Defined functions
`xfs	External functions
`globs	Global objects
`deps	Dependencies
`ops	Defined operators
`null	Not in use, not a valid name, or not one of the above

Name List _nl{y;x}

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:

• Where the left argument is shown as `ctx, it can also be Null (absent), indicating the current context.
• Where the left argument is shown as ` (the root context), it can also be Null (absent), indicating the current context.

Name Search _ns{y;x}

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

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:

• If y is a vector or the ravels of x and r are the same length, then the result is y with r in place of every occurrence of x found in y itself.

• Otherwise, the result is the ravel of y with r in place of every occurrence of x found in the ravel of y; if no occurrences were found, the result is simply the ravel of y.

See also the examples in "String Search and Replace".

     _nsr{'This is ''is''';'is';'are'}
This are 'is'

NaN Find _nanfind{x}

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}

Remove Dependency Definition _undef{name}

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

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}

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}.

• A domain error is reported if the first item of _cfi{s;1} would be zero.

Scalar Fix Input _sfi{s}

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}.

• A domain error is reported if the first item of _fi{s;1} would be zero.

Screen Format _sfmt{f;d}

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.

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}

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.

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}

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

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#pØc%v)ûd  ã if i is nested
  (i#,pØc%v)ûd ã if i is simple
     or
  (pØc%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}

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

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}

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.

The differences between callback functions established by _spcb and _scb are:

• preset callback functions on dependencies are called when either a dependent variable is assigned a value or a dependency is evaluated (after the evaluation of the dependency definition is completed), whereas callback functions are called only when the dependent variable is assigned a value;

• _spcb{y;x} causes the callback function specified in x to be called just before the value of the global variable (or, indeed, function) named in y is changed, but _scb is called just after;

• preset callback functions are used to validate new values for global variables and they therefore return meaningful results (namely, the validated data), whereas callback functions do not;

• for the Append form of Selective Assignment, the indices i are not valid for _spcb, since the appending has not yet been done, but they are valid for _scb.

Since preset callbacks are used for validating new values of global variables, the following rules should be followed in their definitions:

• if a new value is valid, set the result of the preset callback function to that value;
• if a new value is invalid, signal an error (see "Signal"); the value of the global variable will remain unchanged.

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

Set System Variable _ssv{y;x}

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., 100Íx 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.

• A domain error is reported if y does not name a system variable that can be set or x is an impermissible setting for y. Although $Df 2 is a no-op, _ssv{`Df;2} is a domain error.

String Search _ss{y;x}

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.

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

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

     _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}

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.

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

• A nonce error is reported if x is a function scalar that is a primitive function;
• a domain error is reported if x is a symbol naming a system function, but not if x is a function scalar that is a system function.

Work Area _wa{x}

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

Argument	Effect and Result
n,  for n¦1	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      4«nÓ1
`float    8«nÓ1
`sym      4«nÓ1
`box      4«nÓ1 plus the storage for each of its elements
`func     4«nÓ1
`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:

• the actual code of the A+ process, and dynamically loaded routines;
• dynamic memory (heap space);
• atmp space;
• mapped files.

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+".

Back to Home page

© British APL Association 2001
Please send any comments to Adrian Smith via adrian@causeway.co.uk - thank you.