UNIX* APL\11 User's Manual John D. Bruner A. P. Reeves School of Electrical Engineering Purdue University West Lafayette, IN 47907 This manual is intended to serve as a guide to the use of UNIX APL. It is not intended to be a reference manual on the APL language; rather, it describes the local implementa- tion of APL. Portions of this manual are intended for the new APL user; persons who have used other APL systems will probably want to skim most sections, and concentrate on the sections concerning error messages, the state indicator, editing functions, and the appendices. For these users, differences between UNIX APL and standard APL are noted where appropri- ate. 1. What's a Workspace? One of the most important concepts pertaining to the use of APL is the idea of a ``workspace''. Simply stated, a workspace is a collection of information (including both functions and data) to be processed. Programmers accustomed to compiler languages such as FORTRAN may find this concept somewhat unusual so let's explore it a bit further. Perhaps the best way to start describing a workspace is to define another term - ``file''. A file is also a collec- tion of information. On UNIX, however, a file usually con- tains only one type of information; e.g. a C program or data for a FORTRAN program. A standard program, perhaps written in FORTRAN, may access data in the file by ``opening'' the file and reading it. The file may also be ``created'', written, or removed. APL differs from FORTRAN in that, while it is running, all of the information it needs is internal to itself. That is, all of the variables that the functions will require are *UNIX is a trademark of Bell Laboratories. August 14, 19113 - 2 - already available. As functions are written, they are added to this internal storehouse of information. As the func- tions are run, and data is generated, the data is added to this internal storehouse. APL provides the facility to save part or all of this information in a special format (``workspace'' or "load" format) in a UNIX file. This file can only be used by APL in later runs (it should not, for instance, be printed on the line-printer). In addition, APL is capable of working with more con- ventional files, which are in character format and can be edited and displayed outside of APL. These files are in ``ASCII'' format. 2. Getting Into and Out of APL 2.1. Getting on UNIX In order to use UNIX APL you must first obtain a UNIX account. Your account will have a ``login name'' and also a ``password''. Your login name is your user identifier. Find an unused UNIX terminal and turn it on. Hold down the Control key and type a D. The terminal should erase the screen, print a message identifying the UNIX system, and ask: login: Type your ``login name'' followed by a carriage return. The system will respond with: Password: Type your password. UNIX will not display what you type so someone cannot look over your shoulder at the terminal and steal your account. When UNIX is satisfied that you can login it will print the ``message of the day'', which is comprised of any impor- tant news about the system, and then it will type out a dol- lar sign*: $ This is the standard UNIX prompt, which means that it is waiting for you to enter a command. *The dollar-sign prompt is used by the ``standard'' shell ``/bin/sh''. If you are using the C-shell (``/bin/csh'') the prompt will be a percent sign. The command interpreter which is used is of little impor- tance for the examples in this manual. August 14, 19113 - 3 - 2.2. How do I start APL? The answer in this case is extremely simple - type the command: $ apl APL will print a title identifying itself and the date of the current version, will print ``clear ws'', and will then tab 8 spaces to the right. This is APL's prompt, which means that it is expecting you to type something. The ``clear ws'' message means that you do not have anything in your workspace (no functions or variables have been defined). Equally important to getting into APL is getting out. To terminate APL, use the ``)off'' APL system command. You will once again get the dollar-sign as a prompt. 2.3. What are all of those funny characters? Part of the power of APL comes from the fact that it has so many primitive operators, usually referred to as ``functions'' in the APL literature. That is, many common functions, from addition and subtraction, to trigonometric functions, and to matrix operations, can be specified with a couple of characters. As a result, the character set for APL does look a little strange. Basically, there are two major types of primitive functions. The most common func- tions, such as the arithmetic operators, etc., are represented by a single character. For example, the symbol ``+'' represents addition. Because there are only so many keys on the keyboard, the other operators in APL, for exam- ple, matrix inversion, are called ``overstrike'' characters. An overstrike character is treated as one symbol by APL, but requires three keystrokes on the terminal. One common exam- ple is the ``comment'' symbol. This symbol is composed of the three characters: C J. (The is also the same thing as J C.) On an APL terminal, the equivalent characters are ``intersection'' and ``jot''. This brings up another point. UNIX APL is capable of operating with one of two character sets. By default, the ASCII character set is used, since most computer terminals implement at least this set. When this character set is in use, lowercase letters are used to form variable and func- tion names. Special symbols, such as ``+'', and the upper- case letters are used to form the APL operators. To run APL from an ASCII terminal, the command is simply: $ apl APL may also be instructed to use the APL character August 14, 19113 - 4 - set. This is useful only on an APL terminal. ASCII is always used internally, so work may be done interchangeably on both APL and ASCII terminals. If you wish to use the APL character set rather than the ASCII character set, use the command: $ apl -m A list of the character set for UNIX APL appears in Appendix A. 2.4. When is a ``Control-H'' not a backspace? When it's an erase character. By default, the Purdue Engineering Computer Network (ECN) UNIX systems use the character ``control-H'' as an erase character. (A ``control-H'' is typed by holding down the ``CTRL'' key and pressing an ``H''.) The ``erase'' char- acter is a special character which tells the UNIX operating system to back up one character on the line you are typing. Thus, if you mistype a letter, you can type the erase char- acter (which will physically erase the previous character on the screen) and then type the correct character. Unfortunately, APL needs to use ``control-H'' as a ``backspace'' character to produce overstrike symbols. If you are running APL from a ASCII terminal, you will need to change your erase character to something other than ``control-H''. You can do this with the stty command. For example, to change your ``erase'' character to the under- score (which is not required in APL), type: $ stty erase When you want to correct mistakes, type an underscore. When you want to type an overstrike symbol, type Note that because of the way ASCII terminals are built, when you finish typing this only the second character will be visible. From an APL terminal things are a little easier. You may use the stty command to change your erase character, and you may use control-H as a backspace character. A better method, however, is to use the ``backspace'' key, located at the far right end of the keyboard (the key is marked ``^'' and ``~''). When you type: the terminal will print the overstrike character on the August 14, 19113 - 5 - screen. (Recall that ASCII terminals display only the second character.) While we're on the subject of the ECN UNIX APL termi- nals, it would be a good idea to explain how to use the APL character set. All public terminals are conventional ASCII terminals. A few, all currently located in the EE building, have been specially modified to use the APL character set. These terminals can be distinguished from the others by the presence of a small switch on the left-hand side. When the switch is in the upward position, the terminal functions as an ASCII terminal. When the switch is set down, the termi- nal uses the APL character set. 3. APL System Commands There are a number of ``system commands'' in APL. These commands are used to control your current session. System commands may be typed at any time when APL is prompt- ing for input. (They may not be included in APL functions, however.) As stated previously, when APL is waiting for input from the keyboard, it will type eight spaces. There are two types of system commands, those which request information and those which specify action by APL. All system commands are preceeded by a right parenthesis. As an example, the following is a typical entry into APL: $ apl a p l \ 1 1 25 oct 1978 clear ws (the underline character ``'' represents the ``cursor'' on the terminal). The ``)lib'' command could then be typed: )lib Commands which specify action are composed of the com- mand name and some other value. For instance, to set the output width (number of characters per line that APL will print) to 64, the command is: )width 64 A final warning - the command name and the right parenthesis must be together: ) width 64 August 14, 19113 - 6 - is invalid and will give an error message. The available commands are described fully in Appendix B. 4. Automatic Workspace Loading UNIX APL has the nice feature that you can automati- cally load a workspace file into the internal workspace when you start APL. Instead of using the command: $ apl $ apl -m and then loading the workspace you want with the system com- mand: )load workspace you can say: $ apl workspace $ apl -m workspace APL will be started, and will automatically look for and load the file ``workspace''. As an additional convenience, APL will automatically load a file named ``continue'' if it exists. Thus, if you wish to use the file ``continue'' as your initial workspace, you need only type: $ apl $ apl -m The system command ``)continue'' facilitates use of this handy automatic loading feature, providing a convenient method of terminating an APL session and restarting it at some later time with a minimum of effort. You may, for instance, end your APL session with: )continue which will save your workspace in a file named ``continue'' and terminate APL. To resume your work at some later time, type the shell command: $ apl $ apl -m (Recall that if you don't have a file named ``continue'' when you type this, APL starts with ``clear ws''.) 5. Workspace Library When you specify a workspace to be loaded, APL will first look in your directory. If it finds the workspace, it August 14, 19113 - 7 - will load it. If not, it will look in the library direc- tory: /usr/lib/apl. Thus, if you do not have a file named ``news'' and you type: $ apl news APL will be started, will see that you don't have a ``news'' file, and will print: [using /usr/lib/apl/news] Equivalently, if you are in APL and you type: )load news )copy news you will get the library file if you don't have a file named ``news''. If the workspace you specify does not exist in either your directory or in /usr/lib/apl, an error message will be printed. 6. Editing Functions Function editing on UNIX APL differs from that on other APL systems. The ``del'' character is not used. Instead, the UNIX editor is used. There are two alternatives. The ``)editf'' system command is used to edit a func- tion residing in the internal workspace. The command )editf fn writes the function ``fn'' into a temporary file and calls the editor to process it. When the editor is finished, APL reads it back in. The command: )edit junk invokes the editor to process the UNIX file ``junk''. When the editor is terminated via the ``q'' command, control returns to APL, which will read ``junk'' into the internal workspace. Note that this method involves files external to APL. ``)editf'' is generally a better choice since it allows all information relating to the workspace to be con- tained within the workspace. Because of the way in which editing is performed, there are two points which need special attention. First, it is not possible to edit a suspended function. (For a descrip- tion of suspended functions and how to reset them, see ``The State Indicator''.) Second, if the function header (first line of the function) contains a syntax error, APL will not read in the function. In general, this means that the August 14, 19113 - 8 - function is no longer defined in the workspace, and the only other copy exists in a temporary file. In order to save you a lot of work retyping, APL will automatically copy the tem- porary file into a file called ``apl.badfn'' An example is probably called for at this point to clear the mud somewhat. The following shows the creation of the function ``fact'' which computes factorials by multipli- cation. )editf fact [new fn] XED 0 lines >a [ 0 ] n { fact+i [ 1 ] n { 1 [ 2 ] loop: } (i = 0) / 0 [ 3 ] n { n X i [ 4 ] i { i - 1 [ 5 ] } loop [ 6 ] . >w >q n { fact+i ^ syntax error Function saved in apl.badfn The error in line 0 (``fact+i'') caused APL to stop reading the function, so it was automatically copied to the file ``apl.badfn''. To get it back, you can say: )editf fact [new fn] XED 0 lines >r apl.badfn 5 lines >0s/+/ /p [ 0 ] n { fact i >w >q If you use ``)edit'' instead of ``)editf'', APL will not worry about saving the function in ``apl.badfn'' because you were editing from a UNIX file rather than the internal workspace, and that file still exists. 7. The State Indicator APL is a recursive language which supports local vari- ables. Therefore, it is essential that it maintain some August 14, 19113 - 9 - sort of information concerning its current state of execu- tion, local variables, and status of functions. Part of this information - the current status of active functions, is called the ``state indicator''.* Each time a function begins execution, APL keeps track of the current line number in that function. When the current function calls another function, the line number where the request was made is recorded in the state indicator. When a function terminates abnormally, it is said to be ``suspended''. This means that APL stops execution of the function, but retains all information about its current state of execution. In some cases, the problem can be corrected and the function restarted where it left off. This discussion will not include that technique. In any event, when the function is suspended, APL will print a traceback automatically, perhaps such as: varx: used before set at fn3[5] from fn2[12] from main[4] In this case, the error (undefined variable) occurred in the function ``fn3'' at line 5. ``fn3'' was called by the func- tion ``fn2'' at line 12, which in turn was called by the function ``main'' at line 14. The ``)si'' command produces a similar traceback. For the above example, the traceback could be: fn3[5] * fn2[12] main[4] This shows that the function ``fn3'' was suspended due to error, and that ``fn2'' and ``main'' are waiting for ``fn3'' and ``fn2'', respectively. When an error occurs and a function is suspended, all of that function's variables are accessible from the key- board. Thus, you can examine the current variables to help *Users of other APL systems should note that the state indicator as implemented on UNIX APL is similar in con- cept to the standard APL state indicator, but does not function entirely the same way. In particular, the system command ``)siv'' is not supported, and the state indicator is cleared in a different manner. Read on. August 14, 19113 - 10 - determine the problem. As stated above, in some cases it may be possible to change some variables and resume execu- tion of the suspended function. However, in general, after you examine the variables you will probably want to restart from the beginning. In order to do this, type the ``)reset'' command. This causes APL to clear the state indicator, resetting suspended functions and releasing local variables. If you do not use ``)reset'', you will find two things. First, if you get another error, the state indicator may look like: fn3[3] * fn2[12] main[4] fn3[5] * fn2[12] main[4] This shows that ``fn3'' was suspended due to an error at line 3, and it traces execution back to the start of ``main''. Then, it shows that in a previous run, ``fn3'' was suspended due to an error at line 5, and it traces exe- cution back to the start of ``main''. You can still use the ``)reset'' command to get back to a clear state indicator. The other effect which you will notice if you do not ``)reset'' the state indicator is that you will be unable to edit some functions. If a function is suspended (it appears in the state indicator), it cannot be changed, because it is possible that the error condition may be corrected and exe- cution resumed. Therefore, if you try to edit a function which appears in the state indicator, you will get the error message: si damage -- type ')reset' To edit the function, clear the state indicator with ``)reset'' first, and then you may proceeed with an ``)edit'' or ``)editf'' command. A useful technique for finding errors is to look at the function which ``blew up'' and try retyping the line which failed, a little bit at a time. This often helps isolate the problem. Generally, you want to do this before the state indicator is ``)reset'' so that the state of APL is exactly the same as it was when the error was detected. Since you cannot run the editor to list the function without typing ``)reset'', you will probably want to use the ``)list'' command to look at the bad function. August 14, 19113 - 11 - As an example, suppose your ``friend'' Chris (male or female, take your pick) gave you the following program to compute the reciprocal of the numbers from 1 to x: r { recip x [1] r { % Ix You are using origin 0, and your attempt to run the function yields the following: recip 10 recip domain at recip[1] It looks like Chris gave you a bum steer. You decide to try to debug the function. You can't use the editor to look at it with ``)editf'' unless you type ``)reset'' first. You don't want to ``)reset'', because that would take you back to the beginning and you would lose any temporary variables (in this case, just ``x''). Thus, you can use the ``)list'' command: )list recip y { recip x [1] y { %Ix Now, you can experiment with the function by typing the com- mands yourself: x 10 Ix 0 1 2 3 4 5 6 7 8 9 At this point, you immediately spot the trouble - APL was trying to take the reciprocal of 0. The function ``recip'' was written assuming that the origin was 1, but Chris did not tell you and you were using 0 instead. Thus, you merely say: )reset (now that you've found the problem, you want to reset APL to clear the state indicator), and )origin 1 was 0 recip 1.00000000e+00 5.00000000e-01 3.33333333e-01 2.50000000e-01 2.00000000e-01 1.66666667e-01 1.42857143e-01 1.25000000e-01 1.11111111e-01 1.00000000e-01 August 14, 19113 - 12 - 8. Special Functions 8.1. Quad Functions Quad functions are special operators that perform tasks which are closer to the system level, but are accessible within APL functins. There are many available quad func- tions in UNIX APL, but only two are probably of interest to you at this time. The interested user is referred to Appen- dix C for a complete list. []run xxx This function can be used to execute a UNIX process from inside an APL function. The variable ``xxx'' should be a character vector containing the command to be executed by the UNIX shell (command program). For example, to run the ``who'' program, the expression might be: []run 'who' x { 'who' []run x Note that any output generated by the program run by ``[]run'' is not written to a script file if ``)script'' was used. []cr xxx This quad function is a standard APL quad function. The argument ``xxx'' should be a character vector containing the name of an APL function which exists in the internal workspace. ``[]cr'' will return a character array containing the function definition in ASCII. This provides a very convenient way to get the listing of an APL function. For exam- ple, if you want to define the array ``fnlist'' to be the function definition of the function ``xyz'', you can say: fnlist { []cr 'xyz' or, equivalently, fnname { 'xyz' fnlist { []cr fnname Another possible use of ``[]cr'' is to list a function on the terminal without having to use ``)editf''. (As we discussed earlier, when an error occurs you cannot edit a suspended func- tion without using ``)reset'' first, and August 14, 19113 - 13 - ``)reset'' gets rid of the current state of APL.) However, the ``)list'' system command is far more efficient for this purpose and is therefore strongly recommended. 8.2. I-Beam Functions The I-beam function in UNIX APL is a method of obtain- ing system parameters. The available I-beams are listed in Appendix D for the interested user; they are not generally required for the average APL session. 9. What are those funny messages? You probably figured that at some point in this manual you'd see something about error messages. Unfortunately, errors do occur, and some of APL's error messages can really throw you. Users of other APL systems have little advantage over APL novices in this area, for UNIX APL error messages are, in general, nonstandard. To make matters worse, APL's status messages can be cryptic at times. Thus, in this sec- tion we'll explore some of the more common status and error messages. First, some of APL's less obvious and relatively common abbreviations are: asgn assignment cat catenation crc circle dfmt dyadic format dibm dyadic i-beam exec execute fn function imm immediate iprod inner product mdom monadic domino menc monadic encode miot monadic iota oprod outer product red reduction var variable There are three major types of error messages which may be generated as a result of an APL session. The error mes- sage may be the result of a fatal error in APL which has caused APL to abort, the result of some internal problem in APL, or an error produced by incorrect use of APL. 9.1. Non-fatal Error Messages Usually, APL can detect serious errors before they become fatal. When this occurs, it will issue an error August 14, 19113 - 14 - message but will not terminate. You can then take appropri- ate action. Unfortunately, unlike most APL implementations, UNIX APL does not report the position on the line where the error occurred. However, a traceback from the function in which the error occurred is printed. (See ``The State Indi- cator'' for more information on function tracebacks and error recovery.) As an example of this type of error, it is possible to completely fill up the internal workspace. Usually APL will not attempt to get more internal workspace memory if it already has the maximum permissible amount. It will then inform you: workspace exceeded Other possible messages of a similar nature are: directory botch save botch elid botch stack overflow pop botch In general, if an error message such as this occurs, you should save your internal workspace in a different file than you started from (in case it may have been ``corrupted'' or otherwise damaged by the error in APL), and then should exit APL and restart. You can then determine whether or not any- thing happened to your workspace, and can recover any losses from the original workspace file. These type of errors gen- erally occur as the result of some other error, such as a function which calls itself indefinitely or declaring an array which is too large for the workspace. By far, majority of non-fatal error messages produced by APL are not serious, but simply indicate some error in the definition or execution of a function. These errors fall into some common types: conformability The variable which you are passing to a function or operator does not ``con- form''. That is, it is not the proper shape (e.g. array has the wrong number of dimensions or a scalar is used instead of an array, etc.) For example, trying to add a 2X2 array to a 2-element vector will produce this error. botch A ``botch'' can occur for several rea- sons. Attempting to read a non-existant element of an array will produce a ``getdat botch''. (Storing into a non- existant variable or array element will August 14, 19113 - 15 - produce a ``putdat botch''.) domain A domain error means that somehow the variable passed to a function or opera- tor cannot be used. For example, attempting to take the logarithm of a negative number will produce a ``log domain'' error message. index A bad index was specified. A quick example of this error is to have ori- gin=1 and attempt to access A[0]. Attempting to concatenate two arrays along a non-existant dimension will pro- duce a ``cat index'' error message. syntax This error message is probably painfully familiar - it indicates that the indi- cated APL expression was not syntacti- cally correct. If this error occurs during the processing of a function, the traceback will show which line was incorrect. rank This type of error indicates that the argument to an operator or function has the wrong number of dimensions. As an example, if you attempt to declare an array with more than 8 dimensions, you will get a ``max rank'' error message. Some other common error messages do not fall into any of the above classes. These include: used before set This message means that a variable was referenced which had not yet been defined. An easy example: y { 2 z { x + y x: used before set no fn result This error occurs when an attempt is made to use the returned value of a function which doesn't return a value. As an example, if the function ``xyz'' returns no value, then the following sequence will result in an error: z { xyz no fn result August 14, 19113 - 16 - si damage This error message, discussed earlier, usually occurs when an attempt is made to edit a function which is suspended due to an error. Type ``)reset'' and then you may edit the function. can't open file t open file'u>(480u+1n) .br This error message occurs when a non-existant file is used for a ``)load'', ``)read'', ``)save'', etc. not a fn In most cases, an attempt to use a func- tion which has not been defined, or which has been defined as a variable, will result in a ``syntax error.'' There are some special circumstances in which this error will slip past the ordinary error-checking code. In the event this occurs, the message ``name: not a fn'' will be printed. 9.2. Fatal Error Messages In most cases, when APL detects that some irreparable damage has been done, it will print an error message of the form: fatal signal: message where the ``message'' represents a type of UNIX termination. The most common one probably is ``segmentation violation'', which means that APL needed too much memory for its internal workspace and was aborted in its attempt to get more than permitted in UNIX. Other possible messages include: quit illegal instruction trace trap emt trap bus error bad sys call write no pipe Despite the severity of the error, APL attempts to dump the workspace into a file named ``aplws.abort'' in order to facilitate recovery. This file should be viewed with suspi- cion. If another fatal signal occurs while this dump is being performed, APL will abort immediately, without com- pletely writing the file. Even if the dump was successful, the file format may not be internally consistent since APL was probably changing something when it was forced to abort. It is therefore advised that you restart APL and recover any information you need from this dump file, writing that information into a new workspace (see the description of the August 14, 19113 - 17 - ``)vsave'' system command in Appendix B). Never copy ``aplws.abort'' into your original workspace file without thoroughly checking it out. In some rare cases, APL is unable to print a termina- tion message, and the system aborts it. This usually will result in a message such as: Memory fault -- core dumped and the operating system will produce a file named ``core'' in your directory. This file is probably useless and you can delete it with: $ rm core 10. A ``startup'' function in APL? APL has a startup facility which allows automatic exe- cution of an APL expression when a workspace is loaded. If you define the variable ``[]lx'' to be some APL expression and then save the workspace, when you next ``)load'' the workspace, APL will automatically read and execute ``[]lx''. For example, if you have the function ``hello'' which looks like this: hello [1] 'hi there, my friend' [2] 'welcome to apl' and you want APL to perform ``hello'' when you load the workspace file ``hi'', you can say: []lx { 'hello' )save hi 14.59.31 10/26/78 saved hi )off Then, if you run APL with: $ apl hi you will get: a p l \ 1 1 25 oct 1978 14.59.31 10/26/78 loaded hi hi there, my friend welcome to apl August 14, 19113 - 18 - 11. UNIX APL\11 Limitations UNIX APL does have some limitations. Tracing, which is controlled by the ``)trace'' and ``)untrace'' commands, is not compatible with the standard APL trace facility. Some operators have not been implemented (for example, laminate is not supported). Dyadic format is available in a restricted form: the left argument cannot be a scalar or one-element vector and negative precision (``E format'') is not permitted. There is a function /usr/lib/apl/fn/dft which performs dyadic format according to the standard definition. Inner and outer product will not work with character data. Functions which are created with ``[]fx'' should not have the same name as existing variables; occasionally APL gets confused and mistakenly zaps a newly-fixed function. Functions containing overstrikes that were created by ``[]fx'' cannot be properly edited. The only quad variable which has been implemented is ``[]lx'', and it is always a global variable. The biggest limitation for PDP-11 UNIX APL is space. Despite efforts to use as much memory as UNIX and the com- puter itself permit, only about 5000 numeric values may be stored in an APL workspace. In order to permit workspaces containing more data, there is a second version of UNIX APL called ``apl2''. APL2 is used exactly the same way as APL - the only difference is that it uses single precision floating-point instead of double-precision. As a result, some precision is lost, but APL2 allows twice as many workspace items as APL. Although APL2 and APL workspaces are in different formats, APL and APL2 will convert each other's workspace files they are loaded with ``)load'' or merged with ``)copy'', so workspaces may be used interchang- ably. In all other respects, the operation of APL2 is identical to the operation of APL. (On the VAX 11/780, the size of the workspace is essentially limited only by the virtual memory system. Hence, APL2 provides no real advan- tage over APL). Finally, an unfortunate restriction in using APL on both PDP-11's and VAX-11/780's is that workspaces are not directly interchangeable between machines. However, there is a program to convert them. To convert a PDP-11 workspace to the VAX, run (on the VAX) the command: $ aplcvt filename The workspace will be converted to VAX format and placed into the file ``filename.vax''. Similarly, you can convert VAX format workspaces to PDP-11 format by running ``aplcvt'' on a PDP-11. (There are other options available; for a August 14, 19113 - 19 - description of these see the online manual by typing $ help aplcvt $ man aplcvt 12. Conclusion Well, that wraps up this manual. Reference information about APL is found in the online manual. Type: $ help apl $ man apl for the online document. Good luck with APL! August 14, 19113 - 20 - Appendix A - The APL\11 ASCII Character Set Note that the ASCII character set for APL uses both upper-case and lower-case. a-z letter 0-9 digit ` negative sign '--' string C J C comment ( ) [ ; ] indexing L quad L ' quote quad dyadic monadic ------ ------- + add plus - sub negate X mult sign % div reciprical | mod absolute value D min floor S max ceiling * pwr exp O * log ln (log base e) O circle funct pi times ' . combinatorial factorial ! combinatorial factorial ^ and V or ^ ~ nand V ~ nor < lt > gt $ le & ge = eq # ne ~ not ? deal random number R rho rho I iota iota E epsilon N encode B decode \ O transpose transpose , catenate ravel * Y take U drop { assign } goto B N i-beam i-beam August 14, 19113 - 21 - L % matrix div matrix inverse | H grade up * G | grade down * B J execute N J format / compress * / - compress \ expand * \ - expand O | rotate reverse * O - rotate reverse op / reduce * op / - reduce J.op outer product op.op inner product * may be subscripted with a scalar backspace (ctrl h) August 14, 19113 - 22 - Appendix B - APL\11 System Commands The following is a complete list of APL system commands. )clear This command is used to completely initialize an APL workspace. Usually when APL is started, it will print: ``clear ws''. This means that no internal variables or functions are defined. Sometimes, it is desirable to completely erase everything, and this command serves that purpose. To let you know that everything has been erased, APL will output the message ``clear ws''. )code fn This command causes APL to print the compiled internal code for the function ``fn''. This is intended for APL system development and not for general use. )continue ``)continue'' is a combination of the ``)save'' and ``)off'' commands (see below). The internal workspace is saved in a file named ``continue'', and then APL is ter- minated. Since APL will by default look for the file ``continue'' in the current directory when it is next run, this provides a con- venient method of suspending and resuming an APL session. )copy xxx This command instructs APL to locate the UNIX file ``xxx'' and load it into its internal workspace, similar to the ``)load'' command (see below). The difference between ``)load'' and ``)copy'' is that ``)load'' will replace the current internal workspace with the one being read in, while ``)copy'' merges the current internal workspace with the one being read in. Functions and variables which are loaded from the file take precedence over functions and variables of the same name existing already in the internal workspace. )digits n This command is used to specify to APL how many digits are to be displayed when a number is printed in floating-point or exponential format. By default, APL will print 9 digits. You may specify any number between 1 and 19 for the number of digits (n). APL will respond with the number of digits it was using. )debug This command invokes ``debug mode.'' In this August 14, 19113 - 23 - mode, every action which APL takes is logged on the terminal. This mode is excellent for generating reams of hopelessly cryptic output and exists only to facilitate APL development. It is not intended for general use. Debug mode can be turned off by issuing the ``)debug'' system command a second time. )drop list This command performs the same function as ``rm'' in UNIX. The names of the files to be deleted should be separated by spaces or tabs. The files may be APL workspaces, ASCII files, or any other type of UNIX file. )editf xxx This command is used to create and edit func- tions. If the function named ``xxx'' exists in the workspace, APL will write it into a temporary UNIX file and then will execute the UNIX editor on that file. When you have fin- ished editing the file, and you exit the edi- tor, APL will come back and will read the function from the temporary file. )edit xxx This command is similar to ``)editf'' except that ``xxx'' is a UNIX filename. APL will execute the editor to edit the UNIX file named ``xxx'', and when the editing is complete, APL will read that file into the workspace. The difference between ``)edit'' and ``)editf'' is that ``)editf'' essentially edits functions directly from the workspace, while ``)edit'' gets the functions from the UNIX directory. )erase list This command is handy when it is desirable to get rid of parts of a workspace without using ``)clear'' to eliminate all of it. A list of function and variable names (separated by spaces or tabs) may be specified. The named functions and variables will be deleted from the internal workspace. The remainder of the workspace will not be affected. )fns This command causes APL to list the names of all of the functions which are defined in its internal workspace. )lib This command is similar to the ``ls'' command in UNIX. It causes APL to list the names of all of the UNIX files in the current direc- tory. )list xxx This command causes APL to print out the func- tion named ``xxxx''. This is very handy for looking at a function without having to use August 14, 19113 - 24 - the editor - especially when an error has occurred and you wish to look at a function without disturbing the state indicator. )load xxx This command is used to instruct APL to load the UNIX file ``xxx'' as a workspace. After the file is loaded, APL's internal workspace will be the same as it was when the workspace file was saved with ``)save'', and that previ- ous APL session may be resumed. If the workspace file exists and is successfully loaded, APL will print the time and date that the workspace was last saved. )off This command terminates the APL session. The UNIX command program will come back and print its prompt (``$ '' or ``% ''). )origin n This command is used to change the ``origin''. By default, the origin is 1. The ``origin'' is the starting index for arrays. For exam- ple, if the origin is 0, then the first ele- ment of a 3-element array A is A[0]. If the origin is 5, the first element will be A[5]. Although standard APL permits only 0 or 1 for the origin, UNIX APL allows any integer value. APL will answer with the origin it was using. )prws This command causes APL to print the contents of the workspace in a readable format. Non- scalar variables are displayed along with their dimensions; functions are displayed as via the ``)list'' system command. )read xxx At times it is desirable to read a function which is stored in an ASCII file into the internal workspace. The ``)read'' command causes APL to read the UNIX file named ``xxx'' into the workspace as a function. Note that ``)read'' and ``)load'' (see above) are not the same thing. ``)load'' reads a complete new workspace into APL from a workspace-format file, while ``)read'' reads a function from an ASCII file and adds it to the current workspace. )reset This command is used to reset the state indi- cator. All suspended functions are reset; the state indicator will be cleared. APL returns to the global level. )save xxx This command causes APL to write its internal workspace into a UNIX file. This allows the current session to be resumed at a later time. August 14, 19113 - 25 - If the save is successful, APL will output the date and time. )script xxx This command places APL into a ``protocol'' mode. Following this command, APL will copy all input from the terminal and output to the terminal to the file ``xxx''. Thus, ``xxx'' is a complete transcript of the APL session. To turn off the script file, type ``)script off''. The protocol file which is produced will contain all of the output produced by APL itself, but will, unfortunately, not contain any output produced by another process (such as the editor). )shell This command is useful when it is desired to return to UNIX temporarily without having to save the current internal workspace, exit APL, and later re-enter APL and reload the workspace. ``)shell'' causes APL to execute the UNIX ``shell'' program (command inter- preter). When you have finished with the shell, logout and you will be returned to APL. )si This command is useful when something goes wrong. When an error occurs, the function that was executing is ``suspended''. The ``)si'' command causes APL to print a trace- back of the suspended functions. Each func- tion is listed, in the reverse order that it was called. The current line number for each function is also printed. Functions followed by an asterisk (``*'') were suspended due to an error; these were called by functions listed on the following lines whose names are not followed by an asterisk. )trace This command turns on APL's internal ``trace'' mode. When tracing is turned on, APL will report the function name and line number of each line in every function executed. Thus, the flow of execution from the start to the end of a run can be followed. )untrace This command turns off ``trace'' mode. )vars This command causes APL to list the names of all of the variables which are defined in its internal workspace. )vsave xxx This command allows parts of a workspace to be saved. The functions and variables which are specified will be saved in a UNIX file in the same format as produced by ``)save'' (see August 14, 19113 - 26 - above). APL will prompt for the names of the functions and variables to be saved. When you have entered the last name, type a blank line to end the save operation. The workspace you have created with ``)vsave'' may be loaded with ``)load'' at some later time. ``)vsave'' does not affect variables in the internal workspace. )width n This command tells APL to print n characters per line. This is useful to keep output from being printed outside of the physical terminal width. Lines longer than this length will be ``wrapped-around''. APL will respond with the previous terminal width. )write xxx This command is the complement of ``)read'' (see above). It takes the function ``xxx'' from the current workspace and writes it to an ASCII file named ``xxx''. This is useful for writing functions which will be ``)read'' later into other workspaces. Note that ``)write'' and ``)vsave'' are not the same thing, for ``)write'' is used to write a func- tion into an ASCII file while ``)vsave'' saves a selected subset of the internal workspace in a workspace-format file. August 14, 19113 - 27 - Appendix C - APL\11 Quad Functions The following standard quad functions are available in UNIX APL: []cr 'name' The result of ``[]cr'' is a charac- ter array containing the function whose name is passed as an argument. []fx newfn The contents of the character array specified as an argument are fixed as an APL function. []nc 'arg' This function can be used to deter- mine what type of variable an APL symbol is. The apl symbol must be specified inside quote marks, as shown. The returned value will be: 0 - symbol is undefined 2 - symbol is a label or variable 3 - symbol is a function name 4 - unknown type (should not occur) []nl arg The argument should be a scalar or vector with components 1, 2, or 3. This function returns a two- dimensional character array contain- ing the names of all items whose types are specified in the vector (same type definitions as for ``[]nc'' above). The ordering of names in the matrix is fortuitous. The following non-standard quad functions are defined: fd []ap 'string' This quad function is used to append a character string onto the end of a UNIX file. The first argument specifies the file descriptor of the file (which should have been opened earlier). The second argument is a character array which is to be appended. A carriage return is automatically appended to the end of each row of the character array when it is appended to the end of the file. []chdir 'directory' This quad function can be used to change APL to another directory. August 14, 19113 - 28 - Normally, APL runs in the directory that you were in when it was started by the ``apl'' command. The argu- ment is a character vector specify- ing the new directory (there is NO way to default this). A 0 is returned if the ``chdir'' was suc- cessful; a -1 is returned if it failed. []close fd This function complements ``[]open''. The argument is the file descriptor of a UNIX file to be closed. This function returns 0 for success or -1 for failure. mode []creat 'file' This function creates a UNIX file. If the file already exists, it is truncated to zero length. The crea- tion mode is specified as the first argument The filename is specified in a character vector as the second argument. The file descriptor of the created file (or -1 for error) is returned. []dup fd This function executes the ``dup'' system call. It returns an integer number which may be used as a file descriptor on later I/O calls. The new file descriptor is a duplicate of the argument ``fd''. If the argument file descriptor could not be duplicated, -1 is returned. []exec matrix Takes a two-dimensional character matrix and formats it into a UNIX ``exec'' system call. The matrix passed as an argument must be two- dimensional, the rows must be zero terminated. []exit code This quad function is used to ter- minate the execution of the current process, with the completion code ``code''. It should be used to ter- minate child processes and can be used to terminate an APL session; however, it is recommended that the system command ``)off'' be used for that purpose. []float charvect This quad function is useful in con- junction with ``[]write'' and August 14, 19113 - 29 - ``[]read''. Although any type of data may be written to a UNIX file with ``[]write'', when it is read with ``[]read'' it will be inter- preted as character data. This function will convert a character array into numeric form. The array must be a multiple of 4 elements long for apl2 and 8 for apl. The converted array is the returned value. []fork xx ``xx'' is a dummy argument. A ``fork'' system call is performed. This quad function probably will be followed by a ``[]exec'' quad func- tion. The process-id of the child is returned to the parent; a zero is returned to the child. pid []kill signal This function executes the ``kill'' system call. The first argument specifies what process is to be sig- nalled. The second argument speci- fies what signal is to be sent. A 0 is returned for a successful ``kill''; -1 is returned if the specified process could not be found or is not owned by the current user. mode []open 'file' This function is dyadic. It opens a UNIX file for use by an APL function with calls via ``[]read'' and ``[]write''. The first argument is the mode for the open (0=read, 1=write, 2=read/write). The second argument is a character vector con- taining the file name. The file descriptor of the opened file is returned (-1 for error). []pipe xx This quad function can be used to set up a pipe (used for interprocess communication) It returns a 2- element vector containing the two ``pipe'' file descriptors. []rd fd This function reads one line from the file descriptor specified. If the line is completely blank, a null string is returned. An end-of-file will also return a null string. Otherwise, the returned value is the character string which was read. August 14, 19113 - 30 - []rm 'filename' The specified file will be removed, equivalent to )drop filename. A 0 is returned for a successful remove; -1 is returned if the file could not be removed or does not exist. fd []read nbytes This function reads a specified number of bytes from a designated file. The first argument is the file descriptor; the second is the number of bytes to be read. The data which is read is returned. Note that the returned vector is always character data - to convert to numeric format see the function ``[]float''. []rline fd This quad function is identical to ``[]rd'', described above. []run 'unix command' The argument passed to ``[]run'' is executed as a UNIX shell command. []seek (fd,pos,mode) This function executes the ``seek'' system call on a UNIX file. The argument to ``[]seek'' is a three- element vector containing the file descriptor, seek offset, and mode A 0 is returned for a successful seek; -1 is returned if an error is detected. signal []sig action This quad function allows signal processing to be turned on and off under APL function control. The first argument is the signal whose processing is to be changed. The second argument specifies how the signal will be processed - if zero, the signal will cause termination of APL and a possible core dump; if non-zero, the signal will be ignored. Note that the special way in which interrupts and other sig- nals are processed by APL is turned off by a call to ``[]sig'' and can- not be turned back on. A -1 is returned on error, a positive number or zero for success. []wait xx This quad function is used in con- junction with ``[]fork'' - it returns a 3-element vector of infor- mation about a child process which August 14, 19113 - 31 - has terminated. The first element is either the process-id of a com- pleted child process or -1 (no chil- dren). The second is the status of the dead process, and the last is the completion code. fd []write data This function writes data to a specified file. The first argument is the file descriptor; the second is the data to be written. The number of bytes written is returned as the count. Any type of data (character or numeric) may be writ- ten in this manner. August 14, 19113 - 32 - Appendix D - APL\11 I-Beam Functions The following monadic i-beam functions are available: 20 This i-beam returns the time-of-day as the total number of 1/60 seconds which have elapsed since midnight. Division by 60 gives the number of seconds since mid- night, etc. 21 This i-beam returns the total amount of CPU time used by the current APL session in 1/60 seconds. This includes the amount of time spent by the system per- forming I/O (sys time) and computational time (``user'' time). 22 This i-beam returns the number of 8-bit bytes which are left in the workspace. However, this value is not really meaningful since the in-core workspace will be expanded, if possible, when full. 24 This i-beam returns the time-of-day (in 1/60 seconds) when the current APL session was begun. 25 This i-beam returns the current date as a 6-digit number of the form mmddyy. Thus, February 23, 1978 would be 022378. 26 This i-beam returns the line number in the function currently being executed. Thus, if it is used in line 3 of a function, it will return 3. 27 This i-beam returns a vector of the line numbers in pending functions (functions which called the current function and are waiting for its completion). 28 This i-beam returns the date (as a 6-digit number, mmddyy) when the current APL session began. 29 This i-beam returns the current origin, set by the ``)origin'' system command. 30 This i-beam returns the current width, as set by the ``)width'' system command. 31 This i-beam returns the current number of digits to be displayed, as set by the ``)digits'' system command. 32 This i-beam returns the number of workspace bytes which are being used. It is the complement of i-beam 22, which tells how many bytes are unused. Thus, the max- imum workspace size (in bytes) can be calculated by August 14, 19113 - 33 - adding i-beams 22 and 32. 36 This i-beam returns the second element of the vector returned by i-beam 27 - that is, it returns the line number of the function which called the current func- tion. 40 This i-beam returns the total amount of CPU time spent by any child processes of APL. Children of APL include the editor, the shell if ``)shell'' is used, anything run by ``Lrun'', and any processes executed using ``Lfork''. 41 This i-beam returns the total amount of ``user'' time spent by APL and all of its children. 42 This i-beam returns the total ``system'' time spent by APL and all of its children. 43 This i-beam returns the total amount of ``user'' time (computational time) spent by APL. 44 This i-beam returns the total amount of ``sys'' (I/O and other system calls) time spent by APL. 95 This i-beam causes APL to print out its namelist table. It is intended for system development of APL. 96 This i-beam causes APL to dump its stack on the termi- nal. It is intended for system development of APL, and is probably useful only in generating a big messy- looking display. 97 This i-beam returns the total number of elements on APL's internal stack. It is intended for system development and debugging of APL itself. 98 This i-beam function turns off the trace of all memory allocations and deallocations which i-beam 99 turns on. It returns a 1 if the trace was on, and a 0 if it was off already. 99 This i-beam turns on the alloc/free trace mentioned above, which i-beam 98 turns off. It also returns a 1 if the trace was already on, or a 0 if it was off. The following dyadic i-beam functions were implemented to compensate for the lack of sufficient quad variables. They may be subject to future change. The function is specified by the right argument, the left argument is a parameter to that function. The available i-beams are: August 14, 19113 - 34 - 29 This i-beam may be used to set the origin to any per- mitted value. The left argument specifies the new ori- gin, and the previous origin is returned. 30 This i-beam may be used to set the terminal width to any permitted value. The left argument specifies the new width, and the previous width is returned. 31 This i-beam may be used to set the number of digits displayed to any permitted value. The left argument specifies the new number of digits, and the previous value is returned. 34 This i-beam implements the system ``nice'' function. The ``nice'' of the APL process will be set to the value specified by the left argument. A zero will be returned for success, a -1 is returned for failure. This is intended for background processing, not interactive use of APL. 35 This i-beam implements the system ``sleep'' function. APL will suspend itself for the number of seconds specified (by the left argument). The value returned is the value of the left argument. 63 This i-beam implements the system ``empty'' function. The left argument specifies a file descriptor of a pipe. If the pipe is empty, a 1 will be returned, if not-empty, a 0 will be returned. A -1 will be returned if the file descriptor is illegal or is not a pipe. 90 Normally, APL will not exit if it reads an end-of-file from a terminal. This safety feature may be disabled by using i-beam 90 with a zero left argument. A non- zero left argument restores the requirement that the user exit with ``)off'' or ``)continue''. [Note: this feature cannot be enabled if the input device is not a terminal.] 99 This i-beam causes the buffered version of APL to flush the buffer associated with the file descriptor speci- fied as the left argument. A 0 is returned for suc- cess, -1 for failure. In unbuffered APL, 0 is always returned and no action is taken (since the command is meaningless). Note that flushing a pipe used for input may cause information to be lost. August 14, 19113