System Commands


All system commands begin with a dollar sign ($) as the first nonblank character on the line. They cannot appear directly in defined functions or expression groups, but can appear in character vectors executed by Execute, but not by Value, with $ the first nonblank character. The result of Execute for a command is Null. The result is not the text that appears as a result of executing the system command directly in an A+ session.

If A+ recognizes a command as clearly erroneous, it gives incorrect as a response. It simply ignores (correct) A+ commands that have missing or wrong arguments, like $rl or $rl 'a'.

Any command that is not recognized by A+ as either one of those described below or clearly erroneous is assumed to be a Unix command and is executed in a child process forked from the A+ process, and responded to (including error responses) by that process. A+ invokes sh by default, not ksh, csh, or whatever; in particular, this means that ~ in path names is not interpreted as a "magic" character. If you need this or some other property of one of these shells, invoke that shell explicitly in the command, as in
$ksh -c "ls ~user/dirnm/*.+".
(The quotes in the example are necessary: ksh -c takes only one argument.)

Warning: The result of a Unix command depends upon the particular system under which it is executed - $unixcommand is highly nonportable. If you need advice about the use of such a command, you should usually ask someone who knows a lot about Unix, and not necessarily someone who knows a lot about A+.

Classification of System Commands

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


Definitions of System Commands

Callback Flag $Sf [n]

This flag is a debugging aid that enables (1) or disables (0) callback functions. Normally, with callbacks enabled  ($Sf 1),  a callback function is invoked when an associated variable changes. With callbacks disabled  ($Sf 0),  no callback function is invoked. The default setting is 1. $Sf alone displays the current setting. This flag can be used to inhibit callbacks while clearing suspensions: set it to 0, clear, set it back to 1, and continue execution. Note that the screen management system uses callback functions, as may any A+ utility, and therefore setting this flag to 0 can have unpredictable effects. Caution is advised when using $Sf.

Change Directory $cd [path]

If path is present, it must be a valid Unix directory path, and the effect of the command is to change the current directory to the one named in path. If path is not present, the user's home directory becomes the current directory. After a file is loaded, the current directory is the same as it was when the Load function or command was issued: it is automatically restored if it was changed during execution of the lines of the file. The PWD environment variable is set. See "Change Directory" (_cd).

Commands $cmds

Displays a list of the system command names. See "Name List" (_nl).

Context $cx [name]

If name is present, it must be a valid context name (see "User Names"), and the effect of the command is to make that context the current context. If the context does not exist it will be created. The root context is specified by a dot (.). If name is not present, the name of the current context is displayed. If the context is changed when a function is suspended, resumption of execution will automatically change the context back. After a file is loaded, the current context 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.

Contexts $cxs

Displays a list of all the context names in the active workspace. See "Name List" (_nl) and "Expunge Context" ($excxt).

Debugging State $dbg [subcommand list]

Several subcommands (with any parameters for them) can be given as arguments to $dbg, separated by blanks, as in
     $dbg +load +beam +dyld +pack
and
     $dbg indent 4 char >.
If no argument is given, the current settings are displayed. A listing of the various arguments together with their meanings is displayed in response to the subcommand help.

There are some additional messages. For example, when load tracking is on and a load command cites a nonexistent file, a debugging message mentioning the failed load command is issued.

The two subcommands char x and indent n are used to control the formatting of debugging messages. For example, if x is | and n is 2, a display when tracing is on might look like this:

    .f entered
    | .g entered
    | | .h entered
    | | .h exited
    | .g exited
    .f exited
whereas if x were > and n were 4, the third line, for instance, would look like this:
    >   >   .h entered
The
table below shows all the subcommands. The arguments that are not entered literally as shown are b, which is 0 or 1 (if b, +, and - are omitted, the command acts as a toggle); c, which is a context name or names; x, which is a character; and n, which is a nonnegative integer. You need enter only initial segments of the literal parts of the arguments just long enough to make them unambiguous.

$dbg Subcommands (Arguments)
SubcommandSignificance
(none)Display all current settings.
1 or 0 Turn all tracing and tracking on (1) or off (0).
beam b
+beam
-beam
Turn beam tracking (mapping and unmapping) on (+beam or b=1) or off (-beam or b=0), or toggle (just beam).
bitwise b
+bitwise
-bitwise
Turn checking for nonboolean And and Or arguments on (+bitwise or b=1) or off (-bitwise or b=0), or toggle (just bitwise). The default is to check.
char x Set character to be used in dbg messages (see example above).
+cxt c
-cxt c
Limit tracing to the contexts listed in c (+) or all but the contexts listed in c (-). If c is absent, trace all contexts (whether + or -). Message indentation always corresponds to execution depth, regardless of omissions.
def b
+def
-def
Turn tracking of function and dependency definition on (+def or b=1) or off (-def or b=0), or toggle (just def).
dep b
+dep
-dep
Turn dependency evaluation tracing on (+dep or b=1) or off (-dep or b=0), or toggle state (just dep).
disp map Display the limit on the number of concurrently mapped files; a list of files currently mapped, with reference counts; and some internal index information.
display beam Display all current mappings of files.
display flags Display the value of several key system variables; highlight nondefault values.
do b
+do
-do
Turn Monadic-Do tracing on (+do or b=1) or off (-do or b=0), or toggle state (just do).
dyld b
+dyld
-dyld
Turn dynamic load tracking on (+dyld or b=1) or off (-dyld or b=0), or toggle state (just dyld).
fmt b
+fmt
-fmt
Turn messages from _fmt on (+fmt or b=1) or off (-fmt or b=0), or toggle state (just fmt). The default is no message display.
func b
+func
-func
Turn defined function and operator tracing on (+func or b=1) or off (-func or b=0), or toggle state (just func).
helpDisplay all permissible settings and their significance.
indent n Set dbg message indentation per level of execution depth.
inv b
+inv
-inv
Turn on (+inv or b=1) or off (-inv or b=0) or toggle (just inv) the tracing of dependency invalidations and the triggering of a callback (if a callback function is defined, using _dbg). Messages are indented to make tracing of dependency trees easier. A warning is issued when inv is on and a cyclic dependency is encountered during invalidation.
levels n Maximum (execution) depth of tracing. 0: off. No n: unlimited.
load b
+load
-load
Turn load tracking on (+load or b=1) - showing full path names - or off (-load or b=0), or toggle state (just load).
nan b
+nan
-nan
Turn on (+nan or b=1) or off (-nan or b=0) or toggle (just nan) the checking of files as they are beamed in for NaN and Inf. If checking is on and such an undesirable is found in a file being beamed in, an error message is sent to stdout. Cf. _nanfind.
pack b
+pack
-pack
Turn packfile command tracing on (+pcb or b=1) or off (-pcb or b=0), or toggle state (just pcb).
pcb b
+pcb
-pcb
Turn preset-callback tracing on (+pcb or b=1) or off (-pcb or b=0), or toggle state (just pcb).
_prcb b
+_prcb
-_prcb
Turn prereference-callback tracing on (+_prcb or b=1) or off (-_prcb or b=0), or toggle state (just _prcb).
print b
+print
-print
Display tracing messages (+print or b=1) or not (-print or b=0), or toggle (just print). The default is to display them. Designed to be used in conjunction with callbacks, which are set using _dbg{`cb;(fn;cd)}.
_rcb b
+_rcb
-_rcb
Turn reference-callback tracing on (+_rcb or b=1) or off (-_rcb or b=0), or toggle state (just _rcb).
scb b
+scb
-scb
Turn set-callback tracing on (+scb or b=1) or off (-scb or b=0), or toggle state (just scb).
sfs b
+sfs
-sfs
Turn system function tracing on (+sfs or b=1) or off (-sfs or b=0), or toggle state (just sfs).
tkerr b
+tkerr
-tkerr
Turn reporting of otherwise silent execution errors that do not cause execution suspension on (+tkerr or b=1) or off (-tkerr or b=0), or toggle state (just tkerr). ("tk" is for toolkit.) The default is 0.
wa b Turn tracing of $wa on or off, or toggle. Will also trace _wa and workspace size changes by soon.
xeq b
+xeq
-xeq
Turn Execute (Protected or not) tracing on (+xeq or b=1) or off (-xeq or b=0), or toggle state (just xeq).
xfs b
+xfs
-xfs
Turn external function tracing on (+xfs or b=1) or off (-xfs or b=0), or toggle state (just xfs).


     Examples:
      2 1 2 ^ 1 1 0     $dbg +bitwise is the default.
     Warning: found 2 nonbooleans in left argument of ^.
  1 1 0

      2 1 2 ^ 7 1 8
     Warning: found 4 nonbooleans in both arguments of ^.
  1 1 1

     f{}:c.g{}
     c.g{}:'c.g'
     $dbg func 1      Trace function calls.
     f{}
    .f entered
      c.g entered
      c.g exited
    .f exited
c.g
     $dbg levels 1    Limit the levels traced to 1.
     f{}
    .f entered
    .f exited
c.g
     $dbg levels      Trace all levels.
     $dbg +cxt c      Limit tracing to the c context.
     f{}
      c.g entered    Note the indentation, which indicates the level.
      c.g exited
c.g

     $dbg 0    Reset debugging; default for fmt is 1: issue _fmt msgs.
     do line'i3,7c1'_fmt(n185;1 7' spread')
 _fmt: Missing edit specification
 _fmt: i3,7c1
 _fmt:     ^^
<  9
< domain
     $dbg -fmt        Turn off messages from _fmt.
     do line'i3,7c1'_fmt(n;1 7' spread')
<  9
< domain

Dependencies $deps [name]

If name is present it must be a valid context name (see "User Names"), and the effect of the command is to display a list of dependency names in that context. If name is not present the names of dependencies in the current context are displayed. See "Name List" with `deps right argument.

Dependency Definition $def name

This command displays the definition of the dependency named in name. See "Dependency Definition" (_def), and "Dependencies".

Dependency Flag $Df [n]

This command enables (1) or disables (0) dependencies, by setting `Df. Normally, with dependencies enabled ($Df 1), dependency definitions are evaluated when dependencies are referenced, and their definitions are marked for evaluation. With dependencies disabled ($Df 0) dependency definitions are never evaluated, which has the effect that dependencies act like normal global variables. However, they are still marked for evaluation and will be evaluated if so marked when referenced after $Df is reset to 1. Display mode ($Df 2) no longer exists, its function having been incorporated in $dbg; the argument 2 is a no-op. If no parameter is given to $Df its current value is displayed. The default setting is 1.

Warning! Disabling dependencies can cause confusion. Be careful.

Dependent Object Names $dep name

This command displays the names of all dependencies whose definitions explicitly reference name. See "Dependent Object Names" (_dep).

Execution Suspension Flag $Ef [n]

Execution suspensions due to A+ errors occur normally when this flag is set to its default value 1. When it is set to 0, these suspensions do not occur: an A+ error causes abandonment of execution instead, without any message. If no argument is given to $Ef, its current value is displayed. Note that errors include signals generated by the primitive function Signal. See also the in attribute. This definition is experimental and may be refined in the future, or replaced by a different mechanism.

Expunge $ex names

This command removes the global objects whose names are listed in names from the active workspace. These objects can be variables, functions, dependencies, and operators. Global variables and dependencies bound to display classes will not be removed (see the functions is and free); in these cases the command will display the message name: is bound.  See "Expunge" (_ex).

Expunge Context $excxt context

This command removes the context whose name is listed in context from the active workspace. The context must be empty, else the command displays the message context: not empty.  The Global Objects command $globs name can be used to list all objects that would prevent the expunging of a context. See "Expunge Context" (_excxt).

The root context cannot be expunged. Any attempt to expunge it or a nonexistent context is ignored.

External Functions $xfs [name]

The command lists external compiled C program names in the current context if name is not present, else in the context name.

Functions $fns [name]

If name is present, it must be a valid context name (see "User Names"), and the effect of the command is to display a list of the user function names in that context. If name is not present, the names of functions in the current context are displayed. See "Name List" (_nl).

Global Objects $globs [context]

This command lists the names of all global objects of any kind that appear in the given context. The list of names includes names for which attributes have been set (using _set), even if they have not been given values and consequently are not listed by $vars. If context is omitted, the current context is assumed. This command is especially useful in connection with the Expunge Context command, $excxt. See "Name List" (_nl).

Input Mode $mode [apl | ascii | uni]

If apl or ascii or uni is present, the keyboard mode is set to the one specified. Otherwise, the current mode is displayed. APL mode means that the special graphic characters that denote A+ primitive functions are to be entered, using the APL union keyboard. ASCII mode means that instead of each of these special graphics a specified sequence of one or more standard ASCII characters is to be entered; see the table below. There is also a mode like ASCII but more consistent and presumably easier to read and remember, namely UNI; see the second table below (which, unlike the first table, includes characters that are the same as for APL mode). It is important to understand that the latter two modes involve only simple token substitution.

Session output is in the specified mode, but expressions being executed, in functions or directly from the session input, are never translated or otherwise reconstructed. Derived functions, however, are re-created when displayed. s.box, incidentally, seems to live at some sort of halfway house.

UNI tokens are:

  1. ASCII characters;

  2. sequences of two ASCII characters in which the second character is =, /, or \ (used because such sequences are not otherwise legal A+ expressions); and

  3. strings consisting of an uppercase letter, a period, and a token as in 1. or 2. (again, not otherwise an A+ expression). The uppercase letters are used to group the symbols:
    • M for mathematical;
    • I for indexing;
    • S for shape;
    • O for outer products, but Q where an M.y is involved, resulting in Q.y;
    • P for inner product;
    • B for bitwise;
    • A for argument;
    • F for file;
    • E for evaluate and inverse evaluate (Format); and
    • Y for symbols.
     Examples:
     $mode apl
     q
     f{}:00
     34
 0.75
     34
 4
     q
()
     $mode uni
     q
(*~)
     3%4
 0.75
     3 M.+ 4
 4
     -3 4
 -3 4
     1 + -3 4
 -2 5
     - 3 4
 -3 -4
     1 + - 3 4
 -2 -3
     g{}:0%0
     g{}
//[error]  %: domain
*     $si
g{}
.g: 0%0

*     
     f{}
//[error]  %: domain
*     $si
f{}
.f: 00

*     
     s.box -3 4
-3 4
     s.box - 3 4
-3 -4
     s.box 2 3 4
2+3
     $mode apl
     s.box 3 4
3 4
     s.box -3 4
3 4
     s.box 2 3 4
2+3
     g{}
[error]  : domain
*     $si
g{}
.g: 0%0

ASCII Mode Equivalents To APL Graphics
APLASCII
APLASCII
APLASCII
APLASCII
:= each ^& ?
* % log ==
max .max.
see below
min in
~= <= >= *^
rot flip iota rho
take drop upg dng
pack unpack bag pick
eval form rtack where
pi mdiv ?rand beam
%ref dot // ~bwnot
^bwand bwor <bwlt bwle
=bweq bwge >bwgt bwne

Note to table: In ASCII mode, every valid outer product .f is replaced by s. (read "s-dot"), where s is the string of symbols that replaces f. For example, >=. replaces ..

UNI Mode Equivalents To APL Graphics
APLUNI  APLUNI  APLUNI  APLUNI
+ + -
(minus)
- (and
perhaps
space
)

(high
minus)
- *
% * M.* M.& | M.|
M.# M.+ M.- M.<
M.> ? M.? M.^ ^ &
| ~ ! < < <=
= = >= > > !=
== E.% E.* % ^
Y.& / / \ \ A.<
A.> := F.! # #
I.> I.# I.+ I.-
I.? I.< S.+ S.-
, , S.? S.| S.\
! S.! +/ +/ / */ / M.+/
/ M.-/ ^/ &/ / |/ +\ +\
\ *\ \ M.+\ \ M.-\ ^\ &\
\ |\ .+ O.+ .- O.- . O.*
. O.% .* Q.* .| Q.| . Q.+
. Q.- .< O.< . O.<= .= O.=
. O.>= .> O.> . O.!= +. P.*
.+ P.+ .+ P.- ^ B.& B.|
~ B.! < B.< B.<= = B.=
B.>= > B.> B.!= @ @
~ time time case case do do
else else if if while while //
+= e e
(e-
notation)
. . $ $
& ? (stack
vars)
` ` (back-
quote)
' ' " "
: : ; ; ( ( ) )
[ [ ] ] { { } }

Note to table: A UNI minus represents an APL high minus if that is syntactically possible. To force it to be an APL minus, use a blank after a UNI minus when necessary, as shown in the examples.

Load $load script

The argument script is a filename. In response to this command, the directories specified in the environment variable APATH are searched for the file named script. If that file is not found and script does not end with .+ or .a,  these directories are searched again for script.+,  and if that file is not found they are searched for script.a.  Once a file is found, it is loaded into the active workspace by interpreting every line of the file, starting at the top, essentially as if the lines had been entered directly in the active workspace. The difference is that after a file is loaded, the current context and the current directory are the same as they were when the Load command was issued: each is automatically restored if it was changed during execution of the lines of the file. The PWD environment variable is set and restored during this operation.

Load and Remove $loadrm script

This command is the same as the Load command, except that the file is deleted after it has been loaded.

Mapped Files Limit $maplim [n]

The value of $maplim is the number of files that can be mapped concurrently. $maplim n sets the limit to n; the default is 2000. Reducing the limit saves space, since it reduces the size of an internal table.

Off $off

The effect of this command is to terminate the active A+ process. See "Exit" (_exit).

Operators $ops [name]

If name is present, it must be a valid context name (see "User Names"), and the effect of the command is to display a list of the user operator names in that context. If name is not present, the names of operators in the current context are displayed. See "Name List".

Pipe $|var cmd

The effect of this command is to pipe the default display of the global variable named in var to the Unix command named in cmd. The argument var can be a fully qualified name, specifying a context. This is actually a Unix command: see a Unix manual for details. Example:
     txt'Allow for 3-day settlement.'
     $|txt cat >>note.asc

Pipe In $<var cmd

The $<var  cmd  command runs the Unix command cmd and puts the result (the standard output) in the global variable var as a character vector. There must be no space between the $ and < symbols and cmd must not be an interactive command.

To read ASCII file myfile into variable myvar, you can use $<var cat myfile.

Pipe Out $>obj filename

The $>obj  nm.asc  command puts an ASCII version of the A+ global object obj in the file nm.asc, replacing the previous contents if the file already exists. It is equivalent to displaying obj and cutting and pasting it into nm.asc after emptying nm.asc if necessary, and basically equivalent to $|obj cat >nm.asc. If obj is a function, its definition is written in the file. There must be no space between the $ and > symbols.

Pipe Out Append $>>obj filename

The $>>obj  nm.asc  command is just like $>obj  nm.asc  except that if the file nm.asc exists the ASCII text version of the default display of the A+ object is appended to it, instead of replacing the previous contents. There must be no space within the $>> sequence.

Printing Precision $pp [d]

If d is present, then, in the usual case, the effect is, loosely speaking, to set the Printing Precision to d. More precisely, the relevant characters of d are the first nonblank character and the character immediately following it, if that character exists and is nonblank. If the relevant characters are digits, the effect of the command is to set the precision to the number they represent.

If d is omitted (or a relevant character is not a digit), the current setting is displayed.

The Printing Precision `pp normally specifies the maximum total number of digits to be used in the display of a number, not counting the two digits following the e in exponential notation. There are two exceptions:

The maximum meaningful value for $pp is 16. Digits displayed on output beyond the 16th digit are not valid.

See "Printing Precision" (`pp), the examples for Format (), and the examples for Default Format.

Protected Execute Flag $Gf [n]

This flag is a debugging aid that enables (1) or disables (0) protected execution. When disabled, a Protected Execute or a Monadic Do produces the same error message as would the A+ expression it executes. The default setting is 1. See "Execute in Context or Protected Execute" () and "Do - Monadic (Protected Execution)".
     Examples
     $Gf 0
     do{234}
 : type
*     
     $Gf 1
     do{234}
<  6
< type

Random Link $rl n

The random link is set to positive integer n. The random link is used as a seed by the primitive functions Roll and Deal. Setting the random link allows the user to produce repeatable sequences of pseudorandom numbers. See "Random Link" (`rl).

Remove Dependency Definition $undef name

This command removes the dependency definition for name, if any. It leaves everything else, such as value and callback function, unchanged. After this command is executed, name is an ordinary, not a dependent, variable (if it was previously a 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 command. Cf. "Remove Dependency Definition" (_undef).

Reset $reset [n]

The $reset n  command clears n suspensions, and $reset alone on a line clears all suspensions. A negative or otherwise invalid argument is taken as 0, a no-op, and all arguments equal to or greater than the number of suspensions are equivalent. $reset does not clear a multiline entry with unbalanced punctuation and, indeed, is blocked by it; to abort the expression, use either or $ alone.

In terms of asterisks, (or $) always removes one asterisk and may remove more than one if the innermost asterisks signal unbalanced punctuation, whereas $reset alone on a line removes either all or none (when the innermost asterisks signal unbalanced punctuation) and $reset n  removes either n or none.

Stack Information $doErrorStack

Set the system variable `doErrorStack to 0 or 1. See _doErrorStack{}.

State Indicator $si

The name and current line of the currently suspended function are displayed. Any functions pendent, that is, waiting for the currently suspended function to be completed, are displayed on lines above the display line of the suspended function. Any uncleared previously suspended functions and their pendent functions are not shown. Lines displayed in the state indicator are: The user is reminded of the suspension by the appearance of a * in the prompt. To clear the most recent suspension enter $ or right arrow () and press the Enter key. To clear all suspensions, clear each individual suspension in turn. $reset  [n]   allows you to clear as many as you want with one command.

Stop $stop [n]

If n is present, the effect of the command is to set the stop debugging state to n. The valid settings for n are 0 (none), 1 (stop), and 2 (display). See "Stop" (^) for the meaning of the three states. If n is not present, the current value of the stop debugging state is displayed.

Warning: If you are running A+ from Emacs and you set this state to 1, then if the Stop function (^) is executed while a menu's contents are displayed but before a selection is made, the machine is hosed until the Emacs session is killed.

System Functions $sfs

This command displays a list of the system function names. See "Name List" (_nl). ($_sfs lists system functions which are for the use of A+ implementers only.)

Terminal Flag $Tf

Turns terminal input (stdin) off. When programming an A+ application to be run from a Unix shell script, put $Tf at the end of the application file; otherwise A+ will be in open keyboard mode after the application file has been read, and the Unix shell script will not be executed past the point where A+ was invoked. This mechanism will be replaced in the future. See "Standard Input": `stdin when 0 has the effect of $Tf but queues keyboard entries for processing when it is subsequently reset to 1.

Variables $vars [name]

If name is present, it must be a valid context name (see "User Names"), and the effect of the command is to display a list of the variable names in that context. If name is not present, the names of variables in the current context are displayed. Dependencies are listed only if they have saved values, which do not need to be valid. Names that have been given attributes using _set but that have not been given values are not listed; see "Global Objects" ($globs). Also see "Name List" (_nl).

Version $vers

The version of the active A+ system is displayed. See "Version" (`vers).

Workspace Available $wa [n]

If n is a positive integer, $wa n adds n megabytes to the active workspace.1 $wa 0 is almost equal to (_wa `fragcounts),(_wa `size),(_wa `atmp),_wa `avail. $wa (with no argument) is almost equal to _wa `avail.

See "Work Area" (_wa). (The slight differences are accounted for by the system requirements for running the command and the function.)

X Events Flag $Xf [n]

Enable (1) or disable (0) X events. When X events are enabled  ($Xf 1),  X events that do not have A+ callbacks will be processed even when A+ programs are running. This gives the appearance of a multithreaded environment. For example, scrolling a window will work even while a long-executing program is running, as long as there is no A+ callback attached to the scrolling event. This setting is the default.

If X events are disabled  ($Xf 0),  then no X events will be processed when an A+ program is running. Instead, they are queued and dispatched after the program execution is completed.

This command has no use in running applications, but the 0 setting may be useful in debug mode.


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