Digital PDFs
Documents
Guest
Register
Log In
AA-GV09C-TE
June 1991
622 pages
Original
29MB
view
download
OCR Version
24MB
view
download
Document:
VAX APL Reference Manual
Order Number:
AA-GV09C-TE
Revision:
000
Pages:
622
Original Filename:
OCR Text
VAX APL Reference Manual AA-GV09C-TE June 1991 This reference manual describes the VAX APL functions, operators, variables, and system commands. Revision/Update Information: This revised document supersedes the VAX APL Reference Manual Vols. 1&I1 . Operating System: 9=y Software Version: Digital Equipment Corporation Maynard, Massachusetts : VMS Version 5.4 VAX APL 4.0 AR -PI4 2D TE 7 aA- GNPAB-TE The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (¢)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1982, 1983, 1985, 1987, 1991. All Rights Reserved. The Reader’s Comments form at the end of this document requests your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: DEC, DECnet, DECwindows, DECstation, VAX, VAXcluster, VMS, VT102, VT220, VT240, VT320, VT330, VT340, and the DIGITAL logo. HDSAVT, HDS201 and HDS221 are trademarks of Human Design Systems, Inc. Tektronix is a trademark of Tektronix, Inc. Contents Preface 1 ooooooooooooooooooooooooooooooooooooooooooooooooooooo Xi VAX APL Primitive Functions and Operators i 1-2 ... . .. 1-10 1.1.1.1 + Conjugate . ...... ... e 1-10 1.1.1.2 - Negative . . ... ... ... e 1-11 1.1.1.3 X SIGNUML . . . ..t 1-11 1.1.1.4 s Reciprocal . . . ... ... ... ... 1.1.1.5 » Exponential ........... ... ... . . i i, 1-11 1.1.1.6 1.1.1.7 e Natural Logarithm ............................ o PiTimes . ... . e 1-12 1.1.1.8 L Floor . . . . e 1-12 1.1.1.9 [ Ceilling . ... 1.1.1.10 1.1.1.11 | Magnitude .......... ... ...t ' Factorial . . ... .. e e e 1-14 1.1.1.12 2 Roll . .. e 1-14 1.1 Primitive Scalar Functions. 1.1.1 1.1.1.13 . .. . .. ... Arithmetic Functions . . . ... .. e e i e i e e 1-11 e e e e 1-12 1-13 .. 1-14 +, -, x, and + Addition, Subtraction, Multiplication, and e 1-16 e 1-16 .. 1-17 1.1.1.16 1.1.1.17 1.1.1.18 o Circle . .. ... e e e e L MINImMuIN . . .t ottt e e e e et e et et e et e e e [ Maximuml . . . .t ot o e e e e e e e e e e e e e 1-17 1.1.1.19 | Residue. .. ... e e e e et e e 1-18 1.1.1.20 P Combinations . . . ... . e e 1-19 1.1.2 Logical Functions . . . ... ....... ... .. . . i, 1-21 1.1.3 Relational Functions . .. ...... .. .. . @ . ... 1-22 DIVISION . .. . ot e e e 1.1.1.14 P OWET . . o e e e e e e 1.1.1.15 e Logarithm . .. ... ... ... ... ... . .. . . i i i e i e e 1-18 1-18 1.2 1-22 1 1-27 oooooooooooooooooooooooooooooooooooooooooooo ¥ 1-31 ------------------------------------------- and ; Catenate/Laminate. ... ... ... ... .. . . . . . . . . .. ... 1-34 Contains . . . . . o e e Deal . Depth 1-45 oooooooooooooooooooooooooooooooooooooooooooo 1-47 oooooooooooooooooooooooooooooooooooooooooooo 1-49 oooooooooooooooooooooooooooooooooooooooooo 1-58 oooooooooooooooooooooooooooooooooooooooooooo Enclose . . ... . 1-63 Enlist 1-69 oooooooooooooooooooooooooooooooooooooooooooo 1-70 e m Drop . 1-77 oooooooooooooooooooooooooooooooooooooooooooo 1-79 o < Monadic Grade Down . .. ...... ... a Dyadic Grade Down . ........ ... ... ... ... ... . ... ...... B Monadic Grade Up .. ....... ... . ... . ... 1-96 B Dyadic Grade Up .. ...... ... .. ... . . . . . ... 1-99 -~ Index Generator .. ........ ... .. .. . .. . . .. ... ... 1-105 Index Of . .. ... .. 1-107 - DyadicFormat .......... .. .. ... ... ... . . . .. . .. ... ... — <o > [[X 1-74 First . ... ... ... . .. .. ..... ooooooooooooooooooooooooooooooooooooooo oW 1-82 1-90 1-110 I 1-113 1-116 3 oooooooooooooooooooooooooooooooooooooooooooo 1-87 - 1-119 o Represent . ... ... v Reshape .. ... ... and ¢ Reverse and e Rotate Shape £ > In Ravel e oooooooooooooooooooooooooooooooooooooooooooo 6 . o U m 1-121 Pick oooooooooooooooooooooooooooooooooooooooooooo .. . . ... . e e .. . . . . ..................................... oooooooooooooooooooooooooooooooooooooo ............................................ ooooooooooooooooooooooooooooooooooooooooooo ............................................ 1-123 1-130 1-135 1-138 1-141 1-145 1-149 1-152 1-154 1-161 & Dyadic Transpose . ... ... . . . . .. ... 1-164 U Union . ... e 1-170 U UNIque . ... 1-172 ~ Without 1.3 ... e . .... ... .. . APL Operators . . . ... 1-174 ... . . . 1-176 /and # Slash .. ..... .. . ... . . .. 1-178 \and X Backslash........... ... ... ... ... ... ........ 1-178 1.3.3 . The Dot Operator . ... ........ ... .. . .. ... . .. ..... 1-178 and # Compression and Replication . .. .................. 1-179 and # Reduction . . . .. ... ... . . . 1-185 T~ 1.3.1 1.3.2 1-191 \ and X Expansion ........... .. .. . .. .. ... .. . Vand N Scan .... e 1-201 o. fOuter Product ......... ... . . ... . ., 1-205 f. glnner Product .. ....... ... ... .. ... . ... ... . ... . ... 1-208 [ AXIS . . 1-212 +< Specification Function .............. ... .. ... ......... Strand Assignment with the Specification Function 2 1-196 1-215 ........ .. 1-218 Selective Assignment with the Specification Function . ... ... .. 1-221 VAX APL System Variables and Functions 2.1 System Variables . ... ....... ... .. ... ... . . . . 2.1.1 System Variable Names . .. .. ... ... .. ... 2.1.2 System Variable Characteristics 2.2 System Functions. 22 .......... e 22 .. ...... ... . . . . . . .. . . . .. 2-3 .. .......................... 24 2.2.1 System Function Names 2.2.2 Types of System Functions. 2.3 . . ......... ... ... ... ...... System Variables and Functions Reference .. ............... O0ATI Accounting Information 21 ... ......... ............................ OALPHA Alphabetic Characters 24 2-9 2-13 ... ....................... 2-14 OALPHAL Lowercase Alphabetics ... ...................... 2-15 OALPHAU Underscored Alphabetics 2-16 .. ..................... OARBOUT Arbitrary Output . ......... ... ... .. .. .. ....... 2-17 04Sc1II APL Approximation to the ASCII Character Set ... ... 2-19 O0A4SS Associating Files with Channels . . . .. ................ 2-20 0AUS Automatic Save of the Workspace . . .. .. .............. 2-28 OAV Atomic Vector . ... ... ... e 2-32 [1BOX Forming Character Matrices and Vectors . .. ........... 2-35 . . . i O0BREAK Suspending Execution .......................... 2—-38 O0CHANS Returning Channel Numbers ... ... ............... 2—-40 [1CHS Returning File Organization and Open Status . ......... 2—41 0cIQ and [0coQ Packing and Unpacking Data. .............. 2—-44 OcLSClosing Files . . .. ... ... ... ... ... . ....S 2-52 0 CR Obtaining a Canonical Representation . ................ 2—-54 O0cT Comparison Tolerance 2—56 ................ ... .00 ..u... OCTRL Control Characters . ... ........ ... ... .. ... . ...... 2-58 ODAS Deassigning Files ... ...... ... ... 2—60 ODcC Display Control ... ... ... ....... . ........ ... ... .. . . .. . ... 2—62 O0DL Delaying Execution. .. ........ ... ... ... ... ......... 2—-70 O0DML Maximum Record Length . ... ...................... 2—72 O0DVC Returning Device Characteristics . ... .........e 2—-74 OEFR OFEFS OEFC Event Flag System Functions ............. 2—77 OFRROR Exror Message ... ... ..o 2—-80 iiiie e OFX Erasing a Named Object. . . ......... ... ... ... ......... 2—-83 O0EXP Expansion . 2—-85 ooooooooooooooooooooooooooooooooooooo O0FI Converting Characters to Numerics ................... 2—88 O0FLS Returning File Information ........................ 2-91 ............ ... ... ... ......... 2-93 OFx Establishing an Operation .......... ... ... .......... 2-98 OFMT The Report Formatter O0GAG Preventing Interruptions .......................... 2-100 0I0 Index Origin 2—-102 ooooooooooooooooooooooooooooooooooooo 0L Monitoring Variable Changes .. ....................... 2—-104 0LC Line Counter 2—-106 OLX Latent Expression ........... ... . . . . . . . .. . ... .... O0MAP Defining External Routinesto APL 2-111 OMBX Mailbox System Function . ... ...................... 2-120 OMONITOR Gathering Data on Operations . ................. 2—122 [0NC Returning a Name Classification ..................... 2—-126 ONG Print High Minus .. ............. .. ... . 2-129 ONL Constructing alastof Names . ... ....... ... ... u..... 2—-131 ONUM Digits . ... oooooooooooooooooooooooooooooooooooooo 2-135 O0oM Indexing a Boolean Vector .......................... 2—136 0 PACK Packing and Unpacking Data .. .......... e 2-138 OPP Print Precision . .................... e 2—-142 0 PwW Print Width Vi 2—-108 . ... .............. e e e e ..................................... 2—-144 0Qco Copying Objects from a Workspace . . .. ... ............ 0QLD Loading a Workspace ooooooooooooooooooooooooooooo 2-147 2—-151 0Q@PC Copying Objects with Protection . . . . ................. 2—-154 OR Monitoring Variable Changes . ........................ 2—-157 ORELEASE Unlocking Shared Records . .............. e 2—-159 OREP Replication ........ 2-161 ooooooooooooooooooooooooooooo ORESET Resetting the State Indicator ..................... 2—-164 OREWIND Returning Next-Record Pointer to Start of File . .. ... 2—-165 ORL Link .............. 2—-168 0SF Quad Input Prompt .. O0SIGNAL Signaling Errors . 0SINK Discard Output. . .. 0SS String Search .. ..... ooooooooooooooooooooooooooooo ooooooooooooooooooooooooooooo ooooooooooooooooooooooooooooo ----------------------------- ooooooooooooooooooooooooooooo 2—-170 2-172 2—-176 2-177 0 STOP Suspending Operation Execution . .................. 2—-179 O TERSE Terse Error Messages . . ... ...................... 2—183 OTIMELIMIT User Response Time Lomat . . ................. 2-185 OTIMEOUT Time Limit Report ... ... . ... .. ........... 2—-188 0 TLE Terminal Line Editing Characteristics ................ 2-190 [0 TRACE Monitoring Operation Execution. .................. 2—-192 0 TRAP Trap Expression . .. 2—-195 O07s Time Stamp ........ 07T Terminal Type ... ooooooooooooooooooooooooooooo ooooooooooooooooooooooooooooo ...... OuL User Load . ......... 2—198 ooooooooooooooooooooooooooooo [0 VERSION Interpreter and Workspace Version .............. O VI Validating Input . . ... 0 VPC Vector Process Control [1 VR Visual Representation. OwA Workspace Available . . 2-197 2—201 2—-202 2—203 oooooooooooooooooooooooooooo ooooooooooooooooooooooooooooo ooooooooooooooooooooooooooooo OWAIT Limiting Time on Read Functions 2—-205 2—-207 2-210 .................. 2—211 OWATCH Monitoring Variable Changes .. ............ ... ..., 2—-214 0xQ Executing Expressions 2-221 ooooooooooooooooooooooooooooo Vi 3 VAX APL System Commands 3.1 System Command Form....... 3.2 System Command Categories . . . ooooooooooooooooooooooooo ooooooooooooooooooooooooo 32 32 3.2.1 Query System Commands . . 3.2.2 Query/Change System Commands . .................... 3-3 3—4 ooooooooooooooooooooooooo 3-3 3.2.3 APL Action System Commands ....................... 3.2.4 System Commands that Initiate System Action. .......... 3—4 3.2.5 Workspace Manipulation System Commands . ............ 3-5 3.3 System Command Reference . .. 3-5 )ATTACH Interacting with Other Processes ................. ) CHARGE Displaying Accounting Information................ 3-10 ) CLEAR Clearing the Active Workspace . ................... 3—11 ) CONTINUE Saving the Workspace and Ending the Session . . . .. 3-13 ) COPY Copying Objects from a Workspace . ................. 3-15 )DIGITS Output Precision. . ... 3—-17 ) D0 Executing a DCL Command - . » L - - - - > - * * L) - . 9 # & & o 5 & + 2+ = ------------------------- ) DROP Deleting Stored Workspaces or Files . . . . . ........... 3—21 ) EDIT Editing with VAXTPU . . . 3-22 ) ERASE Erasing Global Names ooooooooooooooooooooooooo . 3-28 ) FNS Displaying a List of Functions ...................... 3—31 ) GROUP Defining or Dispersinga Group ................... 3-33 ) GRP Displaying the Members of a Group . ... .. [ 3—-35 ) GRPS Displaying a List of Groups ....................... 3—-36 ) HELP Obtaining Help on the VAX APL Language ........... 3—-38 ) 3—-45 INPUT Diverting Input to Another Device ... .............. ) LIB Listing Workspace Names . ) LOAD Retrieving a Workspace . ¢ 4 & 4 s & 2 & s s e+ 2 s & e + e & s e e e v v 0w ......................... )MAXCORE Determining the Maximum Workspace Size . ..... .. 3—-47 3-50 3-53 )MINCORE Determining the Minimum Workspace Size ........ 3-54 ) MON Returning to Operating System Command Level ... ... .. 3—56 ) NMS Displaying Names in the Symbol Table .. ............. 3-57 ) OFF Terminating the APL Session ....................... 3—-60 )OPS Displaying a List of Operators ...................... 3—-62 )ORIGIN Determining the Index Origin.................... 3-64 )OUTPUT Diverting Output to Another Device . . .. ........... 3—-65 ) OWNER Displaying Information About Workspace Creation 3—-68 ) PASSWORD Workspace Password viii 3-19 . ... ooooooooooooooooooooooooo 3—-70 ) PCOPY Copying from a Workspace with Protection. .......... 3—74 ) . ............. 377 ) SI Displaying the State Indicator ... .................... 3-80 ) SIC Clearing the State Indicator .. ... ................... 3—-82 ) SINL Displaying the State Indicator and Local Symbols ... ... 3—83 ) SIS Displaying the State Indicator and Executing Lines . . . . . . 3—-84 ) STEP Executing Lines of a Suspended Operation............ 3—-85 ) VARS Displaying a List of Variables . . ... ................. 3—88 SAVE Saving a Copy of the Active Workspace ) VERSION Displaying the APL Version Number YWIDTH Output Width . ... ... .. ... A ............. . . .. ... . . ... 3-91 )WSID Workspace Identification . .. ... ....... ... ... ... ..... 3-93 )XLOAD Retrieving a Workspace 3—-95 ............. .. ... ....... Glossary Index Figures Argument Corners Selected by Take Function . . ... ....... [\)[\)[\).A_L_IL_L_L_L_L_L R O T ) L Tables WON=2NO O bW 3-90 ... System Messages 1-1 3—72 ) PUSH Interacting with Operating System Programs.......... Documentation Conventions Table . . ... ................ Arithmetic Scalar Functions .. ....................... Trigonometric Functions Performed by o .. .............. Determining Result for Dyadic ! . ..................... Truth Table for Logical Functions .. ................... Primitive Mixed Functions . . . . ........ ... ... ........ Dyadic Transpose Definitions . . . . ..................... APL Operators . . ........ . e System Variable Value Ranges . . ... ................... System Variables and Functions .. ... ...... ... ... ..... File Organization Qualifiers. . ... ..................... 2-4 it e e ettt e eee s 2-33 Type Parameter Values .......... ... ... .. ... . ..., 2-46 Elements of DAV(OI0<0) .o v vttt 2—6 Device Characteristics Longword . . ... .. .. e e 2—75 2—7 Characteristics of External Data Types . ................ 2-115 3—1 System Commands ooooooooooooooooooooooooooooooooo 3—-5 Preface This manual describes the VAX APL interpreter, including VAX APL language and programming elements, facilities for controlling the VAX APL environment, the interaction between VAX APL and the VMS operating system, and VAX APL’s I/O capabilities. Intended Audience This manual is intended for experienced APL programmers. This manual is not a tutorial and is inappropriate for novice users. Programmers experienced with other languages such as FORTRAN or BASIC can learn VAX APL from this manual, but are advised to study it in conjunction with an APL language primer. Related Documents The VAX APL User’s Guide describes the VAX APL interpreter and the environment in which it operates. The VAX APL Installation Guide contains instructions for installing VAX APL on the VMS operating system. The VAX APL Installation Guide also explains how to install QAPL, the license- free, execute only version of VAX APL. To find out more about the VMS system, refer to the VMS system documents listed in the Introduction to VMS or use the Help utility by entering HELP at the system prompt ($). The VMS DCL Dictionary and the Introduction to VMS System Management provide detailed information you may need to know to use some of the features of VAX APL. Product References In this document, VAX APL is referred to as APL. Xi Conventions The following conventions are used in this manual. Table 1 Documentation Conventions Table Conventions Meaning Default values used in The default value for the index origin (0I0)1s 1, unless explicitly stated to be 0. Numeric print precision (0 PP) examples is 10 digits. Enclosed arrays are displayed with boxes around enclosed items and with all values in the top left - corner of the display areas. This is done using: ODC« (T17123) Delimiting pairs This manual uses ntextn ; other delimiting pairs may be any of the following pairs: o UPPERCASE ' ++++]]--" Ll - . Uppercase words and letters, used in format examples, indicate that you should type the word or letter exactly as shown. A B K The APL characters 4, B, and X are used in generic descriptions of command formats. A represents a left argument, B represents a right argument, and x represents an axis argument. ttalics Italicized lowercase words and letters, used in format examples, indicate that you are to substitute a word or value of your choice. Quotation mark (') The term quotation mark refers to the APL single quotation mark (' ). The equivalence symbol means “is equivalent to”. I The double square brackets indicate that the item or string of items inside the brackets is optional. Individual ~ items within a string of items are delimited by the .ab character, which indicates that you may choose only one item from the string. | [ ] Single square brackets that appear in the format specification for a language element are required syntax for the element being described. (continued on next page) Xii Table 1 (Cont.) Documentation Conventions Table Conventions Meaning {1 Braces are used to enclose lists from which one item must be chosen. The items in such a list are delimited by the | character. For some user-defined operation headers, the braces are required syntax (this requirement is described in Chapter 3 of the VAX APL User’s Guide). n/a and n/s These abbreviations indicate that something is Not Applicable or Not Supported in the context being discussed. A horizontal ellipsis indicates that the preceding items can be repeated one or more times. A comma preceding the ellipsis indicates that successive items must be separated by commas. A vertical ellipsis indicates that not all of the statements in an example or figure are shown. Color Color 1in examples shows user input. <CR><LF> The <CR><LF> symbol indicates the presence of a control sequence representing a Carriage Return and a Line Feed. Ctrl/X The Ctrl/X symbol indicates that you must press the key labeled Ctrl while you simultaneously press another key, for example, Ctrl/C, Ctrl/Y, Ctrl/O. XXX A symbol such as indicates that you press a key on the terminal. For example, the symbol represents a single stroke of the Return key on a terminal. Unless otherwise noted: * All numeric values are represented in decimal notation. * You terminate commands by pressing the Return key. * All examples in the manual are executable, and comments beginning with the lamp (s ) symbol are part of the examples; comments surrounded by parentheses are not part of the examples. Xiii 1 VAX APL Primitive Functions and Operators VAX APL provides functions that allow you to perform various operations with arrays. These functions are termed primitive because they represent the basic capabilities of the language. You do not have to write programs to perform these operations; they are built in. That is, the APL interpreter already knows how to perform them. Primitive functions may be classified by the characteristics of their arguments and results. One distinction is whether a function is scalar or mixed. The APL primitive scalar functions perform scalar (or scalar-like) operations; the APL primitive mixed functions perform mixed-rank operations. Primitive functions are either monadic or dyadic. Monadic functions require only one argument, which is placed immediately to the right of the function. Dyadic functions require two arguments, one on either side of the function. Primitive functions also have a domain and a range. The domain of a function 1s the permissible type, shape, and values of its argument arrays; the range is the permissible type, shape, and values of its result array. In addition to describing the APL primitive functions, this chapter describes the APL primitive operators (operations that produce functions as results), and the specification function (a function used to associate values with identifiers). APL also provides functions for system communication and for I/0. These are explained in Chapter 2, Chapter 3, and in Chapter 5 of the VAX APL User’s Guide. APL Reference Manual 1-1 APL Primitive Functions 1.1 Primitive Scalar Functions 1.1 Primitive Scalar Functions The primitive scalar functions include the arithmetic, relational, and logical functions that almost everyone is familiar with—addition, subtraction, equality, and, or, and so on—plus a few operations that are less familiar, such as residue and roll. These functions are called scalar functions because they take scalar arguments and return scalar results. For example: 13 aFACTORIAL OF 3 The primitive scalar functions are extended on an item-by-item basis when the argument array is not a scalar (the argument can be any shape, simple or enclosed). In effect, APL operates on a sequence of scalar arguments and returns one value for each argument. This process is known as scalar product. For example: '3 45 6 24 7 21 AEACH ITEM IS TREATED AS A SCALAR 120 4 9 + 3 12 AEACH PAIR OF ITEMS IS ADDED Here, APL applies the factorial (! ) and addition (+ ) functions as if each item were a scalar argument. For factorial, each of the three items in the argument (a vector) returns a value. For addition, each corresponding pair of items is added. The results are just as if five statements had been entered as follows: 24 !5 120 4 + 3 9 + 12 7 21 Monadic scalar functions take only one argument, which is placed immediately to the right of the function. The shape of the argument determines the shape of the result. For example, a scalar argument returns a scalar result, and a vector argument returns a vector result. 1—-2 APL Reference Manual APL Primitive Functions 1.1 Primitive Scalar Functions Dyadic scalar functions have two arguments that must conform to each other. They conform if one of the following is true: e Their shapes match. e At least one of the arguments is a singleton. When the shapes match, the function is applied a number of times equal to the number of items in the arguments, and the resulting array has the same shape as the argument arrays. Each item in the left argument array is associated with the item that has the same position in the right argument array, and the result is placed in that same position in the resulting array. For example: ASHAPES OF BOTH ARGUMENTS CONFORM 123+123 2 46 ASHAPES DO NOT CONFORM 123+123H4 10 LENGTH ERROR 123+123%4 A When one of the arguments is a singleton, the shape of the result is the same as the shape of the nonsingleton argument. Again, the function is applied on an item-by-item basis, but either the right or left argument (whichever is the singleton) is the same each time the function is applied. For example: 2 3 4 6 7 8 1+ 123 aSINGLETON EXTENSION LEFT ARGUMENT 4 5 6 + 2 aSINGLETON EXTENSION RIGHT ARGUMENT [« 4 « 10 I (15 18 + 30 (8 4) 21) 30 |15 18 +---+ 21| | | o |8 u| poemt me+ 5 15 | | + A 4--=====------o- + 35 120 23 +----+ 26| | | |13 9} t----t | | m e+ fomm e APL Reference Manual 1-3 APL Primitive Functions 1.1 Primitive Scalar Functions When both arguments are singletons, the shape of the result is the same as the shape of the argument with the higher rank. For example: B<(1 1 C«<(1 1 p3) 1 p2) "B IS A RANK 3 SINGLETON nC IS A RANK 2 SINGLETON D«B + C ASMALLER RANK WILL D - ADISPLAY D, CONFORM TO LARGER A SINGLETON OF SHAPE 1 1 1 5 The primitive scalar functions are pervasive functions; that is, their operations extend pervasively throughout the depth of enclosed arrays: RBOTH ARGUMENTS HAVE DEPTH = 0« A« 10 10 (15 4==---——mmmmmm- + |15 18 (8 u) 21) 3 30 30 18 +---+ 21| | | |8 vl | -t fom e + 0« B <« 5 5 pommmmmm |12 11 (3 3) 2) 25 25 11 +---+ 2| | | 13 3] pent fomm | | - ———m -4 A 5 (12 e+ - B 4mmmmmmmmm e+ |3 7 +---+ 19] | | 15 1 et 5 | R e+ The conformance rules for the arguments of the primitive scalar functions are also pervasive; APL does a conformance check at each level of enclosed arrays. During the check, APL performs singleton extension when necessary. The following example uses the dyadic minimum function (L ), which returns the smaller of two arguments: L o=t (5 3) L (26) 1 +---+ 12 4] |1 1] t-——+ +---+ In the preceding example, APL first pairs the corresponding items (through the process of scalar product). The pairs are 4| (2 6) and (5 3) | 1. Second, APL pairs the singleton argument with each element inside the enclosed arguments (through the process of singleton extension). These pairs are ( (412) (416) ) (3L1)). Finally, APL evaluates each pair of scalar arguments. and ((501) 1-4 APL Reference Manual APL Primitive Functions 1.1 Primitive Scalar Functions The following example shows two arguments that conform at the top level of their nesting, but do not conform at a lower level. This example uses the monadic enclose function (<), which encloses its argument, as well as the dyadic minimum function (L ). 4 (5 3) L <261 10 LENGTH ERROR 4 (5 3) L <261 A In the preceding example, APL first pairs the corresponding items. The pairs are 4| (2 6 1) and (5 3) L (2 6 1). Second, APL pairs the singleton argument with each element inside the enclosed argument. These pairs are ((ul2) (416) (uL1)). Third, APL recognizes the length error in the pair of enclosed arguments (5 3 and 2 6 1 ) and signals the error. (If one of these enclosed arguments had been a singleton, APL would have applied singleton extension.) Primitive scalar functions generally take numeric arguments. The argument domain for relational functions (<, >, <, >, =, =), however, includes both character and numeric arguments. The equal (=) and not equal (# ) functions can take both character and numeric arguments in the same expression. The result domain for all primitive scalar functions is a scalar numeric array. Primitive scalar functions return empty arrays when there 1s an empty argument (provided that APL does not detect an error before evaluating the result). For example: a10 ALWAYS GENERATES AN EMPTY ARRAY (APL outputs a blank line) 142+3+4+10 TAY <1 (APL outputs a blank line) nARGUMENT SHAPES DO NOT CONFORM (1 0 3p1) + 15 + 15 9 RANK ERROR (1 0 3p1) A You can specify an axis ([K]) with dyadic scalar functions. For example, this allows you to apply a vector to each row or each column of a matrix. The seneral form of axis is as follows: Af(X1B, where A and B are the arguments to f (a scalar function), and X is the axis argument. Note that k¥ specifies the axes of subarrays constructed from whichever argument has the larger rank. The argument of smaller rank is combined with these subarrays. APL Reference Manual 1-5 APL Primitive Functions 1.1 Primitive Scalar Functions For example, if you specify axes [1 37, then the shape of the subarrays of the larger rank argument is the lengths of that argument’s first and third axes, and the smaller rank argument has the same shape as these subarrays. When APL combines the two arguments, it does so along the second axis of the larger rank argument of scalar extension. The length of the second axis in this case 1s the number of subarrays involved. In all cases, the axis argument must be near-integer in the vector domain. The length of ¥ must be equal to the smaller of the ranks of the arguments, and the values in ¥ must be between the index origin and the larger of the ranks of the arguments (you cannot specify an axis that does not exist). The order of the items in the axis argument makes no difference; however, & may not contain duplicates. The arguments to the function f must conform by having their shapes match along the axes specified by x. The shape of the result is the same as the argument with larger rank. For an enclosed argument, the application of the axis does not pervade, but works only at the top levels of nesting. See the following examples: A < 10 100 0« B« 3 1 2 3 4 5 6 7 8 9 10 11 12 A +[1] 11 12 B 106 107 108 1010 1011 1012 A+ 1 10 B 20 x[2] 300 100 5 60 700 8000 100 1100 12000 o o o = 0« A « 2 0, 3 .5 0.6 N O N @O O F w - 0« B« 2 16 17 18 19 20 21 22 23 24 1 OF B 1000 CONFORMS TO AXIS 2 OF B ~ACREATE NEW A ad 4000 9 .2 CONFORMS TO AXIS 14 105 A ACREATE A ACREATE AND DISPLAY B nd 13 1009 1 16 1000 up112 APL Reference Manual 3p0.1x16 aCREATE NEW A 4 aCREATE NEW B 30124 APL Primitive Functions 1.1 Primitive Scalar Functions AORDER OF AXIS ARGUMENT UNIMPORTANT F N 6.3 8.2 9.3 11.2 12.3 15.6 F O 5.2 14,5 & 19. 3.3 17.5 18.6 &£ 16. 2.2 20.5 21.6 = T O«Z«4A+[3 1]B 23.5 24,6 ad CONFORMS TO AXES 1 AND 3 OF B aTHE FOLLOWING SUBSCRIPTS DEMONSTRATE a SUBARRAY COMBINATIONS USED BY APL aMATCH RETURNS 1 WHEN TRUE Z[;1;]1 = A + B[;1;] Z20;2;1 = A + B[;2;5] 7203331 = A + B[;3;] Z0;4;] = A+ BL;4;] o 0.3 0.4 o S o O 0« A4 <« 2 .2 .6 0,7 0.8 4p0.1x18 aCREATE NEW A = N w 8.3 11.4 O 6.2 14,5 O 3.1 5.2 17.6 18.6 3 2.1 20.7 21.7 o lop) (S S N e 0« Z <« A +[1 2] B aA CONFORMS TO AXES 1 AND 2 OF B 9.3 12.4 15.5 23.8 2u4.8 aTHE FOLLOWING SUBSCRIPTS DEMONSTRATE a SUBARRAY COMBINATIONS USED BY APL 203313 = A + Bl;;1] 7205321 = A + B[;;2] Z0333] = A + B[;;3] 3p0.1x112 aCREATE NEW A o O O F = O O = ~N O < U APL Reference Manual 1-7 APL Primitive Functions 1.1 Primitive Scalar Functions W w O D OF B O W 3 N W CONFORMS TO AXES 2 AND W 21, WO 20. 24, 15. 18, 25, N == 14, 17. 1 A O U1 N 12 U1 M 0 5. 8. 00 - Y 2. = = N e 0 «Z <+« A +[3 2] B .1 aTHE FOLLOWING SUBSCRIPTS DEMONSTRATE A Z[1;;] = A + B[1;;] Z02;;] = A + B[2::] PC«2 3p(13) PC 3l 4] 71 1-8 |1 2 3] |4 5 6] (13) |3 4 5| |4 5 |6 7 8] |7 8 APL Reference Manual (13) SUBARRAY COMBINATIONS USED BY APL (2 3p16) (2 3p16) (2 3p16) APL Primitive Functions 1.1 Primitive Scalar Functions RAXIS IS NOT PERVASIVE SO PLUS (+) a WITH AXIS APPLIES BETWEEN a 4PC[2:3] AND +ER[3] WHICH n IS A RANK ERROR PC+[2]ER 9 RANK ERROR PC+[2]FER A The individual descriptions of the primitive scalar functions are presented in three sections. Section 1.1.1 describes arithmetic functions, Section 1.1.2 describes logical functions, and Section 1.1.3 describes relational functions. Most of the individual descriptions include examples of how the functions work. APL Reference Manual 1-9 APL Primitive Functions Arithmetic Functions 1.1.1 Arithmetic Functions The arithmetic functions, which are summarized in Table 1-1, perform wellknown mathematical operations. All of them take numeric scalar arguments and return numeric scalar results. Table 1-1 Arithmetic Scalar Functions Monadic Function Dyadic Meaning Function Meaning +B B A+B Add 4 to B -B Negative of B A-B Subtract B from 4 xB Sign of B AxB Multiply A and B +B Reciprocal of B A+ B Divide 4 by B *B e to the B th power A% B A to the B th power | B Magnitude of B Al B A residue of B [B Ceiling of B ATB Maximum of 4 and B LB Floor of B ALB Minimum of 4 and B ®B Natural logarithm of B Ae B Logarithm of B to the base 4 ! B Factorial of B A!B Binomial coefficient (number of combinations of B things taken 4 at a time) oB Pi times B ?B Random integer from : B AoB Trigonometric functions (B is in radians; see Table 1-2) 1.1.1.1 + Conjugate The monadic + function returns a result that is the same as its argument; thus, + B is identical to B. For example: +5 1-10 APL Reference Manual APL Primitive Functions Arithmetic Functions 1.1.1.2 - Negative The monadic - function returns the negative of its argument; thus - B is the - negative of B. Be careful not to confuse the negative function with the high minus sign (7) used to denote a negative number. For example: 1.1.1.3 x Sighum The monadic x function identifies the sign of its argument; thus, x B is the sign of B. The signum function returns ~ 1 if the argument is less than 0, 1 if the argument is greater than 0, and o if the argument is equal to 0. For example: x99 1 xQ 0 X 5 1 1.1.1.4 : Reciprocal The monadic = function returns the reciprocal of its argument; thus, + B 1is the reciprocal of B. For example: +0 15 DOMAIN ERROR (DIVISION BY ZERO) 0 A 1.1.1.5 * Exponential The monadic = function raises the value of e (2.71828182845904523536...) to the power specified by its argument; thus, B is e to the B th power. For example: APL Reference Manual 1-11 APL Primitive Functions Arithmetic Functions *0 1 * 1 2.718281828 *10 22026.46579 *50 5.184705529F21 1.1.1.6 o« Natural Logarithm The monadic e function returns the natural logarithm of its argument; thus, ¢ B is the natural logarithm (base e) of B. For example: ®1 0 ®2.718281828459 1 ®22026.,46579 10 ®5,184705529F21 50 The e symbol is formed with the o and * symbols. 1.1.1.7 o Pi Times The monadic o function returns the product of its argument and the value of 7 (3.14159265358979323846264...). For example: 01 3.141592654 03 9.424777961 1.1.1.8 | Floor The monadic | function returns the greatest integer not greater than its argument, within a tolerance defined by [0 ¢T. For example: 73 2.5 l4.111 u L4.999 Ly 1-12 APL Reference Manual APL Primitive Functions Arithmetic Functions Note that the 0 CT setting may affect the result of L. For example: 0CT+«0 |4.9999999999 10 OCT«1E [4.9999999999 5 The following is a formal description of how the floor function is implemented: VZ«FLOOR B (1] [2] [3] (4] 1.1.1.9 ;0CT ;BXCT ;N BXCT«{CT ¢ [CT<0 N<(xB)x[0.5 + |B Z+«N-(N-B)>BXCT x 4T|N ¥ [ Ceiling The monadic | function returns the smallest integer not less than its argument, within a tolerance defined by 0CT. For example: [72.5 fu,111 5 [4,999 5 Note that the 0CT setting may affect the result of [. For example: 0CT+0 [4,0000000001 10 OCT<«1E [4.0000000001 4 The [ and | functions are related in the following manner: [B«~>- | - B. For example: fu.111 -{-4,111 APL Reference Manual 1-13 APL Primitive Functions Arithmetic Functions 1.1.1.10 | Magnitude The monadic | function returns the absolute value of its argument; thus, | B is the absolute value of B (that is, B= | B, if B0 and (-B) = | B, if B<0). For example: |9 9 — |9 9 1.1.1.11 ! Factorial The ! of B (for integer arguments) is the product of the first B positive integers. For example: 120 If the argument to the factorial function is 0, the result is 1. If the argument 1s a negative integer, APL signals DOMAIN ERROR. If the argument is not an integer, ! B is defined in terms of the mathematical function GAMMA as follows: !B <> GAMMA(B+1) The ! symbol is formed with the quote (') and period (. ) symbols. For more information on the Gamma function, see Milton Abramowitz and Irene A. Stegun, eds., Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables (National Bureau of Standards, November 1964), pp. 255-293; or John F. Hart, et al., Computer Approximations (Robert E. Krieger Publishing Company, 1978), pp. 130-136, 243-254. 1.1.1.12 ? Roll When applied to an argument B, the monadic 7 function generates an integer randomly selected from the integers : B (for a near-integer argument). For example: 1-14 APL Reference Manual APL Primitive Functions Arithmetic Functions 75 4 7 8 6 2 9 3 2 10 15 20 25 15 20 25 25 75 10 10 A<2 3p1 b A 7A 7A 111 3 36 At the completion of the roll function, the value of 0 RL changes: ORL 695197565 ?5 4 ORL 1133752294 If the argument is not a near-integer, or if a near-integer argument is less than the value of 010, APL signals DOMAIN ERROR: 0I0<«1 20 15 DOMAIN ERROR 20 A 0I0+«0 20 0 Note that the roll function is JI0-dependent: ?B when to (for the same value of DRL) 1+ ?B when 10 is 1, is equivalent 110 is 0. The roll function is analogous to the rolling of several dice. Roll may generate duplicate values; thus, it differs from the dyadic deal function (7 ), which generates a set of unique random numbers. APL Reference Manual 1-15 APL Primitive Functions Arithmetic Functions 1.1.1.13 +, -, x, and + Addition, Subtraction, Multiplication, and Division The dyadic +, -, x, and + functions return the sum, difference, product, and quotient of their arguments, respectively. The right argument for the division function may not be 0 unless the left argument is also 0. For example: 0+0 1 1.1.1.14 + Power The dyadic * function raises the value of its left argument to the power specified by its right argument. For example: 5%3 125 " 5%3 ~125 3%x2.5 15.588u5727 "3%2.5 15 DOMAIN ERROR “3%x2.5 A The power function’s domain is restricted to the following combinations of arguments: Left Right Any 0 0 20 >0 Any <0 Integer Note that 0x0 1s 1. If the right argument of the * function is exactly 0.5, APL returns the square root of the left argument. 1-16 APL Reference Manual APL Primitive Functions Arithmetic Functions 1.1.1.15 e Logarithm The dyadic e function returns the logarithm of its right argument in the base of its left argument; thus, Ae B is the logarithm of B in base 4. For example: 10®1 0 1010 1 510 1.430676558 Both arguments must be greater than zero. The left argument may not be 1 unless the right argument is also 1. For example: 11 1is 1. The ® symbol is formed with the o and *» symbols. 1.1.1.16 o Circle You use the dyadic o function to perform trigonometric functions. The left argument of o specifies which trigonometric function is to be performed. Only certain combinations of arguments are valid for the circle function. For arguments 4 and B, Table 1-2 lists the possible values of 4 (near-integer argument), and indicates the operation associated with each value. Table 1-2 Al Trigonometric Functions Performed by o Function (Z<AoB)? Domain Result Domain ~7 arc tanhB 1> | B "6 arc cosh B B> 1 7> 0 ~5 arc sinhB 4 (T 1+4Bx )% 0.5 1< | B 2= 0 3 arc tan B S 2 arc cos B 1> | B (0sZ)nrZs<so1 ! arc sin B 1> | B (1Z2)<00.5 0 (1-Bx2)*0.5 1> | B (Z=20)A2Z<1 1 sin B (|Z)<00.5 (12)=<1 1The value of 4 must be a near-integer from ~ 7 through 7. 2The value of B is given in radians. (continued on next page) APL Reference Manual 1-17 APL Primitive Functions Arithmetic Functions Table 1-2 (Cont.) Trigonometric Functions Performed by o Function Al (Z<AoB)?2 2 cos B Domain Result Domain (1Z)=<1 3 tanB Y (1+B*x2)*x0.5 Bz2|B+00.5 5 sinh B 6 cosh B Z>1 7 tanh B (1Z)s<1 2> 1 1The value of 4 must be a near-integer from =~ 7 through 7. 2The value of B is given in radians. L Minimum 1.1.1.17 The dyadic L function returns the smaller of its two arguments. For example: 415 I 45 12 301 26 3 [ Maximum 1.1.1.18 The dyadic I function returns the greater of its two arguments. For example: 415 5 45 4 1.1.1.19 5 | 3[1 26 6 Residue The dyadic | function returns the residue of the right argument with respect to the left argument. The residue is obtained by adding or subtracting multiples of the left argument from the right argument. The result of a residue operation takes the sign of the left argument. If the left and right arguments are equal, the residue is 0. (Note that the residue function is [ CT-dependent.) If the left argument is 0, then the residue equals the value of the right argument. If the left argument is not o, then the residue is in the range of the left argument through o ; it may equal 0 but may not equal the value of the left argument. For example: 1-18 APL Reference Manual APL Primitive Functions Arithmetic Functions 518 3 517 73 717 0 710 0 017 7 2]5.8 1.8 1]123.4567 0.4567 5 3 3 2 2 2 2 2 2 5(8 8 55 5|2 512 2 2 A<3 0 73 B«6 5 4 7372 7101231456 Ao, |B 0 6 20 1 20 1 20 5 4 73 72710 1 2 1 23 4 56 07271 0 1 072710 271072710 ! Combinations 1.1.1.20 For arguments 4 and B, the dyadic ! function returns the number of combinations of B elements taken 4 at a time. For example: 204 6 10110 1 For arguments 4 and B, the function’s domain is described as follows: ~(B<0)A(~ INTEGER B)An~ INTEGER A INTEGER is a function that returns 1 if all the items in its argument are integers, and 0 otherwise. APL determines the result of the dyadic ! function based on the algorithms explained in Table 1-3. The value 1 in the table for 4, B, or B- 4 means that the argument or the difference between the arguments is a negative integer; the value 0 means that the argument or the difference between them is not a negative integer. APL Reference Manual 1-19 APL Primitive Functions Arithmetic Functions Table 1-3 A Determining Result for Dyadic ! B B-4A Result 0 0 0 (!B)+(!'A)x!B-A 0 0 1 0 0 1 0 APL signals DOMAIN ERROR 0 1 1 (" 1xA)xA'A-B+1 1 0 0 0 1 0 1 Not a possible case 1 1 0 (" 1xB-A)x(|B+1)!(|4A+1) 1 1 1 0 Note that the dyadic ! function is related to the mathematical function BETA as follows: BETA(A,B)<~» +Bx (A-1)!A+B-1 «»> +Ax (B-1)'!'A+B-1 The ! symbol is formed with the ' and. symbols. For more information on the Beta function, see Milton Abramowitz and Irene A. Stegun, eds., Handbook of Mathematical Functions with Formulas, Graphs, and Mathematical Tables (National Bureau of Standards, November 1964), pp. 255-293; or John F. Hart, et al., Computer Approximations (Robert E. Krieger Publishing Company, 1978), pp. 130-136, 243-254. 1-20 APL Reference Manual APL Primitive Functions Logical Functions 1.1.2 Logical Functions The monadic ~ (Not) and the dyadic »~, v, ~, and » functions (And, Or, Nand, Nor, respectively) are commonly called logical functions. The domain and range of logical functions are restricted to the Boolean values 0 and 1. Table 14 is a truth table that shows the results of logical operations for arguments 4 and B. Table 1-4 Truth Table for Logical Functions Functions Arguments And Or Nand Nor Not A B AAB AV B A~B A% B -B A B AAB AV B A~ B AB -5 ° ° ! ! 0 0 0 1 - _ _ _ _ ~ 1 0 0 0 0 - 1 1 1 0 B 0 1 1 1 _ ° ! 0 ! B i _ ~ 1 ~ — 1 The » symbol is formed with the A and ~ symbols . The » symbol is formed with the v and ~ symbols. APL Reference Manual 1-21 APL Primitive Functions Relational Functions 1.1.3 Relational Functions The dyadic <, <, =, #, >, and > functions are commonly called relational functions. The domain of relational functions is not restricted; they can take both numeric and character arguments. However, only the equal and not equal functions can have mismatched arguments, that is, one numeric and one character argument simultaneously. For example: 1AV =5 0 5125 0 The result domain of relational functions is restricted to the Boolean values 0 and 1. A relational function returns the result 1 if true and o if false. For example: 9>6 1 4>6 0 10> A 1 When <, <, >, or > have character arguments, the order of characters in JAV is used as a collating sequence, and the evaluation is based on the respective positions of the arguments. When the relational functions have numeric - arguments, the comparisons between the arguments are affected by the value of OCT. When you use relational functions with Boolean arguments, the relational functions can perform logical operations. For example, the not equal (») function performs an exclusive OR operation if its arguments are 0 s and 1 s: (020),(0=21),(120),1=21 0110 1.2 Primitive Mixed Functions The primitive mixed functions allow more extensive array manipulation than the scalar functions. Scalar functions take scalar arguments, return scalar results, and are extended to arrays on an item-by-item basis. Mixed functions are not as predictable. For example, depending on the values of their arguments, mixed functions may do the following: 1-22 APL Reference Manual APL Primitive Functions Relational Functions Take a scalar argument and return a vector result: 19 123456789 Take a vector argument and return a scalar result: 2112347 1234 Take a matrix argument and return a vector result: ACREATE AND DISPLAY B O«B<«l4 3p112 2 3 M 5 b6 7 8 9 1 10 0 1 112 aRAVEL B (MAKE B A VECTOR) ,B 123456789 10 11 12 Table 1-5 summarizes the primitive mixed functions, which are described in this section. Table 1—5 Primitive Mixed Functions Function Name Meaning ALB Base Bases the representation of B in number system 4. +B Branch Modifies the standard order of execution in a user- A,B Catenate Catenates 4 to B along the last axis of 4. defined operation. A,[K1B Catenate/ Cétenates/laminates A to B along the k¥ th axis of 4. A+ B Catenate Catenates 4 to B along the first axis of 4. A>B Contain Determines whether all the items in array B are A?B . Deal Deals 4 integers selected randomly in the range 1 B. >B Disclose Reduces the depth in an array. > [K]1B Disclose Discloses B and arranges the substructure axes (X ). AV B Drop A5 [K]B Laminate also found in array 4. For A> 0, drops the first 4 items of B;for 4<0, drops the last | 4 items of B. (continued on next page) APL Reference Manual 1-23 APL Primitive Functions Relational Functions Table 1-5 (Cont.) Primitive Mixed Functions Function Name Av [K]B Drop Meaning For A> 0, drops the first 4 items along the axes of B specified by K ; for 4<0, drops the last | 4 items along the axes of B specified by x. B Enclose Builds enclosed arrays. Returns a scalar containing B. < [K1B Enclose Builds enclosed arrays; subarrays along axes X become scalars. €B Enlist Builds a simple vector with all of the simple scalars 1n its argument. ¢B Execute Executes the character string B. MB M [K1B File Input Reads records from an external file into an APL workspace. ABB File Output Writes information to an external file from an APL AB[K]B workspace. | B [K]1B BB B Format Formats array B. AvB Format Formats character array B with width and precision specified by 4. VB Grade Down Generates an index vector that can be used to sort B in descending order. VY (K1B Grade Down Generates an index vector that can be used to sort B in descending order, row by row or column by column. AV B Grade Down Generates an index vector that can be used to sort B in descending order using collating sequence 4. AB Grade Up Generates an index vector that can be used to sort B in ascending order. A[K]B Grade Up Generates an index vector that can be used to sort B in ascending order, row by row or column by column. AAB Grade Up ‘ 1 B A1 B Generates an index vector that can be used to sort B in ascending order using collating sequence 4. Index Generates the first B consecutive integers from the Generator current index origin. Index Of Finds the first occurrence of B in vector 4. (continued on next page) 1-24 APL Reference Manual APL Primitive Functions Relational Functions Table 1-5 (Cont.) Primitive Mixed Functions Function Name AnB Intersection Meaning | Returns a vector of the common items in the arrays A and B. A=B Match ABB Matrix Divide Determines whether arrays 4 and B are identical in rank, shape, and value. Performs matrix division, solves linear equations, and finds a least-squares solution. BB Matrix Inverse Inverts the matrix B. Ae B Membership Determines if 4 is a member of array B. A>B Pick Discloses an item from any depth of an array. ,B Ravel Returns the ravel of B (makes B a vector). ,[K1B s [K1B Ravel Merges or adds axes to the shape of B depending on the value of X. ATB Represent Represents B in number system 4. Ap B Reshape Reshapes B to the shape specified by 4. ¢B Reverse Reverses along the last axis of B. ¢ [K1B Reverse Reverses along the k¥ th axis of B. eB Reverse Reverses along the first axis of B. AB Rotate Rotates by 4 along the last axis of B. A$ [K1B Rotate Rotates by 4 along the ¥ th axis of B. AeB Rotate Rotates by 4 along the first axis of B. e [K]B Ae [K]B pB Shape Returns the shape of B. AcB Subset Determines whether all the items in array 4 are also found in array B. A+ B Take For 4> 0, takes the first 4 items of B; ford< 0, takes the last | A 1items of B. A+ [K]B Take For 4> 0, takes the first 4 items along the axes of B specified by X ; for 4<0, takes the last | 4 items along the axes of B specified by X . 8 B Transpose Transposes the axes of B (for a matrix, exchanges the rows and columns). (continued on next page) APL Reference Manual 1-25 APL Primitive Functions Relational Functions Table 1-5 (Cont.) Function 1-26 Primitive Mixed Functions Name Meaning A8 B Transpose Transposes the axes of array B according to 4. AuB Union Returns a vector of the items in the arrays 4 and B. uB Unique Removes the duplicate items of array B. A~B Without Returns a vector of the items of array A that are not found in array B. APL Reference Manual Primitive Mixed Functions L Base 1 Base Form Al1B Left Argument Domain Type Numeric Shape Any Depth 0 or 1 (simple) Right Argument Domain Type Numeric Shape Any Depth 0 or 1 (simple) Result Domain Type Numeric Rank Of 2+(ppA)+ppB Shape (T1vp4),14+p0B Depth 0 or 1 (simple) Implicit Arguments None. Description The dyadic 1 function (known as base or decode) reduces a representation in a number system to a value. More specifically, it converts to decimal those vectors along the first axis of the right argument that are expressed in the positional number bases of radices given by vectors along the last axis of the left argument. The base function is best explained as the converse of the represent function (t). The following example shows the two functions operating on a quantity expressed in yards, feet, and inches: APL Reference Manual 1-27 Primitive Mixed Functions 1 Base a1 YARD, 1760 3 1211 2 1760 3 12763 2 FEET, 3 INCHES IS 63 INCHES 3 63 123 The expressions AT B and A1 B differ only in the value included in B; A expresses the number base in both cases. The number of items in both arguments, for example A4 and B, must generally be the same; the first item in 4 expresses the radix in which the first item in B is decoded, and so on. However, if 4 is a singleton, it is extended so that its length is the same as that of the first axis of B. For example, the following expression has the effect of producing the base 10 value of the base 8 number 3777 (octal-to-decimal conversion): 7 7 7 813 2047 For arguments 4 and B, the argument arrays for 1 must conform to one of the following rules: e A or B is a scalar. e The results of “14+p 4 and 1+ p B are equal. e FEither " 14p A4 or 14 p B equals 1. If the argument arrays conform to the last rule, the axis that equals 1 is extended to match the appropriate other axis. For example: (2 3p5)L(3 4p3) 93 93 93 93 93 93 93 93 (2 3p5)1(1 4p3) 93 93 93 93 93 93 93 93 (2 1p5)L(3 93 93 93 93 93 93 93 93 U4p3) The following are some other uses of the base function: 1-28 APL Reference Manual Primitive Mixed Functions 1 Base ACONVERT 1312 13 3 YDS. 2 FT. 4 IN. TO INCHES 24 | 13 6 RDETERMINE IF A 2.5 IS A ZERO OF THE POLYNOMIAL ((BxX*2)-(7%xX))-20 2.516 7 20 nYES RBASE 514 3 10 EQUIVALENT OF BASE 5 NUMBER 4 119 You can use the base function to evaluate polynomials; the expression X1 C evaluates a polynomial in X with coefficients given by the vector C. For vectors 4 and B, the base function can be thought of as a form of the inner product operator. The expression A1 B is equal to ¥+ . x B, where W is the weighting vector (W<¢ x\ "1+ ¢4, 1) given by the expression WL(-N)+pd] ¥[p 4] «~> 1, and isequal to AL (-N)+1p Al xW[ (-N)+1+pA]. The value of A[ 1] is irrelevant. The following example shows two equivalent operations: A«1760 B«1 2 3 12 3 ALB 63 36 12 1+.xB 63 Note that if the right argument is empty, the type of the left argument is not significant: (3 2 1p'4r)L (3 2 1p0)1 ! 00 0 10 o 0 0 O 0 APL Reference Manual 1-29 Primitive Mixed Functions 1 Base Possible Errors Generated 1-30 10 LENGTH ERROR ( LENGTHS OF INNER AXES DO NOT MATCH) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED ). 15 DOMAIN ERROR ( INCORKRECT TYPE) 27 LIMIT ERROR ( FLOATING OVERFLOW) 27 LIMIT FRROR ( VOLUME TOO LARGE) APL Reference Manual Primitive Mixed Functions -+ Branch - Branch Form +B Argument Domain Type Near-Integer Shape Any Depth 0 or 1 (simple) Result Domain None. Implicit Arguments None. Description The monadic > function (known as branch) modifies the standard order of execution in a user-defined operation. Normally, APL lines in operations are executed in the order of their line numbers; execution begins at the first line following the operation header and ends with the last line in the operation. Branch changes the sequence of execution by transferring control to another line in the operation. There are two types of branches: unconditional and conditional. Unconditional branches specify the next line to be executed. The result of an expression evaluation determines the next statement in a conditional branch. Unconditional branches consist of a branch symbol (-), followed by a representation of the number of the operation line to which you want to transfer control. The argument can be a label, a constant, a variable, or an expression. Its value (or, if it is a vector, the value of its first item) is equivalent to an integer line number within the current definition. Execution continues at that line. APL Reference Manual 1-31 Primitive Mixed Functions ~ Branch Conditional branches can be expressed in one of the following three forms: > line-number x1 logical-expression Here APL evaluates the logical expression that is the right argument of 1. The logical expression returns either a 1 (true) and the control passes to the specified line or a 0 (false) and the control passes to the next statement. (This form only works when (170+0.) In the following example a simple counter controls the number of times the statements in a loop are executed. The example branches to line number 0, an out-of-range number, and forces an exit from the operation: V COUNTER [1] 0«'NUMBER OF ENTRIES:' o N+{] [2] [3] (4] [5] C+0 LOOP: »0x1C=N C<«C+1 +LO0OP [6] v ~+logical-expression / line-numbers This type of conditional branch specifies several line numbers and associated logical expressions as possible branch destinations. Control passes to the line number corresponding to the first logical expression that evaluates to 1 (true). For example: VF A [13 [2] [3] [ul ~+(4>0)/3 '"WILL NOT ACCEPT NEGATIVE NUMBERS' '"FUNCTION CONTINUING NORMALLY' ¥ F 5 FUNCTION CONTINUING NORMALLY F 2 | WILL NOT ACCEPT NEGATIVE NUMBERS 1-32 APL Reference Manual ¢ =0 Primitive Mixed Functions - Branch e line-numbers [K] Here the value of X is used as an index to select the corresponding line number. For example: V [1] [2] [3] [4] [5] [6] labs K+<2 +~(LAB1,LAB?2 ,LAB3) [K] LAB1: '"LAB1 IS EXECUTED' o -0 LAB2: LAB3: ¢ =0 ¢ -0 'LAB2 IS EXECUTED' '"LAB3 IS EXECUTED' v LABS LAB? IS EXECUTED Note that -~ is described in greater detail in Chapter 3 of the VAX APL User’s Guide along with other information on user-defined operations. Possible Errors Generated 7 SYNTAX ERROR ( BRANCH NOT ALLOWED IN MIDDLE OF AN EXPRESSION) 11 VALUF ERROR (BRANCH HAS NO RESULT) 15 DOMAIN ERROR ( ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR ( INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR ( INTEGER TOO LARGE) APL Reference Manual 1-33 Primitive Mixed Functions ., and ; Catenate/Laminate , and ; Catenate/Laminate Form A,B A,LK]B A+ B A-[K]B - 18 formed with , and - Left Argument Domain Type Any Shape — Depth Any Right Argument Domain Type Any Shape — Depth Any Result Domain Type = Rank 1T (ppA) [ppB (for catenate) or 1+ (ppA) lpp B (for laminate) Shape — Depth (=4)T=B Implicit Arguments None. Description The dyadic APL function joins together the specified axis of two arrays. If, for A,[K1Bor A; [K]B, K 1s a near-integer, the function is called catenation, and A and B are joined along the K th axis. If ¥ is not a near-integer, the function is called lamination, and 4 and B are joined along a new axis lying between the axes named by | X and [ X. The forms 4, B and 4; B represent catenation and join the arrays along their last or first axis, respectively. 1-34 APL Reference Manual Primitive Mixed Functions , and ; Catenate/Laminate If one of the arguments is a scalar, its length is extended to match the shape of the other argument. If both arguments are scalars, the result is a two-item vector. For example: 5,6 5 aCATENATE 2 SCALARS, RESULT IS A VECTOR 6 3p16 B«2 B,[1]17 12 4 5 7 7 AaCATENATE SCALAR TO FIRST AXIS OF B 3 7 B,7 12 37 L 6 5 ACATENATE SCALAR TO LAST AXIS OF B 7 For catenation, the arguments’ ranks must differ after scalar extension by at most 1. Note that a singleton argument is not extended to conform to the other argument: AaCATENATE SINGLETONS OF DIFFERENT RANKS (1 1p7),1 1 1 1p8 9 RANK ERROR (RANKS DIFFER BY MORE THAN ONE) (1 1p7),1 1 1 1p8 A ATRY AGAIN 0« R+« 7 (1 1p7), 1 1 1p8 8 pR 112 In the following example, two arrays of equal rank are catenated. The shapes of the arguments match except for the axis [ ( k)] along which the arrays are being joined: B<«3 4 5p17? 6 5pik pB 3 4 5 C«3 pC 365 R«B,[2]C pR 3 10 5 Note that B isequaltoR[; 1 4;] andC to R[; 4+16;]. APL Reference Manual 1-35 Primitive Mixed Functions , and ; Catenate/Laminate The next example shows the catenation of two arrays whose ranks differ by 1. Again, the shapes of the arguments match except for the axis along which the arrays are being joined: B«3 4 5p12 pB AB IS RANK 3 345 C+4 4 5p33 pC AC IS KANK 2 R<B,[1]C RCATENATE ALONG FIRST AXIS OF B 5 pR ARATTEMPT TO CATENATE ALONG SECOND AXIS B,[2]C 10 LENGTH ERROR (SHAPES OFF AXIS DO NOT MATCH) B,[2]C A Here, B is equal to R[1 3; :] and C to R[u4; ;7. The following are more examples of catenation: A<5 8 B<b 7 9 A,B 58 ARCATENATE TWO VECTORS 967 10,4,B,12 10 58 96 7 12 'NAME', X1 NAMEXY B«2 3p1 2 3 456 C«2 3p7 8 9 10 11 ACREATE B 12 ACREATE C w o F o B 7 8 9 10 11 12 6 o Ol N ACATENATE ALONG FIRST AXIS 3 9 = O FE o - B,[1]C 12 w ARCATENATE ALONG SECOND AXIS 7 8 9 o + 1-36 S TN B,[2]C 10 11 12 APL Reference Manual Primitive Mixed Functions , and ; Catenate/Laminate B;C U1 N 00 = B F N 9 12 O S aUSE COLUMN CATENATE 3 6 w aCATENATE ALONG SECOND AXIS 7 8 9 o . (&2 £ B,C 10 11 12 [«A+«2 3 3p'ABCDEFGHIJKLMNOP{R' ABC DEF GHI JKL MNO PQR O«B<«2 3 3p'SSSTTTUUUVVVWWWXXX' 5SS ITT uuu 44/ WWW XXX A,B ACATENATE RANK 2 OBJECTS ABCSSS DEFTTT GHIUUU JKLVVV MNOWWWN PQRXXX Note that the catenation of scalars produces a vector: ppl,5 1 For lamination (4, [ X1 B and 45 [ K1 B where K is not a near-integer), the arguments must have the same ranks and shapes after singleton extension. The following are examples of lamination: aCREATE NEW DIMENSION BEFORE THE FIRST a DIMENSION WHEN [K]<1 nADD A ROW O«X«'ABC',[0.5]'DEF! ABC DEF pX 2 3 APL Reference Manual 1-37 Primitive Mixed Functions , and s Catenate/Laminate ACREATE NEW DIMENSION AFTER THE FIRST A O«X<'ABC',[1.3]1'DEF' DIMENSION WHEN 1<[K]<2 a ADD A COLUMN pX aNOW TRY EXAMPLE WITH HIGHER RANK OBJECTS aNOTE THAT APL RESHAPES EACH ARGUMENT ARBEFORE JOINING («E«3 2p'ABCDEF' AB CD EF O«F<«3 2p'UVNXYZ' uv WX Yz ACREATE NEW DIMENSION BEFORE THE FIRST A O«R<E,[.2]F DIMENSION WHEN [K]<1 AADD A PLANE oR 2 32 ACREATE NEW DIMENSION AFTER A nADD A ROW, U«R«F,[1.9]F AB v CD WX EF oR 322 1-38 APL Reference Manual THE FIRST DIMENSION WHEN 1<[K]<2 PREVIQUS ROWS BECOME PLANES Primitive Mixed Functions , and ; Catenate/Laminate aCREATE NEW DIMENSION AFTER THE SECOND A DIMENSION WHEN 2<[K]<3 aADD A COLUMN, PREVIOUS COLUMNS BECOME ROWS [«R<«E,[2.31F AU BV CW DX EY pR 3 2 2 aTRY EXAMPLE USING SINGLETON EXTENSION H«R«E,[.5]'Z" nADD A PLANE AB EF Y YA 77 pK aADD A ROW, PREVIOUS ROWS BECOME PLANES OeR«E,[1.5]"X" AB XX CD XX EF XX pK 3 2 2 rY',[2.5]F aADD A COLUMN YA YB Ye YD YE YF Note that if 070 <~ 0, then ~ .5 is valid as the axis value for lamination. This is the only case in which an axis may take a negative argument (range: ~ 1<X). APL Reference Manual 1-39 Primitive Mixed Functions , and s Catenate/Laminate Further examples: U«A«(0 ('AB')) 0 +--+ | AB| +--+ Q«B+c, 4 Q«Ce!? (APL outputs a blank line) O«MAX+2 3 p A 1 0 '"AB' B C |0 +--+]| | [AB]] |+t +--+ t---+ |AB| +--t | +-+] | |1al] + | +-+] + +---+ MAX,[1]B ACATENATE ALONG FIRST AXIS 10 +--+] | [AB]] |+t +--+ t---+ |AB| t--+ | +-+] | T4l] + | +-+] + +---+ +-+ +-+ | 4] LY +-+ +-+ 0«D«0 0 -+t +-t 'DP' +--+ | DP| +--+ 1-40 APL Reference Manual Primitive Mixed Functions . and ; Catenate/Laminate ACATENATE ALONG SECOND AXIS D, [2]MAX pommmm- + 0 1 0 +-+ |0 +--+| 14B]| 4] | | R+ +--+ +--+ +---+ |DP| |AB| [+=+] | lu]] +--+ +--+ | | +-+ | +-+] +--—+ ASHOW CATENATION OF TWO ARRAYS WHOSE RANKS DIFFER BY 1 pMAX 2 3 O«VIC+B,D +-+ 0 +--+ |l |DP] +-+ +--1 pVIC 3 O«W<MAX,[1]1VIC 1 0 +--+ +--—+ +-+ |AB| | +-+1 to--—-- + |0 +--+] |AB]| | |-t o+ | jul] +-—+ || +-+ |+-+| +--—+ 0 +-+ +--+ | DP| | 4] +--+ +-+ oW 3 3 aSHOW LAMINATION O«X«b4,c,1 4 +-+ |11 +-+ pX 2 B +-+ |41 +-+ pB (APL outputs a blank line) APL Reference Manual 1-41 Primitive Mixed Functions , and - Catenate/Laminate 0«Y<«X,[0.5]B T | 1] +-+ +-+ +-+ LIy +-+ +-+ pY O«Z«X,[1.9]1B +-+ | 4] +-+ +-+ | 4] +-+ pZ Possible Errors Generated 1-42 9 RANK FRROR 9 RANK ERROR (RANKS DIFFER BY MORE THAN ONE) 10 LENGTH FRROR (SHAPES OFF AXIS DO NOT MATC"H) 15 DOMAIN EFRROR (INCORRECT TYPE) 27 LIMIT ERROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN FRROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions > Contains > Contains Form Ao B > 1s formed with > and _ Left Argument Domain Type Any Shape Any Depth Any Shape Any Depth Any Type Result Domain Type Boolean Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Implicit Arguments 0CT (determines comparison precision) Description The dyadic > function determines whether the left argument contains all the items found in the right argument. The result is a Boolean scalar: true, if the left argument is a superset of the right argument, and false if it is not. Duplicate items in either argument do not affect the result. For example: A«3 4p 23 54 98 34 98 47 98 32 78 65 12 23 A > B+1100 = B o> 4 APL Reference Manual 143 Primitive Mixed Functions > Contains The o> function compares items in terms of the match (=) function, which uses the value of JCT. Because = allows mixed-type arguments, you can compare characters with numbers. However, such a comparison is always false, so that if you use mixed-type arguments for dyadic >, the result will be zero. For example: 123 24 25' 5 22 23 24 25 26 0 Further examples: O<WRL«0 0 +--+ 'AB' (c,3) +---+ |AB| [+-+] +--+ | |3]] [ +-+1 +---+ 0«POOL«2 2 p 0 0 'AB' 'EB' +--+ | AB| +--+ t--+ +---+ |EB] |+-+] +--+ [ 13]] | +-+] +---+ POOL > WRL 1 O«VAN«O 0 +---+ 1 | QTH | t---t 'QTH' +---+ ~1 (<,3) | +-+] 1311 | +-+] t---+ O«VIC+(c,4),0,(c'DP') t-+ 0 +--+ 4| |DP] +-+ +--+ VAN > VIC 0 Possible Errors Generated None. 144 APL Reference Manual (c,3) Primitive Mixed Functions ? Deal ? Deal Form A?B Left Argument Domain Type Nonnegative near-integer Shape Singleton Depth 0 or 1 (simple) Right Argument Domain Type Nonnegative near-integer Shape Singleton Depth 0 or 1 (simple) Result Domain Type Nonnegative integer Rank 1 Shape A Depth 1 (simple) Implicit Arguments ORL 0I0 (47B when 0I0 « 1 isidentical to 1 + A?B when 010 < 0 for the same [JRL) Description For 47 B, the dyadic 7 function generates a vector of integers randomly selected from 1 B; no number is selected more than once. The length of the result vector is specified by 4. For example: APL Reference Manual 1-45 Primitive Mixed Functions ? Deal 575 4b 2 315 571.0E7 2047059 8326627 1771140 853115 3809508 6272379 6940437 571.0F7 8895125 7387197 9062050 571.0E7 6693744 185074 2861354 853279 5088023 Unlike the roll function, dyadic 7 is analogous to dealing a number of cards from a deck with no two cards alike. Roll is analogous to rolling several dice independently; roll may generate duplicates, but deal will not. The value of the system variable O RL affects the result of the deal operation, and the value of JRL changes each time a deal operation completes successfully. For more details about 1 RL, see Chapter 2. Possible Errors Generated 9 1-46 RANK FERROR (NOT SINGLETON) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPFE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 15 DOMAIN ERROR (RIGHT ARGUMENT IS LESS THAN LEFT) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual Primitive Mixed Functions = Depth = Depth Form =B Argument Domain Type Shape | Depth Result Domain Type Integer (non-negative) Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Implicit Arguments None. Description The monadic = function (known as depth) indicates the maximum level of nesting in an array. A simple array has 1 level of nesting (0 if the array is scalar). An enclosed array has a depth of at least 2. Examples: U«B+9 aCREATE A SIMPLE SCALAR =B aCREATE A SIMPLE ARRAY J«C«'WHERE ARE YOU GOING?' WHERE ARE YOU GOING? =C 1 APL Reference Manual 1-47 Primitive Mixed Functions = Depth O«D«1 1 +----- + 11 (5 6 7) 11 12 ACREATE AN ENCLOSED ARRAY 12 |5 6 7| +----- + =D 2 ACREATE AN ENCLOSED ARRAY WITH MORE NESTING O0«E«1 1 t--mmmmmm (5 6 7 (8 9 oo + 11 12 |5 6 7 +------ + | | | |18 9 10]] toomoo +] tomm e + =k 3 Possible Errors Generated None. 1-48 APL Reference Manual 10)) 11 12 Primitive Mixed Functions > Disclose > Disclose Form > B >[K]B Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as constituent items in B Rank (ppB)++T/p p (,B),c*B Shape (pB),+T/(p " (,B),c4B)~c10 (pZ)[,K1«>4T/(p (,B)~c10 Depth 0 1+=B Implicit Arguments None. Description The monadic > function reduces the depth of an array. It reverses the building action of the monadic enclose (¢ ) function. Disclose is the left inverse of enclose (B«>>cB and B«>>[K]<[K]B). The rank of the items in B must be the same (singleton items are extended). However, the lengths of the corresponding axes do not need to match. For example, three enclosed items of shape 1 3 1, 2 6 2, and 4 2 4 match in rank, but not in shape. When the shapes do not match, each item is padded along each axis, and the length of each of the result’s axes is equal to the longest corresponding axis among the items of B. In the preceding example, the portion of the result that corresponds to the three items would have the shape 46 4: APL Reference Manual 1-49 Primitive Mixed Functions > Disclose aALL ITEMS SAME RANK F«(3 2p16) (2 3p'ABCDEF') (2 4p10 ¢19) (5 oF 4 7 fo--t +---4 +---4 13 2] |2 3] |2 4| --—% |5 t---t +---+ +---+ +--—% 1| OO O O O O 5 4 Www,m OO S =N O O O O P! i F o O O O O O O OO N o O O ANOTE FILL ITEMS 0 ~ohe < 3 O OO N W =y & O Ul W U«DD«>F pDD L Disclose only reduces one level of enclosure: A«(c13) "ABC' A t-----—- + +---+ | 4= +| |ABC| |11 2 3| +---+ 3 [ +----- t tomm -+ pA 3 =4 1-50 APL Reference Manual 3 1p'TUVXY'") Primitive Mixed Functions > Disclose oA t+ -+ ++ IEIE ++ +-+ ++ X+2A X t----- + t----- + 112 3] |00 t----- + t----- + 0] [0 0 0] -+ t----- + A B C 3 0 0 pX Disclose with axis (form > [ X¥] B) allows you to specify the placement of the disclosed item’s axes. The number of axes specified by ¥ must be equal to the rank of the items of B (ignoring the singleton items), and the axis numbers must be less than the sum of the rank of B plus the rank of the items of BG(ppB)++T\,p p B) The axis numbers must also be unique. The following example shows various combinations of axis arguments and the resulting arrays: R « (3 3p19) (2 3p'ON" 'TI" '"MA' 'NO' "IT'" '"AM') R |11 2 3| |4 5 6] |7 8 9] t-===- + |+--+ +--+ +--+] [[ON] |TI] [MA]] |+--+ +--+ +--+] [+t +--+ +--+]| | INO| [IT] [AM]] | +--+ +--+ +--+]| fom e + A<>R 2 APL Reference Manual 1-51 Primitive Mixed Functions > Disclose t--+ +--+ |ON| | TT| +--+ | MA| t-—+ +--+ +--+ t-—+ +--+ +--+ |NO| | IT| |AM| +-—+ +--+ +--+ t--+ +--+ +--+ +-—+ +--+ +--+ B«>[1 2]R B 1 4--+ | ON| +--+ 2 +--+ | TI| +--+ J +--+ | MA| +--+ bo+--+ |NO| +--+ 5 +--+ | IT| +--+ 6 +--+ | AM | +--+ 7 +--+ +--+ 8 +--+ 9 +--+ +-—+t +-—+ 1-52 APL Reference Manual Primitive Mixed Functions 1] 1] Co =~ > Disclose pAd pB C+«>[1 3]K =( pC C $--+ 2 3 +--1 +--+ | ON | |I | MA| +--+ +--+ +--+ 5 6 +--+ +--+ +--+ |NO| | IT] | AM| +--+ $--+ +--+ 8 9 +--+ +--+ +--+ | . +--1 +--4 +--+ D«>[2 3]K =D pD 2 3 APL Reference Manual 1-53 Primitive Mixed Functions > Disclose t--+ +--+ | ON | | TT| | MA| ==+ t--+ +--+ ==+ +--+ +--+ |NO| [ IT] | AM | +--+ +--+ +--+ ==+ +--+ +--+ +--+ | t--t -+ +--+ F«>[2 1 1]1R +-—4 | OF | +--+ bo+-—+ | NO| +--+ 7 +--+ +--+ 2 +--+ | 71| +-—1 5 +--+ | IT] +-—+ 8 +--+ +-—+ 3 +--+ | MA | +-—+ 6 +--+ | AM| +--+ 9 4--+ +--+ 1-54 APL Reference Manual Primitive Mixed Functions > Disclose 1]R Fes[3 +--4 f--+ -+ | ON| | NO| t--t +--+ +--+ 2 5 8 t-—+ +--1 +--+ | TT] | IT| t-—+ +--1 +--+ 3 6 9 t--t+ +-—+ +--+ | MA| | AM| | t-—+ +--+ +——+ G+>[3 2]K +--+ t--+ +-—t+ | O | |voj | +--t +-—+ +--1 t--+ +--+ +--+ | TT| | IT| | +--+ +--+ +--+ +--+ +-—t+ +--+ | MA | | AM] | to=t =+ -—1 APL Reference Manual 1-55 Primitive Mixed Functions > Disclose If all the items of B are scalars, then the axis, if specified, must be empty: Tec (13)(14)(15) T eT | +----- + 1112 3] S [+-mmmm- I |12 2 3 4]] |]12 | +----- 4= I oI 4 +| 34 5] R +| S ! =7 3 pT 3 2 ++ g 2 2 ++ 0T o+t AR ++ ++ ++ O«S«>[10]7T o+ - + tmmmmm— + |12 3] |12 3¢4] o= T |12 34 5] T+ =5 2 pS 3 The disclose of an array which contains only scalars and empty arrays as item will be an empty array: H "' 3 =y E«2 +E 1-56 APL Reference Manual Primitive Mixed Functions > Disclose X+oF (APL outputs a blank line) 3 0 +X 0 The following expression describes the formal relationship between disclose and disclose with axis: sB<«~> >[(ppB)+1pp+Bl]B Possible Errors Generated 9 RANK ERROR (ITEMS NOT SINGLETON OR ALL THE SAME RANK) 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual 1-57 Primitive Mixed Functions + Drop + Drop Form AV B AV [K]B Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as right argument Rank (p,A)TppB Shape 0l (pB) -4 (if no explicit axis) Depth =B Implicit Arguments None. Description The dyadic + function builds an array by dropping a specified number of items from an existing array. The left argument specifies how many items are to be dropped from each axis in the right argument array. Thus, for 4+ B, item A[ 1s used to drop values along the ¥ th axis of B. Unless the right argument is a scalar, the left argument must have a number of values equal to the rank of the right argument (for arguments 4 and B, o ,A must equal p p B). For instance, if the right argument is a vector, the left argument must have just one value. If that value is positive, APL drops the 1-58 APL Reference Manual K] Primitive Mixed Functions + Drop specified number of items from the beginning of the vector; if the value 1s negative, APL drops items from the end of the vector. For example: 2v15 3 45 2415 12 3 If the right argument is a scalar, it is reshaped to a singleton with a rank equal to the length of the left argument. If the rank of the right argument is greater than 1, the result array is said to be a "corner" of the argument array. The origin of the corner is determined by the signs of the items of the left argument. For example, if the right argument is a matrix, there are four possible corners, as shown in Figure 1-1. The drop function leaves a corner that is diagonally opposite to the origin specified by the signs of the items of the left argument. In the following example, note how the order of the signs determines the "corner” selected from the matrix: H«C«3 3 p19 3 7 Note that for arguments 4 and B, the dimension of the remaining corner is the complement of 4 with respect to p B, or | (p B) - A. If the value of an item in the left argument is greater than the length of the corresponding axis, then, for arguments 4 and B, A+ B returns an empty array with shape o (pB) - | 4. If the left argument is empty, the right argument must be a scalar, and the result is the right argument. When you use + with an axis argument, ¥ is a vector of axis numbers whose lengths are determined by corresponding items of the left argument, 4. Formally, + with an axis argument can be described by the following: Z <« 0>pB O ZIK] « A % Z < ZVB APL Reference Manual 1-59 Primitive Mixed Functions v+ Drop The value for ¥ must be in the vector domain, and each item must be a nearinteger in the set 1 p p B. Therefore, the values of ¥ are 0710 dependent. The items may be in any order, but they may not be duplicated. The length of x must be less than or equal to the rank of the right argument, and it must match the length of the left argument. The value for ¥ does not have to specify all the axes in B. APL regards the lengths of any missing axes as zero. This means that you can drop rows or columns of a matrix without specifying zero for the length of the other axis. For example: [«A«8 5p140 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 3 +[1] 4 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 2 v[2] A 1 2 RDROP 3 ROWS OF A ADROP THE LAST 2 COLUMNS OF 4 3 6 7 8 11 12 13 16 17 18 21 22 23 26 27 28 31 32 33 36 37 38 3 4 +[2 1] 4 ADROP 4 ROWS, 3 COLUMNS OF A 11 4 ARDROP 3 COLUMNS OF A 2425 29 30 34 35 39 40 < 0 0I0 4 24 1-60 3 +[0 25 29 30 34 35 39 40 APL Reference Manual 4 ROWS, Primitive Mixed Functions v+ Drop Further examples: 0«POL<2 0 +---+ 3p0,(c'ABC'),1,0,(c'AB"),"! 1 | ABC| +--—+ 0 +--+ 0 | AB| +-—+ POL 0 +---+ 1 | ABC| t~=—+ 0 O +--+ |AB| +--+ 2 v[1]POL (APL outputs a blank line) 1 y[1]1P0L 0 +---+ 1 | ABC| +--—+ 2 +[2]P0L 1 0 O«MEW<4 3 p'XY' +--+ 1 1 3 (c,1) 2 '" "4V ' ' 01 40 3 | XY | +--1 t---+ 2 ++ | +-+] 111 [ +-+1 || t +---+ 2 1 4 [2 1]MEW APL Reference Manual 1-61 Primitive Mixed Functions + Drop 2 0 v MEW 0 0 The following expression describes the formal relationship between drop and drop with axis: 4+B «> Ay [1ppBlB Possible Errors Generated 9 1-62 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (LEFT LENGTH NOT FQUAL TO RIGHT RANK) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPE) 15 DOMAIN FRROR (NOT AN INTEGER) 27 LIMIT EFERROR (INTEGER TOO LARGE) 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (LEFT ARGUMENT HAS WRONG LENGTH) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR 30 AXIS DOMAIN EFRROR (NOT AN INTEGER) 30 AXIS DOMAIN FRROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual (INCORRECT TYPF) Primitive Mixed Functions c Enclose c Enclose Form cB c[K]B Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as constituent items Rank (ppB)-p,.K Shape (pB)L(1ppB)~K] Depth (02=B)+=8 Implicit Arguments None. Description The monadic = function builds enclosed arrays. For a nonsimple scalar argument, the result of the form < B is always an enclosed scalar item. If the argument is a simple scalar, the depth remains the same: B«~~+cB when B is a simple scalar. The result of the form < [ K] B is an array of enclosed scalars: APL Reference Manual 1-63 Primitive Mixed Functions = Enclose B « 4 C « 15 D+ 2 2 p [J«B+«cH '"ABCD' RENCLOSE A SIMPLE SCALAR, NOTHING HAPPENS M [J«B<c,B aMAKE A SINGLETON +-+ | 4] +-+ [J«C<c( e |1 2 datate + 3 4 5] t--—-—-———-- + D+D+CD +--+ | AB| | CD| +--+ pB o pC ¢ pD RTHE NEW B C AND D ARE SCALAR (APL outputs 3 blank lines) Each time you use monadic <, you increase the depth of the argument by one (unless the argument is a simple scalar). For example: [«D<«2 2p 'ABCD' AB CD pD 2 2 =D aDEPTH OF D SHOWS A SIMPLE ARRAY 1 U«D+cD +--+ | AB| | CD| +--+ oD (APL outputs a blank line) =J)) ADEPTH OF D HAS INCREASED TO 1 Using the catenate function (, ) with < allows you to create arrays with multiple items. In such an expression, you must use parentheses to prevent the scope of « from extending to the rightmost end of the expression. You can also enclose arrays that are already enclosed. The only limit to the depth you create is the memory available to the workspace. APL Reference Manual Primitive Mixed Functions < Enclose For example: B+l C<15 O«E<B , h 4 (<B) aNOTE USE OF PARENTHESES , cC ---mm——- + |1 2 3 4 5] to—mmmm—— -+ 0E 3 =F 2 2 p D<2 O«E<«B , b 4 '"ABCD' (<B) , -+ +--+ |1 2 34 5| tom e + |AB] |CD] (<C) , D aNOTE USE OF PARENTHESES +--+ pE n =F 2 [«E<cE i+ |4 4 | - + +--+] |1 2 3 4 5| |AB]|| | | 4 + lcl| t--+t| o m e+ ASHAPE OF E SHOWS IT IS NOW A SCALAR pE (APL outputs a blank line) =F 3 The result of the form < [ X¥] B is in an array of items formed by enclosing subarrays along the axes given by ¥. The axis numbers in X must be a unique set of numbers in 1 p p B: «5+«2 3p16 cS APL Reference Manual 1-65 Primitive Mixed Functions c Enclose c[1]S fommt to-—t |1 4] |2 5] t--—t |3 6] t---+ t---+ +--—+ c[2]S t----- + -+ 112 3] |4 5 6] t-—--- + -+ cf1 218 t----- + |1 2 3] |4 5 6] fomm-- + c[2 1]§ ACHANGING AXIS ORDER TRANSPOSES SHAPE ==t [1 4] |2 5] |3 6] +---+ SCHILLER«'AGAINST' O«SCHILLER<3 tommmm -S + |AGAINST| |STUPIDITY| tomm t--- -S + -+ -+ | THE GODS| |THEMSELVES| tom - I tomm + -+ -+ |CONTEND| |IN VAIN| tom t o 'STUPIDITY' mm———-- + 0«PHRASES<«5[1.5]c[21SCHILLER o+ | +------- R + | | |AGAINST| |STUPIDITY]| | 4= + - + | oe+ Fo + |+~ t e + | | |THE GODS| | |THEMSELVES]|| 4= L +| o + L L L + | | |CONTEND| |IN VAIN|| | +--==--- t ot + | + o PHRASES J 1-66 L+ |+~ S fom 1 APL Reference Manual 'THE GODS' 2pSCHILLER,'CONTEND' 'THEMSELVES' 'IN VAIN! Primitive Mixed Functions c Enclose If ¥ is empty, than it has no effect if B is a simple array. If B 1s enclosed, then each item in B becomes enclosed one level deeper (c [ 1 01 B <~ < B). For example: [«S«2 3p6 aCREATE S, A SIMPLE ARRAY c[10]S aEMPTY K, 4 5 b = 123 2 3 5 6 NO CHANGE SCHILLER«'AGAINST' 'STUPIDITY' 'THE GODS' 'THEMSELVES' 0<SCHILLER<3 2p SCHILLER, 'CONTEND' 'IN VAIN' c[10]SCHILLER T | | AGAINST|| aEMPTY K, ITEMS NESTED DEEPER ot q | |STUPIDITY|| Further examples: APL Reference Manual 1-67 Primitive Mixed Functions c Enclose [«POL«2 +---+ 0 3 p 'ABC' 0 (c,2) 99 'A' '0' +---+ | ABC| | +-+] -t ]2]] [+-+] +---1 99 A0 cPOL S et T+ | +-=--+ 0 +---+]| [ [4BC| [+===+ | | |99 |+-+]] [12]]] [+-+1] £t A0 tommm l o+ The first two of the following expressions describe the relationship between c and < [ K] . The third expression describes the relationship between < [ the disclose (= [ X] ) function: cB «> c[1ppB]B c[K]B +> c(AK)¥B <[K] B (only true when K includes all axes of B ) B <> o[K] B <> ocB Possible Errors Generated 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 1-68 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN FRROR (DUPLICATE AXIS NUMBER) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCOKRRECT TYPFE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual ¥] and Primitive Mixed Functions e Enlist € Enlist Form € B Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as argument Rank 1 Shape Vector Depth 1 (simple vector) Implicit Arguments None. Description ¢ builds a simple vector by recursively raveling each of the items in its argument. For example: O«4d<«e 2 56 7 (2 (2 2p5 6 8 ABCA 2 7 8)) 'ABC' '"A' 2 5 6 7 8 '"AB(C' 5 6 7 8 ABC Possible Errors Generated None. APL Reference Manual 1-69 Primitive Mixed Functions ¢ Execute ¢ EXxecute Form ¢ B ¢ 18 formed with 1 and o Argument Domain Type Any Shape Any (Vector domain for characters) Depth Any (0 or 1 for characters) Result Domain Type Any Rank Any Shape Any Depth Any Implicit Arguments None. Description The monadic ¢ function executes the expression represented by its characterstring argument as if that expression were entered in immediate mode or included in a user-defined operation. For example, the expressions 1 5 and ¢ ' 15" return the same result: 15 12345 ¢"15! 12345 B<15 ¢ 'B! 2 1-70 345 APL Reference Manual Primitive Mixed Functions ¢ Execute For a numeric argument B, ¢ B returns B. For example: 020 20 B<15 ¢B 12 345 For an enclosed or heterogeneous array B, ¢ B returns B. For example: e 1 2 A 1 2 A 0«POL<2 +---+ 3 3 0 3p ('ABC') 0 (c,2) 99 '4A' O +---+ |ABC| |+-+] t---+ [[2]] [ +-+] t--—1 99 t---+ 40 ¢ '"POL 0 +---+ |ABC| | +-+] t-—-+ [[2]] | +-+1 t---+ 99 t---+ A0 e POL 0 +---+ |ABC| |+-+| t---+ [[2]] [ +-+] t---+ 99 4 0 The ¢ function is similar to the 1 XQ system function; however, there are several differences. One difference is that the 1 xQ system function always returns a value, but the ¢ function returns a value only if the evaluation of its argument returns a value. Another difference is that the 0JXx¢@ function cannot execute a branch function (=), and the ¢ function can. The ¢ and 0 x¢ functions also handle errors differently. Errors resulting from the evaluation of the 0XQ function’s argument cannot be trapped; if an error occurs during the evaluation of its argument, [ XQ returns an empty array whose shape indicates the number of the error. With the ¢ function, however, you can use [] TRAP to trap errors. If an error occurs in the character string being executed by ¢, APL generates—in addition to the normal three-line error message—an execute error message for the line on which the actual execute error occurred. APL Reference Manual 1-71 Primitive Mixed Functions ¢ Execute For example: V GRIFF A B+ed V [1] [2] GRIFF 7 '3, ¢ SYNTAX FRROR (RIGHT ARGUMENT TO FUNCTION MISSING) 3, A 25 EXECUTE ERROR GRIFF[1] B+sA A )SI GRIFF[1] = B 11 VALUE ERROR B A GRIFF' 11 ! VALUE ERROR GRIFF[1] (REQUIRED VALUE NOT SUPPLIED BY EXECUTE) B«<sA A In the previous example, when the argument to the ¢ function was invalid ('3, '), APL generates six lines of error messages and suspends operation execution. The blank argument is a valid one for the ¢ function, but ¢ ' ' does not produce a value, so APL signals VALUE ERROR when the assignment is made to B. If you enter the attention signal while the ¢ function is executing, APL stops and signals ATTENTION SIGNALED. Note that quiet functions are still quiet when executed, provided that the execute is the leftmost function in the statement. When the argument is empty and numeric, the result is an empty numeric vector (¢ 1 0 «»> 1 0). When the argument is empty and character, the result is an empty character vector (' <> o 1-72 ' ') 1if a value is required by the expression. For example: APL Reference Manual Primitive Mixed Functions ¢ Execute [RASR RAASE ¢ 10 o M Ace AQUIET, NO OQUTPUT ! A (APL outputs a blank line.) Possible Errors Generated 9 25 RANK ERROR (NOT VECTOR DOMAIN) EXECUTE ERROR APL Reference Manual 1-73 Primitive Mixed Functions M and B File Input and Output K and B File Input and Output Form B [[mode | index]ll chan [data-typel d is formed with 0 and <« Argument Domain Type Numeric Shape Vector domain Depth Any Result Domain Type Any Rank Any Shape Any Depth Any Form [datall 8 [[[mode | index]] chan [data-typel B is formed with 0 and -~ Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain 1-74 Type Numeric Shape Vector domain Depth 0 or 1 (simple) APL Reference Manual Primitive Mixed Functions 4 and B File Input and Output Result Domain Type Same as left argument Rank o p data-sent Shape o data-sent Depth = data-sent Parameters mode | Is an integer representing one of the modes listed in Table 5-3 in the VAX APL User’s Guide. This parameter is used only when accessing files with ASCII sequential organization. When you specify mode, it must be surrounded by brackets. index Is the component number, record number, or key value in a direct-access, relative, or keyed file, respectively. Index must be surrounded by brackets. chan Is a positive integer scalar whose value is a channel number in the range 1 through 999. data-type Specifies the data type of the record you want to read or write. When you include a value for data-type, you imply that the record contains pure data; that is, the beginning of the record does not contein any header information. If you do not specify data-type, or if you specify a value of 0, APL assumes that there is a header at the beginning of the record data Is the data that is to be written to the file. Description The file input () and file output (8) functions are for reading and writing files. B and B are described in greater detail in Chapter 4 of the VAX APL User’s Guide along with other file I/O information. The file output function (8 ) in its monadic form deletes a component or record from a direct-access, relative or keyed file. APL signals DOMAIN ERROR (DELETION NOT ALLOWED) if you use monadic B with a sequential file. When APL Reference Manual 1-75 Primitive Mixed Functions d and B File Input and Output monadic B is not the leftmost function in the statement, it returns an empty numeric matrix of shape 0 75. The value of the @ function is the record read from the specified file. The B function is quiet. It does not display a result if it is the leftmost function in a statement. When it is not the leftmost function, B returns the value of its left argument. When a B or B function references a channel associated with a file that is not open, APL opens the file and executes the function. Possible Errors Generated 15 1-76 DOMAIN ERROR (DELETION NOT ALLOWED) APL Reference Manual Primitive Mixed Functions + First 4 First Form + B Argument Domain Type Any Shape Any - Depth Any Result Domain Type Same as selected item Rank Same as selected item Shape Same as selected item Depth Same as selected item Implicit Arguments None. Description The monadic + function builds an array by disclosing the first item from an existing array. If B is empty, then + returns the prototype of B: B <« 4 C « 15 +C D« 2 2 p "ABCD! +D APL Reference Manual 1-77 Primitive Mixed Functions + First 0« E <« B, et + |12 (cC) , cD -t 34 5] |AB| fom e + |CD| +--+ +E aFIRST OF E =1E "DEPTH SHOWS A SIMPLE SCALAR ARRAY 1E[2] AFIKRST OF SECOND ITEM OF E 4 0 12345 =4E[2] ADEPTH SHOWS A SIMPLE ARRAY ptE[2] ASHAPE SHOWS A tE[3] AFIRST OF THIRD ITEM OF E =+E[3] ADEPTH SHOWS A SIMPLE ARRAY ptE[3] ASHAPE SHOWS A MATRIX + REMPTY ARG RETURNS 1 VECTOR 5 AB CD 1 2 2 0 3p99 PROTOTYPE 0 (L + 0p(1 aPROTOTYPE 2 3) IS A CHARACTER BLANK "ABC! 000 For simple arrays, the result of monadic + is the same as it would be with the dyadic take function (+) when all the items of the left argument are 1. Formally, this can be represented as follows: +B <+ ( (ppB) p 1) + B. However, note that take does not disclose items of an array. First is also related to the pick (=) function as follows: Possible Errors Generated None. 1-78 APL Reference Manual +B <~ (c(ppB)p1)>B Primitive Mixed Functions v Monadic Format ¢ Monadic Format Form 7B 7 18 formed with T and - Argument Domain Type Any Shape Any Depth Any Result Domain Type Rank Character 1[ ppB for simple numeric or heterogeneous B ppB for simple character B 2 for nonsimple B Shape (T 14 pB)<+> (" 1y presult) for simple B Depth 1 (simple) Implicit Arguments PP (Determines decimal precision) [1NG (Determines minus sign placement) O0DcC (Displays control of enclosed arrays) Description The monadic ¥ function formats its argument array as a character array, making it look as it would appear when displayed by APL. Thus, if the argument array is already of type character, the result is identical to the argument: APL Reference Manual 1-79 Primitive Mixed Functions s Monadic Format O«4+«3 S5p'STAN SAM STEVE' STAN SAM STEVE 74 STAN SAM STEVE p¥A 35 If the argument array is of type numeric, the result appears to be identical to the argument; however, the blank characters displayed along with the items are actually part of the result array. For example: 4p18 A«2 B«s4 A 12 34 56 7 8 pA 2 U B 1234 56 78 pB 2 7 (" ",B)[;2x14] 1234 5678 Note the difference between the shapes of the numeric array 4 and the character array B. Since it is not feasible to indicate both shape and depth in a two-dimension display, the format of an enclosed array is always a matrix. Shape is indicated by blank lines in the same manner as for simple arrays. Display of depth is controlled by O0DcC, the display control system variable. Further examples: O0<POL«2 +---+ 0 3p +---+ |ABC| |+-+] -t | 12]] | +-+] +--—+ 99 A0 pPOL 2 1-80 3 APL Reference Manual ('ABC') 0 (c,2) 99 'A' 0 Primitive Mixed Functions v Monadic Format 0«B«3P0L t+---+ 0 +---+ | ABC| | +-+] t=-=t []2]] | +-+] +--=1 A0 99 pB aTHE SHAPES OF B AND POL ARE DIFFERENT 0«XT« 3 p (2 0 p 5) ('") (10) aCREATE AN EMPTY ARRAY pXT O«B«3XT ++ ++ ++ REEEEEE || ++ ++ o B Possible Errors Generated None. APL Reference Manual 1-81 Primitive Mixed Functions 7 Dyadic Format ¥ Dyadic Format Form As B 7 1s formed with T and - Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Numeric Shape Any Depth 0 or 1 (simple) Result Domain Type Character Rank 1l ppB Shape (T14pB) ,+/104(2,70.5%p,A)pA (provided no widths are 0) Depth 1 (simple) Implicit Arguments ONG (determines minus sign placement) Description The dyadic # function formats its right argument according to the width and precision information supplied by its left argument. The left argument generally contains one pair of numbers for each column (last axis) in the right-argument array. The first number specifies the width of the field; the second number controls the print precision. For example: 1-82 APL Reference Manual Primitive Mixed Functions ¢ Dyadic Format J«B<«2 12 3 56 7 U4p18 4 8 A<5 2 4 1 4 06 3 R<A%B R 1.00 2.0 3 4,000 5.00 6.0 7 8.000 pR 2 19 Because the right argument has four columns, the left argument (4) has four pairs of numbers. The last axis of the formatted array () has a length of 19, the sum of the widths specified in 4 ( 5+ 4+ 4+6). The second number of each pair in 4 specifies how many digits are to be displayed to the right of the | | decimal point. You do not have to specify more than one pair of numbers as the left argument. If you specify only one pair, that pair is replicated a number of times equal to the length of the last axis of the right argument. The last axis of the formatted array Y, below, has a length of 36 because the format function specifies that each of the three columns should have a width of 12. The items are displayed with four digits to the right of the decimal point because the second number of the left argument pair is . Note the difference in the results when the array is formatted so that all columns have a width of 9 and a print precision of 2, and then a width of 6 and a print precision of 0. If a print-precision specification in the left argument is negative, the associated item is formatted in scientific rather than decimal form, and the argument represents the number of digits in the item’s mantissa. O«X<2 3p 31.16 0 ~1.07 15.578 8 235.61 ~1.07 0 31.16 ~15.578 8 235.61 pX 2 3 O«Y<«12 31.1600 ~15.5780 UsX 0.0000 8.0000 ~1.0700 ©235.6100 pY 2 36 A<9 A 31.16 - 15,58 23X 0.00 8.00 “1.07 235.61 pA 2 27 APL Reference Manual 1-83 Primitive Mixed Functions ¥ Dyadic Format O«R<«6 0%X 31 0 1 " 16 8 236 pR 18 2 0«B«9 23X 3.1F1 0.0F0 "1.6E1 8.0F0 “1.1F0 “2.4F2 0«C«7 13X 361 0F0 “1E0 “2E1 8E0 . The width specification in the left argument may be omitted or may be 0. If it is omitted, the entire left argument must be a singleton and is extended to (2x"14pB)p 0,4, for arrays 4 and B. If the width specification is 0, then APL uses the minimum width possible, allowing for one blank between the formatted columns. Two more examples of dyadic # follow. The first illustrates the formatting of a O 2p18 J«C+«5 234 =N 2 oo ~ O«4«2 O W rank 3 array; the second shows how you can use s to format tables. 1.00 2.00 3.00 4,00 5.00 6.00 7.00 8.00 pC 2 2 10 3p 1 00101111 = O o N O0«B«3 1 0 ¥B 101 111 1-84 APL Reference Manual Primitive Mixed Functions # Dyadic Format Second example: ATABLE FORMATTING RONS<«5 7p'APL COLS«"'" USERS FORM+«5 3p4 ( ') (74" FORTRANCOBOL PROGS BASIC PLI ! GSYST ROWS),COLS;7 USERS PROGS SYSTS APL 1 2 3 FORTRAN 4 5 COBOL 7 8 1 BASIC 2 3 4 PLI 5 6 7 O0%FORM If the right argument to the dyadic format function is empty, the shape of the result is determined by the following function: Vi<l EMPTY SHAPEF R ;C;W;P [1] [2] [3] [4] [5] [6] L«<(( 14pR),2)p((1=p,L)/0),L [7] [8] Z<( 1¥pR), (-W[1]=0)++/C W<L[;1] P<L[;2] CeW,(P+3),2,6,[1.5]6-P Z«(W=0)x2+(-xP)+< 1 C<(Z¢C) ;1] V For example: 0 10 0 9 p5 0 0 290 2p5 p0 2 5 0%0 2p5 Possible Errors Generated 9 RANK EFRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPF) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN FRROR (NEGATIVE NUMBER NOT ALLOWED) APL Reference Manual 1-85 Primitive Mixed Functions 7+ Dyadic Format 1—86 15 DOMAIN ERROR (WIDTH TOO SMALL) 27 LIMIT FERROR (INTEGER TOO LARGE) 27 LIMIT FRROR (PARAMETER OUT OF RANGE) APL Reference Manual Primitive Mixed Functions ¥ Monadic Grade Down Y Monadic Grade Down Form Y B VYVLK]B ¥ is formed with v and | Argument Domain Type Homogeneous Shape Matrix, vector, or scalar (not singletons of rank >2) Depth 0 or 1 (simple) Result Domain Type Nonnegative integer Rank 1 Shape (¢pB) [K] Depth 1 (simple) Implicit Arguments 010 (YB when ,0I0 « 1 is identical to 1 + ¥B when ,0I0 « 0) Description The monadic ¥ function returns a numeric vector whose items can be used to sort the items of the argument in descending order. Thus, grade down does not actually sort arrays. It creates a permutation vector of the index numbers of the argument array’s items, and this vector can then be used to sort the array. Sorting a vector requires two steps. First, the vector is the argument to the grade down function, and then the result is used to index the vector: 7 9 A<2 4 3 10 4 0«B+Y4 6234751 A(B] 10 97 4 4 32 APL Reference Manual 1-87 Primitive Mixed Functions ¥ Monadic Grade Down If two or more items of a vector or matrix have the same value, the order of the items is determined by their relative positions in the original array (this is called a stable sort). For character arguments, the collating sequence is determined by the value of 0 AV. Note that for numeric arguments, the result is not [J CT-dependent. When you use the grade down function to sort a matrix, APL treats each row or column as a string. Thus, you can use the function to sort row by row or column by column, but not to sort individual items within a row or column. When applied to a matrix, the grade down function produces a vector whose length is equal to the number of rows or columns in the matrix. The following sorts the matrix B by rows and then sorts the matrix by columns 1 8 3 2 32 1503197032080 OO 2 5p < O 3 3 xR~ e 5 7 O Y w O«B«3 In this example, the original first row remains the first row, the third row becomes the second row, and the second row becomes the third row. Note that ¥B and ¥ [ 2] B are equivalent. | You can also sort character arrays by rows or by columns. For example: 1-88 APL Reference Manual Primitive Mixed Functions ¥ Monadic Grade Down O«B<«3 5p'"ALLENALAN ALLAN' ALLEN ALAN ALLAN ALLEN BLYB;] ALLAN ALAN B[;V[1]B] NLLEA LANA NLLAA If the argument to V is a scalar, the ravel function is applied to extend it to a one-item vector, and the result of the ¥ function is ,J7I0: R«V5 R 1 1 ppR Note that 0 CT is not an implicit argument to the grade down function. Possible Errors Generated 9 RANK ERROR (NOT A SCALAR, VECTOR, OR MATRIX) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 27 LIMIT ERROR (INTEGER TOO LARGE) 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual 1-89 Primitive Mixed Functions ¥ Dyadic Grade Down V¥ Dyadic Grade Down Form AV B ¥ is formed with v and | Left Argument Domain Type Character Shape Any Depth 0 or 1 (simple) Right Argument Domain Type Shape Character | Depth Any 0 or 1 (simple) Result Domain Type Nonnegative integer Rank 1 Shape 14 p 5B Depth 1 (simple) Implicit Arguments 0710 (AVB when ,J7I0 <« 1 1s identical to 1+ A4Y¥B when ,JI0 « 0) Description The dyadic ¥ function returns a numeric vector whose items can be used to sort the items along the first axis of the right argument in descending order. (The sort is performed according to the collating sequence defined in 4.) Grade down does not actually sort arrays; it creates a permutation vector of the index numbers of the argument array’s items, and this vector can then be used to sort the array. If either argument is empty, the result of the grade function is 1 14 p B. If the length of the first axis of B is one, then the result is ,[JI0. 1-90 APL Reference Manual Primitive Mixed Functions ¥ Dyadic Grade Down If two or more items of the right argument have the same value, the order of the items is determined by their relative positions in the original array (this is known as a stable sort). Sorting an array requires two steps. First, the array is the right argument to the grade function, and then the result is used to index the array. The left argument determines the order in which APL collates the items of the right argument; APL evaluates the collating sequence from right to left. For example: ALPHA1<"IVXLCDM' o N<'CMXIVCILI! X <« [0 « ALPHA1VN 2168354749 N(X] MCCLXVIII DATES<[IBOX 'MCCLXVIII VIl MLXXIII DCCCXXIIT CLXVI MDCLIII CLXXI AVIIL! X < [ « ALPHA1VDATES 6 1 3 4758 2 DATES[X;] MDCLIII MCCLXVIII MLXXIII DCCCXXIII CLXXI CLXVI XVIII VII HEX+«' 0123456789ABCDEF" HD<[IBOX '8E7 3DA 976 AE8 F8 3D5 4o APL Reference Manual 1-91 Primitive Mixed Functions v Dyadic Grade Down X « 0 « HEXVHD 4 312657 HD[X;] AE8 976 8E7 3DA 3D5 F8 40 To sort an array that contains more than one font, you can use sequences similar to the following, depending on the desired result: a7 SORTS AFTER 7 AND BEFORE Y G T I T e T e e e e e mmhm e eaam dmie e e X + [ « ALPHA2YWORDS 87263511 ] WORDSLX; PALM NEAR nZ SORTS AFTER A AND BEFORE Y ALPHA3+«'ABCDEFGHIJKLMNOPQRSTUVNXYZABCDEFGHIJKL MNOPQRSTUVWXYZ' X « [0 « ALPHA3VWORDS 72 358¢61H41 WORDSLX; ] NEAR 1-92 APL Reference Manual Primitive Mixed Functions ¥ Dyadic Grade Down If any items appear in the right argument when they have not been specified in the left argument, APL considers them equal and places them at the end of the sort sequence. For example: ALPHA4«'"ABCDEFGHIJKLMNOPQRSTUVWNXYZ' GAMES«[JBOX 'FREEIE TAG MONOPOLY HIDE AND SEEK BACKGAMMON FRISBEE' X « [J « ALPHAUYGAMES 2 34651 GAMES[X; ] MONOPOLY HIDE AND SEEK FRISBEE BACKGAMMON FREEZE TAG When the left argument has a rank greater than one, each axis represents a level of comparison and the last axis receives the highest priority. For example, when the left argument has two rows, each containing an alphabet in a different font, APL gives higher priority to the order specified by the columns (last axis) than it gives to the fonts specified by the rows (first axis). For this reason, the word #ELM precedes the word HEEL in the end result of the following example: APL Reference Manual 1-93 Primitive Mixed Functions ¥ Dyadic Grade Down » ALPHAS+'ABCDEFGHIJKLMNOPQRSTUVWXYZ ABCDEFGHIJKLMNOPQRSTUVWXYZ' WORDS«{1BOX 'HOPE X+ 0 < ALPHASYWORDS 723586 11U WORDS([X;] NEAR Duplicate items, such as character blanks, in the left argument (4) may yield an unexpected collating sequence. APL compares the locations of a duplicate item and bases its position in the final collating sequence on this comparison. The final location of a duplicate item is the minimum value along each axis for each occurrence. For example, if a duplicate ¥ appears at locations 1 1 3 and 2 1 2 in a three-dimensional array, then the position of the ¥ in the final collating sequence is 1 1 2. If the position 1 1 2 is occupied by a value other than v, the two are treated as equivalents: (0«D+2 2 3p'ABCDEFGCIJKL' («B<«4 3p'ABFAAFACFABF' ABC DEF GCI JKL ABF AAF ACF ABF B[DYB;] ABF ACF ABF AAF 1-94 APL Reference Manual aNOTE THAT C AND B ARE EQUIVALENT Primitive Mixed Functions ¥ Dyadic Grade Down In the following example, D appears at locations 1 2 and 2 1, and B appears at locations 1 1 and 2 2. In the final collating sequence, both are positioned at location 1 1 and are treated as equivalent values: [l«L«2 2p'BDDB' [«R<«5 2p'DBBDBDDBBD' BD DB DB BD BD DB BD LYR aD AND B ARE EQUIVALENT, NO CHANGE 12345 For more information about how the dyadic grade function is implemented, see Smith, H.J., "Sorting - A New/Old Problem." APL Quote Quad 9 (June 1979) ppl123-127. Possible Errors Generated 10 LENGTH FRROR (ARGUMENT STRING IS TOO LONG) 15 DOMAIN EFRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 30 AXIS DOMAIN ERROR (INCORRECT OPERATION) APL Reference Manual 1-95 Primitive Mixed Functions A Monadic Grade Up A Monadic Grade Up Form A B A[LK]B A is formed with Ao and | Argument Domain Type Homogeneous Shape Matrix, vector, or scalar (not singletons of rank > 2) Depth 0 or 1 (simple) Result Domain Type Nonnegative integer Rank 1 Shape (¢pB) [K] Depth 1 (simple) Implicit Arguments 0710 (ABwhen[1I0 « 11s1dentical to 1 + AB when 070 « 0) Description The monadic 4 function returns a numeric vector whose items can be used to sort the items of the argument in ascending order. Thus, grade up does not actually sort arrays; it creates a permutation vector of the index numbers of the argument array’s items, and this vector can then be used to sort the array. Sorting a vector requires two steps. First, the vector is the argument to the grade up function, and then the result is used to index the vector: A€2 97 4 3 O«B<)A 1547326 A[B] 23447910 1-96 APL Reference Manual 10 4 Primitive Mixed Functions A Monadic Grade Up If two or more items of a vector or matrix have the same value, the order of the items 1s determined by the relative positions of the items in the original array (this is called a stable sort). For character arguments, the collating sequence is determined by the value of 04V. Note that for numeric arguments, the result is not 00 CT-dependent. When you use the grade up function to sort a matrix, APL treats each row or column as a string. Thus, you can use the function to sort row by row or column by column, but not to sort individual items within a row or column. - When applied to a matrix, the result of the grade up function is a vector whose length is equal to the number of rows or columns in the matrix. The following sorts the matrix B by rows and then by columns: B+«3 503 2 1503197032080 AB 2 31 A[2]B ;4 [1]B] 012 091 00 2 In this example, the original second row becomes the first row, the third row becomes the second row, and the first row becomes the third row. Note that A B and 4 [ 2] B are equivalent. You can also sort character arrays by rows or by columns. For example: O«B<«3 Sp'ALLENALLINALLAN' ALLEN ALLIN ALLAN BLAB;] ALLAN ALLEN ALLIN B(;4[1]B] AELLN AILLN AALLN APL Reference Manual 1-97 Primitive Mixed Functions A Monadic Grade Up If the argument to 4 is a scalar, the ravel function is applied to extend it to a one-item vector, and the result of the 4 function is ,010: R<AS R 1 ppR 1 Note that 0 CT is not an implicit argument to the grade up function. Possible Errors Generated 1-98 9 RANK EFRROR (NOT A SCALAR, VECTOR, OR MATRIX) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 27 LIMIT ERROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual | Primitive Mixed Functions A Dyadic Grade Up A Dyadic Grade Up Form AAB A is formed with A and | Left Argument Domain Type Character Shape Any Depth 0 or 1 (simple) Right Argument Domain Type Character Shape Any Depth 0 or 1 (simple) Result Domain Type Nonnegative integer Rank 1 Shape 1+p 5B Depth 1 (simple) Implicit Arguments [1I0 (AAB when 070 « 1 isidenticalto 1 + AAB when 110 <« 0) Description The dyadic A function returns a numeric vector whose items can be used to sort the items along the first axis of the right argument in ascending order. (The sort is performed according to the collating sequence defined in 4.) Grade up does not actually sort arrays; it creates a permutation vector of the index numbers of the argument array’s items, and this vector can then be used to sort the array. If either argument is empty, the result of the grade function is 1 14 p B. If the length of the first axis of B is one, then the result is ,[0 0. APL Reference Manual 1-99 Primitive Mixed Functions A Dyadic Grade Up If two or more items of the right argument have the same value, the order of the items is determined by their relative positions in the original array (this is known as a stable sort). Sorting an array is accomplished in two steps. First, the array is the right argument to the grade function, and then the result is used to index the array. The left argument determines the order in which APL collates the items of the right argument. For example: ALPHA1<'"IVXLCDM' N«'"CMXIVCILI' X « [« (OALPHAL) AN 2168354749 N[X] MCCLXVIII DATES«[JBOX "MCCLXVIII VIII MLXXIII DCCCXXIII CLXVI MDCLIII CLXXI XVIII! X « [0 « ALPHA1ADATES 2 8574316 DATES[X;] VIIT XVIII CLXVI CLXXI DCCCXXIII MLXXIII MCCLXVIII MDCLIII HEX«' 0123456789ABCDEF" HD«<[]BOX '8E7 3DA 976 AES8 F8 3D5 40 1-100 APL Reference Manual Primitive Mixed Functions A Dyadic Grade Up X « [0 « HEXAHD 756 2134 HD[X;] 40 F8 3D5 3DA 8E7 976 AF8 To sort an array that contains more than one font, you can use sequences similar to the following, depending on the desired result: — v e a— e T e e mmm em— e m— m— e e e e e e e e e mven e e e —t—— X « [0 « ALPHA2JWORDS L' 1536278 WORDS[X;] HELM HOPE HEEL HEEL NEST ALPHA3+«[(+«'ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKL MNOPQRSTUYNXYZ' ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKL MNOPQRSTUVWXYZ X « [1 « ALPHA3AWORDS 416 853 27 APL Reference Manua! 1-101 Primitive Mixed Functions A Dyadic Grade Up WORDSL[X; ] If any items appear in the right argument when they have not been specified in the left argument, APL considers them equal and places them at the end of the sort sequence. For example: ALPHA4<«'"ABCDEFGHIJKLMNOPQRSTUVNXYZ' GAMES+[1BOX 'FREEZE TAG MONOPOLY HIDE AND SEEK BACKGAMMON FRISBEE' X « [0 « ALPHAYAGAMES 5164 2 3 GAMES[X;] BACKGAMMON FREEZE TAG FRISBEE HIDE AND SEEK MONOPOLY When the left argument has a rank greater than one, each axis represents a level of comparison and the last axis receives the highest priority. For example, when the left argument has two rows, each containing an alphabet in a different font, APL gives higher priority to the order specified by the columns (last axis) than it gives to the fonts specified by the rows (first axis). For this reason, the word #EE L precedes the word ZELM in the end result of the following example: 1-102 APL Reference Manual Primitive Mixed Functions A Dyadic Grade Up ALPHAS<2 26p'ABCDEFGHIJKLMNOPQRSTUVWXYZ ABCDEFGHIJKLMNOPQRSTUWXYZ' WORDS+[JBOX 'HOPE e e i s i X « [ « ALPHASAWORDS 53412768 WORDSLX;] HEEI HEEL HELM HOPE Duplicate items, such as character blanks, in the left argument (4) may yield an unexpected collating sequence. APL compares the locations of a duplicate item and bases its position in the final collating sequence on this comparison. The final location of a duplicate item is the minimum value along each axis for each occurrence. For example, if a duplicate ¥ appears at locations 1 1 3 and 2 1 2 in a 3-dimensional array, then the position of the ¥ in the final collating sequence is 1 1 2. If the position 1 1 2 is occupied by a value other than ¥, the two are treated as equivalents. O«D<«2 2 3p'ABCDEFGCIJKL' ABC DEF GCI JKI, («B+u4 3p'ABFAAFACFABF' ABF AAF ACF ABF B[DAB;] ANOTE THAT C AND B ARE EQUIVALENT AAF ABF ACF ABF APL Reference Manual 1-103 Primitive Mixed Functions A Dyadic Grade Up In the following example, D appears at locations 1 2 and 2 1, and B appears at locations 1 1 and 2 2. In the final collating sequence, both are positioned at location 1 1 and are treated as equivalent values. O«L+«2 2p'BDDB' («R+5 2p'DBBDBDDBBD' LAR aD AND B ARE FQUIVALENT, NO CHANGE 12345 For more information about how the dyadic grade function is implemented, see Smith, H.J., "Sorting - A New/Old Problem," APL Quote Quad 9 (June 1979) pp123-127. Possible Errors Generated 1-104 10 LENGTH ERROR (ARGUMENT STRING IS TOO LONG) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT OPERATION) APL Reference Manual Primitive Mixed Functions 1 Index Generator 1 Index Generator Form 1 B Argument Domain Type Nonnegative near-integer Shape Singleton Depth 0 or 1 (simple) Result Domain Type Nonnegative integer Rank 1 Shape ,B Depth 1 (simple) Implicit Arguments 010 (1 Bwhen[JI0 « 1 is identicalto 1 + 1 B when JI0 « 0) Description For an argument B, the monadic : function generates a vector of B consecutive, ascending integers starting with the value of the index origin. For example: Jed« 1l 2 3 I pA APOWERS OF 2 2x112 32 64 128 16 MO w 4 a0 2 0w 1 10 256 512 1024 2048 4096 5p110 X<7 5 1 3 4 1pX 2 34 APL Reference Manual 1-105 Primitive Mixed Functions 1 Index Generator If the index origin is 1, the integers have values 1 through B; if the mdex origin is 0, the 1ntegers have values 0 through B - 1: 0io 1 15 12 345 0I10<0 15 012314 Regardless of the value of 010, 1 0 is the numeric empty vector: 10 (APL outputs a blank line) p10 Possible Errors Generated 1-106 9 KRANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN FRROR (NEGATIVE NUMBER NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEFGER TOO LARGE) APL Reference Manual Primitive Mixed Functions 1 1 Index Of Index Of Form A1 B Left Argument Domain Type Any Shape Vector domain Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Nonnegative integer Rank oppB Shape o B Depth - 0 or 1 (simple) Implicit Arguments 0CT (determines comparison precision) 0I0 (A1B when IO « 1 isidentical to 1 + 418 when[JI0 < 0) Description The dyadic : function returns the position of the first occurrence in the left argument of the corresponding items in the right argument. For example: 4 9 6 3 8 1t 6 4 1 The result indicates that 6 is the third item in the left argument and 4 is the first item. APL Reference Manual 1-107 Primitive Mixed Functions 1 Index Of The result will always have the same shape as the right argument, so that an index is returned for each of the values in the right argument. If a particular value in the right argument does not appear in the left argument, APL supplies a value equal to the last index value of the left argument plus one. For example: "ABCDEFGH' 1 "HEADER! 8514589 The value R does not appear in the left argument, so APL returns the value 9 (there are eight values in the left argument) for the position corresponding to R. Note that the dyadic : function is 0 70-dependent: when 0I0 is 0, each item in the result is one less than when 010 is 1: DI0+0 "ABCDEFGH'1'HEADER' 3048 740 If the right argument of the dyadic 1 function is empty, the result is empty. If the left argument is empty, the result is all 1s (0 70«~>1): 10)12 (10 5p110 11111 11111 Note that comparisons of the items in the right and left arguments are defined in terms of the match (=) function (and so are (] cT-dependent). Because match allows mixed-type arguments, you can compare characters with numbers. However, such a comparison is always false, so that if you use mixed-type arguments for dyadic 1, the items in the result will be equal to the last index value of the left argument plus one. Further examples: O«VIC«'"ABC' 0 0 $--=+ | ABC| $---t $--+ 1-108 0 0«VOOF+ 'AB' 0 ~3 'ABC' "3 +---+ | AB | | ABC| +--1 $---4 99 APL Reference Manual 1 99 1 Primitive Mixed Functions 1 Index Of VOOF 4 VIC 2 aNOTE THAT DYADIC 1 IS (IO-DEPENDENT OI0+0 VOOF 3 1 VIC 1 O«XIP« 0 p (1 2 3) 'ABC' (APL outputs a blank line) O«V«(1 t----- + |1 2 2 3) 'ABC' +---+ 3] |ABC| t---=- + +---+ V v XIP p V 1 XIP XIP 1 ¥V aEMPTY RIGHT ARGUMENT (APL outputs a blank line) 0 aEMPTY LEFT ARGUMENT 00 Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) APL Reference Manual 1-109 Primitive Mixed Functions n Intersection N Intersection Form AnB Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type See explanation below Rank 1 Shape pu((,4)eB)/ A Depth — Implicit Arguments 0cT (Determines comparison precision) Description The dyadic n function returns the common items found in both arguments. The result is the intersection of the arguments with the duplicate items removed. Note that the order of the items in the result is not predictable. For example: 1-110 APL Reference Manual Primitive Mixed Functions n Intersection "CBEFGH' n 2 3p'ABCD' CB (2 3p "ABCD') n 'CBEFGH! BC (16) 3 45 3 45 57 n 3 57 3 n 16 4 4 You can use the intersection function to remove duplicate items from an argument. However, the unique function is the preferred method for this task. For example: A«<1 212 1 An A 212 345 65 345 34 67 34 67 1 65 34 67 1 34 ADUPLICATES ARE 1 AND 34 u 4 1 212 345 65 The type of the result depends on the types of the arguments, as shown in the following table: Argument Resulting Type Neither empty Same as left argument One empty Same as nonempty argument Both empty Same as left argument The n function compares items in terms of the match (=) function, which uses the value of JCT. Since match allows mixed-type arguments, you can compare characters with numbers. However, such a comparison is always false, so that if you use mixed-type arguments for dyadic n, the result will be empty. Note that the following definition applies: 4nB «> u (( ,A) =B) / ,A, where the order of the items may differ. Further examples: J«A<c,3 +-+ | 3] +-+ O«B<(1 2 5) 125 APL Reference Manual 1-111 Primitive Mixed Functions n Intersection O«WRL+(<,3) t---+ +----- + | +-+] |1 2 (1 2 5) 1 1 5| 3] 4=m--- + | +-+1 +---+ O«MIC«2 2 p t---+ +----- + |+-+] |1 2 AB TM10 5] [131] +----- + | +-+1 +---+ 10 MIC n WRL +---+ +----- + |+-+] |1 2 AZERO NOT IN INTERSECT 1 5] 13t +----- t | +-+] +---+ MIC u <,3 t--—+ +----- + |+-+1 aNO INTERSECTION BETWEEN TWO ARGUMENTS 10 11 2 5] |13 +-+ |31 +----- + +-+ | +-+] +---+ O«VAN«(1 2 3) 'ABC' +--==- I e s+ |1 2 3] |ABC| |+----- +| [ |1 2 3] +--— - + +---+ (c,1 2 3) ACREATE VAX | +----- t] o= + A«(1 2 3) A n A" VAN t--——- + 112 3 t--=-- + Possible Errors Generated None. 1-112 APL Reference Manual ACREATE NEW A Primitive Mixed Functions = Match = Match Form A=B = 1s formed with = and _ Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Boolean Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Implicit Arguments O0CT (determines comparison precision) Description The dyadic = function determines whether the two arguments are identical in rank, shape, and value. The result is a Boolean scalar: true, if the arguments are identical, and false if they are not. For example: APL Reference Manual 1-113 Primitive Mixed Functions = Match YABCD' = '"ABCD' YVABCD' = TACBD' "ABCD' = 2 2p'ABCD' 1 0 0 TAY = 147 0 123=123 1 123=12 0 123=1223 0 123="1"12 3" 0 ' = 10 0 The = function compares the simple items in terms of the equal (=) function and identifies equal items based on the value of 0 CT. For example: 1E 15 OcT 4 = 4-5F 16 1 Further examples: [l«A<Uu n [J«B<«c, i +-+ | 4] +-+ A =8B aNOTE DIFFERENCE BETWEEN = AND = 0 A =B +-+ 1] +-+ O«VIC«(1 2 3) +---=- + +---+ 3] |+-+]| |1 2 pommmt | | +-+] +---+ [l«N<c,6u +-+ | 4] +-+ 1-114 APL Reference Manual (c,b) Primitive Mixed Functions = Maich [J«RED«(1 2 3),N 12 3 +-+ |4 +-+ RED = VIC He@ec(1 2 3) Possible Errors Generated None. APL Reference Manual 1-115 Primitive Mixed Functions H Matrix Divide H Matrix Divide Form ABB B is formed with 0 and= Left Argument Domain Type Numeric Shape Matrix, vector, or scalar (not singletons of rank < 2) Depth 0 or 1 (simple) Right Argument Domain Type Numeric Shape Matrix, vector, or scalar (not singletons of rank < 2) Depth 0 or 1 (simple) Result Domain Type Numeric Rank Of " 2+(ppd)+ppB Shape (1+pB) ,14vp4 Depth 0 or 1 (simple) Implicit Arguments O0CT (used in the test for singularity) Description For arguments 4 and B, the dyadic # function determines the generalized solution R to the linear system A=B+ . = R. If B has more rows than columns, then dyadic B returns the least-squares solution to the linear system. The matrix divide function treats scalars and vectors as one-column matrices (except when it is determining the shape of the result). 1-116 APL Reference Manual Primitive Mixed Functions H Matrix Divide The following example shows the use of the matrix division function in solving the linear equations 3A+B=9 and 2A-B=1: X+9 1 Y«2 2p3 1 2 1 XgY 2 3 In the expression X@Y, Y is a matrix whose values are the coefficients of the equations, and X is a vector containing the constant terms 9 and 1. The result is a vector in which the first item is the value of 4 in the linear equations, and the second is the value of B. The following example shows other uses of matrix divide, including a least-squares solution: O«d«(,[1.5]2 5), 2 1 1 51 B«10 19 oJ+«X«BBA 3 U 2 . xX A+ 19 10 . O«Ad«(,[1.5]15), 1 11 2 1 31 4 1 5 1 (PP 10 B«2.001 2.998 4.002 4,997 6.01 O«X+BHA 1.0017 0.9965 B-A+.xX 0.0028 ~0.0019 0.0004 0.0063 0.005 D+X+BA 19 0.1 0.2 0.2 "0.1 "9.356402631F 0.8 0.5 2.000000000E"1 0.1 O.u X+.x4 1.000000000E0 17 2.775557562E 17 T1.04083u4086EF 1.000000000E0 For more information about how the matrix divide function is implemented, see Jenkins, M. A., The Solution of Linear Systems of Equations and Linear Least Squares Problems in APL. New York: IBM Scientific Center, Technical Report No. pp320-2989, June 1970; and Businger, Peter, and Golub, Gene H. "Linear Least Squares Solutions by Householder Transformations." Numerische Mathematik 7 (1965) pp269-276. APL Reference Manual 1-117 Primitive Mixed Functions H Matrix Divide Possible Errors Generated 9 1-118 KANK ERROR (NOT A SCALAR, VECTOR, OR MATRIX) 10 LENGTH ERROR (FEWER ROWS THAN COLUMNS) 10 LENGTH ERROR (NUMBER OF ROWS MUST MATCH) 15 DOMAIN FRROR (DIVISION BY ZERO) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (SINGULAR MATRIX) 27 LIMIT ERROR (FLOATING OVERFLOW) APL Reference Manual Primitive Mixed Functions B Matrix Inverse EH Matrix Inverse Form BB H is formed with 0 and = Argument Domain Type Numeric Shape Matrix, vector, or scalar (not singletons of rank <2) Depth 0 or 1 (simple) Result Domain Type Numeric Rank ppB Shape ¢oB Depth 0 or 1 (simple) Implicit Arguments OCT (used in the test for singularity) Description The monadic B function inverts a matrix to facilitate matrix division and a variety of other matrix operations. If the argument is a matrix, its rows must be linearly independent. If the argument is a scalar or vector, the result is a scalar or vector, respectively, but the result’s items are obtained by treating the argument as a one-column matrix. Formally expressed, for an argument B : BB «>((I,I)p1,(I<]|+pB)p0)H (24 (pB),11))pB Note that the matrix product of B and BB is the identity array. Formally expressed, for an argument B: B+ . xEHB<«~>1 APL Reference Manual 1-119 Primitive Mixed Functions B Matrix Inverse For example: O«A«+(13)o.+ 1+13 1 0.5 0.5 0.3333333333 0.3333333333 0.25 0.3333333333 0.25 0.2 _[]+X<—E]A 9 36 30 36 192 180 30 180 180 X+.x4 1.000000000F0 2.220446049EF 16 1.66533u4537E 16 "4 ,440892099E 15 1.000000000F0 71,332267630E 15 4,440892099E 15 2.220u446049F 15 1.000000000E0 For more information about how the matrix inverse function is implemented, see Jenkins, M. A., The Solution of Linear Systems of Equations and Linear Least Squares Problems in APL. New York: IBM Scientific Center, Technical Report No. pp320-2989, June 1970; and Businger, Peter and Golub, Gene H. "Linear Least Squares Solutions by Householder Transformations.” Numerische Mathematik 7 (1965) pp269-276. Possible Errors Generated 9 RANK ERROR (NOT A SCALAR, VECTOR, 10 LENGTH ERROR (THERE ARE FEWER ROWS THAN COLUMNS) 15 DOMAIN ERROR (DIVISION BY ZERO) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (SINGULAR MATRIX) 27 1-120 OR MATRIX) LIMIT FRROR (FLOATING OVERFLOW) APL Reference Manual Primitive Mixed Functions e Membership € Membership Form AeB Left Argument Domain Any Type Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Boolean Rank ppA Shape oA Depth 0 or 1 (simple) Implicit Arguments 0cT (determines comparison precision) Description The dyadic ¢ function determines whether particular items of the left argument array occur as items of the right argument array. The result is a Boolean array whose shape is the same as that of the left argument: a 1 indicates that the corresponding item in the left array is present somewhere in the right array; a 0 indicates that the item is not present. For example: A<2 3p7 8 2 46 9 Ae1b 001 110 APL Reference Manual 1-121 Primitive Mixed Functions e Membership The result identifies the items in 4 that are also items in 1 6. You can use the compression function (/) in conjunction with the membership function (¢ ) to identify the particular items that are members of both argument arrays: («A«'ABCDEF €' HEADED' GH' 10011001 A/'ABCDEFGH' ADFH Note that comparisons of the items in the right and left arguments are defined in terms of the match (=) function (and so are [1cT-dependent). Since match allows mixed-type arguments, you can compare characters with numbers. However, such a comparison is always false, so that if you use mixed-type arguments for dyadic ¢, the result will be all 0 s. Further examples: 0«ACT«(1 2 3) t---—- L ei |1 2 [ABC| |+-+] t----- + +---+ ||U4]] 3] '"ABC' (c,4) [ +-+] t--=4 [0«B0Y<«2 t---+ -+ |+-+| [Tul] | +-+] |BC| 4 2 p (c,4) +---1 ACT € BOY Possible Errors Generated None. 1-122 APL Reference Manual 'BC' (1 2 3) 0 ‘ Primitive Mixed Functions > Pick > Pick Form Ao B Left Argument Domain Type Nonnegative near-integer Shape Vector domain Depth Less than or equal to 2 Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Any Rank Any Shape Any Depth (=B) -p A (provided 4 is along the deepest path) | Implicit Arguments 0I0 (A>B when JI0+«1 is identical to ('1+,4) >B when J70<0) Description The dyadic > function selects and discloses an item from an existing array. The items in A specify the coordinates of items in B. For example: V<21 22 23 24 25 26 2>V aSELECT SECOND ITEM IN V V2] aNOTE SIMILARITY TO INDEXING 22 22 APL Reference Manual 1-123 Primitive Mixed Functions > Pick You can select an item from any depth in an enclosed array. The length of 4 determines the depth of the selected item: when 4 has one item, the selection is from the top level of B; when 4 has two items, the selection is from the second level; and so on. For example: O«B«('1A" tmmm '1B') ('24" '2B') -eI ('3A' | +--+ +--+| |+--+ +--+] [+=-+ +--+]| | 1141 []24] |[3A| 11B{| [+--+ +-=+| F--m— 12B[| [+--+ +--+] -S t '3B') + |3B]] [+--+ +--+]| oA + =B 3 o ALEFT ARG LENGTH IS 1, PICK FROM TOP LEVEL 0«Z+<25B t--+ +--+ |24 |2B]| t--+ +--1 =7 2 pZ 2 J«X«2 258 aPICK FROM SECOND LEVEL 2B =4 1 pX 2 The length of each item of 4 is equal to the rank of the corresponding array in B. The first item in 4 has a length equal to the rank of B; the second item has a length equal to the rank of the array selected by the first item in 4 ; the third item has a length equal to the rank of the array selected by the second item 1n 4; and so on. In the following example, the rank of # is 2, and the rank of item H[ 1; 2] is 3. To select an item from A[ 1; 2], the first item of 4 must contain two elements, and the second item must contain three elements. When you pick from the top level of an array, 4 must have length 1, and if 4 1s enclosed, the contents must be in the simple vector domain. 1-124 APL Reference Manual Primitive Mixed Functions > Pick O«H+2 2 p (10x15) fommm + (2 3 4p124) (2 2p100x14) 1000 t------—--—- + |10 20 30 40 50| | o m e +]1 | 1 2 3 4] 5 6 7 8 9 10 11 12| | | |13 14 15 16/ |17 18 19 20| |21 22 23 24| pmmmmm e — -+ t-————— + 1000 1100 200| 1300 400| fo-mm— + =f ? O«Z«((1 2) (2 2 3)) o H APICK FROM SECOND LEVEL 19 =7 0 (c1 2)>2H 1 2 3 4 5 6 7 8 g 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 1 224 10 LENGTH ERROR (LEFT ITEM LENGTH NOT EQUAL TO SELECTED ITEM RANK) 1 2of A When B and all the items in B are in the vector domain, then 4 is in the simple vector domain. When 4 is empty, then 4>B «~ B. O«F<'A" A UAN' (VANT' ('ANTI' +--+ +-—--—-----mm + |AN| +--+ |+---+ +-------—=—---- + | | |ANT| |+----+ +----- +1| |+---+ | |ANTI| |ANTIC]|]| | ] '"ANTIC')) | +-=--t +---—- +1] fom + | fom e + =F L pF 3 APL Reference Manual 1-125 Primitive Mixed Functions > Pick o F ++ -+ 12 12| ++ +-t +-+ J«P+3 fommt ASHAPE OF EFACH OF F -+ > F aPICK 3RD ITEM OF F e+ |ANT| [+----+ +----~ +| +---+ | |ANTI| |ANTIC|] | +----4 +----- + | fom e + =P 3 pP 2 J«@«3 2 > F fo-——t -+ |ANTI| |ANTIC] to-m=t -+ AnPICK 1 LEVEL DEEPER 2 ¥ 2 «R«3 2 1 o F APICK ANOTHER LEVEL DEEPER 2 1 aPICK FROM 4TH LEVEL OF F ANTI =R 1 0R I 0«5«3 3 o F T =5 0 pS (APL outputs a blank line) G<(10)>F G=F 1 When an item in B is a scalar, the corresponding item in 4 must be empty. For example: 1-126 APL Reference Manual Primitive Mixed Functions > Pick O«X«2 2p'"ABC" (<2 2p(1 2)(2 3)(3 4)(4 5)) '"XYZ' (15) | ABC| $--—+ [ T4t 111 2] | [+--—+ [ l4+---+ 113 uf [ [+---+ bt ] 12 3[]] +---+]] +---+]| |% S]] +---+]] +--—+ | XYZ]| +-——+ nSHAPE OF EACH OF X RPICK X[1;2] aUSE EMPTY TO PICK INTO SCALAR (1 2) ' (2 1)2X RPICK DEEPER To select more than one item from an array, use pick with the each () operator. For example: APL Reference Manual 1-127 Primitive Mixed Functions > Pick 0«Y<«2 3pc[2]X«6 2p , 'ABCDEFGNIJKL' t=+| |4+ +-+] [+-+ +-+] |BI1 LICl TIEL IDI t-+] |+=+ +-+| +=+] |+-+ +-+| INEL LD =+ 1T [+=+ +=+| GETA«(1 1) 1 GETL+(2 3) 2 GETA o Y GETL o Y |FI| |+-+ +-+]| |+-+ +-+| e 1L |+-+ +-+] GETA GETL >~ cY ARUSE FACH TO PICK MULTIPLE ITEMS +-+ | L] +-+ GETA GETL >~ Y Y +-+ aTHIS IS AN ALTERNATIVE FORM +-+ |4] | L] +-+ +-+ The following relationship between the take (+ ) function and pick is true for any nonempty B: +B <> (c(ppB)pUIO)>B. Possible Errors Generated 9 RANK FRROR (LEFT ITEM NOT VECTOR DOMAIN) 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (LEFT ARGUMENT LENGTH GREATER THAN RIGHT ARGUMENT DEPTH) 1-128 10 LENGTH ERROR (LEFT ITEM LENGTH NOT FQUAL TO SELECTED ITEM RANK) 14 DEPTH FRROR (LEFT ARGUMENT DEPTH GREATER THAN 2) 15 DOMAIN FRROR (INCORRECT TYPE) 15 DOMAIN ERROR (INDEX LESS THAN INDEX ORIGIN) 15 DOMAIN FRROR (INDEX OUT OF RANGFE) APL Reference Manual Primitive Mixed Functions > Pick 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 1-129 Primitive Mixed Functions , Ravel , Ravel Form ,B ,[K1B Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as argument Rank 1 (for ,B) Shape x / p B (for ,B) Depth 1[=B Implicit Arguments None. Description The monadic APL, function returns a vector made up of the items of the argument array, stored in row-major order (by increasing index position). For example: A«?2 3p1 2 3 O«B+,A 123456 pB b 1-130 APL Reference Manual 4 5 6 Primitive Mixed Functions , Ravel O«A«2 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 3 3 p118 123456789 10 11 12 13 14 15 16 17 18 0,4 18 pA 2 3 3 If the argument array is a scalar, APL returns a vector that contains one item. Note the difference in the shape of a scalar and the shape of a scalar to which the ravel function has been applied: puU (APL outputs a blank line) P,k 1 If the argument is a vector, APL returns a vector that is identical to the argument: A<16 A 1234560 , A 12 3 456 If the argument is an empty array of any rank or shape, APL returns an empty vector that is the same type as the argument. When you use ravel with an axis argument, X is in the vector domain and its items are numeric. The result depends on whether ¥ is a noninteger singleton or a near-integer vector. (If ¥ is a near-integer singleton, the shape of B is unchanged.) When the axis argument is a noninteger singleton, APL inserts a new axis (of length one) in the indicated position. For example, if X is a fraction between 1 and 2, APL will insert an axis between the first and second axes of B. Note that ¥ must be between ~ 1+0710 and 010+ p ¢ B. The rank of the result is 1+ pp B: APL Reference Manual 1-131 Primitive Mixed Functions , Ravel A<2 309 8 7 6 5 U4 ,[1.5]4 0,[1.5]4 2 13 If you specify a noninteger singleton axis when B is a scalar, the result is a one-item vector: ,[.5] 28 p,[.5] 28 28 1 When the axis argument is a near-integer vector, APL merges the specified axes into a single axis. In this case, X must contain contiguous ascending axis numbers between 070 and p p B. The rank of the resultis 1+ (ppB) -p , k. If X is empty, then the resultis ( (pB), 1) p B. Note that , [ 1 p p B] B is the same as , B: B«2 3 6p'SARAH SELLS SHELLSBETH BUYS BOATS ' B SARAH SELLS SHELLS BETH BUYS BOATS pB 2 36 ,[2 31B SARAH SELLS SHELLS BETH BUYS BOATS o,[2 3]B 2 18 If you want to add an axis to the end of the shape of an array, you can use 1 0 as the axis argument. If you want to add an axis to the beginning of the shape of an array, you can use ~ .5+ I0 as the axis argument: A«2 3p 9 76 ,[10]4 1-132 APL Reference Manual 5 4 Primitive Mixed Functions , Ravel p,[10]4 2 31 .5 + 01014 7 6 54 9 2 3 1 o, .5 + 0I0]4 If you specify 010 or 1 0 as the axis argument when B is a scalar, the result is a one-item vector: ,[1] 28 28 o,[1] 28 ,[10] 6 1 6 p,[10] 6 1 Further examples: [J«A<c.3 [J«B<«'ABC' [J«C<'! 2 O«D<+" O«E«2 0.3 2 p ABCD +---+ | ABC| +---1 ++ 2 p E B 0.3 +--—-+ ++ 2 |ABC| || +---+ ++ p LE ,[1.5]F 0.3 +--——+ | ABC| t+---+ APL Reference Manual 1-133 Primitive Mixed Functions , Ravel ,[1.51F p ,[0.5]F 0.3 +--~+ | ABC| +--—+ o ,[0.5]F Possible Errors Generated 1-134 27 LIMIT FRROR (INTFEGER TOO LARGE) 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH FERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN FRROR (AXES NOT IN CONTIGUOUS ASCENDING ORDER) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN FRROR (INCORRECT TYPF) 30 AXIS DOMAIN FRROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions T Represent T Represent Form ATB Left Argument Domain Type Numeric Shape Any Depth 0 or 1 (simple) Right Argument Domain Type Numeric Shape Any Depth 0 or 1 (simple) Result Domain Type Numeric Rank (ppA)+ppB Shape (pA).,pB Depth 0 or 1 (simple) Implicit Arguments None. Description The dyadic T function (known as represent or encode) represents an array in any number system. The left argument specifies the number system; the right argument specifies the array to be represented. For example, to represent the decimal value 7 as a four-digit binary number, specify the following: 2 2 2 277 0111 APL Reference Manual 1-135 Primitive Mixed Functions T Represent In the expression AT B, A can be considered as the representation rule to be applied to B. Each item of the vector 4 is defined in terms of the item immediately to its left. You can specify mixed bases in the left argument. For example, the represent function can express some number of inches in miles, yards, feet, and inches, or some number of milliseconds in days, hours, minutes, seconds, and milliseconds: Thus, in representing a number as miles, yards, feet, and inches, the left argument specifies, from right to left, 12 inches in 1 foot, 3 feet in 1 yard, and 1760 yards in 1 mile. In the following example, a miles specification is not defined in terms of another quantity, so 0 is printed in the miles column. AMILES, 0 4 546 2 1760 3 8 6 15 FEET, INCHES 5 aDAYS, 0 YARDS, 127273125 24 32 60 HOURS, 60 MINUTES, SECONDS, MILLISECONDS 10007713732523 523 The following examples of base 3 conversions demonstrate the specification of different numbers of columns in the left argument and illustrate the way in which negative numbers are represented: 3 3 3 37117 APRODUCES 3'S COMPLEMENT OF 17 0122 333 371 17 APRODUCES 3'S COMPLEMENT OF 17 2101 Another useful application of T is to return the integer and fractional portions of a number: X+823,.7513 0 823 17X 0.7513 The following are more examples of the use of the v function: A<®Q3 B<«5 2p2 3 2 1-136 o o o (SRR = J«R+ATH APL Reference Manual Primitive Mixed Functions T Represent pB pA pR 0w R o O 692 107C w w Ut 103 NN O C«2 2p865 429 X « 10 10 0« pX 128X 2 2 N o w 0w N W = o n 3 aPRODUCES 2'S COMPLEMENT OF 13 2 2 2713 1 00 WO N 01101 aPRODUCES 2'S COMPLEMENT OF 13 2 2 2 27 13 1 If4 is a scalar, AT B is the same as A | B with JCT+0. Note that 0CT 1s not an implicit argument to the represent function. Possible Errors Generated 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPF) 27 LIMIT EFERROR (FLOATING OVERFLOW) APL Reference Manual 1-137 Primitive Mixed Functions o Reshape 0 Reshape Form Ap B Left Argument Domain Type Nonnegative near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as right argument Rank 0,A Shape A Depth — Implicit Arguments None. Description The dyadic p function creates an array of items from the right argument taken in row-major order and arranged in the shape specified by the left argument. For example: 2 3 p 16 12 3 4 1-138 5 b APL Reference Manual R2 ROWS, 3 COLUMNS Primitive Mixed Functions o Reshape If the right argument does not contain enough items to fill an array that has the shape specified by the left argument, the right argument is reused starting at its beginning: 1N W N w (SN — TN 3 3 p 16 3p5 555 If the right argument has more items than are required for an array that has the shape specified by the left argument, the extra items are ignored: 2 2 1 2 3 U p 16 Note that the right argument may be any type and shape (it is, in effect, raveled before it is reshaped): [J«B+3 5p'STAN SAM STEVE' STAN SAM STEVE 20pB STEVESTAN STAN SAM For arguments 4 and B, if B is empty, 4 must contain at least one 0 value, and the result is empty with the shape , 4. For example: J«R<«2 0 p 10 (APL outputs a blank line) oR 2 0 If 4 is empty, the result is a scalar whose value is the first item of B in row-major order; formally expressed: (10)pB «» ' 'pB <> (,B)[0I0] For example: (10)p5 7 9 APL Reference Manual 1-139 Primitive Mixed Functions o Reshape Further examples: O«VAN<'ABC' (1 3 +-----—- + |ABC| |1 2 4] | +-+| t-=—t -+ | 13]] 3 1.2 2 t---t+ u4) 1.2 (<,3) +---+ [+-+1 +---+ p VAN n («VAN<2 ==t 2 p VAN t-----—- + |ABC| |1 2 t-—=t $-—--—- + 3 u] +-——+ | +-+] | 131] | +-+] +-==1 o VAN 2 2 0«(10) p VAN AEMPTY LEFT ARGUMENT +-—-+ | ABC| +-——+ Possible Errors Generated 9 1-140 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN FRROR (NOT AN INTEGER) 15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual Primitive Mixed Functions ¢ and e Reverse ¢ and © Reverse Form ¢ B ¢ [K]1B eB e[ K]B ¢ 1s formed with o and | o is formed with o and - Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as argument Rank ppB Shape pB Depth =B Implicit Arguments None. Description The monadic ¢ function returns the items of the argument array in reverse order along the relevant axis. You specify the axis to be reversed in square brackets. For example: O«A+«2 12 34 56 78 U4p18 o[1]4 56 7 8 1 2 34 L 3 2 1 8 7 6 5 ¢[2]4 APL Reference Manual 1-141 Primitive Mixed Functions ¢ and e Reverse If you do not specify an axis, ¢ reverses the items along the last axis, and o reverses the items along the first axis. For example: 3p19 jon} = U 0«G+3 o N N = e OO oo lon] oG Iy 7 The following reverses a matrix along both axes simultaneously: = TN W O O i N J«X<2 1 3p16 LW deX For singleton, vector, or empty arguments, both ¢ and e return the same value. For an empty array or singleton, they return the original argument; for a vector, they return the items of the vector in reverse order. For example: b5 e5 $10 (APL outputs a blank line) ¢1 1 1p6 6 15 54 321 54 321 815 1-142 APL Reference Manual Primitive Mixed Functions ¢ and e Reverse Note that reverse is not the same as transpose: O«X<«2 12 3 5 6 3p1 2 3 4 56 0P¢ 14 3 6 Further examples: N«MIZZ«2 4 p t---+ 0 1 "ABC' 0 1 2 'XYZI' 4 (c,3) 100 2 | ABC| +---+ fo-=+ b +---+ 100 | +-4] | XYZ] Ik | +-+] +--—+ e[1]MIZZ fo--+ 4 +---+ | XYZ| | +-+] ot | 13]] | +-+] 100 +--—+ +---+ 0 1 2 | ABC| +--=t 6[2]MIZZ 2 0 +---+ 1 | ABC| +--—+ 100 +---+ 4 +---+ | +-+] | XYZ| IEIN [ +-+] R +-—-+ beMIZZ 100 +---+ 4 +---4 |+-+| | XYZ| 131 | +-+] +---+ $---+ 2 1 0 +---+ | ABC| +--—+ APL Reference Manual 1-143 Primitive Mixed Functions ¢ and e Reverse Possible Errors Generated 1-144 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK FERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPFE) 30 AXIS DOMAIN FRROR (NOT AN INTEGER) 30 AXIS DOMAIN FRROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions ¢ and e Rotate ¢ and © Rotate Form AP B AP [K]1B Ae B Ae [ K] B ¢ 1s formed with o and | o 1s formed with o and - Left Argument Domain Type Near-integer Shape Conforms to right argument (pA4)=(pB)[ 10 pB)~)K] Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as right argument Rank ppB Shape o B Depth =B Implicit Arguments None. Description The dyadic ¢ or e function rotates items along the relevant axis of the right argument in a way specified by the left argument. The rotation is cyclical and, for each axis, continues for the number of places specified by the corresponding item in the left argument. If the left argument is positive, the shift is to the left; if it is negative, the shift is to the right. For example: APL Reference Manual 1-145 Primitive Mixed Functions ¢ and e Rotate 3615 4 5 1 2 3 “3¢15 3 4512 The axis to be rotated must be specified in square brackets, as in the following example: J«A4+«3 5p115 1 2 3 4 5 6 7 8 9 10 11 12 14 15 13 2 1 4¢[2]4A 3 4 5 1 72 7 8 9 10 6 15 11 12 13 14 2 10 2 3¢6p[1]4 11 7 3 14 5 112 8 4 10 13 9 15 6 2 If no axis is specified, ¢ rotates the items along the last axis, and e rotates the items along the first axis: o ooTM oo 0«G+2 123 56 7 3 41 6 7 8 5 2 3 4p18 166G 2 0 1eG 1674 Note that, in general, the shape of the left argument must be the same as the shape of the relevant axis in the right argument. If the left argument is a singleton, it is extended to conform to the relevant axis of the right argument. For example: 202 1-146 3 4 8 9 5p110 512 10 6 7 APL Reference Manual Primitive Mixed Functions ¢ and e Rotate Further examples: O«MIZZ«2 4 p $---+ 0 1 '"ABC' 0 1 1 'XYZ' 4 (c,3) 100 1 | ABC| +---+ +---+ b +---+ | XYZ| | +-+| t-—=+ |]3]] | +-+] 100 t---+ 13 ¢ MIZZ 1 +---+ | VR | ABC| t---+ 100 +---+ 4 +--——+ | XYZ| | +-+] t---+ [[3]] | +-+] ===+ 1011 ¢ t---+ 0 +---+ |XYZ| | +-+] t--=+ |]3]] | +-+] [L1IMIZZ 100 t--=4 +---+ 4 1 1 | ABC| +---+ 10 F-—-+ 0 116e MIZZ +---+ | XYZ| | +-+]| p-o=t |13 | +-+1 100 +--—+ +--—+ 4 1 1 | ABC| +---+ Possible Errors Generated 9 RANK ERROR (RANKS DIFFER BY MORE THAN ONE) 10 LENGTH ERROR (SHAPES OFF AXIS DO NOT MATCH) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) APL Reference Manual 1-147 Primitive Mixed Functions ¢ and e Rotate 1-148 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH FRROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN FRROR (INCORRECT TYPFE) 30 AXIS DOMAIN FRROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions o Shape o Shape Form p B Argument Domain Type Shape Depth Result Domain Type Nonnegative integer Rank 1 Shape ppB Depth 1 (simple) Implicit Arguments None. Description The monadic p function returns a vector of nonnegative integers that represent the lengths of each of the axes of the argument array. If the argument is a vector, APL returns an integer vector that represents the number of items in the vector: 4 6 8 A«2 pA B«'"ABCDEF' pB p,9 APL Reference Manual 1-149 Primitive Mixed Functions o Shape If the argument is a matrix, APL returns the number of rows and columns: [«A«2 3p16 123 b 5 2 3 6 pd If the argument is a scalar, APL returns an empty numeric vector: K+3 pK (APL outputs a blank line) You can use the shape function to determine an array’s rank. Because the shape function returns one item for each axis of the array, the shape of shape is an integer vector that represents the number of axes in the array: («A«5 6p130 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 pd 56 ppA 2 Further examples: O«V<«'XY' +——+ (1 2 3) ' ! +-—-—- + | XY| |1 2 +--+ +----- + 3| pV 3 O0«B«(2 0 p5)(" ++ ++ R | ] ++ ++ pB 3 1-150 APL Reference Manual ")(10) Primitive Mixed Functions p Shape O«M«2 3 p 1 ('') 1 ++ "ABC' 0 2 & +---+ || |ABC| ++ +---+ 0 24 oM M pp 2 <~ ,1 Note that for all B: pppB Possible Errors Generated None. APL Reference Manual 1-151 Primitive Mixed Functions < Subset c Subset Form AcB c is formed with < and _ Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Boolean Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Implicit Arguments O0CT (determines comparison precision) Description The dyadic < function determines whether the right argument contains all the items in the left argument. The result is a Boolean scalar: true, if the left argument is a subset of the right argument, and false if it is not. Duplicate items in either argument do not affect the result. For example: 1-152 APL Reference Manual Primitive Mixed Functions c Subset O«A<3 23 4 p 54 98 98 47 98 32 78 65 12 23 Ac 1100 Ac 190 23 54 98 34 98 u7 98 32 78 65 12 23 34 1 0 The < function compares items in terms of the match (=) function, which uses the value of 1 ¢T. Because match allows mixed-type arguments, you can compare characters with numbers. However, such a comparison is always false, so that if you use mixed-type arguments for dyadic c, the result will be zero. For example: "23 24 25'c 22 23 24 25 26 0 Further examples: O«V«0 'AB' O«M<2 2 VecM p (1 2 3) (1 2 3) '0'" '"AB'" 'A! aNOTE CHARACTER AND NUMERIC ZEROS Note that the following definition applies: AcB «+ A/ ,4¢B Possible Errors Generated None. APL Reference Manual 1-153 Primitive Mixed Functions + Take 4+ Take Form A+ B A+ [K]B Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as right argument Rank (p,A)lppB Shape | , A (af no explicit axis) Depth — Implicit Arguments Fill item Description The dyadic + function builds an array by taking a specified number of items from an existing array. Each item in 4 corresponds to an axis in B. The value of each item in 4 specifies how many items to take from the axis. Thus, for A+ B, item A[ K] is used to take values along the ¥ th axis of B. If an item in 4 is a positive integer n, APL takes the first n items from the appropriate axis of B. If an item in 4 is negative, APL takes the last n items from the appropriate axis of B. 1-154 APL Reference Manual Primitive Mixed Functions + Take R«1 2 3 4 24R aTAKE FIRST TWO ITEMS OF R T24R aTAKE LAST TWO ITEMS OF R 12 3 4 Unless the right argument is a scalar, the number of items in 4 must equal the rank of B (p , 4 must equal p p B). (When the right argument is a scalar, it 1s extended to be a singleton of the appropriate rank.) If you use the axis form (CX]), the number of items in 4 must equal the length of ¥. (Examples of axis form are presented at the end of this section.) Thus, if the right argument is a matrix, the left argument must have two values: +R«3 12 3 b 5 6 7 89 3p19 ALEFT ARG MUST BE LENGTH 2 2+R 10 LENGTH ERROR (LEFT LENGTH NOT EQUAL TO RIGHT RANK) 24K A aTAKE TWO ITEMS ALONG EACH AXIS 2 2+KR 12 4 5 If the value of an item in 4 is greater than the length of the corresponding axis of B, APL pads the result array with fill items. This operation is known as overtake. For example: NUM«<1 2 3 CHA«<'ABC' ROVERTAKE NUM, FILL ROVERTAKE CHA, FILL ITEMS ARE BLANKS ITEMS ARE ZEROS S5tNUM 12300 ACATENATE X TO SHOW END OF FILL ITEMS (5¢+CHA), ' X! ABC X The fill items are determined by the prototype of each vector along the relevant axis. This is important for arrays of rank 2 or more because the fill item for a given position depends on the prototype of that particular column, row, or plane. The following expressions describe such an operation. Note where the fill items are blanks and where they are zeros. (Because the array M is simple, all the fill items are scalars. If ¥ were enclosed, some of the fill items might also have been enclosed.) APL Reference Manual 1-155 Primitive Mixed Functions + Take 3p [«M+2 1 4 1 'A' 2 'B'" 4 5 2 B 45 oM 2 3 AQOVERTAKE M ALONG FIRST AXIS aPROTOTYPE BASED ON VECTORS ALONG FIRST AXIS 4+[11M 1 4 2 B 45 0 0 0 0 aFIRST AXIS IS CHANGED ot [1IM 4 3 aOVERTAKE M ALONG 2ND AXIS 5¢[21M 14200 B u5 2 5 pb5+[2]1M a2ND AXIS IS CHANGED 4 5+M AOVERTAKE M ALONG BOTH AXIS 14200 B us5 0 0 0 000 4 00 plh H4M ABOTH AXIS ARE CHANGED 5 Note that if 4 is positive, any needed fill items are placed at the end of the result array. If 4 is negative, any needed fill items precede the result array. For example: 6412 24 36 48 12 24 36 48 0 0 (104 'TEST'),'X! TEST 0 0 X 6412 24 36 U8 24 12 104 36 U8 'TEST! aFILL ITEMS AT END OF RESULT aCATENATE X TO SHOW END OF FILL ITEMS aFILL ITEMS AT BEGINNING OF RESULT aFILL ITEMS AT BEGINNING OF RESULT TEST If the rank of the right argument is greater than 1, the result array is called a corner of the argument array. The origin of the corner is determined by the signs of the items of the left argument. For example, if the right argument is a matrix, there are four possible corners as shown in Figure 1-1. 1-156 APL Reference Manual Primitive Mixed Functions + Take Figure 1-1 Argument Corners Selected by Take Function > Axis2 <« > Axis?2 <« NU-2233A-RA In the following example, note how the order of the signs in the left argument determines the corner selected from the matrix right argument: J«A«3 3p19 2 ) b If the left argument contains a 0, then, for arguments 4 and B, 4+ B returns an empty array with shape , | 4. For example: A+2 3 042 3 3p118 p4 2 30 If the left argument is empty, the right argument must be a scalar, and the result is the right argument. APL Reference Manual 1-157 Primitive Mixed Functions + Take If the right argument is a scalar, it is extended to a singleton with a rank equal to the length of the left argument. For example: 2 4+ 3 5 000 50 0 Note that for any array 4, 0= 1+ 0p A4 is true if 4 is numeric and false if 4 is character. When you use + with an axis argument, X is a vector of axis numbers whose lengths are determined by corresponding items of the left argument, A. Formally, + with an axis argument can be described by the following: z <« pBo Z[LK] « Ao Z+« Z4+B The value for ¥ must be in the vector domain, and each item must be a nearinteger in the set 1 p p B. Therefore, the values of K are 1 10-dependent. The items may be in any order, but they may not be duplicated. The length of must be less than or equal to the rank of the right argument, and it must | match the length of 4. The value for ¥ does not have to specify all the axes in B. APL determines the lengths of any missing axes by the lengths of the corresponding axes of B. This means that you can take rows or columns of a matrix without specifying the length of the other axis. For example: O«4«8 5p140 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 1 2 3 +[1] 4 3 4 5 6 7 8 9 10 11 12 13 14 15 2 +[2] A 1-158 APL Reference Manual aTAKE 3 ROWS OF A aTAKE THE LAST 2 COLUMNS OF A Primitive Mixed Functions + Take 34 1 2 +[2 1] A aTAKE 4 ROWS, 3 COLUMNS OF A aTAKE 4 ROWS, 3 COLUMNS OF A 3 6 7 8 11 12 13 16 17 18 0I0 < 0 4 1 2 34[0 1] 4 3 6 7 8 11 12 13 16 17 18 O«WRL<(1 2 3) '"ABC' 5+WRL 0 AOVERTAKE TO SHOW FILL ELEMENT Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (LEFT LENGTH NOT EQUAL TO RIGHT RANK) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FERROR (INTEGER TOO LARGE) 27 LIMIT FRROR (VOLUME TOO LARGE) 29 AXIS LENGTH FRROR (LEFT ARGUMENT HAS WRONG LENGTH) 30 AXIS DOMAIN FRROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) APL Reference Manual 1-159 Primitive Mixed Functions + Take 1-160 30 AXIS DOMAIN ERROR (INCORRECT TYPF) 30 AXIS DOMAIN ERROR (NOT AN INTFEGER) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions & Monadic Transpose ® Monadic Transpose Form & B § 1s formed with o and \ Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as argument Rank ppB Shape ¢pB Depth =B Implicit Arguments None. Description The monadic & function transposes the axes of an array; thus, § B is B with the order of the axes reversed. For example, if the argument is a matrix, § exchanges rows and columns: O«A«2 12 3 L 6 5 3p16 YA 14 2 5 3 6 3 2 p R4 APL Reference Manual 1-161 Primitive Mixed Functions § Monadic Transpose If the rank of the argument is less than 2, the function has no effect: 2 A1 3 45 Y4 12345 In the next example, a rank 3 array is transposed: O«B+2 12 34 56 7 12 34 56 7 3 L4p18 8 8 12314 56 7 8 &8 15 5 1 15 2 6 6 2 2 6 37 7 3 3 7 4 8 8 4 4 8 4 3 p&B 2 Further examples: O«MIZZ<2 4 p t--=+ 0 1 1 | ABC| t+---+ t-==+ 4 +---+ |XYZ| | +-+| t---+ |]3]] | +-+] 100 t---t 1-162 APL Reference Manual '"ABC' 0 1 1 'XYZ' 4 (<,3) 100 Primitive Mixed Functions §¥ Monadic Transpose QMIZZ t-—--+ t---+ |ABC| |XYZ| t-—-+ t---+ 0 4 1 +--—+ | +-+] | 1311 | +-+] +---+ 100 1 o MIZZ 2 4 4 2 pRMIZZ Note that 8 B <> (¢pB) 8B Possible Errors Generated None. APL Reference Manual 1-163 Primitive Mixed Functions & Dyadic Transpose & Dyadic Transpose Form AR B § 1s formed with o and \ Left Argument Domain Type Nonnegative near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Shape Depth Result Domain Type Same as right argument Rank RANK«<T[ /A +~010 Shape (1+pA)+L/((1vRANK) Depth =B o.=4) x (RANK,pA)ppB Implicit Arguments A8B when 0I0 « 1 isidenticalto (1 + 4)§B when []I0 < 0 Description The dyadic & function permutes the axes of the right argument in a way specified by the left argument. The shape (length) of the left argument must equal the rank of the right argument; thus, one item of the left argument is associated with each axis of the right argument. In general, the item in the left argument specifies the position to be assumed by the associated axis in the result array. For example: 1-164 APL Reference Manual Primitive Mixed Functions & Dyadic Transpose O«A<2 2 1 3 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 pA 2 3 3 4p124 3 2§4 4 4 O«B<«1 1 5 9 2 6 10 3 7 11 4 8 12 13 17 21 14 18 22 15 19 23 16 20 24 2 43 2 4 pB (pA)[1 3 2] 3 Note that the shape of the result of the & function is equal to the shape of its right argument subscripted by its left argument. The values in the left argument must be less than or equal to the rank of the right argument; thus, if the right argument’s rank is 3, then 1, 2, and 3 are the only permissible values in the left argument (when 010 is 1). However, there is one exception: if the right argument is a scalar, then either 1 (or 0 if 0I0is 0)or 10 is permissible as the left argument; the value returned is the value of the scalar right argument. You may repeat values in the left argument. When you do, the result is a diagonal slice of the right argument. For example: APL Reference Manual 1-165 Primitive Mixed Functions § Dyadic Transpose X<[0«2 4 b4plbk-————k—-—-k-——-%" K- — - —— - *——— —4—— - -———% 1 2 284X 2 1 18X * %k % * % % % * % * % * % * % Y<[1«2 U4 UYp'okkkkmmmmm e * %k % * %k % A 1 1 2§87 2 2 1§Y X X % * % % X Z+«2 1-166 4 Yp'dh-———k-———k———k—=== APL Reference Manual Primitive Mixed Functions §¥ Dyadic Transpose 2 1 2827 * % * % * % * % When you repeat values in the left argument, they must form a dense sequence; that is, in counting from 1 (or 0 if 0 I0 is 0) to the largest item you specify, no number may be left out. Note that dyadic & is sometimes the same as monadic &. Expressed formally, this means § B <> ( ¢ p B) § B. For example: H«A<2 4 2 3 5 6 3p16 84 14 2 5 36 2 184 14 2 5 3 6 Table 1-6 lists transpositions for a variety of arrays: V is a vector, M is a matrix, and A 1s any array. Table 1-6 Dyadic Transpose Definitions Expression Shape of r Definition R«1§QV pV R<«V R<1 28 M oM R<M R<2 18 M (oM)[2 1] RLI;J1<M[J;I] R«<1 18 M L/pM RLI1<M[I;I] R+<1 2 384 p A R<A R«<1 3 28 A (pA)[132] R[I;J;K1«A[I;K; J] R«<2 3 184 (pA)[312] R[I;J;K1<ALJ;K; I R«<3 1 284 (pA)[23 1] R[I;J;KI1<AL[K;I;J)] R«1 1284 (L/(pA)[12]1),(pA)L3] RLI;JI<ALI;1;J] (continued on next page) APL Reference Manual 1-167 Primitive Mixed Functions § Dyadic Transpose Table 1-6 (Cont.) Dyadic Transpose Definitions Expression Shape of R Definition R«1 2 1] A (L/(pd)[2131),(pA)L2] RILI;JI<ALI;J;1I] R+2 1 184 (L/(pAd)[23]),(pA)[1] RLI;JI<ALJ;I;1I] R«<1 1 184 L/ oA RLIJ<ALI;I;1I] Further examples: O«MIZZ+2 +---+ 0 1 4p('ABC') 0 1 1 ('XYZ') 4 (<,3) 100 1 | ABC| t+---+ t---+ 4 +---+ | XYZ] | +-+] t---+ |[3]] | +-+] 100 t+---1 2 t---+ 1§ MIZZ ATHIS IS THE SAME AS MONADIC § +---+ |ABC| |XYZ| t---+ +---+ 0 4 1 +-—=+ | +-+] | 1311 | +-+] t---+ 1 100 O«MIC<«2 +--+ 2 2 +----+ |AB| |1 20| +--+ +----+ 1 72 0 ++ N ++ A +--=+ | XYZ| +---+ 1-168 APL Reference Manual p'AB' (1 20) 1 "2 0 '' 'A' "Xy Primitive Mixed Functions § Dyadic Transpose 12 +--+ 2% MIC 2 |AB| +--+ +--—+ | XY7Z| +---+ 2 +--+ 1 1 QMIC 0 |AB| +--+ 2 +--—+ | XYZ| +---+ 1 2 1 §MIC +--+ |AB| +--+ ++ +--—+ ++ $o==4 +--+ ++ | XYZ| 2 |AB| || +--+ ++ 1 2§ MIC $o--+ | XYZ| +---+ Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (LEFT LENGTH NOT EQUAL TO RIGHT RANK) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (LEFT ARGUMENT NOT DENSE FROM QUAD 10) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 1-169 Primitive Mixed Functions u Union U Union Form AUB Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Any Rank 1 Shape pu(,4),.B Depth 1[=4,B Implicit Arguments O0CT (determines comparison precision) Description The dyadic v function joins the two arguments and removes all duplicate items. The result is a vector that includes all the items from both arguments. For example: "ABCB' u 2 3p'DDEDCC' (2 4 45433)u1l23?2 ABCDE 3 p 45 3 1 2 The v function compares the items in terms of the match (=) function and eliminates duplicate items based on the value of [JCT. 1-170 APL Reference Manual Primitive Mixed Functions u Union Further examples: g«V<«(c,100) +----- + o4t -+ | +---+| |TTY| |99]| 'TTY' '99' | 1100] +---+ +--+ | +-=-+] +----- + O«M+2 100 99 +---+ 0 2 p 100 99 'TTY' 0 | TTY| +--=1 VuM Fom + +---+ +--+ | +---+| |TTY| |99] | 1100]} +---+ +--+ 100 99 0 | +=--+] Note that the following definition applies: AuB<-+u ( ,4),,B Possible Errors Generated None. APL Reference Manual 1-171 Primitive Mixed Functions u Unique U Unique Form uB Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as argument Rank 1 Shape Equal to number of unique items Depth 1 =B Implicit Arguments O0CT (determines comparison precision) Description The monadic v function removes duplicate items from an array. The result is a vector of the unique items in the argument. For example: O« 6 5 4 2 72 6 2 4 « 7 3 4 p 7 1376 u 4 6 542713 B « '"DR.GRANT''S CHEWING GUM' uB DR.GANT'S CHEWIUM 1-172 APL Reference Manual Primitive Mixed Functions u Unique The v function compares the items in terms of the match (=) function and eliminates duplicate items based on the value of 0 CT. For example: 1EF715 OcT Ulh 4-5F 16 L Note that the following definition applies: vB«~>( (B1B)=10B) /B+,B Possible Errors Generated None. APL Reference Manual 1-173 Primitive Mixed Functions ~ Without ~ Without Form A~ B Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Any Rank 1 Shape p(~(,4)eB)/ ,A Depth — Implicit Arguments 0CT (determines comparison precision) Description The dyadic ~ function returns all the items in the left argument that are not found in the right argument. Duplicate items in the right argument do not affect the result. Duplicates in the left argument are not removed unless they are specified in the right argument. For example: 1-174 APL Reference Manual Primitive Mixed Functions ~ Without RAMBLE<'RUN ON RUN ON RUN ON.' SQUISH+"' ! ASQUISH CONTAINS A BLANK SPACE RAMBLE ~ SQUISH aELIMINATE THE BLANKS FROM RAMBLE RUNONRUNONRUNON. [J«A<«3 4p 56 78 105 137 49 329 97 235 142 105 56 59 4 ~ 105 137 56 78 105 137 49 329 97 235 142 105 56 59 1100 329 235 142 105 If your data represent sets, and you want to remove duplicates from your result, you can use the unique function along with the ~ function: A«3 up u 4 ~ 105 137 329 56 78 105 137 49 329 97 235 142 105 56 59 1100 235 142 If the left argument is a subset of the right argument, the result is an empty vector. For example: 2 b6 25 65 9 34 65 34 J«B« 3 2 u 130 B ~ p 2 6 25 65 9 34 76 13 u3 21 The ~ function compares items in terms of the match (=) function, which uses the value of 00 ¢T. Because match allows mixed-type arguments, you can compare characters with numbers. However, such a comparison is always false, so that if you use mixed-type arguments for dyadic ~, the result will be equal to the left argument. For example: (A+'ABC') ~ B<'BA" B~ A (APL outputs a blank line) Note that the following definition applies: 4A~B<«~(~( ,4)eB)/ ,4A Possible Errors Generated None. APL Reference Manual 1-175 Primitive Mixed Functions 1.3 APL Operators 1.3 APL Operators APL operators take either functions or arrays as operands, and produce results called derived functions. Operators are either monadic or dyadic, but not ambivalent. Monadic operators bind to the left; that is, they take a left operand and not a right operand. Dyadic operators take a left and a right operand. Derived functions are either monadic, dyadic, or ambivalent (their classification depends on the arguments to the derived function and not on the valence of the operator). You can specify an axis when you use some of the operators. Because axis binds to the left, it must appear to the right of the operator. There are four APL primitive operators: slash (/ and /), backslash (\ and %), each ("), and dot (.). The following table describes the valence of the operators, the derived functions, and the valence of the derived functions. Note that 4, B, f, and g are all operands where 4 and B are arrays, and f and g are functions. Operator Valence Derived Function Valence Slash Monadic Compress (4/ and 4+) Monadic Replicate (4/ and 4+#) Monadic Backslash Monadic Reduce ( f/ and f#) Monadic Expand (4\ and 4%) Monadic Scan f \ and f\ Monadic Each Monadic Itemwise application (f ) Ambivalent Dot Dyadic Inner product (f.g) Dyadic Outer product (- .f) Dyadic Operators may accept functions or arrays for their operands. You can specify any valid function, including primitive functions, system functions, userdefined functions, and derived functions. (A derived function is a function resulting from the use of an operator.) Because derived functions may be operands for operators, it is possible to build sequences of operators to form function expressions. For example, you can use the inner product derived function (+ . x) as the left operand to the slash operator (/). The result is the inner product reduce derived function, which allows you to perform matrix multiplication along a vector of matrices. Note that the left and right sides of the following expression are equivalent. However, the left side is more concise. The arrays M1, M2, and M3 represent matrix arrays: 1-176 APL Reference Manual Primitive Mixed Functions 1.3 APL Operators +ox /M1 M2 M3 <> M1 +.%x M2 +.,%x M3 The following example uses the outer product derived function (- . , ) as the left operand to the slash operator. The result is the catenate outer product reduce derived function, which in this case extends the monadic iota function (1) to vector arguments to produce the odometer function: V<1 2 3 ,2 o, [ 1 ¥ +----- + |11 1) +----- + |12 2] +----- + +----- + |1 13 1122 1] 4----- + |12 2| TR + f-——-- +ot-———- + ----- + 4-——-- + -+ |12 3] -+ The following expression adds parentheses to show the binding action of the operator sequence: ,> ((o.,) /) (1 ") V¥ Table 1-7 summarizes the operators and derived functions in greater detail, including the forms with axis. The subsequent subsections describe all the forms. Table 1-7 APL Operators Operator Name Meaning A/B Slash A compression/replication along the last axis of B A/ [K]B Slash A compression/replication along the ¥ th axis of B A+ B Slash A compression/replication along the first axis of B first axis of 4 f/ A Slash The f reduction along the last axis of 4 [/ [K]A Slash The f reduction along the ¥ th axis of 4 [t A Slash The f reduction along the first axis of 4 [ B Each The application of monadic f on each item of B Af "B Each The application of dyadic f on corresponding pairs of each item of 4 and B A\B Backslash 4 expansion along the last axis of B A\N[K]1B Backslash 4 expansion along the k¥ th axis of B A+ LK]B f#LK]A AX[K]B (continued on next page) APL Reference Manual 1-177 Primitive Mixed Functions 1.3 APL Operators Table 1-7 (Cont.) APL Operators Operator Name Meaning AXB Backslash 4 expansion along the first axis of B A4 Backslash The f scan along the last axis of 4 ALKk]A Backslash The f scan along the ¥ th axis of 4 Backslash The f scan along the first axis of 4 ANTKIA A4 Ao . fB Af.gB 1.3.1 - Dot Outer product Dot Inner product / and # Slash The monadic slash (/ and #) operator takes a left operand and produces a monadic derived function. When the operand is an array, the derived function is either compression or replication. When the operand is a function, the derived function is reduction. 1.3.2 | \ and % Backslash The monadic backslash (\ and \ ) operator takes a left operand and produces a monadic derived function. When the operand is an array, the resulting function 1s expansion. When the operand is a function, the result is scan. 1.3.3 . The Dot Operator The dyadic dot (. ) operator takes a left and right operand and produces a dyadic-derived function. When the left operand is a jot (- ), the derived function is an outer product. When the left operand is a function, the derived function is an inner product. The right operand is always a dyadic function. 1-178 APL Reference Manual Primitive Mixed Functions / and # Compression and Replication / and # Compression and Replication Form A+ B A/ [K1B A/ B 4 is formed with / and - A+ [K]B Left Operand Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain (of derived function) Type Same as right argument Rank 1fppB Shape (for 010« 1) ((K-1)4pB),(+/| A) ,K+ypB Depth — Implicit Arguments None. Description Compression and replication are monadic functions derived from the slash (/) operator. They build arrays by specifying the items to be deleted, preserved, or duplicated from an existing array, and by indicating where fill items are to be added in the new array. When items only are preserved or deleted, this is known as compression (the left operand is Boolean). When items are d(uplicated, deleted, or filled, this is known as replication (the left operand is integer). You can also use the OREP system function to perform the compress and replicate operations (see Chapter 2 for more information). APL Reference Manual 1-179 Primitive Mixed Functions / and # Compression and Replication For compression, each Boolean item in 4 corresponds to the position of an item in B. When 4 is 1, the item in B is preserved in the result array. When 4 is 0, the item in B is deleted from the result array. 11010/57 57 9 11 13 ATHIS IS COMPRESSION 11 For replication, each positive scalar and each zero in 4 correspond to the position of an item in B. Negative integers, which specify fill items, are not associated with explicit positions in B. When 4 is Boolean, the effects are the same as for compression (items are either preserved or deleted in the result array). When 1> 4, the item in B is repeated 4 times in the result array. When A 1is negative, APL builds | 4 occurrences of the fill item into the new array: 5 7 1 3 7 90 7 1 0O 4 2 2/57 0 0 0 13 13 0 9 11 13 aTHIS IS REPLICATION 0 If A contains only 1 s, the result is B itself; if 4 contains only 0 s, the result is an empty array. For example: 1111 1/15 12345 0 00 0 0/15 (APL outputs a blank line) In general, the length of the relevant axis of B must equal the number of nonnegative items in 4 ((p B) [K1+~+/A20). That is, you must specify an operation (either copy, drop, or replicate) for each item in the right argument. However, APL does perform singleton extension in certain conditions. If 4 is a positive singleton, it is extended to the length of B. (Negative values are not extended. When 4 is a negative singleton, B must be empty along the axis being replicated.) If B is a singleton, it is extended to the length of 4. G«<5 7 K«1 10 9 11 13 10 2/G S 577 99 WSINGLETON EXTENSION ON LEFT ARGUMENT 11 11 K/5 13 13 ARSINGLETON EXTENSION ON RIGHT ARGUMENT 555 (O«M«3 0 1p9 (APL outputs a blank line) oM 301 2 3/M o (2 REXTENSION ON LAST 3/M) 305 1-180 APL Reference Manual (DEFAULT) AXIS (APL outputs a blank line) ATHIRD AXIS EXTENDED 2+3 TIMES Primitive Mixed Functions / and £ Compression and Replication aNEXT EXPRESSIONS USE NEGATIVE SINGLETON IN LEFT ARGUMENT aTHE RIGHT ARGUMENTS MUST BE EMPTY ON APPLICABLE AXIS "2/10 0 0 0 0 ~2/3 0p9 aLAST (DEFAULT) AXIS IS EMPTY 0 0 0 3 0p9 "2/3 RAGAIN, LAST AXIS IS EMPTY 00 0 0 0 0 0 0 0 0 0 0 0 0 0 0 00 G 9 57 13 11 ARIGHT ARGUMENT NOT EMPTY 2/G 10 LENGTH ERROR ARIGHT ARGUMENT NOT EMPTY 2/G A 3p9 ~2/0 aWRONG AXIS IS EMPTY 10 LENGTH ERROR ~2/0 3p9 AWRONG AXIS IS EMPTY A If B is a vector, all four forms of the compression function have the same effect. If the rank of B is greater than 1, the form used determines which axis of the array is affected. For the forms 4/ [ K] B and A/ [ kK] B, the affected axis is axis X : («B<«3 U4p112 12 3 4 5 6 7 8 9 10 11 12 1/[1)B 10 1 2 3 4 9 10 11 12 APL Reference Manual 1-181 Primitive Mixed Functions / and # Compression and Replication 10 1/4[1]B 1 2 3 4 9 10 11 12 101 0/[2]B 10 0#[2]B 3 > 7 9 11 1 3 5 7 9 11 1 The forms 4/ B and 4# B affect the last and first axis of B, respectively: X<«2 3p16 X 12 3 5 6 01 2 3 5 6 1 1/X 04X 123 If 4 1s empty, then B (after extension, if necessary) must have length 0 along the relevant axis. If the left argument contains all negative numbers (indicating fill characters), then the applicable axis in the right argument must be empty, and the result will be the prototype of B repeated + / | A times along the axis. If the applicable axis 1s not empty, APL signals LENGTH ERROR. For example: J«B+3 0p5 "2 "3/B (APL outputs a blank line) aCORRECT AXIS IS EMPTY 00000 00000 00000 J«C<«0 3p5 (APL outputs a blank line) 2 " 3/C 10 A INCORRECT AXIS IS EMPTY LENGTH EFRROR 2 3/C AINCORRECT AXIS IS EMPTY A APL inserts fill items that are determined by the prototype of each vector along the relevant axis. This is important for arrays of rank 2 or more because the fill item for a given position depends on the prototype of that particular column, row, or plane. The following expressions describe such an operation. Note where the fill items are blanks and where they are zeros. (Because the 1-182 APL Reference Manual Primitive Mixed Functions / and # Compression and Replication array M is simple, all the fill items are scalars. If ¥ were enclosed, some of the fill items might also have been enclosed.) aCREATE M, 3p 1 'A" 2 3 4 5 'A" A HETEROGENEOUS ARRAY OF RANK 3 3 4 5 'B" 6 = w N w o &2l N NS o LW O«M<2 2 COL«1 1 11 AREPLICATE M ALONG LAST AXIS (DEFAULT) = W & 2T ~N w = aPROTOTYPE BASED ON VECTORS ALONG LAST AXIS ALAST AXIS IS CHANGED = N N pCOL/M COL«1 1 1 AREPLICATE M ALONG 2ND AXIS pCOL/[2]M a2ND AXIS IS CHANGED COL/[11M aEXPAND M ALONG 1ST AXIS pCOL/[11M alST AXIS IS CHANGED an = o w oy = o w O N w ar O = O w O o w O COL/[2]1M APL Reference Manual 1-183 Primitive Mixed Functions / and # Compression and Replication Further examples: O«WRL<(1 to—--- + |1 2 R +---+ 3| |A4BC| + +---1 1 tom— + 1 2 3) '"ABC' 0 0 0/WRL aCOMPRESSION -+ |1 2 3| |ABC| po— -+ +---+ 3 220 1/WRL to—--- + +----- + 112 3] |12 3] |12 t----- + +----- + AREPLICATION t----- + o 4-—--- + t----- + -t -t 3] |000] |oO0 O] |ABC| |ABC| |0 0 0] H----- t -+ 4--—-- + -t -+ F----- + +----- + Possible Errors Generated 1-184 7 SYNTAX FRROR (NO DYADIC FORM OF DERIVED FUNCTION) 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPE) 15 DOMAIN FRROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN FRROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 30 AXIS DOMAIN FRROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions / and # Reduction / and # Reduction Form f/ B f/ LK1B f+B fA[K1B 4 is formed with / and - Left Operand Domain Type Dyadic value-returning function Right Argument Domain Type Any Shape Any Depth Any Result Domain (of derived function) Type Depends on f Rank 0f "1+ ppB Shape (pB)[(1ppB)~K] Depth Depends on f Implicit Arguments None. Description Reduction is a monadic function derived from the slash (/) operator. To derive the reduction function, use any dyadic function as the operand (f in the form) to slash. f can be a primitive dyadic function, a dyadic system function, a dyadic user-defined function, or a dyadic-derived function. f cannot be a user-defined operator. The result operates as if f were applied between successive 1tems along a specified axis of an array (B). For example: APL Reference Manual 1-185 Primitive Mixed Functions / and # Reduction H«X+16 12 3456 1+2+3+4+5+6 21 +/X 21 1Xx2x3xUx5x%6 720 x/X 720 </TAT A </'AB' 1 </VABC' 15 DOMAIN ERROR (INCORRECT TYPF) </ VABC' A The reduction of a scalar always returns the scalar itself. Thus, the last expression in the preceding example results in a DOMAIN ERROR because 'B'<'(C' evaluatesto 1, and '4' <1 match. is invalid because the data types do not ’ Remember that APL evaluates expressions from right to left. For example: </1 2 3 0 Here, APL evaluated 2< 3 and the result was 1. APL then evaluated 1< 1 and returned 0. The result of the derived function has a rank that is one less than the rank of the original array (unless the original array is a scalar). Thus, the reduction of a matrix yields a vector, the reduction of a vector yields a scalar, and so forth. For the forms f/ [ U«4<2 12 34 56 12 L4p16 +/[2]4A 14 10 +/[1]4 6 1-186 8 4 6 APL Reference Manual k] B and f# [ K] B, the applicable axis is axis X: Primitive Mixed Functions / and # Reduction Further examples: O«Y«(1 2 3) t-—-=- + -+ (32 2) (32 2) 4-----—- I 112 3] 1732 2] |32 2| |10 t--==- + t-———-—- t e + (10 1) + 1] t-—-=-- + +/Y t---— === + |4 6 2] e+ e , /13 anSIMPLE ARG YIFELDS NESTED RESULT e+ |1 2 3] t--—-—- + If the length of the ¥ th axis is 1, the result of the derived function is the original array with the ¥ th axis removed: O«A<5 1p15 1 2 3 Iy 5 +/[114 15 +/[2]4 12 3 45 The forms f/ B and f# B affect the last and first axes of B, respectively: [«A<«2 12 34 56 12 Up16 +/4A 10 14 +#4 6 8 4 b If the length of the applicable axis is 0, and all other axes have nonzero lengths, each result item is the identity function applied to the prototype of the argument, if one exists. The identity function for all scalar dyadic functions 1s p+f/ 10 where p is the prototype of the right argument (p<«+ 0p B) and f is the scalar dyadic function. The identity elements for the identity function of the scalar dyadic functions are listed in the following table: APL Reference Manual 1-187 Primitive Mixed Functions / and # Reduction Dyadic Function Identity Items for the Scalar Dyadic Functions Symbol Identity Item (f/ 1 0) Plus + 0 Minus - 0 Times x 1 Divide + 1 Power * 1 Residue | 0 Maximum [ Most negative representable number (" 1.7E38 approx) Minimum L Largest representable positive number Logarithm ® None Combination ! 1 (1.7E38 approx) Circle o None And A 1 Or Y 0 Nand A None Nor v None Less < 0 Not Greater < 1 Equal to = 1 Not Less > 1 Greater > 0 Not Equal 2 0 The identity functions for the nonscalar dyadic functions are listed in the following table. Note that P is the prototype of the argument B (defined formally as P«+ 0p B). Any functions not listed (including system functions, user-defined operations, and derived functions from arbitrary operator sequences) do not have identity functions. 1-188 APL Reference Manual Primitive Mixed Functions / and # Reduction Identity Functions for the Nonscalar Dyadic Functions Dyadic Function Symbol Identity Function Reshape o o P Catenate , (( " 1+pP),0)pcs(( Rotate d (T1+pP)pO Rotate e (14pP)pO0 Transpose ® tpp P Pick > 1 0 Drop ¥ (ppP)pO Take 0 p P Without ~ 1 0 Matrix Divide B (14pP)o.=14pP 1¥pP),0)pP Possible Errors Generated 7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 7 SYNTAX FRROR (NO DYADIC FORM OF FUNCTION) 11 VALUE FRROR 15 DOMAIN FRROR 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN EFRROR (FUNCTION HAS NO IDENTITY ITEM) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN FRROR (NOT A DYADIC FUNCTION) 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) APL Reference Manual 1-189 Primitive Mixed Functions / and # Reduction 1-190 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN FRROR (INCORRECT TYPE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions " Each " Each Form f B Af B Left Operand Domain Type Any function Left Argument Domain Shape Depends on the function f Depends on the function [ Depth Depends on the function f Type Right Argument Domain Shape Depends on the function f Depends on the function f Depth Depends on the function [ Type Result Domain (of derived function) Type Rank Shape Depth Depends on the function f o p B (after singleton extension) o B (after singleton extension) Depends on the function f Implicit Arguments None. Description The monadic = operator (known as each) takes a function (f) as the left operand. The result is either a monadic or dyadic derived function (depending on the valence of f). f can be a primitive function, a system function, a userdefined operation, or a derived function from an arbitrary operator sequence. The function f does not have to be a value-returning tfunction. APL Reference Manual 1-191 Primitive Mixed Functions " Each When you use ”, the action of a monadic f is applied to successive items of an array (B in the form), and the action of a dyadic f is applied between corresponding pairs of items (4 and B in the form). The action of f 1s only applied to the top level of nesting in an enclosed array (" is not pervasive). B <4 C « 15 D« 2 2 p "ABCD! 0« F <« B, b -+ |1 2 (cC), <D aNOTE USE OF PARENTHESES +--+ 3 4 5| |AB] -+ | CD| +--+ pE ASHAPE OF F SHOWS A 3 0 E ++ +-+ nSHAPE OF EACH OF E SHOWS SHAPE OF ALL ITEMS +---+ 15 (2 2| ++ +---+ +-+ =F aDEPTH OF F SHOWS ONE NESTING LEVEL 2 ="F 0 ADEPTH OF FACH OF E SHOWS DEPTH OF ALL ITEMS 11 [J S « E « cF it I | 3-ITEM VECTOR R+ + +--+] |1 2 3 4 5| |AB]|| |- + |cp]| | t--+] o+ 0 p E ARANK OF EACH ITEM OF E +-+ | 1] +-+ 0« F « cE,E,E T T T e + | 4= t ot t ot + | | |4 +---===- + +-—+| |4 - + ==+ |4 - + +--4]| [l 11234 50 [ABl] | |1 23 45| [4B]] | |12 3¢ 5/ |AB| || I [ + [CDI] t-—+] |+ I T 4--mmmmmms t [CD]] t--+] | | 4-mmmeeee- + [CD]]] t--+]|| t ot +| e oF =F + ASHAPE OF F SHOWS IT IS NOW A SCALAR (APL outputs a blank line) ADEPTH OF F SHOWS ENCLOSED ARRAY, I 1-192 | | APL Reference Manual 3 NESTING LEVELS Primitive Mixed Functions "~ Each ASHAPE OF EACH OF F SHOWS 1 VECTOR OF SHAPE 3) aSHAPE OF EACH/EACH OF F SHOWS 3 VECTORS OF SHAPE 3 aSHAPE OF EACH/EACH/EACH OF F | [++ 4=+ +---+] |++ +-+ +-—-+| [++ +-+ +-—-+]]| | [4++ +-+ +--—+] [++ +-+ +---+| [++ +-+ +---+]| EEE ISt Fre f2 200 stz 20p LI Ist 12 2] VZ<«SH X [1] [2] aTHIS USER-DEFINED FUNCTION RETURNS A RESULT aSH DETERMINES IF ARRAY X IS SIMPLE HOMOGENEOUS [4] v [3] X 00 , " 7 (25=X)n (AZ)n,=2«4+ SH 'A' SH 15 2 3 0 1 SH 2 2p'ABCD! 11 SH (1 2) 3 SH "ABC' 5 0 0 The following example shows the use of system functions with the each operator. The example creates a vector of function definitions and then displays the canonical representation of each of the list of functions: X « 2 2p'F 2 X F 2 Y « 2 3p'F0O01+2" Y FOO 1+2 JENS APL Reference Manual 1-193 Primitive Mixed Functions " Each OFxX" X Y t+-+ +---+ |F| |FOO| t-+ +---+ )FNS F FOO OCR TM t-+ +---+ |F| 2] |FOO| |1+2] t-+ +---+ '"F' 'FOO" 0BOXTM OVRTM <[2]0ONL 3 | VF| (11 | 2] [[1] V| | VFOO| v 1+2] o The next example shows the use of each to derive a dyadic function: X<'WENDY' 'STAN' 'PETER' X +----- T e T |WENDY| |STAN| tom-—- + t--——t + |PETER]| -+ (cOALPHA) A X e+ tmm----- T lu 2 |3 315 fommmm e+ Y « e s+ 412 |24 15 3] t-—----- I (14) (16) + (13) Y tommm - I 142 3 4] R |1 23456 |12 + 3] tommmm o b $ot---——1 2 1 3¢ Y |23 456 R EEEEE L 1341 2] I IsL 1] e+ + |12 3] ot----- + The next example shows each as part of a derived function: +/7 t--—+ (2 2014)(9 8 7) 24 |13 7] t---+ 1-194 APL Reference Manual Primitive Mixed Functions "~ Each Possible Errors Generated 9 RANK ERROR 10 LENGTH FRROR 40 OPERATOR DOMAIN ERROR (OPERAND TO EACH NOT A FUNCTION) APL Reference Manual 1-195 Primitive Mixed Functions \ and \ Expansion \ and % Expansion Form A\ B A\ [LK]B Ax B AX[K]B \ 1s formed with \ and - Left Operand Domain Type Near-Boolean Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain (of derived function) Type Same as argument Rank 1TppB Shape (pB)[(1ppB)~K] Depth 1 and p, 4 on axis X =B Implicit Arguments None. Description Expansion is a monadic function derived from the backslash (\ operator. It builds an array by combining the items of an existing array with fill items. You can also use the JEXP system function to perform the expand operation (see Chapter 2 for more information). Each item in the operand (4 in the form) is a Boolean scalar that corresponds to the position of an item in the right argument (8). When 4 is 1, APL inserts the corresponding item along the relevant axis of B into the result array. When A 1s 0, APL inserts a fill item into that position in the result array. There 1-196 APL Reference Manual Primitive Mixed Functions \ and \ Expansion must be a 1 for each item along the relevant axis in the right argument, so that all the items in B appear in the result array. Any number of fill items may be included: O«LIS<«12 13 13 12 15 15 V«1 0 1 0 1 AZEROS IN V DECIDE LOCATION OF FILL ITEMS VNLIS 12 0 13 0 15 A singleton right argument is extended along the axis to a length that matches the number of 1 s in the left argument: 1 5 0 0 1\5 5 If the left argument is a singleton, APL signals an error: I1N\5 8 7 6 10 LENGTH ERROR 1\ 6 78 A 0\5 6 7 8 10 LENGTH ERROR 6 0\5 7 8 A If the right argument is a vector, all four forms of the expansion function have the same effect. If the rank of the right argument is greater than 1, the form used determines which axes of the array are affected. For the forms 4\ [ O«A<2 10 X] B and 4\ [ X] B, the affected axis is axis X: 3p16 1\[1]4 REXPAND ALONG 1ST AXIS APL Reference Manual 1-197 Primitive Mixed Functions \ and X Expansion 1 0 1%[1]A 101 AEXPAND ALONG 15T AXIS 1\[2]4 AEXPAND ALONG 2ND AXIS 1x[2]4 AEXPAND ALONG 2ND AXIS 1023 4 0 5 6 10 102 3 4 6 0 5 1 The forms A\ B X«3 and 4\ B affect the last and first axis of B, respectively: 9p'"xTHISISANEXPANSIONEXAMPLE* %! X xTHISISAN EXPANSION EXAMPLE %x pX 39 V«1 1111011011 V\ X AEXPAND X ALONG LAST AXIS *xTHIS IS AN EXPAN SI ON EXAMP LE *x% 1 0 1 1XX AEXPAND X ALONG FIRST AXIS *THISISAN EXPANSION EXAMPLE % % When you expand an array, APL uses fill items that are determined by the prototype of each vector along the relevant axis. This is important for arrays of rank 2 or more because the fill item for a given position depends on the prototype of that particular column, row, or plane. The following expressions describe such an operation. Note where the fill items are blanks and where they are zeros. (Because the array ¥ is simple, all the fill items are scalars. If M were enclosed, some of the fill items might also have been enclosed.) w = Ul i o m o o 2 3p 1 0 1 oo O«M«2 ) oM BOO«1 1-198 1 APL Reference Manual "A'" 2 3 4 5 '4" 3 4 5 'B' 6 Primitive Mixed Functions \ and X\ Expansion aEXPAND M ALONG LAST AXIS (DEFAULT) + N o F w o w Ul PROTOTYPE BASED ON VECTORS ALONG LAST AXIS ALAST AXIS IS CHANGED = N N p0BOO\ M BOO«1 0 1 REXPAND M ALONG 2ND AXIS pBOO\ [2]M a2ND AXIS IS CHANGED BOO\ [11M aEXPAND M ALONG 1ST AXIS 0BOO\ [11M alST AXIS IS CHANGED SN o w = O = O a1~ oo w b w O BOO\ [2]M 3 23 Note that the right argument may be empty: 0 0 0\10 000 O«4«0 0 0O\ ' (APL outputs a blank line) pA 3 If the left argument is empty, the right argument (after extension, if necessary) must have length 0 along the relevant axis. For a simple, homogeneous array 4, the result of the expression 0=0\0p 4 is 1 if 4 is numeric, and 0 if 4 is character. For any array X, the result of the expression (2>=X)A (+Z)Ar.=2«4+"0p , Xis 1if X is simple or homogeneous, and 0 if X is either nonsimple or heterogeneous. APL Reference Manual 1-199 Primitive Mixed Functions \ and \ Expansion Further examples: O«WRL<(1 ---+ |1 2 3| +---+ 2 3) ('ABC') 0 0 |ABC| Possible Errors Generated 1-200 7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 15 DOMAIN EFRROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPF) 27 LIMIT ERROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPFE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN FERROR (RIGHT ARGUMENT HAS WRONG RANK) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions \ and X Scan \ and % Scan Form f<B fLK1B f\B fXLCK1B X 1s formed with \ and - Left Operand Domain Type Dyadic value-returning function Argument Domain Array Any Type Any Shape Any Depth Any Result Domain (of derived function) Type Depends on f Rank opB Shape pB Depth Depends on f Implicit Arguments None. Description Scan is a monadic function derived from the backslash (\ operator. To derive the scan function, use any dyadic function as the operand (f in the form) to backslash. f can be a primitive dyadic function, a dyadic system function, a dyadic user-defined function, or a dyadic-derived function from an arbitrary operator sequence. The result operates as if f were applied between successive items along a specified axis of an array (B). Thus, a scan of an array works the same as a reduction, except that the scan returns the results as the function is applied to each successive group of items. APL Reference Manual 1-201 Primitive Mixed Functions \ and \ Scan The result has the same shape as B. The first item of the result is always 1dentical to the first item of B, and the last item is equal to the f reduction of B. For example: +\3 U4 5 3 7 12 As the function is applied to each successive group of items, APL evaluates the resultant expressions from right to left: 34 2 1 -\ 1 712 72 Here, APL returned the following: ®* The first item in the argument array * The result of the expression 1-2 * The result of the expression 1-2-3 * The result of the expression 1-2-3-4 Note that APL treated each expression in the example independently; for example, the result of the expression 1-2 did not affect the evaluation of the expression 1-2-3. If B is an empty array, the result is an empty array. For the forms f\ [ O«A4<2 12 34 56 12 k1 B and f\ [ ¥] B, the applicable axis for the scan is axis X : Up16 +\ [2]4 1 3 6 10 5 11 12 14 +\ [1]4 12 3 4 6 4 6 8 The forms f\ B and f\ B affect the last axis and first axis of B, respectively: 1-202 APL Reference Manual Primitive Mixed Functions d \ Scan \ an [J«4«2 12 U4p1b 34 1 2 56 +\ 4 1 3 6 10 5 11 12 1t +34 12 34 6 U 8 6 Note that the scan operator is never applied if B has the length 1. Thus, +\"A'<«~>" A", Also note that for =\ '4B' «-»> ' 4', 0 is heterogeneous, because the first item of the result would be a character (' 4' ), and the second item would be a number 0, the result of '4'="B". If the dyadic function specified with scan is one of the associative primitive functions (+, x, L, I, <, and v for all arguments; = and = for Boolean arguments), APL uses an optimization that changes the way scan is computed. The definition of R<A\ B (for vectors R[ K] =f/ K+ B0) is changed as follows: R[K] nu = B[1] = R[K-1] H R(1] f B[K] for KeliipB This optimized scan requires fewer operations than the traditional scan. Note that the result of an associative operation may differ slightly from the nonassociative approach, and you should use it carefully if your results require a high degree of precision. For example: A«1FE6 ~1E6 1F 16 4 1000000 1000000 1F 16 +\4 1000000 0 1E 16 +/4 0 Further examples: OeW<(2 2 3) (2 1 0) APL Reference Manual 1-203 Primitive Mixed Functions \ and\} Scan o\3 J 2 1 aSIMPLE ARG YIELDS NESTED RESULT +----- + t----- + 12 2 2] |11 1] t-=-=- + t----- + Possible Errors Generated 1-204 7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) 7 SYNTAX ERROR (NO DYADIC FORM OF FUNCTION) 11 VALUF ERROR 15 DOMAIN FRROR 15 DOMAIN ERROR (INCORRECT TYPE) 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH FRROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN FRROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 40 OPERATOR DOMAIN EFRROR (NOT A DYADIC FUNCTION) APL Reference Manual Primitive Mixed Functions o . f Quter Product o , fOuter Product Form Ao . fB Left Operand Domain Type Always jot (o) Right Operand Domain Type Dyadic function Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Any Shape Any Depth Any Result Domain (of derived function) Type Depends on f Rank (ppA)+ppB Shape (pA4),pB Depth Depends on f Implicit Arguments None. APL Reference Manual 1-205 Primitive Mixed Functions o , f Quter Product Description Outer product is a derived function that specifies an operation to be performed between every item of one array and every item of another array. In the expression R<A4- . fB, R is an array that results from the application of the function f to every pair of items of 4 and B. f can be a primitive dyadic function, a dyadic system function, a dyadic user-defined function, or a dyadicderived function from an arbitrary operator sequence. The function f does not have to be a value-returning function. In the following example, note how the outer product operator affects the operation of the primitive scalar function multiply: 2 6 1 2 3x2 3 4 1 2 30.%x2 3 anSCALAR PRODUCT APPLIES x TO EACH PAIR 12 ITEMS 4 1 [N S o Qe w O O =N AQUTER PRODUCT APPLIES x BETWEEN ALL In the next example, the outer product operator affects the operation of the equal function so that each data item in the left argument is compared to each item in the right argument. Then, the reduction function (derived from the slash operator) is used to determine how many times each item in the left argument appears in the right argument. Note that the left argument determines the number of rows in the result, and the right argument determines the number of columns: G¢1 2 3 2 2 1 (13)o.= aFIND THE LOCATIONS OF 1S5,25,AND 100001 010110 001000 +/(13)0.=CG 2 anUSE REDUCE TO TOTAL THE ROWS 31 ATHERE ARE TWO 15 THREE 2S5 AND ONE Further examples: J«X<«(1 2 3) t----- + +---+ 2 |1 2 1-206 3| |ABC| APL Reference Manual "4BC' 2 3 IN G 35 IN G Primitive Mixed Functions o . f OQOuter Product (12) t----- + o.= X t----- + 0 |10 0] |0 O O t———— + == + t----- + +----- + 101 0] |00 e +-—==- + + HeW<(2 2 ee+ +----- + |2 2 |2 3| to—— + 3) (2 1 2 1 0) 1 0] -+ W o.p0 t-———- + 0 0] W t--—=-- + |2 2 3] |2 1 0] 12 | 2 3] | |2 2 3| |2 2 3] e + |2 1 0] |2 0| |2 0| t----- + ++ ++ | | | | | | | | | | | | ++ | ++ (13) +--+ o.p +-+ 0 AaSIMPLE ARGS YIELD NESTED RESULT +-+ | 1] |2 ] 0] +--+ +-+ +-+ +--——- + +--—+ +--—+ |71 1] |2 2| |0 0] t--—-- + +---+ +--—+ t-——m -+ $----- + t---=- + 171 71 1] |2 2 2] 10 0 0] I + tomm -I Possible Errors Generated 7 SYNTAX FRROR (NO MONADIC FORM OF DERIVED FUNCTION) 15 DOMAIN ERROR 15 DOMAIN ERROR (INCORRECT TYPE) 40 OPERATOR DOMAIN FRROR (NOT A DYADIC FUNCTION) APL Reference Manual 1-207 Primitive Mixed Functions f. g Inner Product f. glnner Product Form Af. gB Left Operand Domain Type Dyadic value-returning function Right Operand Domain Type Dyadic value-returning function Left Argument Domain Type Any Shape Any, inner axes of 4 and B must conform Depth Any Right Argument Domain Type Any Shape Any, inner axes of 4 and B must conform Depth Any Result Domain (of derived function) Type Depends on f and g Rank Of 2+(ppAd)+ppB Shape (T1vpA), 1+pB Depth Depends on fand g Implicit Arguments None. 1-208 APL Reference Manual Primitive Mixed Functions f. g Inner Product Description The derived function inner product produces the common algebraic matrix product of two arrays. The name inner product comes from the application of the function (g) along the inner axes of the two arguments. f and g can be a primitive dyadic function, a dyadic system function, a dyadic user-defined function, or a dyadic-derived function from an arbitrary operator sequence. (The inner axes are the last axis of the left argument and the first axis of the right argument.) For example: («A«2 12 3 4L 5 6 12 3 14 32 3p16 H«B<13 A+, xB RINNER AXES DO NOT MATCH IN NEXT EXPRESSION B+.x4 10 LENGTH FRROR (LENGTHS OF INNER AXES DO NOT MATCH) B+.x4 A In the preceding example, each item along the first axis of the right argument (in this case, B has only one axis) is multiplied by the corresponding item along the last axis of the right argument, and the products of each row are summed. The lengths of these inner axes must conform (in this case they are both 3). The shape of the result is the shape of 4 (2 3) catenated to the shape of B (3) without their inner axes. When each of the arguments has only one axis, the result is a scalar: (13)+.%x13 14 When you want to perform the inner product with one object on itself, use transpose: [«A<«2 12 3 L 6 5 3p16 A+, xQ4 14 32 32 77 APL Reference Manual 1-209 Primitive Mixed Functions f. g Inner Product You can also specify an inner product in which an operation other than multiplication is performed. Commonly, you might also use » . = (And Dot Equals), v.z (Or Dot Not equals), or x.x (Times Dot Star). Using this method, you can locate values containing specific characters or search for a row of one array in which all the items are equal to those in a column of another array. For example: O«B+«2 316 3 aNEXT EXPRESSION COUNTS WHERE 2 AND 6 2 6+.<B n ARE < THE TWO ROWS OF EACH COLUMN IN B 1 U«X<4 3p 'ONETWOSIXTEEN' ONE TWO SIX TFE pX 4 3 pY«'SIX! aFIND WHERE Y OCCURS IN SIX 3 To be used in an inner product operation, the two arguments, denoted 4 and B, must conform to at least one of the following rules: ® A or B is a singleton e The inner axes (the results of “ 14 p 4 and 1+ p B) are equal e Either the last axis of 4 (T 14 p 4) or the first axis of B (14 p B) equals 1 If the first or third rule is true, then the corresponding argument is extended (through the process of singleton extension) so that the arguments have equal lengths along the matching axes. If (0="14+pA)Ar0=1%pB, but no other axes of4 and B are equal to 0, then the inner product operator returns an array of identity items for the function /, as in reduction. 1-210 APL Reference Manual Primitive Mixed Functions f. g Inner Product Further examples: 0«G<1 3 p -+ |12 (123) +--——-—- + 3] | to---- + 2 0 (T2 01) 72 2 1] t------ + G+ .xQ G t—————- + |9 8 14 t-————- + ASIMPLE ARGS (13) pomm e mm 11 2 2 3 t-—— ,.p YIELD NESTED RESULT 13 -+ 3 3] -+ Possible Errors Generated 7 SYNTAX FRROR (NO MONADIC FORM OF DERIVED FUNCTION) 11 VALUE ERROR 10 LENGTH ERROR (LENGTHS OF INNER AXES DO NOT MATCH) 15 DOMAIN EFRROR 15 DOMAIN ERROR (FUNCTION HAS NO IDENTITY ELEMENT) 15 DOMAIN FRROR (INCORRECT TYPE) L0 OPERATOR DOMAIN ERROR (NOT A DYADIC FUNCTION) APL Reference Manual 1-211 Primitive Mixed Functions [ ] Axis []Axis Form fLK]1B AfCK]1B Left Argument Domain Type Monadic or dyadic function Right Argument Domain Type Near-integer (floating for laminate and ravel, Any for userdefined operations) Shape Singleton (Vector for drop, enclose, disclose, ravel, take and all dyadic scalar functions, Any for user-defined operations) Depth 0 or 1 (simple), Any for user-defined operations Result Domain Type Same as left argument Implicit Arguments 0710 (fL K] when JI0<«1 1s identical to fTLK+ 1] when 0I0<«0) Description Axis makes the function to its left apply to the axis specified by the value surrounded by brackets. The following functions and operators may be affected by axis: 1-212 * C(Catenate (, * Derived compress/replicate (/ and #) * Derived reduction (/ and #) * Derived expand (\ and \) * Derived scan (\ and %) * Disclose (o) * Drop (+) and ;) APL Reference Manual Primitive Mixed Functions [ ] Axis Enclose (<) Laminate (, and ;) Monadic grade up (4) Monadic grade down (V) Ravel (, and 5) Rotate (¢ and o) Reverse (¢ and o) Take (+) OEXP OREP All dyadic scalar functions (see Table 1-1 in Section 1.1.1) User-defined operations The use of axis with these functions (and operators) is described in the individual explanations of the functions. For examples and further descriptions of axis with scalar functions, see Section 1.1. When you use axis with the 5, #, \, and e functions, the functions are equivalent to ,, /, \, and ¢ used with axis. The following list shows the definitions and equivalences of these symbols. Note the following: f represents either ,, /, \ or ¢ g represents 5, /, ¥, 0or e A and B represent any arrays S 1is any scalar K is any axis 0I0 is used to select the first axis of an array. gB <+~ flOI0] B flk]l B <+ g[k] B for allx fs «~ fIOI0]1 S <«~>g S <~ g[OIO0l S Ag B+~~> Af[0IO0] B AffK] B+~ AglK] Bforallx AfS <+ A flOI0] S<«> AgsS <~ AglOIO] S Axis is 0 I0-dependent; thus, all the functions named are 00 I0-dependent when they are affected by axis, except user-defined operations. APL Reference Manual 1-213 Primitive Mixed Functions [ ] Axis Possible Errors Generated 1-214 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) 30 AXIS DOMAIN ERROR (AXES NOT IN CONTIGUOUS ASCENDING ORDER) 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN FRROR (DUPLICATE AXIS NUMBER) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT OPERATION) 30 AXIS DOMAIN FRROR (INCORRECT TYPFE) 30 AXIS DOMAIN ERROR (LEFT ARGUMENT HAS WRONG LENGTH) 30 AXIS DOMAIN FRROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 30 AXIS DOMAIN FRROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual Primitive Mixed Functions « Specification Function < Specification Function Form A<B ALK]<B Left Argument Domain Type Variable name or undefined name Shape Any Right Argument Domain Type Any Shape Conforms to index argument &, if any Depth Any Result Domain Type Same as right argument Rank oppB Shape 0B Depth =B Implicit Arguments None. Description The specification function (+) stores values in identifiers. The left argument (4) must be a variable name or undefined. When the function is executed, the value of the right argument (B) becomes associated with the name A. In addition to the uses described below, specification can also be used for strand and selective assignment statements. Specification functions can be included in the construction of other statements. For example, the following assigns the value 7 to ¢, 11 to B, and 14 to 4: A«3+B<U4+(C+7 APL Reference Manual 1-215 Primitive Mixed Functions < Specification Function For the form A[ conform to K] «B, axes of length 1 are dropped from B to allow B to ALK] . (For more details about the A[Xk]<B form of specification, see the VAX APL User’s Guide.) For example: O«A«2 3p16 B«3 1p7 123 4 5 6 1 8 9 Al2;1+B A 123 7 8 9 The specification function is a quiet function; it does not return a value if it is the leftmost function in a statement. A<2 A 2 (4«2) 2 [«A+2 2 Note that the value returned by the specification function (when you require that it returns a value) is the value of the right argument, even if the left argument is indexed. For example: A<5 4 3 2 1 He«A[1]«4 M A b 4 321 Possible Errors Generated Specification not subscripted (form 4+B) 1-216 4 NOT A VALID SYSTEM IDENTIFIFER 7 SYNTAX ERROR (MISSING LEFT ARGUMENT TO ASSIGNMENT) 11 VALUE ERROR (NO VALUE TO ASSIGN) 15 DOMAIN FRROR (ILLEGAL LEFT ARGUMENT TO ASSIGNMENT) 15 DOMAIN EFRROR (NOT A SYSTEM VARIABLE) APL Reference Manual Primitive Mixed Functions « Specification Function Subscripted specification (form A[ K] «B) 11 VALUE ERROR (NO VALUE TO ASSIGN) 11 VALUE ERROR (SUBSCRIPTED NAME IS UNDEFINED) 15 DOMAIN ERROR (INVALID OBJECT IN INDEXED ASSIGNMENT) 15 DOMAIN ERROR (NOT A SYSTEM VARIABLE) 27 LIMIT FRROR (INTEGER TOO LARGE) 36 INDEX RANK FRROR 36 INDEX RANK FRROR (CANNOT INDEX A SCALAR) 37 INDEX LENGTH ERROR 37 INDEX LENGTH ERROR (INDEX LESS THAN INDEX ORIGIN) 37 INDEX LENGTH ERROR (INDEX OUT OF RANGE) 38 INDEX DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 38 INDEX DOMAIN ERROR (INCORRECT TYPE) 38 INDEX DOMAIN ERROR (NOT AN INTEGER) APL Reference Manual 1-217 Primitive Mixed Functions Strand Assignment with the Specification Function Strand Assignment with the Specification Function Form (A1...An) <B Left Argument Domain Type List of variable or undefined names Shape Any Right Argument Domain Type Any Shape Vector domain Depth Any Result Domain Type Same as right argument Rank ppB Shape pB Depth =B Implicit Arguments None. Description Strand assignment (also known as vector assignment) allows you to assign a list of values to a list of objects. APL applies the assignment along successive pairs of items in the left (4) and right (B) arguments in a manner similar to scalar extension. The objects in 4 may be undefined names, variable names, or system variable names. The result of the strand assignment function is the right argument. The length of B must conform to the number of objects in 4, or B must be a singleton, in which case APL performs singleton extension. For example: 1-218 APL Reference Manual Primitive Mixed Functions Strand Assignment with the Specification Function BURR « 32 o TEMP « 0 BURR ¢ TEMP ¢ o COLD « 12 COLD 32 0 12 R PARENTHESES REQUIRED (BURR TEMP COLD) BURR ¢ TEMP ¢ <« 20 4 15 COLD 20 4 15 RSINGLETON EXTENSION (BURR TEMP COLD) BURR ¢ TEMP ¢ <« 3 COLD You can use strand assignment to allow multiple arguments in user-defined operations. For example, FRET is a monadic user-defined function containing three local variables (X, Y, and Z). The header definition of FRET is as follows: VFRET B;X;Y;72 ¥ When FRET is called, the argument (B) contains three items. Inside FRET, there is an expression that performs a strand assignment in which each item in B is assigned to a local variable. For example: BIP«<23 41 'RUE! RBIP CONTAINS 3 ITEMS FRET BIP ATHE CALL TO FRET IS STILL MONADIC (X Y Z)<BIP aTHIS IS EXPRESSION INSIDE OF FRET Note that the length (3) of the left argument to the specification function conforms to the number of items in BIP. If BIP were a singleton, APL would perform singleton extension. Strand assignment is an atomic operation; if any of the assignments fail, no change occurs to any of the names in the left argument list. However, If you have set the display option on the J¥WATCH system function (see Chapter 2 if you have set the signal option, the signal is held until APL completes the entire strand assignment and only the last watched name is signaled. APL Reference Manual 1-219 Primitive Mixed Functions Strand Assignment with the Specification Function Possible Errors Generated 1-220 4 NOT A VALID SYSTEM IDENTIFIER 7 SYNTAX ERROR (MISSING LEFT ARGUMENT TO ASSIGNMENT ) 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR 15 DOMAIN ERROR (INVALID OBJECT IN STRAND ASSIGNMENT) 11 VALUE ERROR (NO VALUE TO ASSIGN) 15 DOMAIN FRROR (NOT A SYSTEM VARIABLE) APL Reference Manual Primitive Mixed Functions Selective Assignment with the Specification Function Selective Assignment with the Specification Function Form (fA) «B (CfA) «B Left Argument Domain Type A 1s a variable name f is a function (see list below) C is any valid left argument to f Shape Any Right Argument Domain Type Any Shape Conforms to left argument Depth Any Result Domain Type Same as right argument Rawrite nk opB Shape o B Depth =B Implicit Arguments None. Description Selective assignment allows you to assign values to specified items of an array. The left argument (f4) contains an expression that selects items from an array. The length of the right argument (B) either equals the number of items selected or is 1 (B 1s a singleton), in which case APL performs singleton extension. For example: APL Reference Manual 1-221 Primitive Mixed Functions Selective Assignment with the Specification Function O«GUT+15 123145 O« (34GUT)+«u48 48 49 48 48 50 O« (34GUT)+u8 48 u9 50 RASSIGN TO FIRST 3 ITEMS OF GUT U5 aSINGLETON EXTENSION U5 ASHAPES DO NOT MATCH (3t+GUT)«u8 10 49 LENGTH ERROR (3+GUT)+«u8 49 A The following table describes the primitive functions you can use in the left argument expression to select items from an array. The symbol I refers to an expression that is a valid argument to the function in the form. Assignment Form Function Name (,A4)<B Ravel (,[KJA) « B Ravel with axis (¢4) « B Reverse (ed) <B (¢ [KJA) « B (e[K]A) « B Reverse with axis (84) « B Transpose (IVA) < B Drop (I+[K14) < B Drop with axis (I+4) « B Take (I+[K]1A) <« B Take with axis (IbA) « B Rotate (IeAd) « B (Ib[KJ1A) « B Rotate with axis (Ie[K]A) <« B (IRA) « B Transpose (IpAd) « B Reshape (INA) « B Expand (IXA) « B (IN[K]1A) < B 1-222 APL Reference Manual Expand with axis Primitive Mixed Functions Selective Assignment with the Specification Function Assignment Form Function Name (IX[K]JA) « B Replicate (I/A) < B (I+A) <« B (I/[KJA) « B Replicate with axis (I+#[K]A) <« B You can use more than one of the eligible functions in the left argument expression. For example: = (@3 (@] 0«BOP«3 0 2 3 I 0 b 7 8 9 O«(2t1 3p19 18BOP)<«0 0 ACHANGE FIRST 2 ITEMS ON THE DIAGONAL You can use other primitive functions in the portion of the left argument expression that evaluates the argument of one of the eligible functions. For example: 0«BOP<+3 3p19 = ()] 3 b 9 BE<1 EP<?2 O«((BE+EP)+1 18BOP)«0 0 0 o = 3 b 0 Possible Errors Generated 4 NOT A VALID SYSTEM IDENTIFIER 11 VALUF FRROR (NO VALUFE TO ASSIGN) 15 DOMAIN ERROR (CANNOT MODIFY SELECTIVE ASSIGNMENT TARGET) APL Reference Manual 1-223 Primitive Mixed Functions Selective Assignment with the Specification Function 1-224 15 DOMAIN EFRROR (INVALID FUNCTION IN SELECTIVE ASSIGNMENT) 15 DOMAIN ERROR (INVALID OBJECT IN SELECTIVE ASSIGNMENT) 15 DOMAIN ERROR (NOT A SYSTEM VARIABLE) 36 INDEX RANK FRROR 37 INDEX LENGTH ERROR APL Reference Manual 2 VAX APL System Variables and Functions Conceptually, there are two parts to the VAX APL interpreter: the APL language and the APL environment. The APL language comprises the lexical and symbolic elements of APL, the parts of APL that are included when it is used as a mathematical notation in a classroom. The APL environment is the setting in which the APL language elements are applied. The APL interpreter recognizes a set of system variables, functions, and commands that allow you to control your APL sessions, as well as to facilitate and preserve the work you do in those sessions. For example, the interpreter allows you to: * Determine or set the values of the index origin, print precision, comparison tolerance, and other elements that affect the operation of functions. e Get information about a workspace, such as its name and size, the names of its user-defined operations and variables, the state of its active operations, and so on. e Manipulate workspaces; that is, load, save, or delete them, copy objects from them, or change their size. * 2.1 Get the system time and date, or get accounting information for a session. System Variables VAX APL system variables, like ordinary variables, can be used in any language expression or function. Unlike ordinary variables, system variables have special meaning to the system, and they allow you to do the following: e Set the index origin and comparison tolerance. e (Change the output precision and line width. * Specify an operation to be performed when a workspace is activated. e Automatically save an active workspace after function editing and data input. APL Reference Manual 2-1 VAX APL System Variables and Functions 2.1 System Variables 2.1.1 System Variable Names The names of APL system variables begin with a quad character (0). The names are considered to be distinguished names, meaning that they are reserved for a specific purpose. You cannot use them as names for user-defined operations or variables, and you cannot copy, erase, or collect them in a group. 2.1.2 System Variable Characteristics System variables are similar to ordinary variables in the following ways: * They retain their values until new ones are assigned. ® Their current values are saved with a workspace (except for 0GAG, OTT, OTLE and 0 VPC). ¢ They can be localized in user-defined operation definitions. Each of the system variables in APL can be assigned a value and can be localized in user-defined operations. Table 2-1 lists the system variables, the range of values you can specify for them, and their default values. Table 2-1 System Variable Value Ranges Variable Value Range Default AUS 0,1,2 0 Ocr 0 to 2.328E 10 1E7 15 OoDcC Nested vector (C1102) ODML 512 to 2048 2048 OERROR Error message tt 0GAG 0,1, 2,3 Terminal dependent OrIo 0,1 1 0L Any 1 0 OLX Expression e OnNG 0,1,2 1 OPP 1to 16 10 0 PW 35 to 2044 Terminal width OR Any 1 0 (continued on next page) 2—2 APL Reference Manual VAX APL System Variables and Functions 2.1 System Variables Table 2-1 (Cont.) Variable ORL System Variable Value Ranges Value Range Default ~ 2147483648 to 695197565 2147483647 OSF Prompt 0:<CR><LF> 6 spaces O0SINK Any Always 1 0 OTERSE 0,1 0 OTIMELIMIT ~ 1 to 255 0 UTIMEOUT 0,1 0 OTLE 0,1 Terminal dependent OTRAP Expression e OrT 1to 19 Terminal dependent OVPC Non-negative integer 30 Note that 1ERROR, OLX, O0SF, and 1 TRAP must have character values; ]DC has a two-item heterogeneous value; all the other system variables must have numeric values. The exceptions are 1L, OR, and 0 SINK, which may take any type of value. 2.2 System Functions APL system functions supplement the primitive functions by providing additional processing capabilities. For instance, they allow you to do the following: e [Express the canonical representation of a user-defined operation and store the operation definition as data. e e Expunge a named object. Construct a name list of labels, variables, or functions, and return the classification of a named object. * Delay execution of an operation for a specified period of time. You access a system function by stating its name and arguments (if any), just as you would access a primitive or user-defined operation. For the system functions that take character arguments, white space (spaces and tabs) is allowed before and after the name (workspace name, function name, and so on) in the argument. For example, all of the following will load the workspace MYWS: APL Reference Manual 2-3 VAX APL System Variables and Functions 2.2 System Functions OQLD ' MYWS ! MYWS ' 0QLD ! O0QLD 'MYWS' MYWS QLD ! Anything other than white space is not allowed before or after the name: QLD ' MYWS 22 A4’ INCORRECT PARAMETER OQLD (EXTRANEOUS CHARACTERS AFTER COMMAND) ' MYNS A A 2.2.1 System Function Names System functions, like system variables, are identified by unique names that begin with a quad character (01); you cannot use these names for user-defined operations or variables, and you cannot copy, erase, or collect them in a group. APL assumes that any system functions in an expression are ambivalent, even though most system functions have a specific valence. This means that if an expression contains a left argument for a monadic system function, APL signals an error. For example: AUARBOUT IS MONADIC 2 JARBOUT 3 7 SYNTAX ERROR (NO DYADIC FORM OF FUNCTION) 2 UARBOUT 3 A 2.2.2 Types of System Functions System functions can be categorized as follows: * Niladic system functions—those that do not take arguments. * Monadic system functions—those that take one argument. * Dyadic system functions—those that take two arguments. * Ambivalent system functions—those that take either one or two arguments. The niladic system functions do not take arguments (you may not assign a value to them), and they cannot be localized in user-defined operations. The niladic system functions and their values (where applicable) in a clear workspace may be summarized as follows: 2-4 APL Reference Manual | VAX APL System Variables and Functions 2.2 System Functions Niladic System Functions Function Description (value in clear workspace) OAT Account information as 4-integer vector HALPHA '"ANABCDEFGHI JKLMNOPQRSTUVNXYZ' OALPHAL 'abcdefghljklmnop qrstuvwxyz' UALPHAU 'AABCDEFGHIJKLMN OPQRSTUVWXYZ' OASCIT 0 AV subset; approximates ASCII characters 04V Atomic vector OCHANS Assigned file channels (empty numeric vector) OCTRL The first 32 ASCII characters and Delete OLC Line numbers in state indicator (1 0) ONUM '0123456789" ORESET Clears the state indicator (no value) Or7s Time stamp as 7-integer vector OUL Process identification number (PID) OVERSION Interpreter and workspace versions OwWA Workspace available in bytes The monadic system functions take one argument, which is placed immediately to the right of the function. The following table of the monadic system functions describes the type, shape, and, where applicable, the units associated with each function’s argument. Note that there are two entries for JASS, which has both action and query uses. Monadic System Functions Function Shape Type Units OARBOUT Vector domain Integer Character codes 04SS Vector domain Character File information O0ASS Vector domain Near-int Channel numbers [0BREAK Any Any N/A [CHS Vector domain Near-int Channel numbers O0CLS Vector domain Near-int Channel numbers OCR Vector domain Character Operation name [0DAS Vector domain Near-int Channel numbers APL Reference Manual 2-5 VAX APL System Variables and Functions 2.2 System Functions Monadic System Functions Function Shape Type Units [0DL Singleton Floating Seconds apvce Vector domain Near-int Channel numbers OEFC Vector domain Near-int Channel numbers OEFR Vector domain Near-int Channel numbers OEFS Vector domain Near-int Channel numbers OEX Matrix domain Character Name list OFI Vector domain Character Numeric string OFLS Vector domain Near-int Channel numbers OFX Matrix domain Character Operation definition OMBX Vector domain Near-int Channel numbers ONC Matrix domain Character Name list [0OM Vector domain Near-Bool N/A 0eco Vector domain Character Workspace name, object names O0QLD Vector domain Character Workspace name OQEC Vector domain Character Workspace name, object names ORELEASE Vector domain Near-int Channel numbers OvI Vector domain Character Numeric string OVR Vector domain Any Value or object name 0xQ Vector domain Any N/A The dyadic system functions take both a left and a right argument. The dyadic system functions and the type, shape, and units, if any, associated with their arguments are as follows. Dyadic System Functions Function 0cIiq 0CoQ OEXP 2-6 Shape Type Units Left: Vector domain Near-int Packed data Right: Vector domain Near-int Control information Left: Array Any Data to be packed Right: Vector domain Near-int Control information Left: Vector domain Near-Bool Expand information APL Reference Manual VAX APL System Variables and Functions 2.2 System Functions Dyadic System Functions Shape Type Units Right: Any Any Array to be expanded Left: Vector domain Character Format string Right: Any Any Data to be formatted Left: Vector domain Near-int Replicate information Right: Any Any Array to be replicated Left: Vector domain Character Pattern string Right: Vector domain Character String Function OFMT OREP 0ss The ambivalent system functions may be monadic or dyadic; thus, they take either a right argument only, or they take both a right and a left argument. The following table of the ambivalent system functions describes the type, shape, and, where applicable, the units associated with each function’s arguments: Ambivalent System Functions Shape Type Units Left: Vector domain Character Delimiter Right: Matrix domain Character Delimited lines Left: Vector domain Character Function header Right: Vector domain Character Function 0BOX OMAP Shared image def/function name [OMONITOR ONL OPACK OREWIND O0SIGNAL O0STOP Left: Vector domain Numeric Line numbers Right: Matrix domain Character Operation names Left: Vector domain Character Letter list Right: Vector domain Near-int Name classes Left: Vector domain Numeric Data packets Right: Matrix domain Character Variable names Left: Singleton Near-int Key of reference Right: Vector domain Near-int Channel numbers Left: Vector domain Character Error message Right: Singleton Near-int Error number Left: Vector domain Near-int Line numbers APL Reference Manual 2-7 VAX APL System Variables and Functions 2.2 System Functions Ambivalent System Functions Function O TRACE OWAIT OWATCH Shape Type Units Right: Matrix domain Character Operation names Near-int Line numbers Left: Vector domain Right: Matrix domain Character Operation names Left: Singleton Near-int Time limit Right: Vector domain Near-int Channel numbers Left: Singleton Near-int Watch mode Right: Matrix domain Character Variable names Another type of system function is the quiet function, a category that is independent of the valence of the function. Quiet functions do not generally cause APL to display a value when they are evaluated as the leftmost function in a statement. The following table shows the quiet functions: Quiet System Functions Monadic Dyadic Ambivalent OARBOUT « H - (always) OWAIT OREWIND OCLS 0XQ (sometimes) [0DAS ¢ (sometimes) 0eco U&LD O0QPC ORELEASE However, a quiet function displays a value if you enclose the function and its arguments in parentheses (note that the branch function (+) is always quiet). The 0XQ and » functions are quiet when the argument is quiet; otherwise [ and ¢ cause APL to display a value. For example: 2-8 APL Reference Manual x¢ VAX APL System Variables and Functions 2.2 System Functions A<5 (A<5) aSPECIFICATION FUNCTION IS QUIET. NO DISPLAY aADD PARENTHESIS IF YOU WANT A DISPLAY 5 (B<'THIS WILL PRINT BECAUSE OF THE PARENTHESES') THIS WILL PRINT BECAUSE OF THE PARENTHESES 0XQ "A+10' a0XQ ARGUMENT IS NOT QUIET 0XQ a[0XQ ARGUMENT IS QUIET. 15 'C«A+10' NO DISPLAY 2.3 System Variables and Functions Reference The following sections describe the APL system variables and functions in alphabetical order. Table 2-2 lists the system variables and functions and gives a brief description of their uses. APL displays an alphabetical list of these variables and functions when you enter the following expression: X«<ONL 2 Table 2-2 3 50 X[AX:] System Variables and Functions Name Meaning OAT Maintains account information on the current APL session. Includes OALPHA Vector of 27 characters: A and 4 through Z. OALPHAL Vector of 26 lowercase characters: a through z. OALPHAU Vector of 27 underscored characters. OARBOUT Writes arbitrary output to the terminal. OASCIT Subset of DAV approximates the ASCII character set. O0ASS Associates a file or mailbox with a channel. OAUS Specifies periodic workspace backup. O0AV Vector of all APL characters. O0BOX Returns a matrix from a character vector and vice versa. (The rows OBREAK O0CHANS user identification, CPU time, and connect time. of the matrix are delimited by a specified string.) Suspends operation execution and returns control to immediate mode. Identifies channel numbers associated with files. O0CHS Returns file organization and open status on one or more channels. O0CIQ Unpacks data packed by 0 C0q. (continued on next page) APL Reference Manual 2-9 VAX APL System Variables and Functions 2.3 System Variables and Functions Reference Table 2-2 (Cont.) Name System Variables and Functions Meaning OCLS Closes the files on one or more channels. 0cog Packs data of different types for storage as one record. OCR Returns a canonical representation of a user-defined operation whose name is the character string specified. gcr Determines the degree of tolerance applied in numeric comparisons. [0CTRL Vector of ASCII control characters. ODAS Disassociates files from one or more channels. apc Controls the display of enclosed arrays. ODL Delays execution by the number of seconds specified. O0DML Controls default maximum record length used to save the workspace or to create a file. Opve Returns the device characteristics longword for one or more channels. OEFC Clears event flags associated with one or more channels. OEFR Returns the setting for event flags on one or more channels. OEFS Sets event flags associated with one or more channels. OERROR Character vector that describes last error to occur. OEX Expunges existing use of a name in the workspace. OEXP Expands an array by adding fill items in the same manner as the expansion derived function. OFI Converts character argument to numeric, placing Os in each position not corresponding to a valid number. OFLS Returns information about files on one or more channels. OFMT Converts argument to character matrix in designated format. OFX Establishes an operation from its canonical representation. O0GAG Indicates whether to accept broadcast messages. 0I0 Sets index origin for arrays; must be 0 or 1. 0L Contains the name of a changed variable that is being watched by LOWATCH. OLC Vector of line numbers in state indicator; most recently suspended operation appears first. (continued on next page) 2-10 APL Reference Manual VAX APL System Variables and Functions 2.3 System Variables and Functions Reference Table 2-2 (Cont.) Name OLX System Variables and Functions Meaning Contains an expression to be executed automatically when workspace is loaded. OMAP Associates an external routine with a user-defined function. OMBX Returns information about mailboxes on one or more channels. OMONITOR Gathers information about operation execution counts and CPU times. OncC Returns the classification of one or more names. ONG Controls recognition and printing of negative sign. [ONL Constructs a list of named objects residing in the active workspace. ONUM Vector of 10 numeric characters: 0 through 9. OoM Returns the index of every occurrence of a 1 in a Boolean vector. O0PACK Packs and unpacks data for storage as one record. OPP Controls precision of noninteger numeric output. 0 PW Sets maximum number of characters in output line. 0QCo Quietly copies a workspace. O0QLD Quietly loads a workspace. gQrcC Quietly copies a workspace with certain protection. OR ORELEASE OREP Contains the previous value of a changed variable that is being watched by OWATCH. Releases all locked records in files on one or more channels. Compresses or replicates an array in the same manner as the compression and replication derived functions. ORESET Clears the state indicator. OREWIND Repositions the next record pointer to the first record of a file on one or more channels. ORL Forms link in chain of random numbers used in roll and deal functions. OSF Prompt for evaluated input. OSIGNAL Passes an error up the stack one level to the caller of the operation in error. O0SINK Discards unwanted output; always 1 0. (continued on next page) APL Reference Manual 2-11 VAX APL System Variables and Functions 2.3 System Variables and Functions Reference Table 2-2 (Cont.) System Variables and Functions Name Meaning 0ss Searches the right argument for every occurrence of a character O0STOP Sets or clears stop bits associated with operation lines. 0 TERSE Suppresses display of secondary error messages. OTIMELIMIT Limits time to respond to quote quad and quad del input requests. O0TIMEOUT Equals 1 if time runs out during quote quad or quad del input string specified in the left argument. request; otherwise, equals 0. OTLE Equals 1 when the terminal line editing attribute is on and 0 when line editing is off. OTRACE Sets or clears trace bits associated with operation lines. 0 TRAP Contains an expression to be executed when an error occurs. OTs Current date and time in base 10 format. OrT Determines the type of terminal being used for the current APL session. OUL Process identification number. OVERSION Interpreter and workspace versions. OovI Returns logical vector giving position of valid numbers in OFI of argument. OveC OVR Controls the use of vector processing hardware. Returns a visual representation of a value or user-defined operation whose name is the argument specified. OWA Maximum amount in bytes by which the active workspace can be increased. OWAIT Determines how long a read function waits for control of a shared record. 2-12 OWATCH Watches changes or references to the values of variables. 0XxQ Executes character strings with error handling. APL Reference Manual System Variables and Functions [0 AT Accounting Information [1 A I Accounting Information Type Niladic System Function Form uic/cpu-time /connect-time <« QAT Result Domain Type Integer Rank 1 (vector) Shape i Depth 1 (simple) Description O0AI returns a vector of the user identification number (uic), computer time (cpu-time) used during the current APL session, and time elapsed (connecttime) since the beginning of the current APL session. For the user identification code GROUP, MEMBER, the uic is MEMBER+ (GROUPx2x16). All times are expressed in milliseconds. The fourth element is always 0. For example: JAI 589825 390 1190 0 VMS expresses the GROUP and MEMBER numbers in J4I[1] in octal. The following APL expression returns those numbers: 1018 8 87(0,2x16)THAI[1] 111 Possible Errors Generated None. APL Reference Manual 2-13 System Variables and Functions O0ALPHA Alphabetic Characters 1AL PHA Alphabetic Characters Type Niladic System Function Form "AABCDEFGHIJKLMNOPQRSTUVWXYZ' <« [JALPHA Result Domain Type Character Rank 1 (vector) Shape 27 Depth 1 (simple) Description [0ALPHA is a subset of JAV; it returns a vector of the 27 alphabetic characters that may be used in identifiers. They are A and 4 through Z, or, expressed in terms of QAV: OAVI(0I0+72),97+126] For example: HALPHA AABCDEFGHI JKLMNOPQRSTUVWNXYZ 0I0«0 72 97 ¢ [JPW<«52 0OAV 1+ [JALPHA 98 99 100 110 111 121 122 101 112 102 113 Possible Errors Generated None. 2-14 APL Reference Manual 103 114 104 115 105 116 106 117 107 118 108 119 109 120 System Variables and Functions OALPHAL Lowercase Alphabetics 1AL PHAL Lowercase Alphabetics Type Niladic System Function Form 'abcdefghijklmnopgrstuvwxyz' < [0 ALPHAL Result Domain Type Character Rank 1 (vector) Shape 26 Depth 1 (simple) Description OALPHAL is a subset of JAV; it returns a vector of the 26 lowercase alphabetic characters. They are a through z, or, expressed in terms of JAV: OAV[129+126] For example: OALPHAL abcdefghijkimnopqrstuvwvxyz 0I0«0 129 o [JPW+52 OAV 1 OALPHAL 130 131 132 142 143 153 154 133 144 134 145 135 146 136 147 137 148 138 149 139 150 140 151 141 152 Possible Errors Generated None. APL Reference Manual 2-15 System Variables and Functions 0ALPHAU Underscored Alphabetics UALPHAU Underscored Alphabetics Type Niladic System Function Form Result Domain Type Character Rank 1 (vector) Shape 27 Depth 1 (simple) Description OALPHAU is a subset of JAV; it returns a vector of the 27 underscored alphabetic characters that may be used in identifiers. They are o and 4 through Z, or, expressed in terms of JAV: JAV[160+127] For example: OALPHAU AABCDEFGHIJKLMNOPQRSTUVWXYZ 0I0«0 o [JPW<«52 OAV 1 OALPHAU 160 161 162 163 164 173 174 175 184 185 186 165 176 Possible Errors Generated None. 2-16 APL Reference Manual 166 177 167 178 168 179 169 180 170 181 171 182 172 183 System Variables and Functions 0ARBOUT Arbitrary Output HARBOUT Arbitrary Output Type Monadic System Function (quiet) Form 10 <« JARBOUT B Argument Domain Type Near-integer Shape Vector domain Depth 1 (simple) Value 0 through 255 Result Domain Type Numeric Rank 1 (vector) Shape 0 (empty) Depth 1 (simple) Description OARBOUT allows you to send untranslated output to the terminal (actually, to the default output device). JARBOUT outputs the argument’s items as if they were character codes. One use of JARBOUT 1is to write a file of ASCII characters, where each of the integers corresponds to a character in the ASCII character set. You cannot use the file system function B (see the VAX APL User’s Guide) with JARBOUT to write the file because J4ARB0OUT sends output only to your default output device, usually your terminal. You can use the )0UTPUT system command (see the VAX APL User’s Guide), however, to divert output from your terminal to a file. For example: APL Reference Manual 2-17 System Variables and Functions [0ARBOUT Arbitrary Output JOUTPUT ASCFILE OARBOUT 35 37 38 42 64 94 95 JOUTPUT RCHANGE TO ASCII CHARACTER SET ) PUSH STYPE ASCFILE.AAS OARBOUT 35 37 38 42 64 #%8*@ )OUTPUT APL does not append a <CR><LF> to JARBOUT output. If you use JARBOUT immediately following M or M output, JARBOUT resets the bare output buffer. For details, see the VAX APL User’s Guide. OARBOUT is a quiet function; that is, it does not return a result if it is the leftmost function in a statement. If it is not the leftmost function, DARBOUT returns 1 0 as its result. Possible Errors Generated 9 2-18 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPF) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) 15 DOMAIN ERROR APL Reference Manual System Variables and Functions 0ASCII APL Approximation to the ASCIl Character Set [1ASCII APL Approximation to the ASCIl Character Set Type Niladic system function Form ASCII-characters « QASCII Result Domain Type Character Rank 1 (vector) Shape 128 Depth 1 (simple) Description DASCIT is a subset of 0 AV; it returns a vector of 128 characters that approximates the 7-bit ASCII character set. 14SCII contains the ASCII control characters (0 CTRL) and the lowercase letters (JALPHAL). For example: (32+[ASCII) 3240CTRL = (T1+0ASCII) = 140CTRL DASCII[33] = ' ! a33RD ITEM IS AN EMPTY SPACE aDISPLAY ALL BUT THE CTRL CHARACTERS 2 47 p 9u+33+4[ASCII PUH#SYL8 () *x+,-./0123456789:;<=>?@ABCDEFGHIJKLMNO PQRSTUVWXYZ[\]r_'abcdefghijklmnopqrstuvwxyz{|}~ Possible Errors Generated None. APL Reference Manual 2-19 System Variables and Functions [0ASS Associating Files with Channels [14SS Associating Files with Channels Type Monadic System Function (action form) Form vartable <« 0ASS ' [[channel] filespec [/ fileorganization]' Argument Domain Type Character Shape Vector domain Depth 1 (simple) Result Domain Rank 0 (scalar) Shape 1 0 (scalar) Depth 0 (simple scalar) Type Monadic System Function (query form) Form current-assignments < [1ASS channel Argument Domain 2—-20 Type Near-Integer Shape Vector domain Depth 0 (simple scalar) Value 999 through 999 (but not 0) APL Reference Manual System Variables and Functions [0ASS Associating Files with Channels Result Domain Type Character Rank 1 or 2 Shape Vector or matrix Depth 1 (simple) Parameters variable Is an optional variable used when writing to or reading from this file and channel combination. channel Is an optional integer scalar whose absolute value represents a channel number in the range 1 through 999. If you do not specify a channel number, APL assigns one for you. APL picks the first available channel number, beginning at 12 and counting down to 1; then APL begins at 13 and counts up to 999. filespec Is the VMS file specification associated with the specified channel. If you do not include the file extension, APL uses the default file extension for the file organization qualifier specified. (See Table 2-3.) /fileorganization Identifies the file organization of the file specified by filespec. The possible values of /fileorganization are listed in Table 2—-3. The default value 1s /DA. Table 2-3 File Organization Qualifiers [fileorganization Default File Qualifier Extension Type of File /AS .AAS ASCII sequential; can open for either read or write, or both (when you specify JUPDATE). /AS* .AAS ASCII sequential; file is positioned at end-of-file to allow appending. (continued on next page) APL Reference Manual 2-21 System Variables and Functions 0ASS Associating Files with Channels Table 2-3 (Cont.) File Organization Qualifiers ffileorganization Default File Qualifier Extension /IS LAIS Type of File Internal sequential; can open for either read or write, or both (when you specify /UPDATE). /IS JAIS Internal sequential; file is positioned at end-of-file to allow appending. /DA ATX Direct-access; can do read and write (this is the default). /RF .ARF Relative; can do read and write. /KY CAKY Keyed; can do read and write. current-assignments A vector containing the current value of assignments. Qualifiers /BLOCKSIZE [:blocksize] For input on nondisk devices, it specifies the minimum size memory buffer for APL to make available. The default is 2044 bytes or the current /MAXLEN value, whichever is smaller. In all other cases, it is ignored. In addition, it is always ignored for ASCII sequential files (the blocksize is always 2044 bytes.) /BUFFERCOUNT [:n] Specifies how many I/0O buffers you want allocated to read and write to a file. The acceptable values for n is 0 through 127. The default is 0, which means that the number of allocated buffers will be the same as the current system default value. /CCONTROL [:keyword] Specifies the carriage control attribute for a new, sequential file. (The qualifier 1s 1gnored for nonsequential file organizations.) When you do not specify / CCONTROL, or when you do not specify a keyword, the carriage controls are set according to the file type. 2-22 APL Reference Manual System Variables and Functions 0ASS Associating Files with Channels Valid keywords include the following: Keyword Carriage control Attribute FORTRAN The first character of each record Default will contain the appropriate carriage control information LIST Implied carriage control (single Default for /45 files. spacing between records) NONE No carriage control information (any Default for /IS files. carriage control information will be placed in individual records) /DEFAULTFILE :defaultspec Specifies a default to be applied to any missing components of the filespec. The defaultspec must be specified. APL first looks at the file specification named in the argument. If any components are missing, APL looks for a default in the /DEFAULTFILE qualifier. If you omit the defaultspec, APL specifies the appropriate APL file type. /DISPOSE [:keyword] Specifies whether the file is temporary or permanent. /DISPOSE:KEEP, the default, means the file is permanent. /DISPOSE :DELETE means the file will be deleted when it is closed. Other keywords send the file to a queue when the file is closed in accordance with the following: Keyword Definition PRINT Sends the file to SYS$PRINT. The file is not deleted. PRINTDELETE Sends the file to SYS$PRINT. The file is deleted when job is finished. SUBMIT SUBMITDELETE Sends the file to SYS$BATCH. The file is not deleted. Sends the file to SYS3BATCH The file is deleted when job is finished. Note that you must have VMS delete privileges to use any of the delete keywords. If you do not have delete privileges, APL signals FILE PROTECTION VIOLATION when the file closes. As a result, APL closes the file, but does not delete it. If you receive the file protection violation error when you press Ctrl/Z, you can exit from APL by pressing Ctrl/Z a second time. APL Reference Manual 2-23 System Variables and Functions [0ASS Associating Files with Channels N JEFN Associates an event flag with a channel number. For more information on event flags see JEFR,0EFS, and JEFC. /MAXLEN [:length]] Specifies the maximum record length (in bytes) for a new file. It is ignored for existing files. The default length is the value of the DML system variable. The maximum record length value is also used as the maximum segment size for segmented records on output. The maximum values are as follows: o 32232 (for prolog 1 or 2) e 32224 for /DA and / KY o 32767 for / IS files o 2048 for / AS files o 32253 for / RF files files (prolog 3) When you write to an /A4S file in quad output mode, the maximum record length is determined by the current setting of 0 P¥. In all other output modes for all file types, the maximum record length is determined by /MAXLEN. /MBX Indicates that an assigned file name actually refers to a mailbox. /NFS A non-file-structured qualifier that tells APL to read from the device without trying to interpret the data. In other words, to return the data on the device as a string of bits. This qualifier is useful when reading foreign devices. /NOSHARFE /NOWRITERS Allows you to write to a shareable file, but prevents other users from doing so. / OPEN [[:keyword]] Specifies that you want APL to open or create a file when the channel is assigned. Using the /0PEN qualifier allows you to detect errors related to the openning or creating of a file at the time of assignment instead of at the time of the first I/O operation. Values for keyword include NEW, used to create a new file, and OLD, used to open an existing file. 2-24 APL Reference Manual System Variables and Functions 0ASS Associating Files with Channels /PROTECTION [[:protection] Specifies the protection to be associated with a new file. It is ignored for existing files. /READONLY [[:NOLOC’KS] Allows you to read the file but not write to it. The NOLOCKS argument specifies that records should be read even if they have been locked by another user. Using /READONLY : NOLOCKS avoids waiting for a locked record to become unlocked. However, note that when OWAIT is set to any value but the default (wait indefinitely), it overrides the NOLOCKS argument. /RECORDTYPE [:keyword] Specifies the record format used by VAX RMS for each record of the file. The default is variable length records. APL ignores this qualifier if the file already exists or if the file type is /D4, /RF, or /KY. You can use the following keywords as values to /RECORDTYPE. Keyword Record Format VARIABLE Variable length FIXED Fixed length STREAM | - Stream format STREAMCR Stream format delimited with <CR>s STREAMLF Stream format delimited with <LF>s Note that when you use fixed-length records, the record size is defined with the /MAXLEN qualifier. The default value is 1 DML. Because APL adds a prefix containing system information to each record of a /IS file, you may want to write data out to these files in pure data mode when using fixed-length records. Otherwise you need to calculate the size of the prefixed information before writing the data. /SHARE Specifies that several users may access the file simultaneously. All users sharing the file must use the /SHARE qualifier when associating a given file with a channel. Sequential file users are exempted from this rule. /SIGNAL Specifies that APL signal the end-of-file indicator when you perform a read operation on a nonexistent record. For /4S5 and /IS files the indicator is EOF ENCOUNTERED. For /DA, /RF, and /KY files the indicator is EOF ENCOUNTERED for a sequential read and RECORD NOT FOUND for a random read. If you do not APL Reference Manual 2-25 System Variables and Functions 0 ASS Associating Files with Channels specify /SIGNAL, APL returns an empty numeric matrix with the shape of 0 75 as the end-of-file indicator. | /UPDATE Specifies that you want both read and write access to a sequential file and that APL should change the rules slightly for sharing the file. /UPDATE is relevant for /45 and /IS files only and is ignored for all other file types. When you use /UPDATE you should consider how you want APL to deal with locked records. See /READONLY :NOLOCKS and ORELEASE for more information. /WRITEONLY Allows you to write to a file, but not read it. A new file is created when APL writes to the file. If the assignment specifies /OPEN:0LD, a new file is not created. However, APL can write to an existing file only if the file is empty, or if /1.5« was specified for appending. Subsequent assignments can gain read access to the file. Description The action form of 0 ASS associates files with channels. 0455 does not create or open a file (unless you use the /0PEN qualifier) or perform any input or output. It establishes a connection between a file specification (and related file information) and a specified channel. When you perform I/O functions, you must refer to channel numbers rather than to file specifications. The APL functions that perform file I/O (8 and B) require channel numbers—not file specifications—as part of their arguments. So, to read or write a file, you must first associate it with a channel. The query form of JASS returns the current value of assignments made previously with the action form. The result of the query form is a character vector or matrix that identifies the parameters you associated with the channels specified. Note that the action and query forms of 1455 are described in in the VAX APL User’s Guide, along with other file I/O information. 2-26 APL Reference Manual System Variables and Functions 0ASS Associating Files with Channels Possible Errors Generated Action Form 15 DOMAIN ERROR (ERROR PARSING ARGUMENT TO CCONTROL) 15 DOMAIN ERROR (REDUNDANT KEYWORD OR QUALIFIER) 15 DOMAIN ERROR (CONFLICTING QUALIFIERS SPECIFIED) 33 I0 ERROR (INVALID RECORD SIZFE) 33 I0 ERROR (FILE CURRENTLY LOCKED BY ANOTHER USER) 68 END OF FILE ENCOUNTERED 69 RECORD NOT FOUND 74 BLOCK TOO BIG Query Form 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-27 System Variables and Functions O0AUS Automatic Save of the Workspace L] AUS Automatic Save of the Workspace Type System Variable Form [NAUS « near-integer-singleton integer-scalar < JAUS Value Domain Type Near-Integer Shape Singleton Depth 0 or 1 (simple) Value 0,1,0r?2 Default 0 Result Domain Type Integer Rank 0 #(scalar) Shape 1 0 (scalar) Depth 0 #(simple scalar) Description OAUS controls a feature that allows you to save the active workspace automatically at periodic intervals. Workspace backup is often critical when you are performing extensive operation editing and debugging, or when you are using quad input to type a large table of values. You could back up your work by periodically issuing a ) SAVE command. However, if you set JAUS to 1 or 2, APL automatically saves the workspace every time you exit from function-definition mode, or every time quad input is requested from the terminal. Then, if the system crashes, you probably will have to reenter only a small amount of input. In addition, when OAUS 18 set to 2, the ) OFF command acts like the ) CONTINUE command (see Chapter 3). 2-28 APL Reference Manual System Variables and Functions 0AUS Automatic Save of the Workspace You can set JAUS to 0, 1, or 2; the default is 0. When 0A4US equals 0O, the automatic save feature is not activated. When JAUS equals 1 or 2, the feature is activated and the workspace is saved in your default directory as follows: Value of J4US File Name of Saved Workspace 1 APLxxxxxxxx.TMP, where xxxxxxxx is the value of OUL, represented in hexadecimal. (Note that 0 UL is an integer that represents your process identification number.) CONTINUF.APL 2 The name of the file saved when JAUS is 1 can be represented as the following APL expression: "APL', ('0123456789ABCDEF' [(JI0+(8p16)TUUL]),"' . TMP' The value of 14US is saved when you save the active workspace and can be localized in user-defined operations. When 04US is 2, APL keeps all versions of CONTINUE .APL, even after the APL session ends. When 0AUS is 1, APL deletes all old versions of APLxxxxxxxx.TMP each time a new version is created during the same APL session. When you successfully execute a ) SAVE, )OFF, or )CONTINUE system command, APL deletes all APLxxxxxxxx.TMP files created during the session, including the one most recently created. Note, however, that APL does not delete APLxxxxxxxx.TMP files created in past APL sessions, unless such an APLxxxxxxxx.TMP file has exactly the same name as a newly created APLxxxxxxxx.TMP file. For example: OAUS<«1 QUL 88 '0123456789ABCDEF' [[110+(8016)TOUL] e [2] v aAPL WRITES YLIB .TMP FILE %, TMP Directory APLGRP: [USER] APL00000058.TMP; 1 APL Reference Manual 2-29 System Variables and Functions [JAUS Automatic Save of the Workspace Total of 1 file. ASTART NEW APL SESSION WITH NEW (UL 040US+«1 OuL 92 '0123456789ABCDEF ' [0I0+(8p16)TOUL] 0000005D VG ¥ [21 8APL Y)LIB WRITES .TMP FILE %.TMP Directory APLGRP:[USER] APL0O0000058.TMP;1 APL0000005D,TMP;1 Total of 2 files. )SAVE ABC SAVED THURSDAY 15-NOV-1990 14:33:21.32 6 BLKS YLIB *.TMP Directory APLGRP:[USER] APL00000058.TMP;1 Total of 1 file. aAPL DELETED NEW o .TMP FILE BUT NOT .TMP FILE CREATED IN FARLIER SESSION Note 0UL has a value that changes each time you log in to VMS, and the names of the 4PLxxxxxxxx .TMP files are probably different if they are created during different VMS sessions. The names are the same if the files are created during the same VMS session, even if they are not created in the same APL session. To recover the JAUS file after a system crash, execute APL and issue a )LIB command to verify that the temporary file exists. Then use ) L0OAD to load the temporary file. APL prints the ) LOAD message. The name of the active workspace is now the name that the workspace had before the backup was performed, not the name of the temporary file: 2-30 APL Reference Manual System Variables and Functions 0AUS Automatic Save of the Workspace )LIB *.TMP Directory APLGRP:[USER] APL0000005C.TMP; 1 Total of 1 file, YLOAD APL0000005C.TMP SAVED THURSDAY 15-NOV-1990 12:30:05.04 53 BLKSx WAS ABC YWSID ABC Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (INCORRECT TYPF) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual 2-31 System Variables and Functions 1AV Atomic Vector 14V Atomic Vector Type Niladic System Function Form all-known-chars < JAV Result Domain Type Character Rank 1 (vector) Shape 256 Depth 1 (simple) Description AV contains a vector of the 256 characters known to APL. Table 2—4 shows the characters and their positions in the vector. The positions are based on an index origin of 0. The index of a character is the sum of its row and column numbers. Symbols with indexes 213 through 255 have no meaning to the APL user. They are used only by the APL implementation and may not be used for input. On output, they print as squish quads ([ ). If you include any of these characters in a character array, the results are unpredictable. The following is useful to display the APL characters in AV order. 6 32p032+[AV T)<s=>]vaz:,+./0123U56789([;x:\ “olnle VAiro'[|TOo*?p[~Yyuwotcerr>OABCDEFGHIJKLMNOPQRSTUVWXYZ{-}$ ‘abcdefghiljkimnopqrstuvwxyz@"#%.8& AABCDEFGHIJKLMNOPQRSTUVWXYZ!p1e® BEBNRAY¥»reoRes/5co=A00000000000 2-32 APL Reference Manual System Variables and Functions AV Atomic Vector Table 2-4 Elements of JAV(0I0<«0) 96 128 160 192 224 - o ‘ A H 0 a A a A 3 0 ) I B b B B 0 ETX < n C C c [ 0 EOT < L D d D 5 ENQ - ¢ E e E A i 6 ACK > _ F f E y 0 7 BEL ] v G g G ¥ 0 8 BS v A H A H » I 9 HT A 1 I i I ~ i 0 dec 0 32 64 0 NUL SP 1 SOH - 2 STX 3 4 I 0 J Ji J ® + ! K k K o) I , 0 L 1 L § I + | M m M o 0 n N - 0 10 LF # 11 VT 12 FF 13 CR . T N SI / 0 9, o) 0 # [ DLE 0 * P p P X I DC1 1 ? Q q Q = 1 I 14 SO 15 16 17 18 DC2 2 P R r R > 19 DC3 3 [ S s S = 0 20 DC4 4 ~ T t T A I 21 NAK 5 ¥ U u U 0 I 0 I 22 SYN 6 u 14 v )4 W W W 0 0 I I I I 23 ETB 7 w 24 CAN 8 =) X X X 25 EM 9 + Y y Y (continued on next page) APL Reference Manual 2-33 System Variables and Functions AV Atomic Vector Table 2—-4 (Cont.) dec Elements of 04V ([0I10<«0) 0 32 64 96 128 160 192 224 Z z Z 0 I 26 SUB ( c 27 ESC C « { @ ! 1 [ 28 FS ; - ~ " A 0 I 29 GS x > } # T [ I > $ % & 0 I - DEL 8 ¥ 0 0 30 RS 31 US \ The index of a character in 14V is the sum of its row and column numbers. Possible Errors Generated None. 2-34 APL Reference Manual System Variables and Functions 0 B0OX Forming Character Matrices and Vectors [] BOX Forming Character Matrices and Vectors Type Ambivalent System Function Form boxed-text « [[delimiter]] DBOX text Left Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Shape Matrix domain Depth 0 or 1 (simple) Result Domain Rank 1 or 2 Shape Matrix or Vector Depth 1 (simple) Description 0BOX produces a character matrix from a character vector or vice versa. When the right argument is in the vector domain, JB0X forms a matrix. When the right argument is a matrix, JB0X forms a vector. If the right argument 1s an empty vector, the result is an empty character matrix with the shape 0 0. If the right argument is an empty matrix, the result is a vector containing a number of delimiters equal to the number of rows in the right argument matrix. When producing a matrix, APL uses a delimiter to determine where to form rows. The left argument optionally specifies a delimiting string. The default delimiter is <CR> <LF> . The number of columns is equal to the longest string APL Reference Manual 2-35 System Variables and Functions [0 B0X Forming Character Matrices and Vectors contained between any pair of delimiters. Shorter strings are padded with ‘ trailing blanks. When producing a vector with the monadic form, APL removes any trailing blanks and inserts the <CR> <LF> delimiter at the end of each row. When producing a vector with the dyadic form, APL does not remove trailing blanks from the rows of the matrix argument. It does insert the specified delimiter at the end of each row. 0BOX is particularly useful for forming a matrix from a vector consisting of lines of data delimited by <CR> <LF> pairs. 1B0X removes the <CR> <LF> and makes each line of data that was between <CR> <LF> s (or between a <CR> <LF> and the end or beginning of the vector) a row in the result matrix. Thus, the result matrix and right argument vector appear the same when displayed by APL. Examples: B « '"FIRST LINK SECOND LINE ......... IS LONGER LINE FOUR' pB 70 (34 12 11 48 # JCTRL 49 55 1 B)/1pB AGENERATE INDEX OF <CR><LF>S 56 oJ«JBOX B FIRST LINE SECOND LINE ......... IS LONGER LINE FOUR 4 35 aNO o«BOX (0BOX B) FIRST LINE SECOND LINE ......... IS LONGER LINE FOUR 65 o«(BOX '4' A 11 2—-36 APL Reference Manual <CR><LF> ADDED TO LAST ROW System Variables and Functions 0 B0X Forming Character Matrices and Vectors ATRAILING <CR><LF> IGNORED o0«0BOX 'A', OCTRL [14 11] A 11 p«Y<«'," OBOX 'ABC,DE,FGHI' ABC DE FGHI 3 4 p«"!" [OBOX Y ABC!DE!FGHI 11 o(«'AB'" [0BOX 'XXXABYYYABZZI' p«'A" 0BOX 1 1 1 p 'B' p«'A" 0BOX 1 1 1 p 'A' XXX YYy 777 3 3 B 11 (APL outputs a blank line.) 10 Possible Errors Generated 9 RANK ERROR (NOT MATRIX DOMAIN) 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPE) APL Reference Manual 2-37 System Variables and Functions [0BREAK Suspending Execution L[| BREAK Suspending Execution Type Monadic System Function Form [0BREAK apl-expression Argument Domain Type Any Shape Any Depth 0 or 1 (simple) Result Domain Type None Shape None Depth None Description [0 BREAKsuspends execution of the operation in which it is contained and returns you to immediate mode. It takes any APL object as an argument and prints the value of that argument before breaking to the terminal. However, the function itself has no explicit result. To return to execution after a break, you can either branch to a specific line number (- 3), or you can use the system function JLC. Use of 0L would return you to the breakpoint, that is, to the line where the 0BREAK executes. To resume at the line after the breakpoint, specify 2-38 APL Reference Manual 0LC+1. For example: System Variables and Functions [0BREAK Suspending Execution VFUNC [1] [2] [3] (4] 'FIRST LINE' [OBREAK 'BREAK AT LINE 2' "RESUME AT LINE 3 Vv FUNC FIRST LINE BREAK AT LINE 2 +~0LC+1 RESUME AT LINE 3 It is illegal to use 0BREAK in immediate mode or as part of the argument to the execute (¢ )function. Possible Errors Generated 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) APL Reference Manual 2-39 System Variables and Functions 0 CHANS Returning Channel Numbers [1 CHAN S Returning Channel Numbers Type Niladic System Function (query) Form current-channels < [1CHANS Result Domain Type Integer Rank 1 Shape Vector Depth 1 (simple) Description 0CHANS displays all of the channel numbers currently associated with file specifications. The result is a vector. In the following example, channels 1 and 5 are each associated with a file: OASS '1 PLAN/AS' o [ASS '5 ANALYSIS/AS' 1 5 OCHANS 15 JCLEAR CLEAR WS OCHANS (APL outputs a blank line) If no channels are assigned, 0 CHANS returns an empty numeric vector. OCHANS is also described in the VAX APL User’s Guide along with other file I/0 information. Possible Errors Generated None. 2-40 APL Reference Manual System Variables and Functions 0 CHS Returning File Organization and Open Status [1 CHS Returning File Organization and Open Status Type Monadic System Function Form file-org[ status < O CHS chans Argument Domain Type Near-integer Shape Vector domain Range ~999 to 999 (but not 0) Depth 0 or 1 (simple) Result Domain Type Integer Rank 1 or 2 Shape Vector or matrix Depth 1 (simple) Description [0 CHS returns the file organization and status of the files associated with the specified channels. The absolute value of chans represents the channels associated with the files you want information on. The following table gives the possible codes resulting from [0 CHS. APL Reference Manual 2-41 System Variables and Functions [0 CHS Returning File Organization and Open Status First Element Second Element Code File Organization Code Open Status 0 Not applicable 0 Channel free 1 /AS 1 Assigned but not open 2 /IS 2 Open for output 3 Not applicable 3 Open for input 4 /DA 4 Open for input and output 5 Not applicable 6 Not applicable 7 /RF 8 /KY If the argument is a singleton, 0 CHS returns a two-item vector: the first item 1dentifies the file’s organization, and the second item identifies the file’s open status. For example: 13 OCHS 1 This means that the file associated with channel 1 is an ASCII sequential file that is assigned and open for input. If the argument is a vector of n items, the result is an array of shape n by 2. For example, the following expression returns a 3-by-2 array: N N F oW O«FILS«[CHS13 pFILS O CHS returns a result of 0 2p 0 if its argument is empty. [1CHS is also described in the VAX APL User’s Guide along with other file I/O information. Possible Errors Generated 9 15 2-42 RANK FERROR (NOT VECTOR DOMAIN) DOMAIN FRROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) APL Reference Manual System Variables and Functions 0 CHS Returning File Organization and Open Status 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual 2-43 System Variables and Functions 0CIQ and [JCoQ Packing and Unpacking Data [1 CI& and[] COQ Packing and Unpacking Data Type Dyadic System Function Form unpacked-data « packed-data 0CIQ header [typel] Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Any Rank Any Shape Any Depth Any Type Dyadic System Function Form packed-data < data 0C0Q header [typell 2-44 APL Reference Manual System Variables and Functions 0CIQ and [JC0 Packing and Unpacking Data Left Argument Domain Type Any Shape Any Depth Any Right Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Integer Rank 1 Shape Vector Depth 1 (simple) Parameters unpacked-data The variable associated with the unpacked data; it must be in the format of the result of 0 C0Q, with or without a header. It may be empty only if header is O. packed-data Specifies the variable associated with the packed data. data Any array you want to pack into an integer vector. header 0, 2, or 4. For 0CIQ, if a header exists, it is 2; if no header exists, it is 0. If you specify 0 and a header does exist, the header is treated as part of the data to be unpacked. With [1C0g, use 0 if you do not want a header; 2 if you do want a header; and 4 if you want only a header. type If specified, it indicates whether the data is to be converted to another data type before being packed. The possible values are listed in Table 2-5. The APL Reference Manual 2-45 System Variables and Functions 0CIQ and [1C0Q Packing and Unpacking Data possible effects of such a conversion are summarized in the VAX APL User’s Guide. Omitting type has the same effect as using type 0. Description 0CIQ and [JCcoq allow you to accumulate data of different types into variables. You can then catenate the variables for storage as one logical record. 0coq takes an argument of any data type and packs it into an integer vector by treating it as if it were a stream of bits. For example, you can put ASCII characters in one variable and internal APL characters in another variable, then catenate them, and write them to a file. Later, you can read the file and use [JCIQ to change the variables from integer vectors back into ASCII and APL characters. The value of 0 C0Q i1s the packed data or, if the header parameter equals 4, the header information associated with the left argument. The value of 0CIQ is the unpacked data. 0CIQ converts the packed data to the internal data type specified by the corresponding external data type identified by the type parameter (the possible effects of such a conversion are summarized in the VAX APL User’s Guide.) Table 2-5 Type Parameter Values O -, N O w Convert to 8-bit ASCII characters Convert to 8-bit unsigned numeric bytes Convert to G_floating double-precision floating-point Convert to H_floating floating-point Convert to 16-bit integer Convert to 8-bit Digital Multinational Characters [ O Convert to 8-bit 2AV characters N Convert to D_floating double-precision floating-point 0O Convert to F_floating single-precision floating-point w0 Convert to 1-bit Boolean [N (&) Convert to 32-bit integer |— No conversion; use type of "data" F External Data Type U Type (continued on next page) 2-46 APL Reference Manual System Variables and Functions 0CIQ and [0C0Q Packing and Unpacking Data Table 2-5 (Cont.) Type Parameter Values Type External Data Type 12 Convert to 8-bit [ 13 Convert to 8-bit 04V characters in KEY-paired APL 14 Convert to 8-bit 0 AV characters in BIT-paired APL 15 Convert to 8-bit 04V characters in APL COMPOSITE 4V characters in TTY mnemonics The header generated by [01Cc0qQ has the following format: length type rank (pdata)[1] (pdata)[2] (pdata)[ rank] NU-2234A-RA Each large box represents a longword as described in the following list: * [ength is the length of the integer vector result of 0C0Q 2 * type is one of the external types in Table 2-5 * rank is the rank of the data that was packed by 0c0qQ The next n (n = rank) boxes contain the shape of the data that was packed. APL Reference Manual 2-47 System Variables and Functions 0CIqQ and [JC0@ Packing and Unpacking Data For example: A+15 2 P<4 [JC0Q P 911512345 o5 o oW o e e ;—» 0 Up1 B+3 10 10 + BOOL 1010101 CIQ 2 N w o O = | O HmDoMQ: O coold ="' () w 10 e — o 12 1365 L[«(32p2)T71365 O N N o «B [1C0Q 2 The first example uses [01¢0Q to pack the vector 1 5. The value of P shows that when 1 5 was packed, the packed data had length 9 (including the header), type 1 (integer), rank 1, and shape 5. In the second example, the Boolean matrix B is packed into @. The value of @ indicates that the packed data with its header has length 6, type 2 (Boolean), rank 2, and shape 3 4. Note that when @[6] is converted to Boolean, the value is the same as that of ¢ , B (the Boolean data values are stored right to left). Finally, 0 c1Q was used to unpack the data, to retrieve the data and translate it back to the original data. In the following example, the functions PACK and UNPACK use 1C0Q and 0 CIQ to pack and unpack values of different types: 2-48 APL Reference Manual System Variables and Functions 0CIQ and [ C0Q Packing and Unpacking Data VP«PACK LIST;I [1] RPACK [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] AINTO A SINGLE P<10 [12] I+1 [13] [14] [15] [16] [17] USES [JC0Q TO PACK A SET OF VARIABLE. THE aDIFFERENT TYPES OR SHAPES. VALUES VALUES THUS, CAN BE YOU CAN aUSE PACK WHEN CATENATE WON'T WORK. aLIST IS A RCONTAINS nlS CHARACTER MATRIX, THE NAME OF A FACH ROW OF WHICH VARIABLE WHOSE VALUE TO BE PACKED. aP IS THE RESULTANT PACKED VALUE: IT IS AN RINTEGER ARRAY. A TEST:>(I>14p0LIST)/0 P<P, (e¢LIST[I;])0C0Q 2 I«I+1 +TEST V VP UNPACK LIST;DATA:I;J;LEN;ENTRY [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] aUNPACK USES [CIQ TO UNPACK A aBY PACK INTO A SET OF aP IS THE PACKED aLIST IS A VARIABLE CREATED VARIABLE NAMES, VALUE, CREATED BY PACK. CHARACTER MATRIX, EACH ROW OF WHICH aCONTAINS THE NAME OF A VARIABLE TO RECEIVE ONE anOF THE PACKED UNPACKED VALUES. AARE STORED INTO SUCCESSIVE VALUES FROM P VARIABLES IN LIST. DATA<P I<pDATA J«1 TEST:»(I<0)/0 +(J>14pLIST)/0 LEN«DATA[1] ENTRY<«DATA ¢ LIST[J:], DATA<LEN + [LEN] "«ENTRY 0OCIQ 2' DATA JJ+1 I<I-LEN +>TEST V ADEFINE SOME NUMERIC VARIABLES: A<l A4« 1 1 AAA« 1 1 1 aDEFINE SOME CHARACTER VARIABLES: B«'B" BB<'BB' APL Reference Manual 2-49 System Variables and Functions 0CIQ and [JC0Q Packing and Unpacking Data aMAKE A LIST OF INPUT VARIABLE NAMES: L1+«5 3p 'A AA AAAB BB ' L1 AA AAA BB aPACK THESE VARIABLES INTO ONE ITEM ACATENATE WON'T WORK P«PACK L1 P 4 2 0152123452137 4500985512 25186 AMAKE A LIST OF OUTPUT VARIABLE NAMES: L2+5 3p'X XX XXXY 1YY ! L2 XX XXX aUNPACK THE PREVIOUS DATA INTO NEW VARIABLES: P UNPACK L2 aTHE RESTORED DATA IS THE SAME AS THE n DATA THAT WAS PACKED. X=4 XX=A4 XXX=AAA 1 Y=B YY=BB Possible Errors Generated For(JCcIrq: 9 2-50 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (ARGUMENT MUST BE 1 OR 2 ELEMENTS) 10 LENGTH ERROR (DATA TYPEF MISSING) 10 LENGTH ERROR (DATA TYPF EXCEEDS DATA LENGTH) 15 DOMAIN ERROR APL Reference Manual System Variables and Functions 0cIQ and [1c0q Packing and Unpacking Data 15 DOMAIN FRROR (DATA TYPE MUST BE UNSPECIFIED OR ZERO) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN EFRROR (INCORRECT TYPE) 15 DOMAIN ERROR (INVALID CIQ HEADER) 15 DOMAIN FRROR (INVALID EXTERNAL DATA TYPE) 15 DOMAIN ERROR (INVALID HEADER TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) For 0C0Q: 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (ARGUMENT MUST BE 1 OR 2 ELEMENTS) 15 DOMAIN ERROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN ERROR (INVALID HEADER TYPE) 15 DOMAIN ERROR (INVALID EXTERNAL DATA TYPFE) 15 DOMAIN FRROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual 2-51 System Variables and Functions [1CLS Closing Files L] CL S Closing Files Type Monadic System Function (quiet) Form 10 « [JCLS chans Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value ~ 999 through 999 (but not 0) Result Domain Type Numeric Rank 1 (vector) Shape 0 (empty) Depth 1 (simple) Description [0CLS closes one or more files without deassigning their corresponding channels. The absolute values of chans represent the channels associated with the files you want to close. 0CLS is useful when you want to return to the beginning of a sequential file. (You can also use the OREWIND system function, which does not close files.) After you close a channel, a read function opens the file and reads the first record, and a write function creates a new version of the file (except for /D4, /RF, and /KY files, where a new file is created only if no version currently exists). With 0 CLS, there is no need to reassign the file to the channel. The following line closes the file associated with channel 2: OCLS 2 Any unassigned channels in the argument are ignored. 2-52 APL Reference Manual System Variables and Functions 0cCLS Closing Files 0CLS is a quiet function; it does not return a result if it is the leftmost function in a statement. When 0CLS is not the leftmost function, it returns an empty numeric vector. If its argument is empty, 0 CLS has no effect. Note that when you use [JCLS, you activate whichever parameter has been set for the /DISPOSE qualifier on 04SS. For example, if you specify /DISPOSE :DELETE, APL deletes the file when you specify the [0 CLS function. APL automatically closes and deassigns all open files when you press Ctrl/Z or execute a )LOAD, )CLEAR, YOFF, or )CONTINUE system command (the )MON and ) PUSH system commands do not have this effect). OcLsS is described in the VAX APL User’s Guide along with other file I/0 information. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-53 System Variables and Functions [1 CR Obtaining a Canonical Representation | CR Obtaining a Canonical Representation Type Monadic System Function Form canonical-rep < [1CR operation-name Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Character Rank 2 Shape Matrix Depth 1 (simple) Implicit Arguments 00 PP (controls precision of numeric constants) Description 0 CR provides a canonical representation of a user-defined operation, which enables you to treat the operation as data. A canonical representation is a character matrix with rows that are the original lines of the operation definition, but are reformatted so that they are the same length. The canonical representation consists of exactly what you typed when you defined the operation, minus the beginning and ending v s, plus blanks added to the end of lines to make their lengths the same as that of the longest line of the operation. Line numbers and brackets are removed from the definition. White space at the beginning (but not at the end) of a line is preserved. Lines that contain labels are not shifted. 2-54 APL Reference Manual System Variables and Functions [0 CR Obtaining a Canonical Representation The argument of the [0 CR system function is a character array representing the name of the operation. The shape of the argument must be in the vector domain. If the argument is empty or does not represent the name of an existing unlocked operation, the resulting character matrix is an empty matrix, with the shape 0 0. (APL considers primitive system functions and external functions as locked.) The display of numeric constants in an operation definition is 0 PP-dependent. [0 cR does not work on operands to user-defined operators that contain derived functions. Use 0 VR instead. For example: VMEANX<NSUBJ MEAN X [1] aSUM VECTOR X [2] [3] SUMX<+/X MEANX<SUMX+NSUBJ v [4] 0 « SHOWCRFX <« [CRK 'MEAN' MEANX«NSUBJ MEAN X aSUM VECTOR X SUMX«++/X MEANX<SUMX+NSUBJ pSHOWNCRFX 4 21 X< 86 39542174 10 MEAN X 4.9 The OFX system function is the inverse of 0 CR. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual 2-55 System Variables and Functions 0 CT Comparison Tolerance [] CT Comparison Tolerance Type System Variable Form OCT <« tolerance-value floating-scalar < OCT Value Domain Type Non-negative numeric Shape Singleton Depth 0 or 1 (simple) Value 0 to 2.328E 10 Default 1E~ 15 Result Domain Type Numeric Rank 0 Shape 1 0 (scalar) Depth 0 (simple) Description 0 CT specifies the degree of tolerance applied when two numbers are compared for equality. If the difference between two numbers is less than or equal to the value of J CT times the larger number, the numbers are considered equal. The value of J CT affects the following primitive functions: Function € 2-56 Function Name Set membership Function I Function Name Residue 1 Index of ) Ceiling > Greater than L Floor APL Reference Manual System Variables and Functions 0 CcT Comparison Tolerance Function Function Name Function Function Name > Greater than or equal to U Set union and unique = Equal to N Set intersection 2 Not equal to ~ Without < Less than or equal to c Subset < Less than > Contains = Match B Matrix inverse and divide The value of 0 CT is saved when you save the active workspace and can be localized in user-defined operations. For example: 0cT 1E 15 1 = 1.00000000009 0 E NCT«110 1 = 1,00000000009 1 The following function is the APL metafunction. It describes an exact definition of how 1 CT is applied. Vz<A DFEQ B ;UCT;T aA=B WITHIN BXCT [1] [2] [0CT<«0 T+<0<(xA)B [3] A<AXT [4] B<BxT [5] Z«(|A-B)<OCTx(|A)T|B [6] 7<ZxT ¥ Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN FRROR (PARAMETER OUT OF RANGE) APL Reference Manual 2-57 System Variables and Functions [0 CTRL Control Characters [1] CTRL Control Characters Type Niladic System Function Form control-chars < [ CTRL Result Domain Type Character Rank 1 (vector) Shape 33 Depth 1 (simple) Description O CTRL 1is a subset of J4V. It returns a vector of the 32 ASCII control characters and Delete, or, expressed in terms of JAV: OAV[132,0I0+127] The control characters are listed in the table below. Note that for any formatting control character, the internal code that appears in 0CTRL is the same as the internal code used by APL for that character. For example: 0I0<«0 97 2-58 98 99 13 o 10 [UAV 1 32 32 "ABCDEF" 32 32 32 100 101 102 Index Name Description Octal Value Hex Value 0 NUL Null 000 00 1 SOH Start Of Heading 001 01 2 STX Start of TeXt 002 02 3 ETX End of TeXt 003 03 4 EOT End Of Transmission 004 04 5 ENQ ENQiry 005 05 APL Reference Manual System Variables and Functions 0 CTRL Control Characters Index Name Description Octal Value Hex Value 6 ACK ACKnowledge 006 06 7 BEL BELI 007 07 8 BS BackSpace 010 08 9 HT Horizontal Tabulation 011 09 10 LF <LF> 012 0A 11 VT Vertical Tabulation 013 OB 12 FF Form Feed 014 0C 13 CR <CR> 015 0D 14 SO Shift Out 016 OE 15 SI Shift In 017 OF 16 DLE Data Line Escape 020 10 17 DC1 Device Control 1 021 11 18 DC2 Device Control 2 022 12 19 DC3 Device Control 3 023 13 20 DCA4 Device Control 4 024 14 21 NAK Negative AcKnowledge 024 15 22 SYN SYNchronous Idle 026 16 23 ETB End-of-Transmission Block 027 17 24 CAN CANcel 030 18 25 EM End of Medium 031 19 26 SUB SUBstitute 032 1A 27 ESC ESCape 033 1B 28 FS File Separator 034 1C 29 GS Group Separator 035 1D 30 RS Record Separator 036 1E 31 US Unit Separator 037 1F 32 DEL DELete 177 7F Possible Errors Generated None. APL Reference Manual 2-59 System Variables and Functions [0DAS Deassigning Files (0DAS DeaSsigning Files Type Monadic System Function (quiet) Form 1 0 « ODAS chans Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value - 7999 through 999 (but not 0) Result Domain Type Numeric Rank 1 (vector) Shape 0 (empty) Depth 1 (simple) Description [1DAS dissociates or deassigns file specifications from channel numbers. The absolute value of chans represents the channels associated with the files you want to deassign. If any files associated with the specified channel numbers have not been closed (by 0 CLS), 0DAS closes them, and then deassigns them. In general, 0 DAS reverses the operations performed by the 2ASS system function. The following line deassigns the files associated with channels 1, 3, and 5: ODAS 1 3 5 Any unassigned channels in the argument are ignored. O0DAS is described in the VAX APL User’s Guide along with other file I/O information. 2-60 APL Reference Manual System Variables and Functions [0 DAS Deassigning Files Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGFE) APL Reference Manual 2-61 System Variables and Functions [0 D¢ Display Control [1 D C Display Control Type System Variable Form 0DC « display-area box-characters current-setting < 0 DC Value Domain Type Enclosed, heterogeneous (see below) Shape 2 (vector) Depth 2 or 3 (enclosed) Default (T1102) " Result Domain Type Enclosed, heterogeneous Rank 1 Shape 2 (vector) Depth 2 or 3 (enclosed) Description 0DcC specifies how APL displays enclosed arrays. You can set 0DC to draw boxes around enclosed items of an array, and the resulting display makes the nested structure of the array clearer. You can also increase the blank space that APL uses to surround an enclosed item. The value you assign to 0DC is a two-item enclosed vector. The first item of the (D¢ value is a simple numeric vector of length 4. Data elements 1 and 2 of this item specify where an item is displayed when its display area is larger than the structure of the item itself. The first data element controls the vertical placement; the item can be at the top, center, or bottom of the display area. The second data element controls the horizontal placement; the item can be at the left, center, or right of the display area. The following table describes the meaning of the values you can specify for these two data elements: 2-62 APL Reference Manual System Variables and Functions 0 DC Display Control Positioning Items in Display Areas First Element Location Second Element Location 1 Top 1 Left 0 Center 0 Center 1 Bottom 1 Right Data elements 3 and 4 of the first item of the 0DC value allow you to change the size of the display areas. The third data element controls the vertical space between rows of items; the integer you specify indicates how many blank rows you want to add. The fourth element controls the horizontal space between columns; the integer you specify indicates how many blank columns you want to add. (Note that the rows and columns containing the characters that form the boxes are included in the number you specify. When you display boxes, the minimum value you can specify for the third and fourth elements is 2.) The default for the third and fourth elements are 0 (no extra rows between rows of items) and 2 (two extra columns between columns of items), respectively. The second item is a character vector that is either empty (' '), if you do not want boxes around enclosed items, or has length 8. The vector specifies the characters for APL to use when it draws boxes around enclosed items. The first four items specify the symbols for the corners of boxes (upper left, upper right, lower left, lower right), the next two items specify the left and right sides, and the last two specify the top and bottom. The following table describes the order and meaning of the eight items in the second item of the D¢ value: Position in Portion of Box Second Item Described Shape 1 Upper left corner Singleton 2 Upper right corner Singleton 3 Lower left corner Singleton 4 Lower right corner Singleton 5 Left side Vector APL Reference Manual 2-63 System Variables and Functions [0 D¢ Display Control Position in Portion of Box Second ltem Described Shape 6 Right side Vector 7 Top Vector 8 Bottom Vector The default value of 0DC1s (71 1 0 2) ''. The four data elements of the non-empty item have the following meanings: ~ 1 positions data at the top of each display area, 1 justifies data to the right, 0 places no extra blank lines between rows of data, and 2 places an extra blank between columns of enclosed items. For example: 0«CSNY<3 t+----+ 3p'LONG' 9823 834 5) (7 'TIME' 98 23 'COMIN' 2 'YO' 9823 834 | LONG| +-—--+ t----+ 98 23 | TIME| t----1 o+ 2 -+ | COMIN | | YO | Fomm -+ +--+ t-——4 O«MUSC+(1 2) +----- + +----—--- + |1 2} |3 +-—-t+ +----- + 6 4 5] |7 (3 8 4 9 6 8 9 10) 10| t-------- + AWITHOUT EXTRA BLANKS, MUSC WOULD APPEAR AS 110 110 123 456789 10 The displays that follow show CSNY and MUSC with the addition of the delta (A ) symbol to clarify the location of the blanks. ALONGAAS823AA83L ATIMEAAANAGBAAAZ3 COMINAAAD 2MMAYO 1A2A0A3A4A5AA6AA7A8A94010 The following examples describe the use of the second item of the 0D value, which specifies the boxes for APL to draw. If you specify '++++| | = ="' as the second item, APL draws boxes that look like the following: 2-64 APL Reference Manual System Variables and Functions [0DC Display Control The items you specify for the corners of boxes must be singleton items. However, the four sides may be character strings (vectors). (Note that the depth increases from two to three when you specify a character string for one or more of the four sides.) For example, if you specified '+' '\ /' '"PETER' '"+' '+' 141 1\ /! 'PETER' as the second item of the 0DC value, APL would draw boxes that look like the following: +PETER+ \ / \ / +PETER+ If a dimension of the box requires fewer characters than the string you specify, APL uses only the number required. If the box requires more characters, APL reuses the string. For example, the boxes might look like the following: +PET+ \ \ +PET+ +PETERPET+ \ / \ / \ / \ / +PETERPET+ When APL displays an array, it places each item of the array into a display area. If all items have the same shape, the display areas are all the same size. If the items vary in shape (as they often do), the display areas also vary in size. For any given row, the vertical dimension of the display area is determined by the maximum number of rows in any item in that row. For any given column, the horizontal dimension of the display area is determined by the maximum number of columns in any item in that column. For example: APL Reference Manual 2-65 System Variables and Functions 0 D¢ Display Control 0DC o+ === + |71 1 2 3| |++++]||--| e+ BUMP«2 -+ 2p(110) 5 (3 u4p112) 'ABC! BUMP pom e oo + |12 3 456 7 8 9 5 10] T+ tomm e+ +-——+ |1 2 3 4] |5 6 7 8] |9 10 11 12] +---+ tommm | ABC| -+ Note the dimensions of the display areas in the preceding example. BUMP[1:1] (c110) determines the dimension for the first column because it is wider than BUMP[2:;1](<c3 4p 1 12). BUMP[2;2] determines the dimension for the second column because it 1s wider than BUMP[1;2] (5). BUMP[1; 1] determines the dimension for the first row because it has more rows than BUMP[1;2] (the rows of the box are part of the display size of BUMP[1;17]). Finally, BUMP[2; 1] determines the dimension for the second row because it has more rows than BUMP[2;2] (< '4ABC'). Note that this manual displays enclosed items as if the 0 DC default were the following: ODcC oT + |71 "1 2 3| |++++]||--]| it + o fmmmm -+ The O0DC setting shown in the preceding example places items in the top left corner of each display area, adds two extra rows between rows of items, adds three extra columns between columns of items, and draws boxes using plus signs, vertical bars, and hyphens. Examples: ODC+(71 71 2 3) '++++]]--" e BUMP<2 2p(110) 5 (3 u4p112) 'ABC! ACHANGE POSITION IN DISPLAY ARFEA 2-66 APL Reference Manual System Variables and Functions [0 D¢ Display Control '++++||--" ODC<(0 0 2 3) e 5 |12 34567 89 10| +--=+ |1 2 3 4] 5 6 7 8 | ABC| |9 10 11 12| t---+ ODC<(0 0 4 5) '4+++4]]--" aCHANGE SIZE OF DISPLAY AREAS 0DcC -+ t----—- + pommm |0 0 4 5| | -] | ++++] o t-——————- + mm + =0DC 2 BUMP fom e + 5 |12 3456 7 89 10| fmmmm e+ e e m e ittt + +---+ 11 2 3 4 |15 6 7 8] | ABC| |9 10 11 12| +---+ -+ tomm aCHANGE BOX, REDUCE DISPLAY AREA USE E FOR ELEMENT 7 a OF SECOND ITEM, F FOR ELEMENT 8 OF SECOND ITEM E+l ________________ ! , F+-'—-g —————————————— ! ODC<(0 0 2 3) 0pc t-—p-—t--p-—--+ | "+' '+t 'V Vv V|V E F) aDISPLAY 0ODC VALUE =e+ P f--p-mmmmmm— - + +--p-—-m + | ('+' 00 23] |++++ | | |--p-------------- | }--V- e | | +--V----+ | t--Vmmm e - + 4=V- +] fomVmm e Vommmmmmmmm e R + =(1DC 3 APL Reference Manual 2-67 System Variables and Functions [0DC Display Control BUMP P 0+ /11234567 89 10] e 5 v+ t-=p-=———-- + |11 2 3 4] +--p+ |5 6 7 |9 10 11 8] 12| | ABC| +--V+ eT+ ASTOP DRAWING BOXES ODC«(0 0 2 3) "' BUMP 123456789 1 2 3 4 5 6 7 8 9 10 11 12 o (C« O«A«cA<«B, 5 ABC ODC<( 1 "1 2 B«4 10 15 3) '"++++]]--" ¢ D«2 (c(C), 2p '"ABCD' <D ATHE FOLLOWING WORKS WELL A TO DISPLAY NESTS OF IN A FORM SIMILAR TO STRAND NOTATION. DDC*‘—(O —1 0 1)(v+t LR SRE N i ‘I(I l)! ] ll) A (4 (1 2 3 4 5) ( (AB)) (CD)) ATHE FOLLOWING PUTS PARENTHESES AROUND ARRAYS DDC*’(0023)('/' i\\lf\\ll/llll!lll!l!) A / \ |/ |4 |1 |\ | \ 2 3 \ /] 4 5| |AB]| / |CD]| \ /] / Possible Errors Generated 2—-68 9 RANK ERROR (MUST BE VECTOR) 9 RANK ERROR (NOT SINGLETON) APL Reference Manual VECTORS Y System Variables and Functions O DcC Display Control 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (DISPLAY CONTROL ITEM WRONG LENGTH) 10 LENGTH ERROR (DISPLAY CONTROL VECTOR MUST BE TWO ITEMS) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (ENCLOSED VALUE REQUIRED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (NEGATIVE INTEGER NOT ALLOWED) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) APL Reference Manual 2-69 System Variables and Functions [0 DL Delaying Execution [l DL Delaying Execution Type Monadic System Function Form actual-delay <« DL seconds Argument Domain Type Numeric Shape Singleton Depth 0 or 1 (simple) Value seconds <~ 1+2%18 Result Domain Type Non-negative numeric Rank 0 Shape 1 0 (scalar) Depth 0 (simple) Description ODL delays execution for the number of seconds specified in the argument. If the argument is less than 0.001, there is no delay. If the argument is negative, there is no delay. | Although DL specifies the desired duration of the delay, the actual delay may be longer because of other demands on the system. The result returned is the actual delay in seconds. For example: 0 « 0DL 8.5 ASET DELAY AND DISPLAY 0 « ODL 7u.36 ANEGATIVE ARG = NO DELAY 9 0 Here, the user instructed APL to wait 8.5 seconds before prompting for input; the actual delay was 9 seconds. 2—-70 APL Reference Manual System Variables and Functions 0 DL Delaying Execution The O0DL function uses a negligible amount of computer time. Thus, you can issue it freely when tests are required at periodic intervals to determine whether an event has occurred as expected. The delay resulting from the execution of 0DL may be canceled by the weak attention signal. When the weak attention signal is thus used, APL stops 0DL and returns the actual delay but does not signal attention. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 27 LIMIT ERROR (DELAY VALUE TOO LARGE) DECLIT VAX APL AA vAX GVOSC reference manual APL Reference Manual 2-71 System Variables and Functions DML Maximum Record Length [l DML Maximum Record Length Type System Variable Form O0DML < default-length integer-scalar < [JDML Value Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value 512 through 20u8 (bytes) Default 2044 Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description O0DML specifies the default maximum record length to be used when you save a workspace or create an external file. The value of 0DML is saved with the workspace and can be localized within user-defined operations. If you do not want to use the default maximum record length, you can use the /MAXLEN qualifier when you save a workspace or create an external file. If you omit the /MAXLEN qualifier, APL uses the value of 0DML as the maximum record length. 2-72 APL Reference Manual System Variables and Functions 0 DML Maximum Record Length Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-73 System Variables and Functions (0 DV C Returning Device Characteristics UDVC Reiurning Device Characteristics Type Monadic System Function (query) Form characteristics <~ [JDVC chans Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value 999 through 999 (but not 0) Result Domain Type Integer Rank 1 0or 2 Shape Vector or matrix (n by 2) Depth 1 (simple) Description O0DvC displays device characteristics. The absolute value of chans represents the channels associated with the files you want information on. For each channel specified in the argument, 0DVC returns one row containing two values. The first value is the VMS device-characteristics longword, and the second value is always 0. For unassigned channels, 0DV returns 0 0. ODVC returns a two-element vector if a single channel is specified. If more than one channel is specified, the result is a matrix of shape n by 2, where n is the length of the argument. If its argument is empty, 0 DVC returns a result of 0 2p 0. Note that to return a value for 1DVc, APL must open files that have been associated with channels but have not yet been opened. Thus, unopened files associated with channels identified by positive integers in the 0DVC argument are opened for input; unopened files associated with channels identified in the 2-74 APL Reference Manual System Variables and Functions 0DV C Returning Device Characteristics argument by negative integers are opened for output. Note that when you open a sequential file for output, APL makes a new copy of the file with a version number that is one higher than that of the previous copy. It is usually helpful to convert the device-characteristics longword to binary format before examining it. For example: UASS '15 DESIGN/DA! 15 PXXXYYY'H 15 A<[IDVC 15 A 474824712 0 (32p1)TA[1] 000111000100110101000000000010°0°0 (-0I0)+00M (32p2)TAL1] 3 459 12 13 15 17 28 You can compare the binary value of the longword with the device characteristics in Table 2—6. The first element in the table 1s associated with the rightmost bit in the longword, the second element is associated with the next rightmost bit, and so forth. Thus, in the previous example, the three rightmost Os indicate that the device is not record-orientated, is not a carriagecontrol device, and is not a terminal; the 1 in the fourth position from the right indicates that the device is directory-structured. Table 2-6 Device Characteristics Longword Bit Type or Condition of Device 0 Record-oriented 1 Carriage-control 2 Terminal 3 Directory-structured 4 Single directory-structured 5 Sequential, block-oriented 6 Being spooled 7 Operator console 8 RA50,RA81,RA82,RH60 9-12 (Bits reserved) (continued on next page) APL Reference Manual 2-75 System Variables and Functions 0 DVC Returning Device Characteristics Table 2—6 (Cont.) Device Characteristics Longword Bit Type or Condition of Device 13 Network 14 File-oriented 15 (Bit reserved) 16 Shareable 17 Generic 18 Available for use 19 Mounted 20 Mailbox 21 Marked for dismount 22 Error logging enabled 23 Allocated 24 Non-file-structured 25 Software write-locked 26 Capable of providing input 27 Capable of providing output 28 Allows random access 29 Real-time 30 Read-checking enabled 31 Write-checking enabled Possible Errors Generated 9 2-76 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLUDES ARRAY NOT ALLOWED) 15 DOMAIN FRROR (NOT AN INTEGER) 15 DOMAIN EFRROR (INVALID CHANNEL NUMBER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions OFFR OEFS OEFC Event Flag System Functions NEFRJEFS [ FEFC Event Flag System Functions Type Monadic System Functions Form event-flag-values « JEFR chans (read) previous-values <« EFS chans (set) previous-values <« 1EFC chans (clear) Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value ~999 to 999 (but not 0) Result Domain Type Numeric Rank 1 or 2 Shape Vector or matrix (n by 2) Depth 1 (simple) Description There are three event-flag-system functions: JEFR to read event flag values, OEFS to set event flags (make them equal 1), and JEFC to clear event flags (make them equal 0 ). The absolute values of chans represent the channels associated with the event flags you want to manipulate. The 0EFR function returns the values of the event flags associated with the channel numbers in its argument. For channels not associated with an event flag, DEFR returns ~ 1. APL Reference Manual 2-77 System Variables and Functions O0FFR OFEFS OEFC Event Flag System Functions The result is a matrix (or vector, if the argument is a singleton) of shape n 1, where n is the shape of the argument. In the example, the result indicates that the event flags are associated with channels 1, 2, and 5. The event flag associated with channel 2 is set, and then cleared, and no event flag is associated with channel 4: (ASS "1 MYFILE/RF/SHARE/EFN:77" [ASS '2 0ASS '4 MINE/IS' UASS '5 MAILBOX/AS/SHARE/MBX/EFN:65" PUBLIC/DA/SHARE/EFN:68' OEFS 2 0 OEFR15 0 1 1 1 0 OFFC 2 1 OEFR15 0 0 1 1 0 The OFFS and OEFC functions set and clear, respectively, the event flags associated with the channel numbers in their arguments. They return a matrix of shape n by 1, where n is the shape of the argument, and the values are the previous values of the event flags. For channel numbers not associated with event flags, 0 EFFS and O EFC return ~ 1. If the argument to DEFR, OEFS, or JEFC is empty, APL returns 0 1p 0 as the result. OEFR, DEFS, and JEFC are described in the VAX APL User’s Guide along with other file I/O information. 2-78 APL Reference Manual System Variables and Functions OFFR OEFS OEFC Event Flag System Functions Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual 2-79 System Variables and Functions (0ERROR Error Message [| ERROR Error Message Type System Variable Form < QFRROR OERROR <« error-text Value Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Default o Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Description [0ERROR contains either the text of the last error message that occurred or the text that you assign to it. (JERROR is set implicitly by the system when an error occurs, but can also be set by the user.) JERROR contains one error at a time; when a new error occurs, the new message overwrites the old one. You can, however, localize ] FRROR within user-defined operations to save error information within an operation’s own environment. The text of DERROR is a character vector of variable-length lines and is delimited by a <CR><LF>. The lines of text in 0 ERROR are the same as the lines of the error message that APL displays on the terminal (except when OTERSE is 1), including secondary error messages and execute error messages. The error number is always contained in the first four characters of 0 ERROR, so you can always extract the error number with the expression ¢ 44 JERROR. OERROR always contains the entire error message text, even if some of the text 2-80 APL Reference Manual System Variables and Functions [0ERROR Error Message was not displayed on the terminal because it was truncated to J P¥ characters. For a description of the text of error messages, see Appendix A. Note that like all the system variables, IERROR can be set by the user; that is, you can use the specification function (V4) to assign a value to it. It is possible that when a WORKSPACE FULL error occurs, there will not be enough memory available to build 1 ERROR. In that case, 0 FRROR will equal ' ' (an empty character array). It is also possible that there will not be enough room to display 0ERROR. In that case, APL signals WORKSPACE FULL with the line in error being JERROR. For example: VABC;UTKAP;UERROR [1] [2] [3] [u] [5] [6] aLOCALIZE [JTRAP AND [ERROR OTRAP<«'> LAB' 5+ aNEXT LINE PRINTS MESSAGE AND INTERRUPTS EXECUTION LAB:[IBREFAK 'CHECK ERROR MESSAGE' "RESUME AT LINE 5! v aNOW GENERATE AN IMMEDIATE MODE ERROR C+A 11 aADD TWO UNDEFINED VARIABLES VALUE ERROR C+A aADD TWO UNDEFINED VARIABLES A aCHECK GLOBAL 11 VALUE OF [JERROR OERROR VALUE ERROR C+A aADD TWO UNDEFINED VARIABLES A aNOW EXECUTE ABC TO GENERATE LOCAL ERROR ABC CHECK ERROR MESSAGE nABC HAS SUSPENDED aNOW CHECK CONTENTS OF [JERROR OERROR 7 SYNTAX ERROR ABC[2] (RIGHT ARGUMENT TO FUNCTION MISSING) 5+ A aNOW BRANCH TO CURRENT LINE + 1 TO CONTINUE EXECUTION +(OLC+1 RESUME AT LINE 5 AFUNCTION HAS FINISHED EXECUTION aAND LOCAL [QFRROR IS GONE ACHECK GLOBAL VALUE OF [QFRROR FRROR 11 VALUE ERROR C+4 aADD TWO UNDEFINED VARIABLES A APL Reference Manual 2-81 System Variables and Functions [0ERROR Error Message Note that if an error occurs during an ¢ execute, ] ERROR contains six lines of text. For example: ¢ 79 '[)BREAK 1! ¢ SYSTEM FUNCTION ILLEGAL IN EXECUTE OBREAK 1 A 25 EXECUTE ERROR ¢ '"[JBREAK 1 A UERROR 79 ¢ SYSTEM FUNCTION ILLEGAL IN EXECUTE UBREAK 1 A 25 EXECUTE ERROR ¢ 'OBREAK 1! A Note that OFRROR is set by 0FXx, 0ASS, and 0XQ, even though no message is displayed when the error occurs. The value of 0 ERROR is saved when you save the active workspace and can be localized within user-defined operations. (See the VAX APL User’s Guide.) The default value is ' ' . Possible Errors Generated 9 2—-82 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPF) APL Reference Manual System Variables and Functions 0 FX Erasing a Named Object [1 £ X Erasing a Named Object Type Monadic System Function Form erased /not-erased < 1EX name-list Argument Domain Type Character Shape Matrix domain Depth 1 (simple) Result Domain Type Boolean Rank 1 Shape o name-list Depth 1 (simple) Description OEX erases the local APL objects named by the rows of its argument. You cannot erase a named object that refers to a label, a group (a group name is always global), or to a suspended or pendent operation. The result of the JEX system function is a Boolean vector that indicates which objects were erased: a 1 signifies that the object now has no value; a 0 signifies that the object cannot be erased. Note that 0 EX returns O if you specify an ill-formed identifier. APL Reference Manual 2-83 System Variables and Functions 0 EX Erasing a Named Object For example: JENS ABCD GROW TEST )SI TEST[2] « A<3 4p'ABCDTESTGROW' A ABCD TEST GROW A OEX 101 JENS TEST If the argument to JEX is empty, the result also is empty. Note that the memory allocated from VMS remains allocated even if you expunge an object from the workspace. If you want to release this memory, follow the sequence of steps discussed in the section on space considerations in Chapter 3 of the VAX APL User’s Guide. Possible Errors Generated 9 2-84 RANK FRROR (NOT MATRIX DOMAIN) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) APL Reference Manual System Variables and Functions [] EXP Expansion [1 £ X P Expansion Type Dyadic System Function Form AQOFXP B A UOFXP[K] B Left Argument Domain Array Simple, homogeneous Type Near-Boolean Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain Type Same as argument Rank 1fppB Shape (K-1)+pB),(p,A),K+pB (for J10=1) Depth 1 =B implicit Arguments None. APL Reference Manual 2-85 System Variables and Functions [JEXP Expansion Description OEXP builds an array by combining the items of an existing array with fill items. OEXP works the same as the expansion derived function. The examples shown for the Expansion operator in Chapter 1a also apply to JEXP (you can substitute 0 EXP for the backslash (\ ) operator). The difference between [] EXP and the backslash operator is that you can use JEXP as an operand to an operator. Operators cannot be used as operands to operators. NEXP applies along the last axis of B unless modified by an explicit axis (¥ ) in brackets. The shape of the result is the same as the original array B except along the applicable axis (p B[X]) where the shape becomes the length of 4 (p , 4). The following examples show OEXP with the each () operator. Although the variables 4 and C are nested in the examples, they conform to the left argument domain requirement that specifies a simple array. This is because the each operator reduces the nesting by one level. O«d«(1 01 1) to--mm -t ot + |10 J110 1 1] tommmm -t 1) 1 -+ 0«B«(2 fo---- + (110 3p16) (4 3p'ABCDEFGHIJKL') o4 |1 2 3| |ABC| |4 5 6| |DEF| to-—- + |GHI| | JKL| +---+ aATTEMPT TO USE OPERATOR AS ARG TO ~ A\ "B nAPL EVALUATES AS (A\)"B 15 DOMAIN ERROR A\ "B (ENCLOSED/HETEROGENEOUS ARRAY NOT ALLOWED) anAPL EVALUATES AS (A\)'B A A OEXP" B e+ -t |1 0 2 3| |AB C| |4 0 5 6| |DE F| -+ |GH I fomm | JK L t----+ A OEXP[2]1"B -+ +----t |10 2 3| 5 6| |DE F| |4 0 2-86 |4B C| APL Reference Manual AEXPAND ITEMS OF B USING THE ITEMS OF 4 System Variables and Functions [0 EXP Expansion O«C«(1 0 1) (1101 ¢ OFXP[1]"B |1 2 3] |0 0 0 v 560 1) aUSE OFXP WITH AXIS ARGUMENT [ABC] |DEF| [ | | JKL| +---+ Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 15 DOMAIN ERROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 27 LIMIT EFERROR (INTEGER TOO LARGE) 28 AXIS RANK FRROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH FRROR (NOT SINGLETON) 30 AXIS DOMAIN FRROR (AXIS LESS THAN INDEX ORIGIN) 30 AXIS DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN FERROR (INCORRECT TYPF) 30 AX1IS DOMAIN FRROR (NOT AN INTEGER) 30 AXIS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) 30 AXIS DOMAIN FRROR (SEMICOLON LIST NOT ALLOWED) APL Reference Manual 2-87 System Variables and Functions [0 FI Converting Characters to Numerics [| £ 1 Converting Characters to Numerics Type Monadic System Function Form numeric-values <~ [0 FI numeric-character-string Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Numeric Rank 1 Shape Vector Depth 1 (simple) Implicit Arguments [ONG (determines minus sign placement) Description [0FI converts a numeric character argument to a vector of numeric values, placing a 0 in each position that does not correspond to a valid number. The shape of the argument must be in the vector domain. If the argument is empty, [ FI returns an empty numeric vector. OFI separates the argument into fields that are delimited by one or more spaces, tabs, or a carriage return (optionally followed by a line feed); converts each field that contains a valid number; and inserts a 0 to replace each field containing an invalid number. For example: 2-88 APL Reference Manual System Variables and Functions (0 FTI Converting Characters to Numerics A<(JFI '12 55¢ 4 (C 2951 8 +5' A 12 0 "4 0 2951 8 0 pA 7 Note that a plus sign preceding a number is not part of the number but is rather an operation to be performed on the number. However, in APL, the negative sign in the expression ~ 5 is a valid part of the number. OFT is often used in conjunction with VI and the compression derived function (see the Section 1.3.2 section) to select the valid numbers from a character string: 00 VI produces the left argument of the compression function, and [ FI produces the right argument. For example: V Z<AVERAGE U«'ENTER A LIST OF NUMBERS' 2«<(0VI Z)/0FI Z L<(+/72)+pZ v [1] [2] [3] [4] ¢ Z<,[ AVERAGE ENTER A LIST OF NUMBERS 1 3.540+2 .50, 2 In the previous example, VI of Z equals 1 1 0 1 0 1 1 0 13.5000 and OFI of Z equals .560 Recognition of negative numbers in the JFI argument depends upon the value of the system variable ONG. If NG equals 1 (the default), negative numbers in the O FI argument must begin with the high minus sign (7) to be recognized. If ONG equals 0, numbers preceded by a minus sign (-) are recognized as negative numbers. If NG equals 2, negative numbers are preceded by an APL "+" symbol. (APL "+" prints as an ASCII "-" so that NG+2 can be used to handle negative numbers in strings that are read or written in ASCII.) For example: ONG<1 a MEANS NEGATIVE X<'66 G 7 +9 4 OFI X 66 0 7 0 4 ONG+0 a- MEANS NEGATIVE OFI X 66 0 0 0 O ONG<2 n+ MEANS NEGATIVE OFI X 66 0 0 +9 0 APL Reference Manual 2-89 System Variables and Functions 0 FI Converting Characters to Numerics Note that when NG is 0, it may be useful for you to use APL to interpret data created by other languages, specifically those that do not use the high minus sign. Possible Errors Generated 9 2-90 RANK ERROR (NOT MATRIX DOMAIN) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) APL Reference Manual System Variables and Functions 0 FLS Returning File Information [1 'L .S Returning File Information Type Monadic System Function (query) Form file-info ~ OFLS chans Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value 7999 to 999 (but not 0) Result Domain Type Integer Rank 1 or 2 Shape Vector or matrix (n by 5) Depth 1 (simple) Description 0 FLS returns information about files. The absolute values of chans represent the channels associated with the files you want to specify. The result contains one row of five values for each channel specified in the argument. The meanings of the values differ according to each file’s organization. The values returned by 0FLS have the following meanings (from left to right): First value Share bit: 1 means that you specified /SHARE in the argument for the associated J45S function; 0 means that you did not. APL Reference Manual 2-91 System Variables and Functions (0 FL.S Returning File Information Second value For sequential files, the second value is the number of records read or written since the file was opened. For direct-access and relative files, it is the value of the last record or component number used for a successful read or write operation. For keyed files, it is the value of the last key of reference used for a successful read, write, or rewind. Third value The maximum record length of the file (0 means there is no user limit on record size). Fourth value The /BLOCKSIZE setting for the file. Fifth value The type of the most recent I/O operation Value Returned I/O Operation 0 None 1 Sequential read 2 Random read 3 Sequential write 4 Random write 5 Sequential delete 6 Random delete O0FLS is described in the VAX APL User’s Guide along with other file 1/O information. Possible Errors Generated 9 2-92 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOQOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions O FMT The Report Formatter L1 FMT The Report Formatter Type Dyadic System Function Form report < format-phrases OFMT {array | (array ; array;...)} Left Argument Domain Type Character Shape Vector domain Depth 1 (simple) Right Argument Domain Type Any Shape Any Depth < 2 (vector of arrays or a simple array) Result Domain Type Character Rank 2 Shape Matrix Depth 1 (simple) Implicit Arguments ONG (determines minus sign placement) Description OFMT combines the data from all the arrays in the right argument and arranges it as a single character matrix whose columns are then formatted according to corresponding format phrases specified in the left argument. The arrays in the right argument can be both character and numeric data. APL Reference Manual 2-93 System Variables and Functions [0FMT The Report Formatter OFMT can edit the data as it is moved to an output field. For example, OFMT fills or erases zeros in numeric fields; round numeric data; and inserts commas, dollar signs, and other text where appropriate. The right argument is a list of arrays of any type or rank. The list must be surrounded by parentheses (unless there is only one array in the list), and the arrays must be separated by semicolons. Alternatively, the right argument may be a single nested vector of simple arrays, which are treated in the same manner as a semicolon list. The left argument is a character vector comprised of one or more format phrases of the form described in Chapter 4 of the VAX APL User’s Guide. The phrases must be separated by commas. The following table summarizes the syntax of the format phrase in the left argument. Note that rep (repetitions) refers to the number of consecutive target columns to be affected by the format phrase; quals refers to one of the qualifiers or decorators described in the following table; width refers to the width in the result array of a value from a column of data in the right argument; dig (digits) refers to the number of decimal places included in the result array; and col (column) refers to either the leftmost column that a value is to occupy in the result array (for type T), or the number of columns to be shifted before the next value is output to the result array. 2-94 Phrase Type of Data [repll [quals] A width Character [rep] [quals]l E width.dig Floating-point with exponent [repl [quals] ¥ width.dig Fixed-point [repll [quals]l G « patterns Picture [repl lquals] 1 width Integer [repl lqualsl Y width Byte lrepl T [coll Absolute tab [repll X [col] Relative tab [replla textn Literal APL Reference Manual System Variables and Functions OFMT The Report Formatter The following table summarizes the qualifiers and decorators used in the format phrase: Qualifiers Meaning B For types I, E, F, G, and Y, if the value of the item in the target column is zero, make the field in the target column blank in the result array. C For types I and F, insert commas between each group of three digits in the integer part of the formatted value. L For types I, F, E, A, and Y, left-justify the fields in the target column. Kn For types I, F, G, and E, before formatting the fields in the target column, multiply the fields by the scale factor 10xn. Sa symbol pairsa For types I, E, F, G, and Y, replace, in the formatted output, all occurrences of the first character in each symbol pair with the corresponding second character of the symbol pair. Wn For type E, use n exponent digits in the formatted output. Z For types I, F, and Y, fill leading blanks in the formatted output with zeros. Decorator Meaning Ma textn For types I, F, and G, replace the sign of negativeformatted values with text placed to the left of the value. Na texta For types I, F, and G, place text to the right of negative-formatted values. Oan textn For types I, F, G, and Y, replace formatted zero values with text. Pa texta For types I, F, and G, place text to the left of positiveformatted values. APL Reference Manual 2-95 System Variables and Functions O0FMT The Report Formatter Decorator Meaning Qn texta For types I, F, and G, place text to the right of positive-formatted values. Ra textn For types I, F, E, A, G, and Y, fill unused columns in the formatted output with text. Note that the delimiting pair s a may also be any of the following pairs: 00 00 < > c D OFMT is also described in Chapter 4 of the VAX APL User’s Guide. Possible Errors Generated 9 2-96 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 14 DEPTH ERROR 15 DOMAIN ERROR (DUPLICATE FMT QUALIFIER) 15 DOMAIN ERROR (DUPLICATE FMT STANDARD SUBSTITUTION CHARACTER) 15 DOMAIN FRROR (EMPTY FMT STRING PARAMETER NOT ALLOWED) 15 DOMAIN FRROR (ENCLOSED ARRAY IS NOT ALLOWED) 27 LIMIT FRROR (FLOATING OVERFLOW) 15 DOMAIN FRROR (FMT DECORATION OR LITERAL STRING TOO LONG) 15 DOMAIN FRROR (FMT RIGHT ARGUMENT DOES NOT MATCH FORMAT PHRASE) 15 DOMAIN FRROR (ILL FORMED FMT PARAMETER) 15 DOMAIN FRROR (ILLEGAL CHARACTER IN FMT LEFT ARGUMENT) 15 DOMAIN FRROR (ILLEGAL FMT FORMAT PHRASE) 15 DOMAIN FRROR (ILLEGAL FMT G FORMAT PHRASE PATTERN CHARCTER) 15 DOMAIN FRROR (ILLEGAL FMT LITFRAL STRING DELIMITER) APL Reference Manual System Variables and Functions O0FMT The Report Formatter 15 DOMAIN FRROR (ILLEGAL FMT S QUALIFIFR SYMBOL) 15 DOMAIN ERROR (ILLEGAL USF OF FMT QUALIFIER) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (MISSING FMT FORMAT PHRASE SEPARATOR) 15 DOMAIN ERROR (MISSING FMT FORMAT PHRASE/QUALIFIER) 15 DOMAIN ERROR (MISSING LITERAL STRING IN FMT LEFT ARGUMENT) 15 DOMAIN ERROR (NO DIGIT SELECTOR IN FMT G FORMAT PHRASE PATTERN) 15 DOMAIN ERROR (NO FMT FDITING FORMAT PHRASE) 15 DOMAIN FRROR (PARAMETER OUT OF RANGE) 15 DOMAIN ERROR (RIGHT ARG TOO DEFEPLY NESTED) 15 DOMAIN ERROR (UNBALANCED TEXT DELIMITER IN FMT LEFT ARGUMENT ) 15 DOMAIN ERROR (UNBALANCED PARENS IN FMT LEFT ARGUMENT) 15 DOMAIN ERROR (UNPAIRED SYMBOL IN FMT S QUALIFIER) APL Reference Manual 2-97 System Variables and Functions [1 FX Establishing an Operation [] F'X Establishing an Operation Type Monadic System Function Form operation-name< [FX operation-definition Argument Domain Type Character Shape Matrix domain Depth 1 (simple) Result Domain Type Character (Numeric if error is detected) Rank 0 or 1 Shape Vector (Scalar if error is detected) Depth 0 or 1 (simple) Implicit Arguments 0 I0 (controls origin of line number in error) Description [0FX reverses the operation of the (1 CR system function; that is, it creates in internal form the operation defined by its argument. The argument is assumed to be a character matrix that contains the canonical representation of an operation. The shape of the argument must be in the matrix domain. Blank lines in the argument are removed in the operation established by O FX. O0FX fails if the operation’s name is the same as that of an existing label, variable, or group, or if it is the same as that of an existing operation that is pendent or suspended. If an operation already exists in your workspace with the same name, [JFX replaces it and removes any trace, stop, or monitor bits that were set on it. 2-98 APL Reference Manual System Variables and Functions (] FX Establishing an Operation The O FX function executes properly if the matrix it references is identical to a canonical representation. If 0FX fails, APL returns a scalar index (which is [0 I0-sensitive) representing the row in the matrix where the error occurred, and no change is made to any operation or array in your workspace. You can check the value of D ERROR for a description of what was wrong with the line in error. If O FX is successful, its result is a character vector containing the name of the operation defined. If the argument is empty, the result is empty. The following example begins where the 0 CR example from the 01 CR section ended. Here, the plus sign in SHOWCRFX is changed to a multiplication sign; then, the O0FX system function is applied to SHOWCRFX to replace the function MEAN with its new version: SHOWCRFX[3:6]«"x! NFX SHOWCRFX MEAN V MEANCO]V VMEANX<NSUBJ MEAN X aSUM VECTOR X SUMX<x/X [1] [2] MEANX<SUMX+NSUBJ [3] v X 8639542174 X 10 MEAN 145152 X<2 4p 'F X1234" X[1:2 3]«0CTRL{14 11] wEMBED CRLF IN OPERATION HEADER OFX X 1 UERROR 5 DEFN ERROR (EXTRANEOUS CHARACTERS AFTER COMMAND) F X A Possible Errors Generated 9 RANK ERROR (NOT MATRIX DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual 2-99 System Variables and Functions [0 GAG Preventing Interruptions | GAG Preventing Interruptions Type System Variable (session) Form 0GAG < near-integer-singleton integer-scalar ~ JGAG Value Domain Type Integer Shape Singleton Depth 0 or 1 (simple) Value 0,1,2,0r 3 Default Determined when APL is invoked Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description 0GAG allows you to specify how APL handles messages that arrive at your terminal from other users. You can set 0 GAG to the following values: Value Meaning 0 Display messages 1 Refuse messages 2 Trap, translate, and display messages 3 Signal BROADCAST RECEIVED Setting 0 GAG to 0 is equivalent to executing the DCL command set terminal /broadcast, and setting 2-100 APL Reference Manual JGAG to 1 has the same effect as the DCL command System Variables and Functions [0 GAG Preventing Interruptions set terminal/nobroadcast. When [JGAG is 1, messages from nonprivileged users are suppressed (note that senders are not told that their messages were not received). For more details, see the VMS DCL Dictionary. When you return to DCL from APL, the original system value for [ GAG is restored, unless the exit from APL was a panic exit; in that case, the setting established in the APL session remains in effect. Setting [1GAG to 2 is equivalent to executing the DCL command SET TERMINAL/BROADCAST, with the addition of instructing APL to display the message in the character set that is currently set for the terminal. If you use an APL terminal, the default setting is 2 when APL is invoked. Setting 0GAG to 3 allows you to trap messages with [ TRAP and to view them at a later time. As messages arrive at the terminal, APL signals BROADCAST RECETIVED followed by a secondary message of the broadcast text. The default setting of JGAG is the current monitor setting. Note that 0GAG 1s a session variable; that is, its value is not saved with the workspace, and 0 GAG is not reset by the execution of a ) CLEAR command (see Chapter 3). 0GAG can, however, be localized in user-defined operations. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-101 System Variables and Functions [0 70 Index Origin [] 1O Index Origin Type System Variable Form [0 I0 <« near-integer-singleton integer-scalar-current-value <« 0I0 Value Domain Type Integer Shape Singleton Depth 0 or 1 (simple) Value 0 or 1 Default 1 Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description 010 specifies the setting of the index origin. This setting determines whether the values of an array are indexed beginning with position 0 or 1. The default position is 1. 010 also affects the operation of axis ([ ]), exceopt when axis is used with user-defined operations. In addition, 010 affects the operation of the following primitive and system functions: 14 A1B 7A A?B AA VA AQB [OM B OFX B The value of 010 is saved when you save the active workspace and can be localized in user-defined operations. 2—102 APL Reference Manual System Variables and Functions [1 10 Index Origin Examples: 0I0+<1 1 3 12 3 A<2 Up16 +/[2]4 10 14 8 4 b6 +/[1]4 +/[0]A 30 AXIS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) +/[0]A A 0I0+0 13 0 1 2 +/02]4 30 AXIS DOMAIN ERROR (ARGUMENT RANK AND AXIS INCOMPATIBLE) +/[2]A4 A +/[1]4 14 10 +/[0]A b 8 4 6 010<«7 15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) O0I0«7 A Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN EFRROR (INCORRECT TYPE) 15 DOMAIN FERROR (NOT AN INTEGER) 15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-103 System Variables and Functions [0 L Monitoring Variable Changes ] L Monitoring Variable Changes Type System Variable Form 0L < any-value variable-name< L Value Domain Type Any Shape Any Depth Any Result Domain Type Character (any when set by user) Rank 1 (any when set by user) Shape Vector (any when set by user) Depth 1 (simple) (any when set by user) Default 10 Description 0L and (R are system variables that are implicitly used by OWATCH. (OL is set implicitly by the system when a variable changes, but can also be set by the user.) OWATCH i1s a system function that is used to monitor any changes in one or more variables. When a change occurs in a monitored variable, APL assigns information to JL and OR: 0L contains a character vector showing the name of the variable that has changed; 1k contains the previous value of the changed variable. APL assigns this information regardless of whether monitoring is set for signal or display mode. The default value for both 0L and 0 R is 1 0. Immediately after a OWATCH event occurs, [JL and OR contain the new information that results from the event. However, this information may change as an operation continues execution (this is especially true if an error occurs during an assignment or reference of a variable that is associated with a watchpoint). 2—-104 APL Reference Manual System Variables and Functions 0 L Monitoring Variable Changes Both 1L and OR can be localized, explicitly assigned values of any type, and saved in the workspace. Note that you cannot include 0L or OR in the right argument to dyadic UWATCH. Possible Errors Generated None. APL Reference Manual 2-105 System Variables and Functions [0 LC Line Counter [1 L C Line Counter Type Niladic System Function Form current-line-number < [1LC Result Domain Type Integer Rank 1 Shape Vector Depth 1 (simple) Default Empty Description O0L¢ (line counter) allows you to obtain a partial report on operations that are currently being executed. The function returns a vector of all the line numbers contained in the state indicator; the numbers are arranged as they would appear in the ) SI system command display (see Chapter 3.) If the state indicator is empty, [ LC returns an empty numeric vector. The 0LC system function is particularly useful in restarting suspended operations. For more information, see the VAX APL User’s Guide. For example: VNEW (1] »1 NEW ¥ aCALL FUNCTION, 18 ATTENTION SIGNALED NEW[1] -1 A OLC 2-106 APL Reference Manual THEN SEND ATTENTION SIGNAL System Variables and Functions [0 LC Line Counter Possible Errors Generated None. APL Reference Manual 2-107 System Variables and Functions [1LX Latent Expression ] L X Latent Expression Type System Variable Form O0LX < character-vector current-value < [QLX Value Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Default H Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Description [0 LX specifies an APL expression that is executed automatically when the workspace is loaded. The value you assign to 0 LX must be a character vector. The default value is ' 1. APL processes the expression as if you had specified « 0LX. Any error messages you receive are produced by the execute function. The OLX system variable is useful in restarting a suspended operation. For example: OLX<«"->[JLC" 0LX is also useful for invoking a particular user-defined operation (see the VAX APL User’s Guide) when you load the workspace. For example: OLX<«' STARTUP' 2—-108 APL Reference Manual System Variables and Functions [1LX Latent Expression The 0 LX system variable is often used to display a message when the workspace in which it is defined is loaded. For example: OLX<'''NOTE NEW LINE PRINTER IN OPERATION''' )SAVE MYWS FRIDAY 16-NOV-1990 10:09:27:02 7 BLKS )CLEAR CLEAR WS )LOAD MYWS SAVED FRIDAY 10-NOV-1990 10:09:27.02 7 BLKS NOTE NEW LINE PRINTER IN OPERATION When you want to load a workspace without invoking 0 LX, you can use the ) XLOAD command (see Chapter 3) if you are the owner of the workspace. APL executes [1LX only in immediate mode and only when the state indicator stack is either empty or has a suspended operation on top. If the top of the stack contains a [J input function, the latent expression is executed only after the pendent [J input is removed from the stack. The latent expression is not executed if the top of the stack contains an execute function, or if the loaded workspace is in function-definition mode. For example: )LOAD MYWS SAVED THURSDAY V [1] (2] (3] (4] 8-NOV-1990 19:42:58.52 15 BLKS F A+«1 X«[XQ') SAVE MYWS' 'X IS ';X "END OF F' V F X IS THURSDAY 8-NOV-1990 17:01:59.54 16 BLKS END OF F )CLEAR CLEAR WS JLOAD MYWS X IS SAVED THURSDAY 8-NOV-1990 17:01:59.54 16 BLKS END OF F In this example, the note about the new line printer is not displayed when the workspace is loaded because the workspace was saved during the execution of an [JXQ system function; thus, the 0x@ function is at the top of the stack when the workspace is reloaded, and APL completes the 1 xQ function rather than executing the latent expression. APL Reference Manual 2-109 System Variables and Functions [1LX Latent Expression If you were to save the workspace after execution of the function F completed, the latent expression would be executed the next time the workspace was loaded: )SAVE MYWS FRIDAY 16-NOV-1990 )CLEAR 10:43:59.54 8 BLKS CLEAR WS YLOAD MYWS SAVED FRIDAY 16-NOV-1990 10:43:59.54 8 BLKS NOTE NEW LINE PRINTER IN OPERATION Note that when the function F was executed, the value of X displayed by operation line [3] was equivalent to the message displayed by the ) S4VE system command: X IS MONDAY 27-SEP-1982 18:07:42,02 8 BLKS However, when the execution of function ¥ was resumed because the saved workspace was loaded by a ) L0AD command, the value of X displayed by operation line [3] was equivalent to the message displayed by the )L0o4D command: X IS SAVED MONDAY 27-SEP-1982 18:07:42.02 8 BLKS Thus, as shown by this example, it is possible to determine whether the workspace has just been saved or has just been loaded. The value of JLX is saved when you save the active workspace and can be localized in user-defined operations. Possible Errors Generated 9 2-110 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN EFRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions OMAP Defining External Routines to APL [1MA P Defining External Routines to APL Type System Function Form external-routine-definition < [IMAP function-name function-name « function-header OMAP image-definition Monadic Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Dyadic Left Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Dyadic Right Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) APL Reference Manual 2-111 System Variables and Functions 0 MA P Defining External Routines to APL Parameters external-routine-definition The operation header returned by the monadic form of OMAP. This is the same header that dyadic OMAP uses when you successfully define the external routine to APL. function-name Specifies the name of the external routine. For dyadic OMAP, if both functionheader and image-definition are empty, and are in the vector domain, then the result i1s an empty vector. For monadic OMAP, if function-name is empty, the result is an empty character vector. If the value of function-name does not name an external routine, APL signals DOMAIN ERROR (NOT AN EXTERNAL FUNCTION). function-header Describes the external routine. function-header has the following form: [result/att«< ]| entry-point [arg1/att [arg2/atf] . . . ] result[ att specifies that the external function returns a result. Note that the result must be a scalar. (If you want to return data that has a rank greater than 0, you can modify a formal parameter with the external routine.) The /att qualifier specifies the type of the result. It has the form /7Y PE: vms-datatype, and must be one of the external data types in the Table 2-7 (excluding JTYPE: 7). Do not specify the /MECHANISM attribute for the result of an external routine; APL determines the mechanism by the value specified for /TYPE. Table 2—7 describes these default mechanisms. If the result type occupies 8 bytes or less, APL assumes the mechanism is IMMEDIATE. If the result type occupies more than 8 bytes, APL assumes the mechanism is DESCRIPTOR for strings and REFERENCE for all others. entrypoint is the name that you want APL to associate with the shared image entry point specified in image-definition. After you define entry-point, you can call the external routine as if it were a user-defined operation. Note that entry-point has a name class value of 3. Dyadic OMAP signals DOMAIN ERROR (NAME IN USE) if entry-point is the same name as an existing label, variable, or group, or if it is the same name as an existing operation that is pendent or suspended. If an operation already exists in your workspace with the same name, and it is not pendent or suspended, [OMAP replaces it. 2-112 APL Reference Manual System Variables and Functions [0MAP Defining External Routines to APL argn specifies the names of the function’s formal parameters. These names are similar to the dummy arguments of a user-defined operation; they are placeholders only, and you specify the actual values for these parameters when you invoke the function. The maximum number of formal parameters you can specify is 255 (including result). The names must be valid APL identifiers; they do not have to be unique. An external function can only be monadic or niladic; all of the formal parameters belong to the function’s right argument. /aft determines the attributes for each of the formal parameters and for the external routine’s result. For parameters, the attributes specify the kind of access that the external routine has to the parameter (either read, write, or both), the data type of the parameter, and the passing mechanism used to send the parameter between APL and the external routine. Valid qualifiers for /att include JACCESS, /TYPE and /MECHANISM. image-definition The name of a shared image (in the form of a VMS file name or logical name) and its entry point. If you use a logical name you cannot change the name once the shared image is mapped by APL. image-definition has the following form: {vms-filename | vms-logical-name} [{/ENTRY | /VALUE} [[:symbol]] vms-filename or vms-logical-name specifies the name of the VMS shared image. If you do not use a logical name, you can only specify a file name, not a complete file specification. The default directory for vms-filename is SYS$SHARE:, and the default file type is .EXE. If you use vms-logical-name, you should not redefine the logical name to point to a different file once the shared image is mapped. Note that you can use the equal sign delimiter (=) in place of the colon (:). Spaces are allowed before and after the /ENTRY or /VALUE qualifier, the delimiter, and the value for symbol. Qualifiers /ENTRY[[:symbol] Used with dyadic OMAP, specifies the name of the entry point in the shared image. An entry point is the starting address of executable code. If you do not specify /ENTRY, or if you specify /ENTRY with no value for symbol, APL assumes that the name of the entry point is the same as the value for function-name. APL Reference Manual 2-113 System Variables and Functions [DMAP Defining External Routines to APL /VALUE[[:symbol] Used with dyadic OMAP, specifies the name of a global constant in the shared image. A global constant is a 32-bit signed longword value. When you specify /VALUE, then function-header must specify a niladic function that returns a value with a return type of I (for example, 'Z/TYP:L«+ F'). If /VALUE is specified when there is no value for symbol, APL assumes that the name of the global constant is the same as the value for function-name. JACCESS Specifies whether the parameter is read only or modifiable. The value I¥ indicates that the external routine reads the parameter and does not modify its value. The value INOUT indicates that the routine reads the parameter and may modify it. The value O0UT indicates that the routine writes a value to the parameter. When you specify INOUT or 0UT, the actual parameter that you specify when you invoke the function must be a character string that names the variable that the routine will read (in the case of I¥0UT) and write. If the variable does not have a value when you call the external routine, APL assumes the variable is a scalar and will accept a scalar only when the value is returned. If you do not specify a value for /ACCESS, APL uses the IN value as the default. You cannot specify the /ACCESS attribute for the result of an external routine; by definition the access is always 0UT. Note that you can abbreviate the values for /ACCESS to their shortest unique prefixes. /TYPE Specifies the attribute for both the formal parameters and the result (if any). It is one of the external types shown in Table 6-1 in the VAX APL User’s Guide. On a formal parameter, /TYPE specifies the VAX data type that the external routine is expecting. On the result, /TYPE specifies the VAX data type that will be returned. Data internal to APL has one of the following types: * Character data in the APL character set (8-bits per value) * Boolean data, a subset of numeric data (1-bit per value) * Integer data, a subset of numeric data (32-bits, signed, per value) * Floating-point, a subset of numeric data (64-bits, D_floating, per value) Because VMS supports many more data types than APL, conversions will take place as data leaves and returns to APL from the external routine. Tables 6-2 and 6-3 in the VAX APL User’s Guide summarize these possible conversions. 2-114 APL Reference Manual System Variables and Functions O MAP Defining External Routines to APL The default data type is /TYPE: Z (unspecified), which indicates that data 1is passed out of the workspace without conversion. Data that is passed out of APL as /TYPE:Z cannot return to APL; for this reason, a formal parameter with the attribute /TYPE: Z must also have the attribute /ACCESS: IN. Note that you cannot abbreviate any of the values to the /TYPE qualifier. Table 2-7 Characteristics of External Data Types External Type DEFAULT result Length Type Name /MECHANISM in Bytes Z Unspecified N/S BU Byte Logical IMM 1 wu Word Logical IMM 2 LU Longword Logical IMM 4 QU Quadword Logical N/S Oou Octaword Logical N/S B Byte Integer IMM 1 W Word Integer IMM 2 L Longword Integer IMM 4 Q Quadword Integer N/S O Octaword Integer N/S F F_floating IMM 4 D D_floating IMM 8 G G_floating IMM 8 H H_floating REF 16 FC F complex IMM 8 DC D complex REF 16 GC G complex REF 16 HC H complex REF 32 Key to Default result /MECHANISM N/S—not supported IMM—by value REF—by reference DES—by description (continued on next page) APL Reference Manual 2-115 System Variables and Functions [0 MAP Defining External Routines to APL Table 2—-7 (Cont.) Characteristics of External Data Types External Type DEFAULT result Length Type Name /MECHANISM in Bytes CIT COBOL Temp N/S T 8-bit Text DES 1 VT Varying Text REF 1 NU Numeric String DES 1 NL Left Sign String DES 1 Left Overpunch DES 1 NLO String NR Right Sign String DES 1 NRO Right Overpunch DES 1 1 String NZ Zoned Sign String DES P Packed Decimal N/S \% Bit IMM vuU Bit Unaligned N/S Z1 Instructions N/S ZEM Entry Mask N/S DSC Descriptor N/S BPV Bound Procedure N/S BLV Bound Label N/S ADT Date/Time N/S other DEC or user reserved N/S Key to Default result 1 /MECHANISM N/S—not supported IMM—by value REF—Dby reference DES—Dby description /MECHANISM Specifies one of the three techniques for passing formal parameters from APL to the external routine. These techniques are DESCRIPTOR. IMMEDIATE, REFERENCE, and IMMEDIATE specifies that the value of the parameter is the value you want to pass. REFERENCE specifies that the value of the parameter is the 2-116 APL Reference Manual System Variables and Functions [0 MAP Defining External Routines to APL address of the value you want to pass. DESCRIPTOR specifies that the value is the address of a descriptor that contains the address and length of the data as well as other attributes (if the descriptor requires them). Note that the descriptor length field contains the length of the object. If you do not specify the /MECHANISM attribute when you invoke dyadic JM¥4P, APL uses a default when you call the external routine. If the parameter i1s /TYPE: Z, APL assumes /MECHANISM:REFERENCE. Otherwise, the default is based on the rank of the actual argument being passed: /MECHANISM:REFERENCE is chosen for scalars and vectors, and /MECHANISM:DESCRIPTOR is used for arrays of rank 2 or higher. When you specify /MECHANISM: IMMEDIATE, the formal parameter must be a scalar; if the internal length of the actual value that you specify when you invoke the external function is greater than 4 bytes, APL signals LENGTH FRROR. When you specify /MECHANISM:DESCRIPTOR, APL uses string descriptors (CLASS_S) for the vector domain, and array descriptors (CLASS_A with a multipliers block) for arrays of rank 2 or greater. (The type of the value being passed does not affect the choice of descriptor.) For more information on descriptors, see the Introduction to VMS System Routines. Note that you can abbreviate the values for /MECHANISM to their shortest unique prefixes. Description Dyadic OMAP defines an external routine to APL. Once a routine is defined in a workspace, the workspace can be saved, loaded, or copied, and the definition for the routine remains intact. The monadic O MAP system function returns an operation header that provides information on the current definition associated with an external routine. APL returns an operation header (external-routine-definition). This is the same header that dyadic ¥4 P uses when you successfully define the external routine to APL. The header’s form is as follows: [result/att < function-name/info [[arg1/att arg2/att ...] function-name shows the name that APL currently associates with the external routine. /info shows the name and entry point of the shared image that contains the external routine. The shared image name is preceded by /IMAGE:, and the entry point name is preceded by /ENTRY:. If the external symbol defines a APL Reference Manual 2-117 System Variables and Functions [0 MAP Defining External Routines to APL global constant instead of an entry point, then the symbol name is preceded by /VALUE:. argn/att ... shows the names and attributes of the external routine’s formal parameters. The attributes describe the settings for /ACCESS, /TYPE, and /MECHANISM that APL associates with each formal parameter. If you did not specify a value for any of the attributes when you defined the external routine, monadic [JMAP reports the following default selections: /ACCESS:IN, /TYPE: Z, and /MECHANISM:UNSPECIFIED (APL does not choose a default mechanism until you call the external routine). result[ att shows the name and attributes of the result that is returned by the external routine if there is one. the attributes describe the settings for the following: /TYPE, which you defined with dyadic OMAP; and /MECHANISM, which APL determines based on the value for /TYPE. Monadic JM¥AP does not report the /ACCESS attribute, which is assumed to be /ACCESS:0UT by definition. If the routine does not return a result, then monadic 0 M4P does not report a value for result/att. The result of monadic JM¥AP contains one blank before each formal parameter, and one blank following the <« symbol (unless the function has no result). Both monadic and dyadic OMXAP are described in Chapter 6 of the VAX APL User’s Guide. Possible Errors Generated Dyadic Form 9 2-118 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (ILLEGAL EMPTY ARGUMENT) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (EFRROR ACTIVATING IMAGE) 15 DOMAIN FRROR (EXTRANFEOUS CHARACTERS AFTER COMMAND) 15 DOMAIN ERROR (FUNCTION NAME MISSING) 15 DOMAIN ERROR (ILL FORMED NAME) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions [1MAP Defining External Routines to APL 15 DOMAIN EFRROR (INCORRECT PARAMFETER) 15 DOMAIN ERROR (INVALID FILFE SPECIFICATION) 15 DOMAIN ERROR (KEY NOT FOUND IN TREE) 15 DOMAIN ERROR (NAME IN USE) 15 DOMAIN ERROR (OPERATION SUSPENDED OR PENDENT) 15 DOMAIN ERROR (WILDCARDS NOT ALLOWED IN FILE SPEC) 27 LIMIT ERROR (ARGUMENT TOO LONG) Monadic Form 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (EXTRANEOUS CHARACTERS AFTER COMMAND) 15 DOMAIN FRROR (INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN EXTEFRNAL FUNCTION) APL Reference Manual 2-119 System Variables and Functions 0 MBX Mailbox System Function [1 MB X Mailbox System Function Type System Function Form mailbox-info < OMBX chans Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value ~ 999 through 399 (but not 0) Result Domain Type Integer Rank 1 or 2 Shape Vector or matrix (n by 3) Depth 1 (simple) Description OMBX returns information on the status of mailboxes. For each channel specified, O MBX returns a row of three elements denoting (from left to right): * The physical device number assigned to the mailbox (or 0 if the mailbox is remote, and ~ 1 if the channel is not associated with a mailbox). * The Process IDentification number (PID, returned by OUL) of the last user to receive a message you sent to the mailbox (or ~ 1 if no messages have been sent). * The PID of the last user from which you received a message in the mailbox (or ~ 1 if no messages have been received). The result is a matrix (or a vector if the argument is a singleton) with the shape n by 3, where n is the length of the argument. 2-120 APL Reference Manual System Variables and Functions 0 MBX Mailbox System Function To return a value for JM¥BX, APL must open the mailbox if it is not already open. (For a list of commands that open files, see the VAX APL User’s Guide.) For channel numbers represented in the argument by positive integers, APL opens the mailbox for input; for channel numbers represented by negative integers, APL opens the mailbox for output. Note that whether a mailbox 1is opened for input or output is not significant, because APL treats mailboxes like terminals: it allows both input and output at the same time, even in sequential modes. | OMBX is described in the VAX APL User’s Guide along with other file I/0O information. Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 15 DOMAIN FRROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-121 System Variables and Functions OMONITOR Gathering Data on Operations LIMON I TOR Gathering Data on Operations Type System Function Form success [ fatlure < line-numbers QMONITOR operation-names monitor-database « [1MONITOR operation-name Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Character Rank 1 0r?2 Shape Matrix domain Depth 0 or 1 (simple) Result Domain Type Integer (dyadic) or Boolean (monadic) Shape Vector or matrix (n by 3) Depth 1 (simple) Description OMONITOR 1s a debugging tool that allows you to gather statistics on an operation. These include the following: * The execution count, or the number of times an operation or operation line 1s invoked while JMONITOR is enabled. The possible range is 0 to ~ 1 + 2%31. 2-122 APL Reference Manual System Variables and Functions [0MONITOR Gathering Data on Operations * The accumulated CPU time charged to an operation or operation line while O0MONITOR is enabled. The possible range is 0 to ~ 1 + 2x31 milliseconds (about 24.5 days). If either of these statistics overflows its range, its value is reset to 0, and the data collection continues. Once JMONITOR is enabled, APL collects data from the moment the operation (or operation line) receives control to the moment it relinquishes control. APL increments the execution count each time the control is relinquished and registers the accumulated CPU time from the beginning moment to the ending moment. If the operation (or operation line) calls another operation, the result includes the time required to execute this second operation. You can view a monitored operation with the )EDIT command, but if you modify the operation with YEDIT, O0FX, or OMAP, you will disable JMONITOR and lose any collected data. If you view the operation with the Ao editor, you can change the contents of individual lines without affecting the status of OMONITOR. Note that you cannot add or delete lines or modify the header of a monitored operation with the A editor. The dyadic form of O¥ONITOR enables and disables monitoring of an operation. The form used is as follows: success/failure <line-numbers OMONITOR operation-names The right argument identifies the user-defined operations you want to monitor. It belongs to the character matrix domain, and each row specifies one operation name. The operations must be user-defined, and they must be unlocked. You can also monitor line O of external functions (this has the same meaning as monitoring line 0 of a user-defined operation). When the same operation name applies to more than one operation in the workspace, APL monitors the most local one. The left argument identifies the lines you want to monitor. It belongs to the near-integer vector domain. The line numbers can be in any order. APL 1gnores negative line numbers, repeated line numbers, and line numbers that do not appear in the operation. If the left argument contains a 0, APL monitors the entire operation. APL Reference Manual 2-123 System Variables and Functions OMONITOR Gathering Data on Operations The result of dyadic JMONITOR is a Boolean vector. Each position in the vector corresponds to a row of the right argument. A 1 means that the attempt to enable [ MONITOR was successful, and a 0 means the attempt was unsuccessful. If the right argument is empty, the result is also empty. For example: PHASEONE < [BOX 'FOO DOUBLE MOVE SPREAD FINAL' (150) [UMONITOR PHASEONE 0000¢0 A PARENTHESES REQUIRED - To disable OMONITOR, use the dyadic form with an empty left argument, as follows: (10) OMONITOR '"DESIGN' 1 [JMONITOR on an operation that is already being monitored, APL reinitializes any previously collected data. If you want to use this data before losing it, you must retrieve it with the monadic form of OMONITOR before you reset it with the dyadic form. monitor-database +~ OMONITOR operation-name The monadic form of DMONITOR queries for any collected data. The argument must be in the character matrix domain, and must have at most one row; you must query for JMONITOR information one operation at a time. Note that the operation must be unlocked and user-defined. Monadic I1MONITOR returns an n by 3 numeric matrix, where n is the number of monitored lines. Each row of the matrix contains the current data for each line since [IMONITOR was enabled. The result is formatted as follows: line-number execution-count cpu-time-in-milliseconds For example: OMONITOR 1 2-124 1 'F0O' 20 2 5 104 3 5 96 4 1 20 APL Reference Manual System Variables and Functions O0MONITOR Gathering Data on Operations The result is an empty 0 by 3 matrix in the following five instances: * The right argument is empty * The right argument does not specify an operation name * The operation does not exist * The operation is locked * The operation is not being monitored Possible Errors Generated The Dyadic Form 9 RANK FRROR (NOT MATRIX DOMAIN) 9 RANK FRROR (NOT VECTOR DOMAIN) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPE) 15 DOMAIN FRROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) Monadic Form 9 RANK ERROR (NOT MATRIX DOMAIN) 10 LENGTH FRROR 15 DOMAIN ERROR 15 DOMAIN ERROR (INCORRECT TYPE) (ENCLOSFED ARRAY NOT ALLOWED) APL Reference Manual 2-125 System Variables and Functions 00 NC Returning a Name Classification [1 N C Returning a Name Classification Type Monadic System Function Form name-class-list « ONC name-list Argument Domain Type Character Shape Matrix domain Depth 0 or 1 (simple) Result Domain Type Integer Rank 1 Shape 1 4+ p name-list Depth 1 (simple) Description ONC responds with the name class of each APL object that you specify in the argument. APL objects include user-defined objects, system variables, and system functions. Each row of the argument must contain the name of one object. The result has a length equal to the number of rows in the argument. If the argument to O 2-126 NC is empty, the result is 1 0. APL Reference Manual System Variables and Functions 0 NC Returning a Name Classification The possible name classes and values returned by ONC are as follows: ONC Name Classes and Values Value Name Class 20 Derived function 5 Niladic system function Ly Group 3 Monadic, Dyadic, or Ambivalent system function O Name not in use = Label N Il1l-formed identifier Variable w System variable 1 User-defined function £ 2 User-defined operator Examples: JFNS AVER MEAN ) VARS A B C TOT ONC TAVER' 3 aNec 'c! ONc 'ONc! 2 3 ONC 5 22 20 Lp'A ToT IO MEANB ' 1 APL Reference Manual 2-127 System Variables and Functions N C Returning a Name Classification Note that ONC returns the current local rather than global name classification of the object. For example: RF IS A FUNCTION AND A VARIABLE VF; F [1] F«<1 o ONC 'F' [BRFAK 'STOP F' ¥ aTHIS QUERY RETURNS THAT F IS A FUNCTION 3 F REXECUTE F, WHICH GETS SUSPENDED STOP F ONC 'F! aNOW THE MOST LOCAL F IS A 2 Possible Errors Generated 9 2-128 RANK ERROR (NOT MATRIX DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN EFRROR (INCORRECT TYPE) APL Reference Manual VARIABLE System Variables and Functions ONG Print High Minus [] NG Print High Minus Type System Variable Form ONG <« near-integer-singleton integer-scalar < NG Value Domain Type Near-Integer Shape Singleton Depth 0 or 1 (simple) Value 0,1,0r?2 Default 1 (high minus sign) Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description ONG controls the output representation of the APL negative sign, the high minus (). ONG affects the primitive functions monadic and dyadic format and the system functions O0F71, O0VI, and OFMT. The following table describes the display of the minus sign for each of the possible values for ONG. Value Meaning in APL Output 0 The minus sign (-) is used as the negative sign. 1 The higH minus sign =~ (NG in TTY mode) is used as the negative sign. 2 The ASCII minus sign (- ) is used as the negative sign. APL Reference Manual 2-129 System Variables and Functions O0NG Print High Minus When [0NG = 2, negative numbers are preceded by an APL "+" symbol when formatted by * and OFMT. Because APL "+" prints as an ASCII "-", you can use [0NG = 2 to handle negative numbers in strings that will be read or written in ASCII. Note that 0FI and (0 VI recognize negative numbers that are preceded by an APL "+" symbol as negative numbers. The value of NG is saved when you save the active workspace, and JNG can be localized in user-defined operations. Possible Errors Generated 2-130 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions [0 NL Constructing a List of Names [] NL Constructing a List of Names Type Ambivalent System Function Form name-list <« [I1NL name-classes name-list < letter-list (1NL name-classes Left Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Character Rank 2 Shape Matrix Depth 1 (simple) Description NI lists the names of all existing APL objects belonging to the name classes specified in the argument. APL objects include user-defined objects, system variables, and system functions. APL Reference Manual 2-131 System Variables and Functions O NL Constructing a List of Names The right argument specifies one or more name classes. The possible values for the right argument and the classes those values represent are as follows: Value Names Returned -5 Niladic system functions Ty Groups ~ 3 Monadic, dyadic, and ambivalent system functions T2 System variables 1 Labels 2 User-defined variables 3 User-defined functions L User-defined operators Note that ONL returns the current local name of an object rather than the global name. For example: VE, F [1] F<«1 RF IS A o [BREAK 'STOP F' FUNCTION (3) AND A VARIABLE (2) V ONL 3 ATHIS QUERY RETURNS THAT F IS A FUNCTION F REXECUTE F, ONL 2 aNOW THE MOST LOCAL F IS A VARIABLE ONL 3 AaTHE FUNCTION F IS NO LONGER LISTED F WHICH GETS SUSPENDED STOP F F (APL outputs a blank line.) The result of ONL is a character matrix. If the right argument is empty, or if there are no objects belonging to the specified name class, the result is 0 0 p '+, Otherwise, each row contains the name of one object. All rows have the NI pads the ends of the shorter names with blanks. same number of columns; APL returns the objects of each name class in AV order. When the right argument specifies more than one name class, APL catenates the alphabetical lists without merging them together. The order of the lists is as follows: 2-132 * Niladic system functions * DMonadic, dyadic, and ambivalent system functions * System variables ® User-defined names APL Reference Manual System Variables and Functions O NL Constructing a List of Names The dyadic form of ONL allows you to restrict the name list to names beginning with the characters in the left argument. For example, the following constructs a name list of function names whose initial letters are 4 through F: NLIST<« "ABCDEF' [INL 3 The left argument of ONL, if used, must be a character array whose shape is in the vector domain. The order of the characters does not affect the DAV order of the result. APL ignores the left argument if it is empty. Note that the first character of a system function or system variable is the 0 symbol; if you use the dyadic form of ONL and specify either 5, ~ 3, or ~ 2 in the right argument, APL ignores the [ as it searches for the names beginning with the letters contained in the left argument. The following example shows the construction of a matrix containing the names of variables in the active workspace that begin with the letter V: NLIST«'V' ONL 2 NLIST VAR1 VAR? VAR203 VBMAX The ONL system function is useful for a variety of purposes. For example: e [JNL can interact with (1 CR to create functions that automatically display the definitions of some or all the functions in the workspace. e With OFEX, ONL can dynamically erase all the named objects in a certain category. You can also use ONL to design a function that will clear a workspace of all but a preselected collection of named objects. e In its dyadic form, ONL can guide you in choosing names while you develop or interact with a workspace. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (NOT A LETTER) 15 DOMAIN ERROR (NOT AN INTEGER) APL Reference Manual 2-133 System Variables and Functions ONL Constructing a List of Names 2-134 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions [0 NUM Digits [ NUM Digits Type Niladic System Function Form ' < [QNUM '0123u456789" Result Domain Type Character Rank 1 Shape 10 Depth 1 (simple) Description [INUM is a subset of 1AV. ONUM returns a vector of the 10 digits 0123456789, or, expressed in terms of JAV: OAVIu48+110] For example: ONUM 0123456789 HI0+0 O0AVONUM 48 49 50 51 52 53 54 55 56 57 Possible Errors Generated None. APL Reference Manual 2-135 System Variables and Functions [0 OM Indexing a Boolean Vector [1 OM Indexing a Boolean Vector Type Monadic System Function Form indexes < [10M near-Boolean Right Argument Domain Type Near-Boolean Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Integer Rank 1 Shape +/near-Boolean Depth 1 (simple) Implicit Arguments 010 (0oM B when 010 « 1 is identical to1+ JOM B when [JIO « 0 Description 0 oM produces indexes showing the locations of the 1s in a Boolean vector. If the argument is empty, the result is 1 0. For example: MERZ <« 00 0101110010 OM MERZ 46 7 8 11 A « '"THE QUICK BROWN FOX' oM 4 4 10 = ' ! 16 Note that the following definition applies: 2-136 APL Reference Manual JOM 4 <~ A4/1p .4 System Variables and Functions [0 oM Indexing a Boolean Vector Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual 2-137 System Variables and Functions 00 PACK Packing and Unpacking Data L] PA CK Packing and Unpacking Data Type success [ fail < data-packets 0 PACK variable-names Monadic Argument Domain Type Character Shape Matrix domain Depth 0 or 1 (simple) Monadic Result Domain Type Integer Rank 1 Shape Vector Depth 1 (simple) Dyadic Left Argument Domain Type Near-integer Shape Vector Depth 1 (simple) Dyadic Right Argument Domain Type Character Shape Matrix domain Depth 0 or 1 (simple) Dyadic Result Domain 2-138 Type Boolean Rank 1 Shape Vector Depth 1 (simple) APL Reference Manual System Variables and Functions 0 PACK Packing and Unpacking Data Description 0 PACK allows you to pack and unpack data of different types into a single variable known as a packet. The monadic form packs data, and the dyadic form unpacks it. N PrAck differs from [ coQ and 0CIQ because it allows you to pack and unpack variables of different data types with only one invocation of the 1 PACK function. (Otherwise, to pack variables you invoke [ C0Q once for each data type, and then catenate the results into a single variable; to unpack a variable you undo the catenation and then invoke [0CIQ once for each data type.) Unlike 00 ¢c0q, O0PACK does not convert data into different data types before packing it. Use monadic [JPACK to pack data. When you specify a single variable, ] PACK creates a []C0Q packet with a header; it does not perform any data type conversion before creating the packet. When you specify more than one variable, J PACK creates individual 0 C0¢Q packets for each variable and combines them in a single logical record. The argument to the monadic form contains the names of the user-defined variables you want to pack. If the argument to monadic 0 PACK is empty, then the result is 1 0. Use dyadic 0 PACK to unpack data. The left argument must be a vector; it identifies a packet that was created by monadic [J PACK. The right argument contains the names you want to assign to the individual packets as they are unpacked from the left argument. It must have one row for each individual packet in the left argument. Each name can have a name class of 0 or 2 (undefined name or user-defined variable). When the name class is 0, the variable becomes defined. When the name class is 2, APL redefines the variable. If the right argument contains a blank row, APL does not unpack the individual packet associated with that row. The result indicates whether the names contained in the right argument have been successfully assigned the [ ¢IQ value of the individual packets. A 0 indicates an unsuccessful assignment (caused by a blank row in the right argument), and a 1 indicates a successful assignment. Each position in the result corresponds to a row in the right argument. If the left or right argument is empty, then the result is 1 0. The header generated by 0 PACK has the following format: APL Reference Manual 2-139 System Variables and Functions [0 PACK Packing and Unpacking Data length =4 +n type =1 rank =1 n start of 0°°9 packets end of 0°°9 packets NU-2235A-RA Each large box represents a longword. length is the length of the result (an integer vector) of monadic 1 PACK. type always has a value of 1, indicating 32-bit integers. rank is always 1. n indicates the length of the data section of the packet. The data section (elements 5 through 5 + n) contains the integer representations of the individual packets. The following example shows how the individual packets created by 0 P4ACK relate to the packets created by 0C1q. Note the use of 1B0X in the right argument to dyadic 0 PACK; it is used to facilitate the entry of the names of the individual packets as a character matrix: A+15 B«2 4 p '"ABCD' 0« 44 <« 4 [JC0qQ 2 911512345 [0 « BB <« B [JC0Q 2 52 2 4 1684234849 1684234849 D<+[JPACK [JBOX 'A B ! D 201116 9115123457522 0 « N « (pdd) + pBB 16 D= ((N+4), D [PACK [JBOX 2—-140 APL Reference Manual 1 1, '"AAA N),AA,BB 4 1684234849 1684234849 System Variables and Functions 00 PACK Packing and Unpacking Data AAA 12345 AAA = 4 BBB ABCD i BBB e ABCD Possible Errors Generated 9 RANK ERROR (MUST BFE VECTOR) 9 RANK ERROR (NOT MATRIX DOMAIN) 10 LENGTH ERROR (ITEM COUNT MISMATCH) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (ILLEGAL NAME CLASS) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (INVALID CIQ HEADER) 15 DOMAIN ERROR (INVALID LENGTH IN PACK HEADER) 15 DOMAIN ERROR (INVALID RANK IN PACK HEADER) 15 DOMAIN ERROR (INVALID RHO VECTOR IN PACK HEADER) 15 DOMAIN ERROR (INVALID TYPE IN PACK HEADER) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO BIG) APL Reference Manual 2-141 System Variables and Functions 00 PP Print Precision [] PP Print Precision Type System Variable Form 00 PP <« digits-of-precision integer-scalar < [ PP Value Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value 1 to 16 Default 10 Result Domain Type Integer Rank 0 Shape 10 Depth 0 (simple scalar) Description [1 PP determines how many significant digits are displayed in APL floating- point output. It does not affect the display of integers or the precision of internal calculations. It does affect the conversion of numbers to characters by the dyadic format function or the display of floating-point constants in JCR and 0 VR. Legal values for [1 PP are the integers 1 through 16. The default is 10. APL rounds off numbers that contain more digits than the setting. For example: 2-142 APL Reference Manual System Variables and Functions [0 PP Print Precision 0PP 10 123456789.123456789 123456789.1 [OPP<5 123456789.123456789 1. 2346E8 OPP+15 123456789.123456789 123456789.123457 OPP+«10 aLEADING ZEROS ARE NOT SIGNIFICANT aNOTE THAT ROUNDING MAY MAKE RESULT aHAVE FEWER THAN (PP DIGITS ed<2 1p1 4 =+ 101 .009900990099 .0396039604 [JPP<«11 A .009900990099 .039603960396 [JPP+«12 A 0. 009390099009901 0 .039603960396 The value of 0 PP 1s saved when you save the active workspace and can be localized in user-defined operations. Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPFE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual 2-143 System Variables and Functions 00 PW Print Width [1 PW Print Width Type System Variable Form [0 PW < print-posttions integer-scalar < [ PW Value Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value 35 to 2048 Default Determined when APL is invoked Result Domain Type Integer Rank 0 Shape 10 Depth 0 (simple scalar) Description 00 PW specifies the maximum number of characters that can appear on a terminal output line before a <CR><LF> is performed. [0 P¥ has no effect on the length of input lines. The default uses the current VMS setting for set terminal/width=n. If an output line requires more than 0 PW character positions, printing continues on succeeding indented lines. For example: JPW<35 A<'THIS IS A TEST OF THE PRINT WIDTH VARIABLE' A THIS IS A TEST OF THE PRINT WIDTH ARIABLE 2-144 APL Reference Manual V System Variables and Functions O PW Print Width However, if a line in an error message is longer than [JP¥ characters, it is truncated; it is not continued on the next line. If truncating the line prevents APL from displaying the particular point in the line at which the error was discovered, APL cuts off enough characters from the beginning of the line to allow the part in error to be displayed. The value of [0 P¥ is saved when you save the active workspace and can be localized in user-defined operations. When you exit from APL, the original terminal-width value is restored. Actually, APL never changes your terminal width; in effect, it overrides the width by preventing lines from wrapping and then by formatting any output based on the value of 0 PWw. Note that if you interrupt your APL session (for example, by executing a ) PUSH command) and then execute an operating system command to change the value of the terminal width, the value of [J P¥ is not changed when you return to APL. For example: )CLEAR CLEAR WS [PW aRUPW INITIAL VALUE = SYSTEM TERM WIDTH JPW<65 RCHANGE [JPW TO 65 AINTERRUPT APL SESSION 80 ) PUSH $SET TERMINAL/WIDTH = 72 $ LOGOUT Process USER logged out at [PV 16-NOV-1990 13:24:43.11 aQPW NOT CHANGED TO 72 65 If you exit APL via a panic exit, your system terminal width takes effect, but your terminal retains the APL setting that prevents lines from wrapping, regardless of the way wrapping was handled before you began your APL session. If you want lines to wrap, execute the DCL command set terminal /wrap. Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (NOT SINGLETON) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED ) APL Reference Manual 2-145 System Variables and Functions [0 PW Print Width 2-146 15 DOMAIN ERROR (INCORRECT TYPF) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions 0 Qco Copying Objects from a Workspace [1 @ CO Copying Objects from a Workspace Type Monadic System Function (quiet) Form message <~ 1QC0 wsname [object-names] Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Qualifiers /PASSWORD [[:pwj If a workspace is saved with a password, you must specity the password to copy objects from the workspace. /CHECK The optional /CHECK qualifier causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). If damage is detected, a message is displayed and APL tries to recover as much information as possible from the workspace and continues the copy. The recovered workspace may be missing APL variables, user-defined operations, and other APL objects that were damaged. The user must determine what named objects have been removed from the workspace. APL Reference Manual 2-147 System Variables and Functions 0QC0 Copying Objects from a Workspace Description 0@co (quiet copy) retrieves global objects from a workspace and places them into your active workspace. The argument has four parts: the name of the workspace from which you want to copy the objects, an optional password, an optional qualifier (/ CHECK ), and an optional list of objects to be copied. Use the list of objects to identify the specific objects you want to copy. If you omit the list, all global user-defined operations, global variables, and groups are copied. When you specify the objects, you can use the * and + wildecards. Note that 0QC0 does not transfer local values for variables, functions, and operators, nor does it copy the state indicator or system variables like the print width, index origin, or significant digits settings. The 0@CO system function performs the same operation as the )copy system command (see Chapter 3). 1QC0 returns as its result a character vector containing the usual ) COPY command message. However, because JQCO is a quiet function, if it is the leftmost function in the statement, its result is not displayed on the terminal unless there is an error (warnings are not displayed). For example: )COPY AB SAVED TUESDAY CALC 6-NOV-1990 17:49:10.1Y4 16 BLKS ) CLEAR CLEAR WS 0QCO 'AB CALC! ) CLEAR CLEAR WS | MSG<0QCO 'AB CALC TOT! MSG SAVED TUESSDAY NOT FOUND: 6-NOV-1990 17:49:10.14 13 BLKS TOT If your active workspace contains objects with the same names as those in the copied workspace, 1QC0 replaces the global (but not the local) values in your active workspace with the copied ones. For example, if B is a variable in the active workspace with a global value of 10 and a local value of 9, and the workspace being copied has a variable B with a global value of 20, the active 1QC0 executes will have a variable B with a global value of 20 workspace after and a local value of 5. A pendent or suspended operation is not replaced, and an operation being created in the workspace being copied is not copied. 2—-148 APL Reference Manual System Variables and Functions 0QC0 Copying Objects from a Workspace When you copy a group, all members of the group are copied along with their values. However, if a member of a group is itself a group, APL copies only the group name and not its values. For example, suppose the group GROUP1 has as members the variables 4 and B, and the group GROUP2. Also suppose that GROUP?2 has as members the variables ¢ and D. Then, if you copy GROUP1, you copy the values of 4 and B, but only the name of GROUP2, not the values of C and D. If the object list contains objects that are not in the specified workspace, APL returns the warning message NOT FOUND followed by the names (separated by tabs) that were not found. The objects that were found are still copied, however. Examples: )CLEAR CLEAR WS YCOPY T A B SAVED TUESDAY 6-NOV-1990 17:51:20.88 13 BLKS 17:51:20.88 13 BLKS A 1 B 2 C 11 VALUE ERROR C A )CLEAR CLEAR WS MSG+<[QCco 'T! MSG SAVED TUESDAY 6-NOV-1990 )CLEAR CLEAR WS MSG«<QCO 11 'T A B' VALUE ERROR C A APL Reference Manual 2-149 System Variables and Functions 0 QC0 Copying Objects from a Workspace )CLEAR CLEAR WS JCOPY T A D SAVED TUESDAY NOT FOUND: 6-NOV-1990 17:51:20.88 13 BLKS 17:51:20.88 13 BLKS D A 1 B 11 VALUE ERROR B A )CLEAR CLEAR WS MSG«<J@CO 'T A D' MSG SAVED TUESDAY NOT FOUND: 6-NOV-1990 D pMSG 59 Possible Errors Generated 9 2-150 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (ILLEGAL EMPTY ARGUMENT) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (FILFE SPECIFICATION IS MISSING) 15 DOMAIN FRROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions 0 QLD Loading a Workspace ] & LD Loading a Workspace Type Monadic System Function (quiet) Form QLD wsname Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain None. Qualifiers / PASSWORD [:pwi] Specifies the password used when the workspace was saved. If a workspace is saved with a password, you must specify the password to copy objects from the workspace. /CHECK The optional /CHECK qualifier causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). If damage is detected, a message is displayed and APL tries to recover as much information as possible from the workspace and continues the copy. The recovered workspace may be missing APL variables, user-defined operations, and other APL objects that were damaged. The user must determine what named objects have been removed from the workspace. You must use the ) SAVE command if you want to maintain an undamaged version of the recovered workspace. APL Reference Manual 2-151 System Variables and Functions 0QLD Loading a Workspace Description 0QLD (quiet load) makes the specified workspace the active workspace by replacing the currently active workspace and destroying its contents. The argument has three parts: the name of the workspace to be loaded, an optional password, and an optional qualifier (/CHECK). For example, the following loads a workspace named 4BC, which was saved with the password JOHN: OQLD '"ABC/PASSWORD: JOHN' Note that the 0 QLD system function performs the same operation as the )L0AD system command (see Chapter 3), but 0QLD does not print messages on the terminal unless there is an error. 0QLD does not return a result in the usual sense or display a message when it 1s successful, because the context in which QLD was executed is replaced by the loaded workspace. If the 0 LX system variable has a value in a workspace, it executes when 0QLD 1s used to load the workspace, except if the top of the state indicator stack contains an execute function (see the Execute function described in Chapter 1 for details), or if the workspace was saved in function-definition mode (if it was, you remain in function-definition mode after the workspace is loaded). If the workspace was saved inside [1 input, the JLX expression is executed only after the pendent 0 input is removed from the state indicator stack. For example: A 1 )CLEAR CLEAR WS 0qQLp '1 YWSID T A 1 Possible Errors Generated 9 2-152 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (ILLFGAL EMPTY ARGUMENT) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) APL Reference Manual System Yariables and Functions 0 QLD Loading a Workspace 15 DOMAIN ERROR (FILE SPECIFICATION IS MISSING) 15 DOMAIN ERROR (INCORRECT TYPFE) APL Reference Manual 2-153 System Variables and Functions 0 QPC Copying Objects with Protection [1 & PC Copying Objects with Protection Type Monadic System Function (quiet) Form message «~ [1QPC wsname [lobject-names] Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Qualifiers /PASSWORD [:pwl Specifies the password used when the workspace was saved. If a workspace is saved with a password, you must specify the password to copy objects from the workspace. /CHECK The optional /CHECK qualifier causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). If damage is detected, a message is displayed and APL tries to recover as much information as possible from the workspace and continues the copy. The recovered workspace may be missing APL variables, user-defined operations, and other APL objects that were damaged. The user must determine what named objects have been removed from the workspace. You must use the ) SAVE command if you want to maintain an undamaged version of the recovered workspace. 2—-154 APL Reference Manual System Variables and Functions [0 QPC Copying Objects with Protection Description 0QPC (quiet copy with protection) is the same as the 0QC0O system function except that 0QPC does not replace objects in the active workspace with objects of the same name in the copy workspace. Instead, APL returns the warning message NOT COPIED followed by the names of objects (separated by tabs) that were not copied. As with 01QcC0, the argument for [ QPC represents the name of the workspace from which you want to copy the objects, followed by three optional items: a password, a qualifier (/CHECK), and a list of objects. When you specify the objects, you can use the » and + wildcards. When copying groups, 0 QPC does not copy any members of the group that have the same name as a name already in the active workspace. If the group name itself is the same as a group name in the active workspace, APL does not copy the group name or any members of the group. If the list to be copied contains an object that is not in the specified workspace, APL returns the warning message NOT FOUND, followed by the names of the objects (separated by tabs) that were not found. The objects that were found are still copied, however. The 0 QPC system function performs the same operation as the ) PCOPY system command (see Chapter 3). JQPC returns as its result a character vector that contains the usual ) PCOPY command message. However, because 1QCO0 1s a quiet function, if it is the leftmost function in the statement, the result is not displayed on the terminal unless there is an error (warning messages are not displayed). Examples: )CLEAR CLEAR WS A<20 JPCOPY SAVED TUESDAY NOT COPIED: T 6-NOV-1990 17:51:20.88 13 BLKS A A 20 B 2 ¢ 3 APL Reference Manual 2-155 System Variables and Functions 0QPC Copying Objects with Protection )CLEAR CLEAR WS A<20 MSG+<JQPC 'T! MSG SAVED TUESDAY NOT COPIED: 6-NOV-1990 17:51:20.88 13 BLKS 17:51:20.88 13 A A 20 B 2 C 3 MSG<[JQPC 'T A D' MSG SAVED TUESDAY NOT FOUND: NOT COPIED: 6-NOV-1990 BLKS D A pMSG 74 Possible Errors Generated 9 2-156 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (ILLFEGAL EMPTY ARGUMENT) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (FILE SPECIFICATION IS MISSING) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions [0 R Monitoring Variable Changes [] R Monitoring Variable Changes Type System Variable Form UR < any old-value <« OR Value Domain Type Any Shape Any Depth Any Default i Result Domain Type Any Rank Any Shape Any Depth Any Description O0R and 0L are system variables that are implicitly used by OWATCH. DWATCH 18 a system function that is used to monitor any changes in one or more variables. When a change occurs in a monitored variable, APL assigns information to OR and [ L: OR contains the previous value of the changed variable; ] L contains a character vector showing the name of the variable that has changed. APL assigns this information regardless of whether monitoring is set for signal or display mode. Immediately after a OWATCH event occurs, JR and JL contain the new information resulting from the event. However, this information may change as an operation continues execution (this is especially true if an error occurs during an assignment or reference of a variable that is associated with a watchpoint). APL Reference Manual 2-157 System Variables and Functions [1R Monitoring Variable Changes Both OR and 0L can be localized, explicitly assigned values of any type, and saved in the workspace. Note that you cannot include OR or 0L in the right argument to dyadic OWATCH. Possible Errors Generated None. 2-158 APL Reference Manual System Variables and Functions ORELEASE Unlocking Shared Records [JRELEASE Unlocking Shared Records Type Monadic System Function (quiet) Form 10 <« QRELEASE chans Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value ~ 999 through 999 (but not 0) Result Domain Type Numeric Rank 1 Shape 0 (empty) Depth -1 (simple) Description ORELEASE unlocks any locked records in files associated with the channel numbers specified in the argument. The absolute values of chans represent the channels associated with the files you want to unlock. ORELEASE is quiet; it does not return a result if it is the leftmost function in a statement. When it is not the leftmost function, RELEASE returns an empty numeric vector. If its argument is empty, IRELEASE has no effect and its result is an empty vector. Note that APL performs a DRELEASE on all open files whenever a ) MON command is executed. If you read a record that you do not intend to rewrite, it is a good idea to unlock it as soon as possible, because other users who try to retrieve it are put in a wait state until the record becomes available. NRELEASE is described the VAX APL User’s Guide along with other file I/0 information. APL Reference Manual 2-159 System Variables and Functions ORELEASE Unlocking Shared Records Possible Errors Generated 9 2-160 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions P Replication [1RE [ RE P Replication Type Dyadic System Function Form A[OREP B AUREPLK] B Left Argument Domain Type Near-integer Shape domain Depth or 1 (simple) Right Argument Domain Type Any Shape Any Depth Any Result Domain Type as right argument Rank 1lfppB Shape ((K-1)ApB) ,(+/14),K+vpB (for 010 1) Depth 17 =B Implicit Arguments None. Description OREP builds arrays by specifying the items to be deleted, preserved, or duplicated from an existing array, and by indicating where fill items are to be added in the new array. When items are preserved or deleted, this is known as compression (the left argument is Boolean). When items are duplicated, deleted, or filled, this is known as replication (the left argument is integer). APL Reference Manual 2-161 System Variables and Functions P Replication [0 RE OREP works the same as the compress and replicate derived functions. The difference between O REP and the slash operator is that you can use OREP as an operand to an operator. Operators cannot be used as operands to operators. OREP applies along the last axis of B unless modified by an explicit axis (X¥) in brackets. The shape of the result is the same as the original array B except along the applicable axis (p B) [X]. The shape of that axis becomes the sum of the absolute value of the items in 4(+/] 4). The following examples show JREP with the each (") operator. Although the variables 4 and C are nested in the examples, they conform to the left argument domain requirement that specifies a simple array. This is because the each operator reduces the nesting by one level: O«Ad«(1 0 1) (1 "1 t+----- S 110 0 2) + 1] |1 710 2| t-—=-- L + O0«B<(2 t---=- + +---+ |1 2 3| |4 5 6| |ABC| |DEF| tme-- + 3p16) . (4 3p'ABCDEFGHIJKL') |GHI| | JKL| +---+ aATTEMPT TO A/"B 15 USE OPERATOR AS ARG aAPL EVALUATES AS (4/)"B DOMAIN ERROR TO (ENCLOSED/HETEROGENEOUS ARRAY NOT ALLOWED) 4/°B AAPL EVALUATES AS (A/)"B A A OREP"B t---+ |1 3] |4 CC| |4 6| |D FF| t---+ AREPLICATE ITEMS OF B USING THE ITEMS OF 4 +----+ |G II| | J LL| t----+ A OREP[2]" B t---+ |1 3] |4 CC| |4 6| |D FF| t---+ aSECOND AXIS<«~ DEFAULT IN THIS CASE +----+% |G II| | J LL| t----+ 0«C<(2 "1 0) o= t 2-162 t------- + 12 71 0] |1 10 o= + t------- + 1| APL Reference Manual (1 10 1) System Variables and Functions P Replication [] RE ¢ OREP[1] B 2 3] |1 2 3| |1 0 0| |0 aUSE [JREP WITH AXIS ARGUMENT |ABC| |DEF| |JKL| Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) 29 AXIS LENGTH ERROR (NOT SINGLETON) 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) 30 AXIS DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 30 AXIS DOMAIN ERROR (INCORRECT TYPE) 30 AXIS DOMAIN ERROR (NOT AN INTEGER) 30 AXTS DOMAIN ERROR (AXIS LESS THAN INDEX ORIGIN) 30 AXTS DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) APL Reference Manual 2-163 System Variables and Functions O RESET Resetting the State Indicator [l RE'SE T Resetting the State Indicator Type Niladic System Function Form [1RESET Result Domain None. Description ORESET clears the state indicator. When the state indicator is clear, no userdefined operations are suspended, no quad input requests or execute functions are pending, and the ) SI system command (see Chapter 3) does not return a value. ORESET does not return a value. Possible Errors Generated None. 2-164 APL Reference Manual System Variables and Functions 0 REWIND Returning Next-Record Pointer to Start of File [l REWIND Returning Next-Record Pointer to Start of File Type Ambivalent System Function (quiet) Form 10 « OREWIND chans 1 0 <+ key-of-reference QREWIND chans Monadic Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value ~ 999 through 999 (but not 0) Dyadic Left Argument Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value o through 255 inclusive Dyadic Right Argument Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value ~ 999 through 999 (but not 0) APL Reference Manual 2-165 System Variables and Functions [ REWIND Returning Next-Record Pointer to Start of File Result Domain Type Numeric Rank 1 Shape 0 (empty) Depth 1 (simple) Description OREWIND allows you to reposition the next record pointer to the first record of a file without closing the file. The absolute values of chans represent the channels associated with the files you want to rewind. With the monadic form, you can specify a vector of channel numbers in the right argument. This will rewind each of the files associated with the specified channel numbers. If any of the files have a keyed organization, APL performs the rewind on the primary key of reference. Use the dyadic form for keyed files when you want APL to perform the rewind on a key of reference other than the primary key. The right argument specifies the channel number associated with the keyed file. The left argument specifies the key of reference. Zero (0) indicates the primary key, one (1) indicates the secondary key, and so on. You can specify only one file at a time when you invoke dyadic QREWIND. OREWIND is described in the VAX APL User’s Guide along with other file I/O information. Possible Errors Generated Monadic Form 2-166 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INTEGER TOO LARGE) 15 DOMAIN FRROR (NOT AN INTEGER) 15 DOMAIN ERROR (INVALID CHANNEL) 15 DOMAIN ERROR (CHANNEL NOT ASSIGNED) APL Reference Manual System Variables and Functions 0 REWIND Returning Next-Record Pointer to Start of File 15 DOMAIN ERROR (FILE IS ASSIGNED WRITE ONLY) 33 I0 ERROR (INVALID KEY OF REFERENCE FOR $GET/$FIND) Dyadic Form 9 RANK ERROR (NOT A SINGLETON) 15 DOMAIN ERROR (CHANNEL NOT ASSIGNED) 15 DOMAIN ERROR (CHANNEL NOT ASSIGNED TO A KEYED FILE) 15 DOMAIN ERROR (ENCLOSED HETEROGENEQOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (INVALID CHANNEL) 15 DOMAIN FERROR (NOT AN INTEGER) 15 DOMAIN FRROR (PARAMETER OUT OF RANGE) 27 LIMIT ERROR (INTEGER TOO LARGE) 33 I0 ERROR (INVALID KEY OF REFERENCE FOR $GET/$FIND) APL Reference Manual 2-167 System Variables and Functions (0RL Link [1 RL Link Type System Variable Form ORL <« random-seed integer-scalar < [ORL Value Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value ~ 2% 30 through = 1+2% 30 Default 695197565 Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description [O0RL sets the seed of the pseudo-random-number generator used with the roll and deal functions (see Chapter 1). ORL can be set by the user, and is also set implicitly by the system when roll and deal are executed. Every time you execute a roll or deal function, the value of the random link changes. The value of O RL is saved with a workspace and can be localized in user-defined operations. For example: 2-168 APL Reference Manual System Variables and Functions ORL Link ORL 695197565 5?5 4 2 3 1 5 ORL 47060346 575 4 1 2 3 5 ORL 1636171147 Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INC’ORREC’T.TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-169 System Variables and Functions [0SF Quad Input Prompt [0 SF Quad Input Prompt Type System Variable Form O0SF « prompt char-vector < [JSF Value Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Value prompt length< 255 keystrokes Default '0: <CR><LF> 6-spaces’ Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Description 0SF specifies the text to be used as the prompt for quad input (see the VAX APL User’s Guide). You can use any printing characters in the prompt. The prompt is printed each time a request is made for quad input (0). For example: 2-170 APL Reference Manual System Variables and Functions 0 SF Quad Input Prompt A<3+[J+5 O: 5 A 13 B+<{] O: 'INPUT! B INPUT OSF«'"WHAT IS YOUR NAME? C«({] WHAT IS YOUR NAME? 'CARLA' C CARLA Note that you must enclose character-type quad input in single quotation marks. The maximum length for 0 SF 1s 255 keystrokes (a keystroke occurs any time you press a key on the keyboard, including the Space bar and the Backspace key). The value of 0 SF is saved when you save the active workspace and can be localized in user-defined operations. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 27 LIMIT FRROR (ARGUMENT STRING IS TOO LONG) APL Reference Manual 2-171 System Variables and Functions O0SIGNAL Signaling Errors U SIGNAL Signaling Errors Type Ambivalent System Function Form error-number message-text 1 SIGNAL error-number Monadic Argument Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value Any APL error number (except 75, 115 to 499 or greater than 999) Dyadic Left Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Dyadic Right Argument Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value Any APL error number (except 75, 115 to 499 or greater than 999) Result Domain None. 2—-172 APL Reference Manual System Variables and Functions O0SIGNAL Signaling Errors Description 0SIGNAL allows you to signal an error to the caller of the operation in error; thus, the way a user-defined operation that executes 1 SIGNAL fails is similar to the way a primitive function fails. In both the monadic and dyadic forms, the right argument is the error number. You can use an existing APL error number (except 75) as listed in Appendix A, or you can define your own number (within the range 500 through 999). The left argument (dyadic form), if used, is the text of the error message for the error you are signaling. For example: "WILL NOT ACCEPT NEGATIVE NUMBERS' JSIGNAL 501 This statement, if executed within a user-defined operation (0 SIGNAL generally appears within a user-defined operation, but this is not a requirement), signals the following error: 501 WILL NOT ACCEPT NEGATIVE NUMBERS The message 1s followed by the rest of the APL standard three-line error message; that is, the text of the line in error and a caret pointing to the part of the line in error. The three-line error message generated by 0 SIGNAL becomes the value of 0 ERROR. If the error number you supply to 0 SIGNAL is the number of an APL error, the message displayed (and stored in JEFRROR) is the error message that coincides with that number (see Appendix A for a description of APL error messages), and the left argument to 1 SIGNAL becomes the secondary error message (displayed in parentheses following the primary error message). If you do not use an existing APL error number, and you leave the left argument blank, APL signals the following error: ERROR SIGNALED In the following example, notice that the error is signaled at the level of the caller, function #, not at function 7: APL Reference Manual 2-173 System Variables and Functions O0SIGNAL Signaling Errors RFUNCTION F HAS (SIGNAL VF 4 [1] ~(4>0)/3 [2] '"WILL NOT ACCEPT NEGATIVE NUMBERS' [3] "FUNCTION CONTINUING NORMALLY' [4] v [SIGNAL 15 AFUNCTION H CALLS F VH A F A v [1] [2] H5 FUNCTION CONTINUING NORMALLY 7 H 15 DOMAIN ERROR H[1] (WILL NOT ACCEPT NEGATIVE NUMBERS) F A A You can use error number 80 to signal a status condition to the DCL interpreter. The right argument to 0 SIGNAL must be 80, and the left argument is a character string representing a hexadecimal number that is the status code you want to return to VMS. The status code returned is stored as the value of the global symbol $STATUS. For example: '123ABC1" [SIGNAL 80 (APL returns control to DCL) S show symbol SSTATUS == $status "%X0123ABC1" The low-order three bits of $STATUS represent the severity level of the error signaled and are contained by the global symbol $SEVERITY. For example: S show symbol Sseverity SSEVERITY == "1" DCL command procedures interpret the $SEVERITY value 1 to mean success, and the value 2 to mean error. (For details on command procedures, see the Guide to Using VMS Command Procedures.) In the following command procedure, the first line means branch to the label ERROR any time $SEVERITY becomes equal to 2: on error then goto error S apl (APL statements) S write sysSoutput"No Error From APL" 2-174 APL Reference Manual System Variables and Functions 0 SIGNAL Signaling Errors S exit $ error: $ write sysSoutput"APL Returned Error" If '2' OSIGNAL 80 is executed during the APL session, the command procedure branches to ERROR and displays the message "APL Returned Error". If '1' OSIGNAL 80 is executed, the command procedure displays "No Error From APL" and then exits. For more information on the use of 0 SIGNAL, see Chapter 3 in the VAX APL User’s Guide. Possible Errors Generated 15 DOMAIN ERROR (CANNOT SIGNAL EOF) 15 DOMAIN ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLFETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRFECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) 15 DOMAIN FRROR (PARAMETER OUT OF RANGE) APL Reference Manual 2-175 System Variables and Functions 0 SINK Discard Output [1.51NK Discard Output Type System Variable Form O0SINK <« any-value 10 « JSINK Value Domain Type Any Shape Any Depth Any Result Domain Type Numeric Rank 1 Shape 0 (empty) Depth 1 (simple) Description 0SINK immediately discards any value that you assign to it. The value of O0SINK is always 1 0. 0 SINK is useful inside a user-defined operation; it allows you to discard output that you do not want stored or displayed. [0 SINK can be localized and is saved with the workspace; however, neither operation has any effect. Possible Errors Generated None. 2-176 APL Reference Manual System Variables and Functions [1.5S String Search [1.S5.S String Search Type Dyadic System Function Form Boolean «~ pattern-string 0SS target-string Left Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Right Argument Domain Type Character Shape Vector domain Depth 0 or 1 (simple) Result Domain Type Boolean Rank 1 Shape o ,target-string Depth 1 (simple) Description 1SS searches the right argument for every appearance of the character string specified in the left argument. This allows you to determine where a substring begins in the searched string. The result is a Boolean vector equal to the length of the ravel of the right argument. The function places a 1 in any position corresponding to the start of the specified string. For example: APL Reference Manual 2-177 System Variables and Functions (1SS String Search 'ISSI' (0SS 'MISSISSIPPI! 01001000000 O«MONTHS«4 11p'JAN FEB MARAPR MAY JUNJUL AUG SEPOCT NOV DEC! JAN FEB MAR APR MAY JUN JUL AUG SEP 0CT NOV DEC 4 11 p(rAUGY 0SS ,MONTHS) 000000O0O0O0CO0CO 000000O0O0O0CCO0CO 00001000000 000000O0O0OO0CO0CO Possible Errors Generated 9 2-178 RANK EFRROR (NOT VECTOR DOMAIN) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN EFRROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions 0.STOoP Suspending Operation Execution [1.STOP Suspending Operation Execution Type Ambivalent System Function (monadic form is query) Form line-numbers <« 0 STOP function-names success / fail < line-numbers 1 STOP function-name Monadic Argument Domain Type Character Shape Vector domain or one-row matrix Depth 0 or 1 (simple) Dyadic Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Dyadic Right Argument Domain Type Character Shape Matrix domain Depth 0 or 1 (simple) Result Domain Type Boolean (dyadic) or integer (monadic) Rank 1 Shape Vector Depth 1 (simple) APL Reference Manual 2-179 System Variables and Functions [0.STOP Suspending Operation Execution Description 0SToP allows you to suspend the execution of user-defined operations at specified lines. J.STOP is a useful debugging tool; you can use it to execute a portion of a user-defined operation, then to stop execution temporarily and examine the operation’s environment, including the values of its local variables. You can also stop execution at line 1 of an external routine. The external image containing the external routine must be linked with the /SHARE and /DEBUG qualifieres; APL causes VMS DEBUG to set a breakpoint at line 1 (the routine entry point). For dyadic 0STOP, the right argument identifies the operations you want to suspend. Each row should be the name of a valid, unlocked, user-defined operation or an external routine. The left argument specifies where you want to suspend the operations by naming the lines on which stop bits are to be set; the line numbers do not have to be 1n order. Negative line numbers and line numbers that do not appear in the operation are ignored. Note that line [0] can be stopped; APL suspends execution immediately before returning to the caller, thus enabling you to examine the operation’s environment after it has finished executing. The following example sets a stop bit at lines [5], [25], and [55] of the userdefined operations CALC and AVER: 5 25 55 [JSTOP 2 Up '"CALCAVER!' 11 Thus, if you run CALC or AVER, execution is suspended before line [5], and APL displays the operation name and the line number. Execution can be resumed if you type a branch to line [5], but it is suspended again at line [25], and so on. The result of dyadic 0.STOP is a Boolean vector that indicates whether stop bits were set for the objects named. A 1 in the position corresponding to the name in the right argument indicates that the stop bits were successfully set; a 0 indicates that stop bits were not set. 2—-180 APL Reference Manual System Variables and Functions [0.ST0P Suspending Operation Execution To clear all the stop bits associated with an object or objects, use 0 STOP with an empty left argument, as follows: (10) OSTOP 2 4p 'CALCAVER' 11 If you modify an operation with YEDIT, OFX, or QMAP, you clear any stop bits set with 0 sToP. (However, you can view an operation with )EDIT and not clear the stop bits as long as you do not perform any modifications.) If you edit an operation with the Ao editor, stop bits remain on existing lines (provided they are not modified) even if the lines are renumbered when the operation is closed. When operation execution is suspended because a stop bit was set for the line, STOPSET. Thus, you can trap stop bits with [ TRAP. APL signals In its monadic form, 0 STOP returns the line numbers (in ascending order) on which stop bits have been set for a specified operation. The right argument must contain only one row, which identifies the name of the operation. In the case of a stop bit that is set on an external routine, ] STOP returns a one-item vector with a value of 1 (the only allowable line). For example: OSTOP 5 25 'CALC! 55 If the argument is empty or contains a value other than the well-formed name of an unlocked operation, APL returns an empty Boolean vector. For more details about 05T0OP, see Chapter 3 in the VAX APL User’s Guide. Possible Errors Generated Dyadic Form 9 RANK FRROR (NOT MATRIX DOMAIN) 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT EFERROR (INTEGER TOO LARGE) APL Reference Manual 2-181 System Variables and Functions 0.5T0P Suspending Operation Execution Monadic Form 9 2-182 KRANK FRROR (NOT MATRIX DOMAIN) 10 LENGTH FRROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions 0 TERSE Terse Error Messages [ TERSE Terse Error Messages Type System Variable Form [0 TERSE <« terse-verbose integer-scalar <« JTERSE Value Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value 0 or1 Default 0 Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description Each APL error message (see Appendix A) consists of a primary error message (for example, VALUE ERROR or DOMAIN ERROR) and perhaps a secondary error message. The secondary message provides more information about why the error occurred. 0 TERSE determines whether or not secondary error messages are output. When OTERSE is 0, secondary error messages are printed; when it is 1, they are not printed. The default is 0. Note that APL always puts secondary error messages into JERROR, regardless of the value of 0 TERSE. The value of 0 TERSE is saved when you save the active workspace and can be localized in user-defined operations. APL Reference Manual 2-183 System Variables and Functions [0 TEFRSF Terse Error Messages Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 - DOMAIN ERROR 2-184 (INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions OTIMELIMIT User Response Time Limit OTIMELIMIT User Response Time Limit Type System Variable Form OTIMELIMIT < seconds integer-scalar < QTIMELIMIT Value Domain Type Near-integer Shape Singleton | Depth 0 or 1 (simple) Value ~1t0 255 Default 0 (unlimited response time) Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description OTIMELIMIT limits the amount of time allowed for responses to quote quad (M) or quad del (@) input requests. Note that you cannot set JTIMELIMIT on a VT220, VT240, VT320, VT330, VT340, or DECterm terminal designator. If, in responding to input requests, you exceed 0 TTMELIMIT seconds between characters, APL accepts only the characters you typed before you ran out of time, and appends a <CR><LF> to them. You can use the TIMEOUT system variable to check whether the time limit expired. In the following example, the user sets the time limit to 5 seconds, and then supplies a value for 4 before the time limit expires. However, the user does not finish entering a value for B before time expires, so APL accepts what was typed before time ran out. The six spaces after the last character (an angle APL Reference Manual 2-185 System Variables and Functions O0TIMELIMIT User Response Time Limit bracket) are APL’s input prompt, and the comment (a6 SPACES IS PROMPT) is terminal input. OTIMELIMIT<5 A<l YoU HAVE FIVE SECONDS A YOU HAVE FIVE SECONDS B+<{1 NOW STOP TYPING BUT NO <RETURN> ATIMELIMIT WAS EXCEEDED ON PREVIOUS LINE B NOW STOP TYPING BUT NO <RETURN> A negative argument (T 1) makes APL check for type-ahead input, that is, data that was placed in the input buffer before the quote quad or quad del input request was made. You can use this feature to help you determine whether anything was typed after the time limit expired. For example: VIIME (1] (21 [3] [u] [s1 [6] OTIMELIMIT+S O«'RESPOND WITHIN 5 SECONDS' A<l O«'TIMED 0UT' 1 OTIMELIMIT« B<[ (7] A,' [8] v o QOSINK<ODL 5 BEFORE TIMED OUT AND ',B,' aDL DELAYS EXECUTION AFTER' TIME RESPOND WITHIN 5 SECONDS I STOPPED TYPING TIMED 0OUT THIS IS TYPFAHEAD I STOPPED TYPING BEFORE TIMED OUT AND THIS IS TYPEAHEAD AFTER Because 1 TIMELIMIT was set to ~ 1 on line [5], the quote quad request on line [6] captured the input that was typed after time expired on the response to the first quote quad input request (line [3]), but before the second input request (line [6]) was made. You may also want to set 0TIMELIMIT to ~ 1 if you have written a function that checks periodically for a response to a poll or prompt. For example: 2-186 APL Reference Manual System Variables and Functions OTIMELIMIT User Response Time Limit VPOLL ; START [1] [2] [3] [4] [5] OTIMELIMIT<+ 1 [«'WHEN READY TYPE THE NUMBER 1 ' [OSINK<«[ODL 5 a[JDL DELAYS EXECUTION 5 SECONDS START+[] >(START = '"1')/7 [6] +3 [7] aEXECUTION BEGINS HERFE v (8] POLL WHEN READY TYPE THE NUMBER 1 14 The function POLL displays a message telling the user to respond with the number 1 when ready. Until the user enters 1, POLL loops between operation lines [3] and [6]; thus, POLL delays for 5 seconds, then checks whether the user typed 1 during the delay and, if not, branches back for another 5-second delay. When the user enters 1, control passes to line [7] and operation execution continues. The value of OTIMELIMIT is saved when you save the active workspace and can be localized in user-defined operations. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 15 DOMAIN ERROR (TIMEOUT READ UNSUPPORTED FOR CURRENT VALUE OF QUAD TT) 27 LIMIT ERROR (INTEGER TOO LARGEF) APL Reference Manual 2-187 System Variables and Functions OTIMEOUT Time Limit Report OTIMEOUT Time Limit Report Type System Variable Form OTIMEOUT <« 0-or-1 integer-scalar < JTIMEOUT Value Domain - Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value 0 or 1 Default 0 Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description OTIMEOUT queries the system to see whether response time expired for a previously executed quote quad ([1) or quad del (1) input request. (QTIMEOUT is set implicitly by the system when a timeout occurs, but can also be set by the user.) Its value is a Boolean scalar\ 1 means that time ran out, 0 means that it) did not. The amount of time the user has to respond to quote quad or del quad input requests is determined by the For example: 2-188 APL Reference Manual OTIMELIMIT system variable. System Variables and Functions O0TIMEOUT Time Limit Report OTIMELIMIT<S A<l YOU HAVE FIVE SECONDS OTIMEOUT aDID NOT RUN OUT OF TIME 0 A< NOW STOP TYPING BUT NO <RETURN> UTIMEOUT RTIMELIMIT EXCEEDED 1 You may set JTIMEOUT to 0 or 1. APL changes the value of 0 TIMEOUT only when you type one of the following: * Quote quad input from the terminal ([7) * Quad del input from the terminal () The value of 0 TIMEOUT is saved when you save the active workspace and can be localized in user-defined operations. Possible Errors Generated 9 KRANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN ERROR 27 LIMIT FRROR (INTEGER TOO LARGE) (SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) APL Reference Manual 2-189 System Variables and Functions 0 TLE Terminal Line Editing Characteristics [1 T L E Terminal Line Editing Characteristics Type System Variable (session) Form OTLE « 0-or-1 current-value < 1 TLE Value Domain Type Near-Integer Shape Singleton Depth 0 or 1 (simple) Value 0 or 1 Default Determined when APL is invoked Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description 0 TLE controls the terminal line editing attribute. You can assign a O or a 1 to OTLE. By default, 0 TLFE inherits the line editing status that is in effect when APL is started. Note that 0 TLF 1s a session variable; that is, its value 1s not saved with the workspace and 00 TLE is not reset by the execution of a ) CLEAR command (see Chapter 3). OTLE Equivalent DCL Command 0 $SET TERMINAL/NOLINE_EDITING 1 $SET TERMINAL/LINE_EDITING APL determines the default value for 0 TLE depending on your terminal designator. For LA, VT102, GIGI, KEY, BIT, HDS201, and HDS221 (terminals 2-190 APL Reference Manual System Variables and Functions [0 TLFE Terminal Line Editing Characteristics that form overstruck characters with the Backspace key), the default is 0. For VT220, VT240, VT320, VT330, VT340, DECterm and VS (terminals that form overstruck characters with the Compose key or Ctrl/D), the default is 1. In all other cases (TTY for example), the default is the same as the current VMS setting when APL is invoked. Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 10 LENGTH FERROR (NOT SINGLETON) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPF) 15 DOMAIN FRROR (NOT AN INTEGER) 15 DOMAIN ERROR (SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) 27 LIMIT ERROR (INTEGER TOO LARGE) APL Reference Manual 2-191 System Variables and Functions [1 TRACE Monitoring Operation Execution [1 TRA CE Monitoring Operation Execution Type Ambivalent System Function Form line-numbers « [0 TRACE function-name success [ fail « line-numbers 0 TRACE function-name Monadic Argument Domain Type Character Shape Vector domain or 1-row matrix Depth 0 or 1 (simple) Dyadic Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Dyadic Right Argument Domain Type Character Shape Matrix domain Depth 0 or 1 (simple) Result Domain Type 2-192 Integer (dyadic) or Boolean (monadic) Rank 1 Shape Vector Depth 1 (simple) APL Reference Manual System Variables and Functions [0 TRACEFE Monitoring Operation Execution Description [0 TRACE is a debugging tool that allows you to obtain intermediate results of operation execution. In the dyadic form, the right argument identifies the operations that you want to trace. Each row should be the name of a valid, unlocked, user-defined operation. You can also specify the name of an external routine. The left argument specifies the line numbers you want to trace. The line numbers do not have to be in order. Negative line numbers and line numbers that do not appear in the operation are ignored. When you trace line 0 of an operation, APL displays the result returned by the operation before the operation exits. For external routines, you can specify only line O. When you execute a line of an operation that has the trace bit set, APL displays the following information: ® The name of the operation * The line number being traced (always O for external routines) * The final value returned by the statement, provided that the value is not an enclosed array, in which case APL displays a message indicating an enclosed value When the statement traced is not the first statement on the line, APL also displays the statement number. The result of dyadic 0 TRACFE 1s a Boolean vector that indicates whether trace bits were set for the operations named. A 1 in the position corresponding to the name in the right argument indicates that the trace bits were successfully set; a O indicates that trace bits were not set. To clear all the trace bits associated with an object or objects, use ] TRACE with an empty left argument, as follows: (10) OTRACE 2 u4p'CALCAVER' 11 If you modify an operation with YEDIT, OFX, or JMAP, you clear any trace bits set with 1 TRACE. (However, you can view an operation with )EDIT and not clear the trace bits as long as you do not perform any modifications.) If you edit an operation with the A editor, trace bits remain on existing lines (provided they are not modified), even if the lines are renumbered when the operation is closed. APL Reference Manual 2-193 System Variables and Functions [1 TRACE Monitoring Operation Execution In the monadic form, 0 TRACE returns the line numbers (in ascending order) on which trace bits are set for a specified operation. The right argument must contain only one row, which identifies the name of the operation. In the case of a trace bit that is set on an external routine, 0 TRACE returns a one-item vector with a value of O (the only allowable line). The result indicates the lines that exist and have trace bits set on them. For example: OTRACE 5 25 '"CALC' aLINES 5, 25, AND 55 ARE TRACED 55 If the argument is empty or contains a value other than the well-formed name of an unlocked operation, APL returns an empty Boolean vector. For more details about 0 TRACE, see the VAX APL User’s Guide. Possible Errors Generated Dyadic Form 9 KRANK FERROR (NOT MATRIX DOMAIN) 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPF) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT ERROR (INTEGER TOO LARGE) Monadic Form 9 2-194 RANK FRROR (NOT MATRIX DOMAIN) 10 LENGTH FRROR 15 DOMAIN EFRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) APL Reference Manual System Variables and Functions [0TRAP Trap Expression [1TRAP Trap Expression Type System Variable Form [0TRAP < terminal-type current-value <« [JTRAP Value Domain Type Character Shape Vector Domain Depth 0 or 1 (simple) Default vt Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Description 0 TRAP allows you to override a system response with a user-defined response. The value of 0 TRAP is a character vector representing an APL expression. This expression is executed (in ¥ fashion) when any of the events listed in Appendix A are signaled during the execution of a user-defined operation. This includes an attention signal, an abort input signal, or a stop bit (0ST0P). For information on error handling, see the VAX APL User’s Guide. You can set [JTRAP as a global variable or localize it in an operation. When an error occurs during execution of a user-defined operation, APL searches for the most local O TRAP. If 0 TRAP is set to anything other than the empty vector (the default value), APL executes it in the envirnoment of the operation where the error occurred. For example: APL Reference Manual 2-195 System Variables and Functions O TRAP Trap Expression V R;[JTRAP [1] [TRAP« [2] A<+5 [3] B+«0 [4] C+A+B '[! [5] aDIVISION BY 0 [6] L: [7] '"TRAPPED ERROR, IS DOMAIN ERROR THEN CONTINUED' "EXECUTED LAST LINE' ¥ R TRAPPED ERROR, THEN CONTINUED EXECUTED LAST LINE )SI OERROR 15 DOMAIN ERROR R[4] (DIVISION BY ZERO) C<A+B A The following example shows what happens when [J TRAP is not set: VG A<5 [1] B+0 [2] [3] C<A+B V G 15 DOMAIN FRROR GL[3] (DIVISION BY ZERO) C<«A+B A )ST GL3] = If execution of an operation’s [ TRAP expression does not transfer control to a new statement, the operation becomes suspended. If such an operation is a locked operation, APL cuts back the state indicator to the first unlocked operation and then signals DOMAIN ERROR (UNSUCCESSFUL TRAP IN LOCKED FUNCTION). Because a [ TRAP expression can call an operation, you may want to localize OTRAP in the called operation and set 0 TRAP to ' ' to avoid unwanted loops. Possible Errors Generated 9 2-196 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (UNSUCCESSFUL TRAP IN LOCKED FUNCTION) APL Reference Manual System Variables and Functions 0TS Time Stamp [1 TS Time Stamp Type Niladic System Function Form current-time/date <« 0TS Result Domain Integer Type Rank 1 Shape 7 Depth 1 (simple) Description 0TS (time stamp) returns a vector (in base 10 format) representing the current time and date. This vector is known as a time stamp and contains the current year, month, day, hour, minute, second, and millisecond. For example: ars 1990 11 21 A21-NOV-90 11:31:55.134 11 31 55 134 Possible Errors Generated None. APL Reference Manual 2-197 System Variables and Functions [0 TT Terminal Type [] T T Terminal Type Type System Variable (session) Form OTT « terminal-type integer-scalar <« (O TT Value Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value 0 through 19 Default Determined when APL is invoked. Resuilt Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description 07T (terminal type) indicates the type of terminal being used for the current APL session. When you invoke APL, you specify the terminal type in an initialization stream or in response to the terminal designator prompt. 07T allows you to change the terminal type during an APL session. The following table shows the possible values and meanings for O 77: 2-198 APL Reference Manual System Variables and Functions O0TT Terminal Type OTT Values - APL COMPOSITE terminal N TTY-type terminal W Digital VK100 (GIGI) terminal (key-paired) ks~ Digital LA-type terminal (key-paired) O APL/ASCII key-paired terminal O API/ASCII bit-paired terminal 00 Meaning Digital VT102 (key-paired) Q© Value Digital VT220 (key-paired) 10 Digital VT240 (key-paired) 11 Tektronix 4013 terminal (key-paired) 12 Tektronix 4015 terminal (key-paired) 13 HDSAVT (key-paired) 14 HDS201 (key-paired) 15 HDS221 (key-paired) 16 Digital VT320 (key-paired) 17 Digital VT330 (key-paired) 18 Digital VT340 (key-paired) 19 Digital VAXstation running DECwindows (key-paired) Digital VAXstation running VWS(composite) You can query for the current 0 TT value by entering 0] TT without assigning a value. APL responds with the current value. For example: Sapl/term=decterm /silent=all Orr 19 If you specify APL as your terminal designator when you first invoke APL, OTT is set to 5. You can change the value of 0 7T by assigning it a valid terminal type. For example: aTERMINAL DESIGNATOR IS APL 110 12345678910 OTT « 2 .1010 “The terminal 123456789 type is now TTY 10 APL Reference Manual 2-199 System Variables and Functions 07T Terminal Type If you change the value of 07T, APL may send an escape sequence to the terminal to change its character set. This escape sequence is the same as the one that is sent after you identify the terminal when invoking APL. If the value of0 TT is currently 9, 10, 16, 17, 18 or 19 and you leave the APL environment temporarily (with a )Do, )EDIT, or ) PUSH command), you should be careful about changing your terminal type while at the operating system level. If you return to APL with a different terminal type, or if the font files for the APL character set are not available, APL signals an error. (You also get an error if you restricted access to those files while at the DCL level.) Note that 07T is a session variable; that is, its value is not saved with the workspace and 0 TT is not reset by the execution of a ) CLEAR command (see Chapter 3). However, it can be localized in user-defined operations. Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH FRROR (NOT SINGLETON) 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (ERROR ACTIVATING IMAGE) 15 DOMAIN ERROR (FONT FILE COULD NOT BE OPENED) 15 DOMAIN FRROR (INCORRECT TYPE) 15 DOMAIN ERROR (NEGATIVE INTEGER NOT ALLOWED) 15 DOMAIN FRROR (NOT AN INTEGER) 15 DOMAIN ERROR (PARAMETER OUT OF RANGE) 27 LIMIT ERROR (INTEGER TOO LARGE) 2-200 APL Reference Manual System Variables and Functions 0 UL User Load [1UL User Load Type Niladic System Function Form pid <« OUL Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description The result of 0 UL (user load) represents the user’s process identification number (PID). VMS assigns you a unique PID each time you log in to the system. If you log off and then log back in to VMS, your PID (and thus, your 0 UL value) probably will have changed. For example: e 93 You can use the following expression to convert a PID from decimal, as it appears in the APL environment, to hexadecimal, as it appears in the DCL environment: '01234567890ABCDEF"' [0I0+(8p16)THUL] 00000055 Possible Errors Generated None. APL Reference Manual 2-201 System Variables and Functions [0 VERSION Interpreter and Workspace Version [l VERSION Interpreter and Workspace Version Type Niladic System Function Form version-info <« (JVERSION Result Domain Type Character Rank 1 Shape Vector Depth 1 (simple) Description 0 VERSION returns a two-row character vector, with each row followed by a <CR><LF>. The first row identifies the version of the interpreter under which the current workspace was saved; the second row identifies the version of the interpreter that is currently running. The display is in the form lv.u-edit, where [ is the support letter, v is the version number, u is the update number, and edit is the edit number. For example: OVERSION V3.2-834 ¥3.2-834 Possible Errors Generated None. 2-202 APL Reference Manual System Variables and Functions [0 VI Validating Input [] VI Validating Input Type Monadic System Function Form valid /invalid-number « O VI character-vector Argument Domain Type Character Shape Vector domain Depth 1 (simple) Result Domain Type Boolean Rank 1 Shape Vector Depth 1 (simple) Implicit Arguments [1NG (controls negative number recognition) Description 0 VI determines the valid numbers in a character argument. 0 VI examines fields in the argument that are delimited by one or more spaces, tabs, or a carriage return (optionally followed by a line feed), and returns a Boolean vector that contains a 1 in each position corresponding to a field containing a valid number, and a 0 in each position corresponding to an invalid number. If the argument is empty, 0 VI returns an empty array. O VI is often used in conjunction with JFI and the compression function (see Section 1.3.1) to select the valid numbers from a character string; OVI produces the left argument of the compression function, and 0 FI produces the right argument. For example: APL Reference Manual 2-203 System Variables and Functions [ VI Validating Input A«'1.5 3 4 75 3.. 1.0F +1 "3 A OvI 11010001 A OFI 1.530 5000 3 (OVI A)/OFI A 1.53 5 3 Recognition of negative numbers in the (] VI argument depends upon the value of the system variable ONG. If ONG equals 1 (the default), negative numbers in the 0 VI argument must begin with the high minus sign (7) to be recognized. If 0NG equals 0, numbers preceded by a minus sign (-) are recognized as negative numbers. If ONG equals 2, negative numbers are preceded by an APL "+" symbol. (APL "+" prints as an ASCII "-" so JNG_2 can be used to handle negative numbers in strings that will be read or written ia ASCIL.) For example: ONG+1 o MEANS NEGATIVE X«'66 G 7 +9 -u! OvI X 10100 ONG+0 OVI X A- MEANS NEGATIVE 10001 ONG<2 A+ MEANS NEGATIVE X Ovi 10010 Note that the case where NG is 0 may be useful when you use APL to interpret data created by other languages, specifically those that do not use the high minus sign (7). Possible Errors Generated 9 2-204 KRANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPE) APL Reference Manual System Variables and Functions 0 VPC Vector Process Control [1] VPC Vector Process Control Type System Variable (session) Form N VPC <« session vartable integer-scalar < [JVPC Value Domain Type Non-negative near-integer Shape Singleton Depth 0 or 1 (simple) Default Determined when APL is invoked. Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description [0 VPC determines the threshold at which vector processing is used. A value of 0 indicates that vector processing is not used; a value of 1 indicates that the vector processing is always used. When you invoke a session, APL determines whether a vector processor is available. O VPC is set to 0 if no vector processor is available; it is set to the non-negative, near-integer default if a vector processor is available. You can also specify the value for 0 VPC when you invoke an APL session with the qualifier /INOJVECTOR=n (see the section on initializaiton streams in the VAX APL User’s Guide). If a vector processor is not present, setting 0 VPC to a non-zero value results in the use of the vector processer emulator. The vector processer emulator may be useful for testing. The vector processer emulator should not be used for APL Reference Manual 2-205 System Variables and Functions [0 VPC Vector Process Control applications because APL’s performance with the emulator is usually poorer than APL’s performance with the scalar processor. O VPC is a session variable; that is, its value is not saved with the workspace, and 0 VPC is not reset by the execution of a ) CLEAR command (see Chapter 3). However, it can be localized in user-defined operations. You can query for the current [J VPC value by entering [J VPC without assigning a value. APL responds with the current value. For example: gvec 30 Controlled testing can help you identify the threshold at which the increased overhead of running the vector processer is compensated for by increased performance. Possible Errors Generated 9 2-206 RANK ERROR (NOT SINGLETON) 15 DOMAIN ERROR (NEGATIVE NUMBER NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN FRROR (VECTOR PROCESSOR NOT AVAILABLE) APL Reference Manual System Variables and Functions 00 VR Visual Representation [] VR Visual Representation Type Monadic System Function Form O0VR {value | object-name} Argument Domain Type Any Shape Any Depth Any Result Domain Type Character Rank Any Shape Any Depth Any Implicit Arguments O0Dc¢ (Controls display of enclosed arrays) [0 PP (Controls precision of numeric constants) Description 00 VR returns a character array of the visual representation of an APL object. The argument is either a numeric array of any rank or a character array with its shape in the vector domain. If the argument is numeric, [] VR works the same way as monadic 7: the numeric array is formatted into a character array that looks as the numeric array would appear when displayed by APL (which is dependent on the 0 PP setting). APL Reference Manual 2-207 System Variables and Functions [0 VR Visual Representation If the argument is type character, its value must represent the name of an APL object. If the character argument represents a variable or label, the result is the same as for numeric arguments: APL formats the variable or label value as a character array, making it look as it would appear when displayed by APL. If the character argument represents a user-defined operation, ] VR returns a character vector that is similar to the canonical representation of the operation. Specifically, the visual representation of a user-defined operation, F, is the operation definition displayed by the editor command a1 A. The result starts and ends with a A character, and each line begins with a line number surrounded by square brackets and ends with a <CR><LF>. If the character argument represents a derived function such as an operand of a user-defined operator, 0 VR returns a character representation of it. For example, if the operand is plus (+), then 0 VR returns the string '+ '; if the operand is outer product (+. «), then [JVR returns '+. +'; and if the operand is OCR, then O VR returns '[0CR"'. If the argument to 0 VR is empty, the result is an empty character vector. Examples: ACREATE FUNCTION FRTH [1] VZ « A FRTH B; L: Z « A + BV X JFNS FRTH U«V<«2 12 3 4L 5 6 2 3 3p16 ACREATE AND DISPLAY oV J«A<JVR 12 3 4L 5 6 2 5 'V pA U«B<[JVR 'FRTH' VZ « 4 FRTH B; [1] L: 7 « A4 + B V 0B 54 2-208 APL Reference Manual X V System Variables and Functions 0 VR Visual Representation Possible Errors Generated 9 RANK ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN ERROR (OPERATION LOCKED) APL Reference Manual 2-209 System Variables and Functions [0 WA Workspace Available [1 WA Workspace Available Type Niladic System Function Form available-space +~ 1WA Result Domain Type Integer Rank 0 Shape 1 0 (scalar) Depth 0 (simple scalar) Description OWA (workspace available) returns an integer scalar representing an estimate of the amount of available storage space, in bytes, in the active workspace. This value allows you to determine the maximum amount by which your workspace can increase. APL obtains the value by subtracting the current data-segment size from the maximum data-segment size which is the current ) MAXCORE setting (see Chapter 3). Thus, the value returned by 0”4 may be greater than the amount of available memory or the amount of memory allocated by APL. For example: OWA 516980 Possible Errors Generated None. 2-210 APL Reference Manual System Variables and Functions OWAIT Limiting Time on Read Functions WA IT Limiting Time on Read Functions Type Ambivalent System Function (dyadic form is quiet) Form current-timelimit < QWAIT chans 10 <« timelimit OWAIT chan Monadic Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Value ~ 999 through 999 (but not 0) Dyadic Left Argument Domain Type Near-integer Shape Singleton Depth 0 or 1 (simple) Value ~ 1 through 255 (seconds) Dyadic Right Argument Domain Type * Near-integer Shape Singleton Depth 0 or 1 (simple) Value ~ 999 through 999 (but not 0) APL Reference Manual 2-211 System Variables and Functions OWAIT Limiting Time on Read Functions Result Domain Type Integer Rank 1 Shape Vector Depth 1 (simple) Description Dyadic OWAIT specifies the amount of time you want APL to wait when it tries to read a shared record that is locked by another user. When you set a waiting period, APL waits even if you specified the /READONLY : NOLOCKS qualifier when you assigned the file to a channel with 0455 (NOLOCKS normally causes a read to happen without waiting). The left argument (¢imelimit) determines the time limit; it has the following meanings: Value of Time Limit Meaning 1 Don’t wait, return immediately Wait indefinitely (this is the default) n Wait for n seconds Monadic OWAIT queries the system for the current time limits associated with individual channel numbers. For each channel number in the argument, monadic JWAIT returns a value between ~ 1 and 255 that can have the following meanings: Value Returned Current Time Limit 1 Don’t wait Wait indefinitely n Wait for n seconds OWAIT is described in the VAX APL User’s Guide along with other file I/O information. 2-212 APL Reference Manual System Variables and Functions OWAIT Limiting Time on Read Functions Possible Errors Generated Monadic Form 1 FILE NOT FOUND (FILE NOT FOUND) 10 LENGTH ERROR (NOT VECTOR DOMAIN) 15 DOMAIN ERROR (ENCLOSED HETEROGENEQUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (INCORRECT TYPFE) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGFR TOO LARGE) Dyadic Form 1 FILE NOT FOUND (FILF NOT FOUND) 10 LENGTH FRROR (NOT SINGLETON) 15 DOMAIN ERROR (INCORRECT TYPE) 15 DOMAIN ERROR (ENCLOSED HETEROGENEOUS ARRAY NOT ALLOWED) 15 DOMAIN ERROR (NOT AN INTEGER) 15 DOMAIN FRROR (PARAMETER OUT OF RANGE) 15 DOMAIN ERROR (INVALID CHANNEL NUMBER) 15 DOMAIN ERROR (CHANNEL NOT ASSIGNED) 27 LIMIT ERROR (INTEGER TOO LARGE) 33 I0 ERROR (TIMFOUT PERIOD EXPIRED) APL Reference Manual 2-213 System Variables and Functions 0 WATCH Monitoring Variable Changes [l WA T'CH Monitoring Variable Changes Type Ambivalent System Function Form currentmode <~ [OWATCH object-name success [failure mode-number QWATCH object-names Monadic Argument Domain Type Character Shape Vector domain or one-row matrix Depth 0 or 1 (simple) Dyadic Left Argument Domain Type Near-integer Shape Vector domain Depth 0 or 1 (simple) Dyadic Right Argument Domain Type Character Shape Matrix domain Depth 0 or 1 (simple) Result Domain 2-214 Type Integer Rank 1 or 2 Shape Vector or matrix Depth 1 (simple) APL Reference Manual System Variables and Functions 0 WATCH Monitoring Variable Changes Description OWATCH is a debugging tool that allows you to monitor changes in the value of APL objects. APL either displays or signals information when a watched object is referenced or modified. You can set watch modes on variable and label names and most system variables and niladic system functions. You cannot set watch modes on nonniladic system functions, ill-formed identifiers, user-defined operations, or group names. A watch mode remains in effect when the watched object occurs in a locked operation; the watch bit is not reset, as is the case with 0 STOP and [0 TRACE. A modification occurs any time a value is explicitly assigned to a variable (niladic system functions and labels cannot be modified). A reference occurs any time an object is referenced for its value. In display mode, APL sends information to the current output and continues execution of the operation where the reference or modification occurred. In signal mode, APL signals an error (trappable with (] 7RAP) and suspends the operation. Implicit in the use of the OWATCH command are the 1L and OR system variables. Each time a modification occurs on a watched object, APL reassigns the values of these variables: 0L contains the name of the changed object; OR contains the previous value of the changed object. The object contains the new value. Dyadic 0 WATCH enables watchpoints on one or more objects. The right argument specifies the objects you want to watch. Each row contains the name of one niladic system function or one variable (which can be a defined or undefined variable), a system variable, or a label. You cannot watch the following system variables: OR, 0L, or 0 ERROR. If the right argument 1s empty, or if it contains the name of an object that cannot be watched, APL returns an empty Boolean vector. The left argument determines the watch mode: either display or signal mode. In addition, you can specify the watch mode for either modifications or references. APL Reference Manual 2-215 System Variables and Functions 0 WATCH Monitoring Variable Changes There are six watch modes: N W Display if referenced O Signal if referenced Signal if modified or referenced 1 Signal if modified Display if modified » Meaning Ot Mode Display if modified or referenced The result of dyadic OWATCH is a Boolean vector indicating whether the watch mode was set for the specified variables. Each position in the vector corresponds to a row of the right argument. A 1 indicates that the watch mode was successfully set; a 0 indicates that the watch mode was not set. For example: B <« 3 5 p '"BABELSABLECABLE'! B BABEL SABLE CABLE 4w UWATCH B 111 To clear the watch mode associated with an object or objects, use dyadic OWATCH with an empty left argument. The result is a Boolean vector indicating whether the watch mode was turned off. Each position in the vector corresponds to a row of the right argument. A 1 indicates the watch mode was successfully turned off; a 0 indicates the watch mode was not turned off. For example: "' OWATCH 3 5 p '"BABELSABLECABLE' 111 In signal mode, you can trap a reference or modification with 0 7r4P. APL signals a primary message and one of three secondary messages. The signals have the following form: 2-216 113 WATCH POINT ACTIVATED (VARIABLE HAS BEEN REFERENCED) 113 WATCH POINT ACTIVATED (VARIABLE HAS BEEN MODIFIED) APL Reference Manual System Variables and Functions OWATCH Monitoring Variable Changes 113 WATCH POINT ACTIVATED (VARIABLE HAS BEEN MODIFIED BY INDEX) In display mode, APL displays information in different forms depending on whether the event is a reference or a modification. For a reference, the display form is as follows: function-name [line ¢ statement] object-name OLD NAME CLASS: nc SHAPE: rho-vector value For a modification, the display form is as follows: function-name [ line ¢ statement] object-name OLD NAME CLASS: nc SHAPE: rho-vector value NEW NAME CLASS: nc SHAPE: rho-vector value Note that if value is an enclosed array, APL does not display the value. Instead, APL displays a message indicating that value is enclosed. If the operation that contains the reference or modification is locked, APL displays the name of the object with a protected del (¥) symbol (there is no line . number). Monadic []WATCH returns information indicating the current watch mode for the object specified in the right argument. The right argument must have at most one row, which means you must query for the watch mode one object at a time. The result of monadic WATCH is a one-element integer vector (unless the argument is empty, in which case APL returns 1 0). There are seven possible values which indicate the following watch modes: Mode Meaning 1 Object not being watched 2 Signal if modified 3 Display if modified 4 Signal if referenced APL Reference Manual 2-217 System Variables and Functions O0WATCH Monitoring Variable Changes Mode Meaning 5 Display if referenced 6 Signal if modified or referenced 7 Display if modified or referenced When OWATCH is set in mode 2 or 6 on a name that is the left argument of a strand assignment, the signal is delayed until APL has completed all the assignments. If there is more than one watched name in the left argument, APL only signals information on the last (rightmost) one. (For more information, see the strand assignment sections in Chapter 1.) Some events do not activate a OWATCH signal or display (immediate mode events, for example). In addition, a watchpoint is not activated when the following occur: * A variable is used as an output parameter in a call to an external function. * An object becomes shadowed by an operation invocation. * An object becomes unshadowed by an operation termination. * A variable is included in the argument of any of the following commands: OEX, YERASE, )COPY, )PCOPY, [1QC0, and JQPC. When you enable O WATCH, the watchpoint is set on the most local version of the specified objects. When a watched object becomes shadowed, APL saves the current O¥ATCH definition and restores it when the object becomes unshadowed. Labels are always local to an operation and are defined only when the operation is being executed. To watch the referencing of a label, you must enable OWATCH within the context of the operation (either inside the operation or in immediate mode while the operation is suspended or pending). (The VAX APL User’s Guide has more information on debugging operations.) An example of this behavior follows: X<5 3 UWATCH ADEFINE GLOBAL X 'X! AENABLE WATCHPOINT ON X 1 VSHAGL; X [1] [2] [«X«1 7V SHAG1 RDEFINE LOCAL X ASIMPLE ASSIGNMENT ACALL TO SHAGL1, , LOCAL X SHADOWS GLOBAL X aNO OWATCH EVENT OCCURS 2-218 APL Reference Manual System Variables and Functions O0WATCH Monitoring Variable Changes This same behavior occurs when a local variable becomes shadowed by a more local variable: VSHAG1; X [1] RRE-WRITE SHAG1 O«X«1 [2] 3 OWATCH [3] [4] SHAG? v [1] [2] eX<«2 v V X! AENABLE WATCHPOINT ON LOCAL X aCALL SHAG? SHAG?2:X RADD ANOTHER LOCAL X aSIMPLE ASSIGNMENT SHAG1 AEXECUTE SHAG1 1 (Value of local X In 2 ( SHAG? SHAG1) local X shadows SHAG1 local X) Examples: F+<5 3 aDEFINE GLOBAL F UWATCH '#"! aENABLE DISPLAY IF MODIFIED 1 VFOO [1] [2] [3] eDEFINE FUNCTION FOO F < 19 F v aSIMPLE ASSIGNMENT MODIFIES F ALINE 2 REFERENCES F FOO FOO[1] aEXECUTE FO0O F NAME CLASS: 2 SHAPE: 5 NEW NAME CLASS: 2 SHAPE: 9 12345678279 12345671839 5 OWATCH 'F'! aREPLACE PREVIOUS WATCHPOINT AND 1 aENABLE DISPLAY IF REFERENCED FOO FOO[2] F OLD NAME CLASS: 123 2 SHAPE: 9 456789 12345067839 2 OWATCH 'F' WREPLACE PREVIOUS WATCHPOINT AND 1 nENABLE SIGNAL F <5 aNO SIGNAL IF MODIFIED FOR INTEKACTIVE ASSIGNMENT FOO 113 WATCH POINT ACTIVATED FOO[1] F « 19 (VARIABLE HAS BEEN MODIFIED) ASIMPLE ASSIGNMENT MODIFIES F A APL Reference Manual 2-219 System Variables and Functions OWATCH Monitoring Variable Changes )SI FOO[1] F = 0L F 12345671879 OR 5 Possible Errors Generated Monadic Form 9 RANK ERROR (NOT MATRIX DOMAIN) 10 LENGTH FRROR 15 DOMAIN ERROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN FRROR (INCORRECT TYPE) Dyadic Form 2-220 9 RANK FRROR (NOT MATRIX DOMAIN) 9 RANK FRROR (NOT VECTOR DOMAIN) 10 LENGTH ERROR 15 DOMAIN FRROR (ENCLOSED ARRAY NOT ALLOWED) 15 DOMAIN EFRROR (INCORRECT TYPE) 15 DOMAIN ERROR (INVALID WATCH MODE) 15 DOMAIN ERROR (NOT AN INTEGER) 27 LIMIT FRROR (INTEGER TOO LARGE) APL Reference Manual System Variables and Functions [0 XQ Executing Expressions [] X @ Executing Expressions Type Monadic System Function (sometimes quiet) Form result « 0XQ apl-expression Argument Domain Type Any Shape Any Depth Any Result Domain Type Any Rank Any Shape Any Depth Any Description [0 XQ executes the expression represented by its argument as if that expression were entered in immediate mode or included in a user-defined operation. For example, the expressions 1 5 and JXQ'15' return the same result: 15 123 45 HXQ' 15" 12 3 45 The argument can be a numeric (any shape) or a character array (vector domain). If the argument to 0XQ is numeric, APL returns the value of the argument): 0XQ 55 55 APL Reference Manual 2-221 System Variables and Functions [0 XQ Executing Expressions APL treats a <CR><LF> in the argument as a statement separator as if it were input from the terminal, so multiple lines are allowed. The 0xQ function always returns a value: either the value of the last statement evaluated in its argument, or, if the last statement has no value, an empty array. For example: D+[JXQ'5+4 3+2 6 ! 9 5 6 The 0 xq function can execute system commands or invoke the function editor. For example: HXQTVR«FOO A<? B+<3 R<A+B v ! FOO0 5 OXQ')FNS! FOO 0Xq' ) VARS' A B . 0XQ')ERASE 11 ' ,[0XQ")VARS' ARERASE ALL VARIABLES VALUE FRROR A A Pendent (1 XQ functions are indicated by the '0XQ' characters in the state indicator. For example: 0xg ')SI X4 Note that quiet functions are still quiet when executed, pr0V1ded that JxQ is the leftmost functionin the statement: 0XQ' Z+1! LUXQTZ+1! 2-222 APL Reference Manual System Variables and Functions [0 XQ Executing Expressions When the argument is empty and numeric, the result is an empty numeric vector (JXQ 10 <» 10). For example: 0XQ 10 When the argument is empty and character, the result is an empty character vector ("' = 0xQ ') if a value is required by the expression. For example: nxe ! A.(__DXQ RQUIET, NO OUTPUT 11 If APL encounters an error while evaluating the 0XQ function’s argument, it does not signal an error; instead, it stops evaluating the argument and returns an empty array whose shape is 0 n, where n is a number indicating the error that was encountered (see Appendix A for a complete description of all APL errors). The complete text of the error message is placed in JERROR. For example: E<[0XQ'5+5 3+2, 41 10 F (APL outputs a blank line) oF 0 7 UERROR 7 0XQ SYNTAX ERROR (RIGHT ARGUMENT TO FUNCTION MISSING) 3+2, A If you enter the attention signal while the 0 X¢@ function is executing, APL stops executing the argument to 0xQ, and 0 XQ returns an empty array whose shape is 0 18. Then, the normal order of execution continues. The 0 X9 function cannot execute a branch statement; if one 1s entered, the branch is not taken, and the result of the [0 XQ function, if needed, is an empty vector. Thus, 0XQ never alters the flow of control within an operation. Possible Errors Generated 9 RANK FRROR (NOT VECTOR DOMAIN) APL Reference Manual 2-223 3 VAX APL System Commands VAX APL provides a wide variety of system commands that allow you to examine or change the state of the system. For example, you can do the following: e e e (lear, save, or name the active workspace Load or copy a workspace from a secondary storage device List workspace, variable, and user-defined operation names e Display the status of user-defined operations and local variables in the e Set the index origin, the maximum number of significant digits, and the e workspace output line width End an APL session Unlike system functions and system variables, system commands are not considered part of the APL language. e System commands are particularly useful in function-definition mode, becaus on they are executed immediately instead of being executed when the operatifrom is executed. Thus, you can change the APL environment without exiting and at 50, the function editor. For example, if the terminal print width is set use the could you long, ers charact 60 is that line on you display an operati )WIDTH system command to change the print width so that the operation line is displayed on one line. Note that by giving system commands as arguments to the 0 XQ system function, you can use the commands within user-defined operations, rather than having them execute immediately. APL Reference Manual 3-1 System Commands 3.1 System Command Form 3.1 System Command Form APL system commands begin with a right parenthesis, as shown in the following form: Ywhite command-name [ space white arguments ] The right parenthesis is a required part of the system command name. white is optional white space; that is, zero or more spaces or tabs. Space is a required blank space. Arguments may or may not be allowed. See the individual descriptions of the system commands for more details. You can abbreviate a command name to its shortest unique form. Some system commands take required or optional parameters; when you include them, you must separate the individual items of the parameter list with at least one space or tab. If a system command that takes no arguments is followed by nonwhite space, or if an argument is invalid, APL signals INCORRECT PARAMETER. The following examples show the form of several system commands: JCONTINUE )CONT )CONTIN )SAVE MYWORK YWS4L0 A B C VARG N The first three examples invoke the same system command, ) CONTINUE; note that the first four letters of each of the command names are the same. In the fourth example, MYWORK is an argument to the ) SAVE system command. The fifth example shows a ) COPY command that takes a series of arguments. 3.2 System Command Categories There are two broad categories of system commands: * Query commands obtain information * Action commands that change the state of a workspace or the operating environment The action commands can be further categorized into the following logical groups, which are described in the following sections: * Query/change commands find out about or change the state of the environment, 3-2 * APL action commands manipulate APL objects in a workspace * System action commands terminate or interrupt an APL session APL Reference Manual System Commands 3.2 System Command Categories - Workspace manipulation commands manipulate workspaces There are some system commands that specifically affect APL I/O; they are described in detail in the VAX APL User’s Guide. Table 3—1 summarizes the system commands. 3.2.1 Query System Commands The query system commands return information about the current state of the session, the active workspace, or the APL system or environment. The query system commands follow: )ENS ) GRP )GRPS YNMS YOPS ) VARS )SIT )SINL )SIS ) VERSION ) CHARGE ) OWNER )LIB YHELP - 3.2.2 Query/Change System Commands The query/change system commands are both action and query commands; that is, they can return information about the present state of the APL environment, or they can be used with an optional parameter to change the state of the environment. The )ORIGIN command, for instance, can either return or change the index origin setting. In the following example, )ORIGIN is used first as an action command; it sets the index origin to 0 and reports that the previous setting was 1. Then, )ORIGIN is used as a query command; it reports that the current setting of the Index origin is 0 : JORIGIN O WAS 1 JORIGIN 0 APL Reference Manual 3-3 System Commands 3.2 System Command Categories Each of the query/change commands can be thought of as displaying, or changing and displaying, a system variable. There are two types of system variables: workspace and session. Workspace variables are associated with a particular workspace; that is, they are saved and loaded with the workspace. The system commands associated with the workspace variables are as follows: YWSID lwsnamel [/ PASSWORDI: Tpwlill YPASSWORD [[l/PASSWORD [ : [pwlll | pwl YORIGIN [nl )DIGITS [nl YWIDTH [[n] Session variables are associated with the current APL session; they do not change when the current workspace is changed, and they cannot be saved with a workspace. The system commands associated with the session variables follow: YMAXCORE [[n] YMINCORE [[n] Note that the system variables 1GAG, 0 TLE, variables. 0TT and JVPC are also session 3.2.3 APL Action System Commands The APL action system commands cause some action to take effect within the current workspace. The APL action system commands are as follows: ) CLEAR )EDIT object-name /qualifiers YERASE [/FNST [/GrPS] [[/0PST [/ VARS] list ) GROUP group-name [group-member-list] )SIC )STEP [n] [/SILENT] [/INTO | /OVERI 3.2.4 System Commands that Initiate System Action This section describes the system commands that terminate or interrupt an APL session or initiate some other program. You can exit from APL in a variety of ways: e e Returning to the DCL command level Terminating the APL session, optionally returning to the DCL command level e 3-4 Terminating the session and saving the active workspace APL Reference Manual System Commands 3.2 System Command Categories e Interrupting the session and running other programs while at the DCL command level, eventually returning to APL The following system commands are in this category of commands that initiate system action: YMON )OFF JCONTINUE ) PUSH JATTACH )DO 3.2.5 Workspace Manipulation System Commands The workspace manipulation system commands preserve, make active, and delete workspaces. They also copy objects from workspaces to the currently active workspace. The workspace manipulation system commands are as follows: )LOAD )XLOAD )SAVE ) COPY )PCOPY YDROP 3.3 System Command Reference The following sections describe the APL system commands in alphabetical order. Each description indicates the general category of the command: query, query/change, apl action, system action, or workspace manipulation. Table 3—1 lists all the system commands and gives a brief description of their uses. Table 3—1 System Commands Command Meaning YATTACH Temporarily suspends the APL session and returns control to a ) CHARGE Displays a record of activity for the current APL session specified process (continued on next page) APL Reference Manual 3-5 System Commands 3.3 System Command Reference Table 3—-1 (Cont.) System Commands Command Meaning ) Replaces active workspace with clear workspace CLEAR YCONTINUE Saves active workspace and exits APL ) COPY Copies global objects from another workspace YDIGITS Displays or changes the number of significant digits to be displayed )DO Executes a VMS command; returns output to APL )DROP Deletes workspaces or files from a directory-structured device YEDIT Edits a global object with the VAXTPU editor )ERASE Erases the named global object from the current workspace YENS Displays an alphabetical list of global function names )GROUP Collects named objects into a group )GRP Lists members of a group )GRPS Displays an alphabetical list of group names YHELP Displays information about APL features )INPUT Diverts input to a device other than your terminal )LIB Displays names of workspaces or files on a directory-structured device YLOAD Retrieves a workspace from secondary storage YMAXCORE Displays or changes the setting for maximum workspace size YMINCORE Displays or changes the setting for minimum workspace size YMON Returns you to operating system command level YNMS Displays all names in the symbol table )OFF Ends current APL session )OPS Displays an alphabetical list of global operator names YORIGIN Displays or changes index origin YOUTPUT Diverts output from your terminal to another device ) OWNER Displays information about the creation of the current workspace ) PASSWORD Displays or changes the workspace password ) PCOPY Same as ) COPY but protects names already in use | (continued on next page) 3-6 APL Reference Manual System Commands 3.3 System Command Reference Table 3—1 (Cont.) System Commands Command Meaning ) PUSH Temporarily suspends the APL session, returning control to the operating system )SAVE Saves a copy of the active workspace ) ST Displays workspace state indicator )SIC Clears workspace state indicator )SINL Displays workspace state indicator, local symbols for each userdefined operation, and argument to pending execute functions ) SIS Displays workspace state indicator, currently executing line, and argument to pending execute functions )STEP Executes lines of a function one at a time ) VARS Displays an alphabetical list of global variables ) VERSION Displays the APL version numbers for the workspace and interpreter YWIDTH Displays or changes the terminal line width YWSID Displays or changes workspace name; optionally changes workspace password YXLOAD Retrieves a workspace from secondary storage without executing OLX APL Reference Manual 3-7 System Commands YATTACH Interacting with Other Processes ) AT TACH Interacting with Other Processes Type Action System Command Form YATTACH {process-name} Qualifiers /PARENT Specifies that you want to attach to the first process established in the current job. Description Note that you must specify either /PARENT or the process-name, but you cannot specify both. YATTACH interrupts the APL session and attaches to a process that already exists within your current job. The APL session is not terminated when you use )ATTACH. To return to APL, you can use the DCL command ATTACH on the process name of the APL process. When you return to the interrupted APL session, program execution resumes at the point after the execution of the YATTACH command. Examples: HGAG <« 2 ABROADCASTS WILL BE DISPLAYED IN APL CHARACTERS aEXECUTE MAIL IN A SUBPROCESS NAMED MAILPROC )PUSH/PROCESSNAME=MAILPROC MAIL MAIL>ATTACH/PARENT aWE ARE BACK IN APL nGO READ THE NEW MAIL YATTACH MAILPROC You have 1 new message. MAIL>read/new #1 From: To: 8-NOV-1999 15:15:15:41 APLVAX: :USERZ USER1 CC: Subj: | Pizza today? Do you want to have pizza for lunch today? 3-8 APL Reference Manual System Commands YATTACH Interacting with Other Processes MAIL>attach/parent aWE ARE BACK IN APL )DO SHOW PROCESS/SUBPROCESSES 8-NOV-1990 15:39:04.42 User: USER1 Node: APLVAX There are 2 processes in Process ID: Process name: 00000067 alUSER<2na this job: «~TWA2: USER1+2 () aUSER1<1 IS THE PROCESS FOR DO) YOFF TWA?2: THURSDAY 8-NOV-1990 15:39:05.01 CONNECTED 00:00:39.53 CPU TIMF 00:00:01.09 1 OPERATIONS 6 STATEMENTS 306 PAGE FAULTS 410 BUFFERED I0 S show process/subprocesses 8-NOV-1990 15:47:58.25 125 DIRECT I0 User: USERI1 Node: APLVAX Process ID: Process name: 00000005A " _TWA4:" There are 3 processes in this job: _TWA4: (%) USER1_1 MAILPROC Possible Errors Generated 22 INCORRECT PARAMETER (MISSING ARGUMENT) 22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIER KEYWORD) 114 ERROR PROCESSING ATTACH (ATTACH REQUEST REFUSED) 114 KERROR PROCESSING ATTACH (INVALID LOGICAL NAME) 114 ERROR PROCESSING ATTACH (NONEXISTENT PROCESS) 249 FEXTRANEQOUS CHARACTERS AFTER COMMAND 383 PARENT QUALIFIER REPEATED APL Reference Manual 3-9 System Commands ) CHARGE Displaying Accounting Information ) CHA RGE Displaying Accounting Information Type Query System Command Form ) CHARGE Description ) CHARGE displays a record of activity during the current APL session and includes the following: * Your terminal identification * Current time and date * Length of time connected to APL * Amount of computer CPU time used inside APL * Number of APL operations executed * Number of page faults while inside APL * Number of buffered I/O and number of direct I/O while inside APL For example: )CHARGE WEDNESDAY SYS$INPUT: CONNECTED 14-NOV-1990 00:00:01.33 0 STATEMENTS 0 CPU TIME 16:03:22.16 00:00:00.40 OPERATIONS 160 PAGE FAULTS 20 BUFFERED I0 15 DIRECT IO Possible Errors Generated 22 3-10 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual System Commands ) CLEAR Clearing the Active Workspace ) CLEAR Clearing the Active Workspace Type APL Action System Command Form )CLEAR Description ) CLEAR empties the active workspace by erasing all variables, groups, and user-defined operations; resetting all workspace variables (but not session variables) to their default values; closing all open files; and clearing the state indicator. The clear workspace has the following characteristics: Contains no user-defined operations, groups, or variables Has an index origin (01 10) of 1 Has an output line length (0 P¥) determined by the operating system width specification Has a comparison tolerance value (0CT) of 1ETM 15 Has a random link value (ORL) of 695197565 Has an empty character array as the value for 1LX, 0TRAP, DERROR, and OR I, Has the automatic save feature turned off (1AUS is 0) Outputs the negative sign (T ) in TTY mode as .NG (NG is 1) Displays both primary and secondary error messages when an error occurs (O0TERSE 1s 0) Has a workspace and interpreter version that are the same (the lines returned by [0 VERSION match) Displays numbers with ten significant digits (0 PP) Has a clear symbol table and state indicator Has the name CLEAR WS Has an empty password APL Reference Manual 3-11 System Commands ) CLEAR Clearing the Active Workspace * Requests quad input with the message [1: followed by a <CR><LF> and six blanks (0 SF) e Has a default 0DC valueof (71 1 0 2) '', which means that there are no boxes around enclosed arrays Note that APL gives you a clear workspace when you begin a work session, unless you have a CONTINUE workspace in your default device and directory area, or unless you use an initialization stream to specify a workspace to be loaded. Also note that ) CLEAR clears only the active workspace; it has no effect on workspaces you have saved with the ) SAVE system command. When the ) CLEAR command completes execution, APL displays the message CLEAR WS. For example: )JCLEAR CLEAR WS YMINC, YMAXC, 0GAG,OTLE, and OTT are not affected by ) CLEAR. Possible Errors Generated 22 3-12 INCORRECT PARAMETER (EXTRANEQUS CHARACTERS AFTER COMMAND) APL Reference Manual System Commands ) CONTINUE Saving the Workspace and Ending the Session ) CONTINUE Saving the Workspace and Ending the Session Type System Action System Command Form YCONTINUE [HOLD | LOGOUT] Default in Clear Workspace HOLD Description )yCONTINUE works the same way as the ) 0OFF system command, except that before ending the session ) CONTINUE saves the active workspace in your default device and directory area under the name CONTINUE .APL. If files named CONTINUE .APL already exist in your directory, the new CONTINUE workspace will have a version number that is one greater than the next most recent version. The H0LD parameter (the default) returns you to DCL command level after ending the APL session. The LOGOUT parameter logs you off the system after ending the APL session. The ) CONTINUE command prints the same message that the ) SAVE command prints, followed by the same summary information that ) OFF displays. For example: )CONTINUE HOLD WEDNESDAY 28-NOV-1990 SYS$INPUT: CONNECTED 00:00:01.62 0 STATEMENTS 16:04:29.46 WEDNESDAY 28-NOV-1990 0 191 PAGE FAULTS 15 BLKS 16:04:29.90 CPU TIME 00:00:00.,42 OPERATIONS 24 BUFFERED I0 21 DIRECT I0 If a CONTINUE workspace exists in your default area when you begin an APL session, it is loaded as your active workspace, unless you specify a different workspace in an APL initialization stream, or unless the workspace had a password when it was saved. If the CONTINUE workspace is saved with a password, APL signals WORKSPACE LOCKED when the APL session begins. You can still load the workspace by executing the command ) LOAD CONTINUE /PASSWORD : pw. APL Reference Manual 3-13 System Commands ) CONTINUE Saving the Workspace and Ending the Session Note that the name of a CONTINUE workspace that is loaded is not CONTINUE; the name is the one the workspace had when it was saved. The load message displayed when APL is invoked identifies what the name was when the workspace was saved. For example: )LOAD CONTINUE SAVED WEDNESDAY 28-NOV-1990 16:04:29.46 15 BLKS WAS EXAMPLE YJWSID EXAMPLE Note APL does not delete your CONTINUE workspace after it is loaded. A particular CONTINUE workspace in your default area may be loaded as your active workspace each time you invoke APL, not just the first time that you invoke APL after the workspace was created. If you do not want the CONTINUE workspace to be loaded, you must explicitly delete it from your default area, or specify a different workspace in an APL initialization stream. Possible Errors Generated 3-14 15 DOMAIN ERROR(EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIER KEYWORD) APL Reference Manual System Commands ) COPY Copying Objects from a Workspace ) COPY Copying Objects from a Workspace Type Manipulation System Command Form ) COPY wsname [[list]] Qualifiers / PASSWORD[:[pwi] Specifies the password associated with the stored workspace. /CHECK Causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). If damage is detected, a message 1s displayed and APL tries to recover as much information as possible from the workspace and continue the copy. The recovered workspace may be missing APL variables, user-defined operations, individual lines of userdefined operations, and other APL objects that were damaged. The user must determine what named objects have been removed from the workspace. Description ) COPY retrieves global user-defined operations, global variables, and groups from a stored workspace (wsname) and places them into your active workspace. If there is a password associated with the stored workspace, you must include it in the command string. You can copy all the named objects in a workspace or a subset of them; list identifies the specific objects to be copied. When you specify a list of objects, you can use the » and :+ wildcards. If you omit the /ist parameter, all userdefined operations, variables, and groups are copied. ) COPY does not transfer local values for variables and functions, nor does it copy the state indicator, channel assignments, or any system variable such as the print width, index origin, or print precision. If your active workspace contains objects with the same name as those in the copied workspace, ) COPY replaces the global (but not the local) values in your active workspace with the copied ones. For example, if B is a variable in the active workspace with a global value of 10 and a local value of 5, and the workspace being copied has a variable B with a global value of 20, after ) cory is executed the active workspace will have a variable B with a global value of APL Reference Manual 3-15 System Commands ) COPY Copying Objects from a Workspace 20 and a local value of 5. A suspended or pendent operation, or an operation still being defined in the active workspace is not replaced, and an operation being created in the workspace being copied is not copied. When you copy a group, all members of the group are copied along with their values. However, if a member of a group is itself a group, APL copies only the group name and not the value. Thus, for example, suppose the group GROUP1 has as members the variables 4 and B, and the group GROUP2. Also suppose that GROUP2 has as members the variables ¢ and D. Then, if you copy GROUP1, you copy the values of 4 and B, but only the name of GROUP2, not the values of ¢ and D. The ) CcOPY command displays the same message as the ) L0AD command. Note that the size printed in this message is the size (in disk pages) of the active workspace after execution of the ) COPY command completes. If the list to be copied contains an object that is not in the specified workspace, APL returns the message NOT FOUND:, followed by a list of the objects (separated by tabs) that were not found. The objects that were found are still copied, however. The ) COPY command performs the same operation as the 0QC0 system function (see Chapter 2), but 0@C0 does not display messages to confirm that the copy was successful. Examples: )COPY AVER SAVED WEDNESDAY 28-NOV-1990 16:20:42.14 24 BLKS )COPY AVER B SAVED WEDNESDAY 28-NOV-1990 16:20:42.14 24 BLKS )COPY AVER G SAVED WEDNESDAY 28-NOV-1990 16:20:42.14 24 BLKS NOT FOUND: G Possible Errors Generated 22 INCORRECT PARAMFETER 22 INCORRECT PARAMETER(ILL FORMED NAME) 27 LIMIT ERROR(ARGUMENT STRING IS5 TOO LONG) 83 DAMAGED WORKSPACE HAS BEEN CORRECTED (SOME SYMBOLS MAY HAVE BEEN ERASED) 3-16 APL Reference Manual System Commands )YDIGITS Output Precision )DIGITS Output Precision Type Query/Change System Command Form YDIGITS [[n] Default in Clear Workspace 10 Description )DIGITS displays or changes the value of the print precision system variable (O PP). The print precision (n in the form) is the number of significant digits displayed in APL floating-point output; it can be an integer from 1 to 16. It does not affect the precision of internal calculations or the display of integers. APL rounds off any number that has more digits than the current setting. Executing the ) DIGITS command in change mode has the same effect as assigning a value to the [ PP system variable (see Chapter 2). Examples: YDIGITS 10 1.234567891234567889 1.234567891 )DIG 5 WAS 10 1.23456789123456789 1.23U46 )DIG 2 WAS 5 1.23456789123456789 1.2 APL Reference Manual 3-17 System Commands YDIGITS Output Precision Possible Errors Generated 3-18 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 22 INCORRECT PARAMETER (PARAMETFER OUT OF RANGE) APL Reference Manual System Commands ) DO Executing a DCL Command ) DO Executing a DCL Command Type System Action System Command Form )DO command-string Qualifiers / LOWERCASE Refers to how you want ) D0 to translate any output from the execution of the command string. Without this qualifier, the )D0 command converts any ASCII lowercase letters to uppercase unless you are using V1102, VT220, VT240, VT320, VT330, VT340, DECterm, VS, or TTY mnemonic mode, or unless the output is the argument to execute (either 0XQ or ¢). Use the /LOWERCASE qualifier if you do not want this conversion to occur. /NOKEY PAD Specifies that you do not want the keypad characteristics of the current process to be available to the new subprocess. The default is that the characteristics are available. /NOLOGICALS Specifies that you do not want the logical name table from the current process to be available to the new subprocess. The default is that the table is available. /NOSYMBOLS Specifies that you do not want the global and local symbol table (defined at the DCL level) from the current process to be available to the new subprocess. The default is that the symbol table is available. Description ) DO interrupts the APL session and creates a VMS subprocess, putting you at the DCL command level without terminating the APL session. Unlike the ) PUSH command, ) DO attempts to recover any output resulting from the execution of the command string. APL Reference Manual 3-19 System Commands ) DO Executing a DCL Command With ) D0, you must always include a command string (do not enclose the string in quotation marks); VMS creates a subprocess, executes the command specified, and then returns to APL when the execution completes. For example, the following executes the DCL command SHOW TIME and returns its output to APL: DOTIME<[1XQ')DO SHOW TIME' DOTIME 8-NOV-1990 16:25:21 The command string must be no longer than 132 characters (after translation to ASCII), not including leading white space (spaces or tabs before the argument begins), but including all other white space within the argument. Any output written to SYSSOUTPUT or SYS$ERROR is retrieved by APL. See the VMS DCL Dictionary for a description of SYS$OUTPUT and SYS$ERROR. While you are at DCL command level, your terminal is in ASCII rather than APL mode, and your terminal characteristics (such as output line width) revert to the system settings. When you return to APL, the APL character set is restored, and your [] PW setting is the same as it was before you executed the )DO command (although the default for 0 Pw changes if you changed your system terminal width). However, other terminal characteristics you may have changed at command level (for example, the 0 GAG setting, or the ability to input lowercase characters) remain changed. Possible Errors Generated 22 INCORRECT PARAMETER (LOWERCASE QUALIFIFER REPEATED) 22 INCORRECT PARAMETER (MISSING ARGUMENT) 22 INC'ORREVCT PARAMETER (NOLOGICALS QUALIFIFER REPEATED) 22 INCORRECT PARAMETER (NOSYMBOLS QUALIFIER REPFEATED) 22 INCORRECT PARAMETER (NOKEYPAD QUALIFIER REPEATED) 73 SUBPROCESS FRROR (COMMAND BUFFER OVERFLOW SHORTEN EXPRESSION OR COMMAND LINE) 3—-20 APL Reference Manual System Commands YyDRO P Deleting Stored Workspaces or Files P Deleting Stored Workspaces or Files ) DRO Type Workspace Manipulation System Command Form )DROP file-spec Description yDROP can delete any file for which you have the necessary protection privileges. You can delete one, several, or all the files on a device and directory. If you do not include a device and directory, your default device and directory are assumed; however, you must always include a file name, file type, and version number. You may use a wildcard designator to substitute for the version number or for all or part of the file name or file type. In the following example, all files on the default device and directory that begin with the letter s are deleted. APL prints the file specification for each file dropped. For example: JDROP *.LIS;x DELETE-I-FILDEL, DEV1:[APLGRPIDOC.LIS;1 deleted (3 blocks) :DELETE-I-FILDEL, DEV1:[APLGRP}SAMPLE.LIS;2 deleted (3 blocks) DELETE-I-FILDEL, DEV1:[APLGRP1SAMPLE.LIS;1 deleted (3 blocks) :DELETE-I-TOTAL, 3 files deleted (9 blocks) The maximum length of the ) DROP command argument is 121 characters (after translation to ASCII), not including leading white space (spaces and tabs before the argument begins), but including all other white space within the argument. Executing the ) DROP command is equivalent to executing the DCL command DELETE/LOG. For more details about the DELETE command, see the VMS DCL Dictionary. Possible Errors Generated 22 INCORRECT PARAMETER (LINE TOO LONG TO TRANSLATE) 22 INCORRECT PARAMETER (MISSING ARGUMENT) APL Reference Manual 3-21 System Commands ) EDIT Editing with VAXTPU ) ED I T Editing with VAXTPU Type APL Action System Command Form )EDIT objectname Qualifiers [vo]l/ cCOMMAND | | Allows you to specify an initialization file to VAXTPU. The value for filespec is a VMS file specification. If you omit the /COMMAND qualifier, or if you do not specity a filespec value, VAXTPU uses the file specification assigned to the logical name TPUINI as a default. [voll/DISPLAY Tells VAXTPU that you are using a support ANSI CRT terminal. This is the default. You should specify /DISPLAY only during an interactive session. /NODISPLAY tells VAXTPU that your are not using a supported terminal. You should use this qualifier only when you run VAXTPU procedures in batch mode. /EXECUTE[:tpucommand]] Allows you to specify a VAXTPU command string that you want to execute after the editor finishes any command or section files. Note, however, that VAXTPU does not execute the /EXECUTE qualifier when either the command or section file contatins a QUIT or EXIT command. The value for tpucommand is a character string containing one or more VAXTPU statements that you want VAXTPU to execute. It should not contain any non-ASCII APL characters or embedded <CR><LF>s. You do not have to place quotation marks around the string, but if quotation marks are necessary for the VAXTPU operation, they must be balanced. The maximum length of the string is 100 characters, and it must be terminated by the end of the line or by another qualifier. If you do not specify tpucommand, APL ignores the /EXECUTE qualifier. The /EXECUTE qualifier is particularly useful when you run APL and )EDIT in batch mode. For example, you can set up an error-checking routine to handle situations where the VAXTPU file is too large to return to the APL environment. If you create a VAXTPU procedure called CHECKMESBUFFER 3-22 APL Reference Manual System Commands ) EDIT Editing with VAXTPU that checks the VAXTPU message buffer for a WORKSPACE FULL error, you can call the procedure with the /EXECUTE qualifier: YEDIT FOO/EXECUTE:CHECKMESBUFFER When you first invoke VAXTPU, the section and command files run, and the /EXECUTE qualifier calls the CHECKMESBUFFER procedure. The procedure does nothing because there is currently no VORKSPACE FULL error message in the VAXTPU message buffer. However, if the editing session ends and the file is too large, APL reinvokes VAXTPU. This time the CHECKMESBUFFER procedure detects the error message and handles it accordingly. /LC Determines whether the line numbers of a user-defined operation appear in the VAXTPU editor. This qualifier is useful because it allows you to view the current line numbers associated with the lines of the operation. APL ignores the /LC qualifier for objects that are not operations. Once the file is in the editor, the line numbers no longer determine the organization of the lines in the operation. When the file returns to the APL environment, APL assigns new line numbers based on the order that it reads the records from the VAXTPU editor. If you add new lines to the operation, you do not have to include any line numbers. When you do not specify /Lc, APL generates the canonical representation of the operation in the VAXTPU editor. (The canonical representation does not include line numbers.) /MODE[:mode] Allows you to determine the input/output mode for the data moving between the AP and VAXTPU environments. The value for mode is the integer 2 or 3, and represents [1 and B, respectively. If you omit the /MODE qualifier, or if you do not specify a mode value, APL uses /MODE: 2 as a default. Note that you must specify MODE: 3 if you have embedded line feeds in an object and want them to remain intact in the file that VAXTPU returns to APL. However, be aware that @ turns off APL overstrike and TTY mnemonic | translation. /NC[[:nc] Determines the name class of the object you are editing. This qualifier 1s useful only when you intend to create a new object in the editor. The value for nc is an integer that specifies the name class of the new object, which has the following characteristics: APL Reference Manual 3-23 System Commands ) EDIT Editing with VAXTPU Name Class Data Type Shape 2 Character Vector 3 Function Not applicable 4 Operator Not applicable When you omit the /NC qualifier, or when you specify /NC without a value, APL uses the name class of the object named by objectname as the default. If objectname specifies a currently undefined object, APL uses 2 as the default value. /NG :ng] Determines how VAXTPU displays the APL high minus sign (*), which is used to indicate a negative number. This qualifier only affects the representation of numeric variables; numeric values within operations are not affected. /NG 1s the equivalent of 0NG and accepts the same values (0, 1, or 2). When ng 1s 1, negative numbers are preceded by the high minus sign (7). When ng is 0, negative numbers are preceded by the minus sign (- ). When ng is 2, negative numbers are preceded by the APL plus sign (+). (The setting 2 is used when reading or writing ASCII files; the ASCII minus sign translates to the APL plus sign. See the discussion of NG in the VAX APL Reference Manual for more information.) The default setting for /NG is the current setting for O NG. / PP[:pp]l Determines the print precision of noninteger numeric values sent to VAXTPU. / PP 1s the equivalent of 0 PP and accepts the same values (1 to 16). If you omit the /PP qualifier, APL uses the current value of 0 PP as the default. If you specify /PP but do not include a value, APL uses the maximum allowable value (16). / PW[[:pwl] Determines how APL segments an object for output to the temporary file in the VAXTPU editor. The value for pw specifies the maximum number of characters in a single line of output. /Pw is the equivalent of 0 P¥ and accepts the same values (35 to 2044). However, the greatest value that VAXTPU will accept from APL is 900. If you specify a /P value greater than 900, APL selects 900 by default. If you do not specify /Pw, or if you specify /Pw without a value, then the default setting is 0 Pw or 900, whichever is smaller. 3-24 APL Reference Manual System Commands ) EDIT Editing with VAXTPU VAXTPU truncates any record that has a length greater than 900. To avoid losing data, APL forms records in the following manner when creating the temporary file: Functions APL breaks records between each line Matrices APL breaks records between each row Vectors APL breaks records at each <CR> <LF> When you enter VAXTPU, some line wrapping may occur, depending on the setting used for /PW. This could cause unexpected changes in the edited object, and may result in an error when you attempt to end the editing session. To avoid confusion, APL places a warning message in the VAXTPU message buffer as you enter the editing session: LINE WRAP HAS OCCURED. The semantics for line wrapping are as follows: e If /PW is not specified, APL wraps records with length > 900 e If /PW is specified, APL wraps records with length > 900 0PV e If /PW=pw is specified, APL wraps records with length >9300 pw [vol/sEcTIOoN]:filespec] Allows you to specify a section file to VAXTPU. The value for filespec 1s a VMS file specification. If you omit the /SECTION qualifier, or if you do not specify a filespec, VAXTPU uses the file specification assigned to the logical name TPUSECINI as a default. If you desire to use the EDT emulation mode, specify /SECTION:EDTSECINI. / TERMINAL[ :termtype] Determines the terminal type you want to use during the )EDIT session. The values for termtype, and the character sets that they represent are as follows: Terminal Type Character Set TTY Tr'TY KEY KEY BIT BIT COMPOSITE COMPOSITE Vri02 BIT VTr220 COMPOSITE Vvr2uo COMPOSITE VTr320 COMPOSITE APL Reference Manual 3-25 System Commands ) EDIT Editing with VAXTPU Terminal Type Character Set V7330 COMPOSITE VTr3uo COMPOSITE HDS201 COMPOSITE HDS221 COMPOSITE VS COMPOSITE DECTERM COMPOSITE If you omit the /TERMINAL qualifier, or if you do not specify the termtype value, APL uses the current terminal type as the default. Description The )EDIT system command allows you to edit global APL objects with the VAXTPU editor. You can edit user-defined operations and variables. You cannot edit enclosed arrays, and you cannot modify an operation that is suspended or pendent. (If you edit a suspended or pendent operation, APL puts an appropriate message in the VAXTPU message buffer, and you must end the VAXTPU session with a QUIT command.) When you invoke ) EDIT, APL creates a temporary file containing the object you want to edit and then invokes VAXTPU. When you exit VAXTPU, APL reads the edited file from VAXTPU into the workspace. Note that APL returns you to the VAXTPU editor if an error occurs as the file reenters the workspace. For more information about VAXTPU, see the VAX Text Processing Utility Manual. Note that YEDIT is also described in the VAX APL User’s Guide. Possible Errors Generated 5 DEFN ERROR (OPERATION SUSPENDED OR PENDENT) 15 3—-26 DOMAIN ERROR (FRROR ACTIVATING IMAGE) 111 EDIT COMMAND FRROR (xx QUALIFIER REPEATED) 111 EDIT COMMAND ERROR (ARGUMENT TO xx IS OUT OF RANGE) 111 EDIT COMMAND FRROR (BAD ARGUMENT T0O xx) APL Reference Manual System Commands ) EDIT Editing with VAXTPU 111 EDIT COMMAND ERROR (EDIT COMMAND UNAVAILABLE DURING FUNCTION DEFINITION) 111 EDIT COMMAND ERROR (ENCLOSED ARRAY NOT ALLOWED) 111 EDIT COMMAND FRROR (EXECUTE QUALIFIER ARGUMENT IS TOO LONG) 111 EDIT COMMAND ERROR (L[LL FORMED NUMERIC CONSTANT) 111 EDIT COMMAND ERROR (ILL FORMED NUMERIC MATRIX) 111 EDIT COMMAND ERROR ([LLEGAL NAME CLASS) 111 EDIT COMMAND FRROR (INCORRECT PARAMFETER) 111 EDIT COMMAND FRROR (MISSING ARGUMENT) 111 EDIT COMMAND ERROR (OPERATION LOCKED) 111 EDIT COMMAND ERROR (UNRECOGNIZED QUALIFIER KEYWORD) 111 EDIT COMMAND ERROR (VOLUME TOO LARGE) APL Reference Manual 3-27 System Commands ) ERASE Erasing Global Names ) ERASFE Erasing Global Names Type APL Action System Command Form YERASE list Qualifiers /FNS Limits the name class of the objects to functions. /VARS Limits the name class of the objects to variables. /GRPS Limits the name class of the objects to groups. /OPS Limits the name class of the objects to operations. Description ) ERASE deletes the APL objects named in the list; it undefines global user- defined functions and operations, erases global variables, and disperses groups and erases their members. When you specify list, you can use the » and + wildcards. You can use the /FNS, /GRPS, /OPS, and /VARS qualifiers in conjunction with wildcards to limit the name class of the objects being erased. You cannot erase pendent or suspended operations, nor can you erase labels or other local names. If you are inside the A editor, you cannot erase the function being edited. If a member of the named group is itself a group, the group name is erased, but the members of the subgroup remain intact. For example: 3-28 APL Reference Manual System Commands ) FERASFE Erasing Global Names )CLEAR CLEAR WS JLOAD TRIG_CIRCLE SAVED THURSDAY 8-NOV-1990 15:08:07.52 12 BLKS JFNS ARC COS DIAM RADIUS SIN TAN aTRIG CONTAINS THE GROUP CIRCLE )GRP TRIG SIN COS TAN CIRCLE ASHOW MEMBERS OF GROUP CIRCLE )GRP CIRCLE ARC RADIUS DIAM YERASE TRIG )GRP TRIG 22 INCORRECT PARAMETER (NOT A GROUP) ) GRP TRIG A AERASING TRIG ERASED GROUPNAME CIRCLE )JGRP CIRCLE 22 INCORRECT PARAMETER (NOT A GROUP) ) GRP CIRCLE A AMEMBERS OF CIRCLE NOT ERASED YENS ARC DIAM RADIUS If a specified object cannot be erased, either because such an operation 1is illegal or because the object is undefined, the following message is displayed: NOT ERASED: list of objects The objects are separated by tabs. There is no message when ) ERASE is successful. Note that ) ERASE leaves a slot in the symbol table for the erased name (symbol). Although you erase a symbol, the slot in the symbol table still exists. If you reuse a name that was in the symbol table, APL places it in the same slot where it was before. If you do a ) COPY of the workspace into a CLEAR WS, APL rebuilds the workspace, thus erasing the slot as well as the symbol. APL Reference Manual 3-29 System Commands ) ERASE Erasing Global Names Examples: 0«B«2 3 2 4 3 4 JERASE B B 11 VALUE ERROR B A V R<F [1] nF CANNOT BE FRASED [2] JERASE F NOT ERASED: F v [2] JENS Gx G2 GI G3 G4 JVARS Gx fUSE QUALIFIER TO LIMIT WILDCARD JERASE [FNS Gx aFUNCTIONS G1 AND G2 ARE GONE JENS AVARIABLES G3 AND G4 STILL DEFINED ) VARS G3 GH Possible Errors Generated 3-30 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (ILL FORMED NAME) 27 LIMIT FRROR (ARGUMENT STRING IS TOO LONG) APL Reference Manual System Commands ) FN.S Displaying a List of Functions ) FFN.S Displaying a List of Functions Type Query System Command Form )FNS [[start-stringllstop-stringli]l Qualifiers /WSID:wsname(l/PASSWORD : pw] Allows you to specify a nonactive workspace. If the nonactive workspace was saved with a password, you must also specify the /PASSWORD qualifier. Description )FNS displays a list of the global names used as user-defined function names in a workspace. By default, APL displays the list from the currently active workspace. The optional string parameters identify starting and stopping points for the list. When you specify the string parameters, you can use the x and = wildcards. The objects are listed in 04V order, separated by tabs. Each output line in the list begins in column one. Note that the wildcard determines the start-string. There 1s no wildcard for the stop-string. If you use ) FNS with no parameters, APL displays all the global function names in the workspace: )LOAD FNS SAVED THURSDAY 8-NOV-1990 17:12:11.52 41 BLKS JENS ALPH HILB INVRS INVT LS4 If you include just one argument, APL uses Z as the default for the stop-string: )LOAD OPERS SAVED THURSDAY 8-NOV-1990 18:06:12.76 12 BLKS JENS IN INVRS INVT LS JENS INV INV INVRS INVT APL Reference Manual 3-31 System Commands ) FN S Displaying a List of Functions To obtain a list of all user-defined function names that begin with a given prefix, use the prefix for both arguments or use a wildcard: )LOAD OPERS SAVED THURSDAY 8-NOV-1990 18:06:12.76 12 BLKS JENS INV* INVRS INVT Possible Errors Generated 1 3-32 FILF NOT FOUND (FILF NOT FOUND) 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMFETER (NOT A LETTER) 57 FILE DOES NOT CONTAIN A WORKSPACE APL Reference Manual ) GROU System Commands P Defining or Dispersing a Group ) GRO U P Defining or Dispersing a Group Type APL Action System Command Form ) GROUP group-name l[group-member-list]] Description ) GROUP collects APL objects together under a single name. The objects can be variables, user-defined operations, and other group names. When you specify the objects, you can use the » and + wildcards. The ) GROUP command is often used with the )CcoPrPY and ) PCOPY commands. After collecting a set of operations and variables under one group name, you can specify the name in a ) COPY or ) PCOPY command to copy the entire collection at one time. In the following example, the functions and variables named INT, FUTVAL, and PRESVAL are collected into a group named FINANCTIAL: )GROUP FINANCIAL INT FUTVAL PRESVAL To add a new member to an existing group, you must list the group name as an item in the member list. Thus, the variable T4X is added to the group named FINANCIAL as follows: YGROUP FINANCIAL TAX FINANCIAL To disperse a group, specify the group name without a group member list. The group name will no longer be defined, but the individual members of the group will still exist under their original names. The following command disperses the group FINANCIAL: JGROUP FINANCIAL A group name is always global; you cannot localize it. For example: APL Reference Manual 3-33 System Commands ) GROUP Defining or Dispersing a Group A<1 B+2 VF:C [1] [2] R«(JXQ 'GROUP C A B'") v F )GRPS C Here, the ) GROUP command executed inside the function F created a global group name C, even though ¢ was included in the function’s local symbol list. Possible Errors Generated 3-34 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NAME) 22 INCORRECT PARAMETER (MISSING ARGUMENT) 24 NOT GROUPED, NAME IN USE APL Reference Manual System Commands ) GRP Displaying the Members of a Group ) GR P Displaying the Members of a Group Type Query System Command Form ) GRP group-name Qualifiers /WSID:wsname ([ /PASSWORD: pw] Specifies a nonactive workspace. If the nonactive workspace is saved with a password, you must also specify the /PASSWORD qualifier. Description ) GRP displays the names of the objects associated with the group name. The names are listed in the order in which they are entered into the group and are separated by tabs. For example: JGROUP APLGRP LEE PETER STAN DAVE ERIC CHIP CHRIS SHOTA )JGRP APLGRP LEE PETER STAN DAVE ERIC CHIP CHRIS SHOTA Possible Errors Generated 1 FILE NOT FOUND (FILF NOT FOUND) 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NAME') 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (MISSING ARGUMENT) 22 INCORRECT PARAMETER (NOT A GROUP) 57 FILE DOES NOT CONTAIN A WORKSPACE ] APL Reference Manual 3-35 System Commands ) GRPS Displaying a List of Groups ) GRPS Displaying a List of Groups Type Query System Command Form ) GRPS [[start-stringlstop-string]] Qualifiers /WSID:wsnamel[l /PASSWORD: pw] | Specifies a nonactive workspace. If the nonactive workspace was saved with a password, you must also specify the /PASSWORD qualifier. Description ) GRPS displays a list of group names in a workspace. By default, APL displays the list from the currently active workspace. When you specify the string parameters, you can use the + and + wildcards. The names are listed in JAV order, separated by tabs. Each output line in the list begins in column 1. Note that the wildcard determines the start-string. There is no wildcard for the stop-string. If you use )GRPS with no parameters, APL displays all the group names in the workspace. For example: )GRPS ALPH HILB INVRS INVT LS5SQ If you include just one argument, APL uses Z as the default for the second string: JGRPS IN INVRS INVT LSQ JGRPS INV INV INVRS INVT To get a list of all group names that begin with a given prefix, use the prefix for both arguments or use a wildcard. )JGRPS INV* INVRS INVT 3-36 APL Reference Manual System Commands ) GRPS Displaying a List of Groups Possible Errors Generated 1 FILE NOT FOUND (FILE NOT FOUND) 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (NOT A LETTER) 57 FILE DOES NOT CONTAIN A NORKSPACE APL Reference Manual 3-37 System Commands ) HEL P Obtaining Help on the VAX APL Language ) HE'L P Obtaining Help on the VAX APL Language Type Query System Command Form YHELP [[string]l Qualifiers /LIBRARY : filespec Specifies a Help library other than the default APL Help library. This feature allows you to write your own Help libraries and reference them through the APL )HELP facility. If you want to make your help library the default (and thus avoid specifying the /LIBRARY qualifier each time you invoke ) HELP), you can define the logical name APL$HELP: as the value for filespec. The /LIBRARY qualifier must follow directly after the ) HELP command, and you must specify the colon or equal sign and the VMS file specification. If you specify a file that does not exist, APL signals FRROR PROCESSING HELP (FRROR OPENING AS INPUT). Description ) HEL P provides controlled access to the APL Help facility via the VMS Help librarian. The APL Help library is a file associated with the VMS logical name APL$SHELP:. You can define that logical name if you want your own help library to be the default. If APLSHELP: is not defined, VAX APL looks for a file named SYS$HELP:VAXAPL.HLB, which is placed on your system during installation. The APL Help Library contains the actual text of the help topics and is organized into multiple levels. For example, JASS is a secondary level topic under QUAD-NAMES, which is a primary level topic. You can gain access to the primary level topics by entering the name of a primary key as the string parameter. Each of these topics contains explanatory text and a menu of secondary level topics. The primary keys include the following. 3-38 APL Reference Manual System Commands ) HEL P Obtaining Help on the VAX APL Language Primary Key Topic Help General information and menus of other topics Error-numbers Error messages beginning with a numeric string Symbols AV characters Qualifiers Qualifiers beginning with the slash (/) symbol Quad-names System functions and variables beginning with the quad () symbol System-commands System commands beginning with the right parenthesis ()) symbol To gain access to a secondary level topic, you can enter the name of a primary key followed by a space and the name of a secondary key. Use the following form: )HELP primary-key secondary-key In many cases, you can omit the primary-key parameter and obtain help directly from a secondary level; if you specify a system command, system function, system variable, qualifier name, or error number, APL generates the primary key for you and uses your string as the secondary key. (Note that APL generates primary keys only when you use the default APL Help library.) For example, you can enter ) HELP OMBX and receive information on JMBX without enterring ) HELP QUAD-NAMES OMBX. The following table describes how APL translates secondary key entries: INPUT TRANSLATION Secondary Key Primary Key null-string Help numeric-string Error-numbers atomic-vector-character Symbols string Qualifiers Ostring Quad-names ) string System-commands APL also performs translations in other instances where the first character (not including blanks) following the ) HELP command is a character from the following table. (These translations do not occur when you have specified JLIBRARY.) APL Reference Manual 3-39 System Commands ) HE'L P Obtaining Help on the VAX APL Language INPUT TRANSLATION Secondary Key Primary and Secondary Keys . Symbols period $ Symbols dollar B Symbols divide ! Symbols shriek ' Symbols ’ @ Symbols at sign A Symbols lamp ? Symbols question mark ( Symbols left parenthesis Aside from the instances described above where APL recognizes a string and generates the appropriate primary and secondary keys, APL assumes that the string you enter is a primary key followed by optional subkeys separated by blanks. For example, )HELP ARITHMETIC-FUNCTIONS provides a description of arithmetic functions and a menu of subtopics on which you could obtain help. Entering )HELP ARITHMETIC-FUNCTIONS FACTORIAL provides information on the factorial function. Once APL determines a primary key, it translates the key and all related subkeys from 0AV characters to TTY mnemonics using [1 mode; this produces keys in a format understood by the Help facility, which then locates the appropriate text. This text is then translated from TTY mnemonics to JAV characters, converted into uppercase, and then sent to the appropriate output destination by APL. (The text is not converted into uppercase in two instances: when your terminal is a VT102, VT220, VT240, VT320, VT330, VT340, DECterm, VS, or is in TTY mode; and when you execute ) HELP with 0XQ or ®.) When you request information that currently exists within the APL Help Library, the output appears in the following form: keyl key2 key3 help text additional help text 3—-40 APL Reference Manual (if any) System Commands ) HEL P Obtaining Help on the VAX APL Language When you request information that currently does not exist within the APL Help Library, the output appears in the following form: SORRY, NO DOCUMENTATION ON xxx ADDITIONAL INFORMATION AVAILABLE ON ... Where xxx is the string you specified when you invoked )HELP, and . .. indicates a menu of available help topics. APL treats the string parameter as a prefix when it locates a topic in the APL Help Library. For example, )#ELP OL finds the help file text for all QUAD-NAMES beginning with 0 L. The APL Help facility accepts wildcards in the form of the ellipsis ( ... ) and pairs of star characters (x » ). (A single » character returns information on the x symbol.) For example: Command Meaning YHELP * % Returns text on all primary key levels. YHELP % x ... Returns all text on all levels. YHELP key-name . . . Returns all text on the primary key (key-name and all its subkeys). Note that you cannot use the ellipsis on secondary (or lower) keys: JHELP HELP The )HELP command provides you with controlled access to the VMS HELP librarian to obtain help on various topics related to the VAX APL language. APL looks for the file associated wilh the If that is not defined, it looks for logical name APL$HELP:. SYS$HELP:VAXAPL.HLB. This system command accepts terms familiar to APL as keys into the APL help library and returns a character vector (help text) with embedded Carriage Returns Line Feeds. Additional Iinformation available: APL-applications APL-command-1ine File-System Function-Names Comments Editor Logical-Functions Relational-Functions Error-Numbers Operators Arithmetic-Functions Execute-only Glossary Quad-Names Qualifiers Specification-Function System-Commands Terminal-Input-Output Terminal-Support Help Axis Indexing Statements Symbols JHELP + SYMBOLS + Plus TTY mnemonic 1s + APL Reference Manual 3—41 System Commands ) HE'L P Obtaining Help on the VAX APL Language o obtain help on monadic + To obtain help on dyadic + JHELP type type )HELP ARITHMETIC-FUNCTIONS CONJUGATE )HELP ARITHMETIC-FUNCTIONS ADD © ERROR-NUMBERS 0006 LABEL ERROR Improper use of a name colon was detected, was entered as a or an improper variable label. Secondary error messages: (DUPLICATE LABEL) (NAME IN USE) An attempt was made to use the same identifier for both a label a local symbol or argument. (OPERATION SUSPENDED, PENDENT, and OR MONITORED) An attempt was made to change a or monitored operation. label definition in a suspended, aNOTE THAT THE ARGUMENT TO )HELP IS TREATED AS A PREFIX aTHERE IS MORE THAN ONE QUAD-NAME THAT STARTS WITH (L JHELP (1L QUAD-NAMES 0L OL - Watched Variable Name Type: System Variable Forms: [L <« any-value variable-name <« [1L Value Domain: Type: Shape: Any Any Depth: Any Result Domain: Type: Rank: Shape: Depth: Default: Character (any when set Dby user) 1 (vector) (any when set by user) Vector (any when set by user) 1 (simple vector) (any when set by user) ! A variable that is used implicitly by OWATCH. [L contains a character vector showing the name of a watched variable that has changed. [L is set implicitly by the system when a variable changes, but can also be set by the user. Additional Iinformation available: Frrors QUAD-NAMES OLC 3-42 APL Reference Manual pendent, System Commands ) HE'L P Obtaining Help on the VAX APL Language OLC - Line Counter Type: Niladic System Function Form: current-line-number <« [LC Result Domain: Default Value: Type: Rank: Shape: Depth: Empty Integer 1 (vector) Vector 1 (simple vector) Vector of line numbers in the state indicator; most recently suspended operation appears first. Typing ~0LC restarts the most recently suspended operation at the beginning of the line where execution was stopped. Additional Information available: Errors QUAD-NAMES 0LX OLX - Latent Expression Type: System Variable Forms: [ULX <« character-vector current-value « [LX Value Domain: Type: Character Shape: Vector domain Depth: 0 or 1 (simple) Default: ! Result Domain: Type: Character Rank: 1 (vector) Shape: Vector Depth: 1 (simple vector) Causes expression when workspace is to be executed automatically loaded. The expression 1Is not executed when you load workspace with the )XLOAD system command. Additional the Information available: EFrrors nTHE NEXT EXAMPLE DEMONSTRATES THE /LIBRARY QUALIFIER YHELP /LIBRARY=DEV1:[APLGRP.LIBRARY]TEMP.HLBE HELP This is a sample help file. You can modify the function file or create additional help files. For help building library files, REFERENCE MANUAL. Additional see the VAX APL HELP VMS LIBRARIAN Iinformation available: APLHELP File Assigning Default_Library Library Source_File Library Utility APL Reference Manual 343 System Commands ) HE'L P Obtaining Help on the VAX APL Language YHELP /LIBRARY=DEV1:[APLGRP.LIBRARYITEMP.HLB APLHELP APLHELP File Certain files may De modified after installation Iif desired. VAXAPL .HLP, the source text of the VAX APL HELP function file, is In SYSSLIBRARY. You can add new text to the HELP library. Refer to )HELP HELP HOW-TO-BUILD while inside VAX APL for Instructions on creating the help file, Possible Errors Generated 3-44 112 ERROR PROCESSING HELP (ERROR OPENING AS INPUT) 112 ERROR PROCESSING HELP (FRROR PARSING ARGUMENT TO LIBRARY) 112 ERROR PROCESSING HELP (INVALID KEY) 112 ERROR PROCESSING HELP (TOO MANY HELP KEYS SPECIFIED) APL Reference Manual ) ) System Commands INPUT Diverting Input to Another Device INPUT Diverting Input to Another Device Type Query/Change System Command Form YINPUT [filespec I /character-set]]l Qualifiers /LIST The query form of the ) INPUT command. Use /LIST to list the names of the currently nested input files. /REVERT Cancels all nested input files and returns to your terminal as the source of input. Description YINPUT allows you to change the source of APL input from your terminal to other devices. Typically, you would select a file (filespec) to be the new source. character-set specifies that the file is to be read in a character set other than the one you designated for your terminal when you invoked APL. The poss1ble values are /TTY, /KEY, /BIT, /COMPOSITE and /APL. If no arguments are used, ) INPUT cancels the current input stream and returns to the previous input stream on the list. The ) INPUT system command is also described in the VAX APL User’s Guide along with other I/O information. APL Reference Manual 3-45 System Commands ) INPUT Diverting Input to Another Device Possible Errors Generated 1 FILE NOT FOUND (FILE NOT FOUND) 14 DEPTH FRROR ( TOO MANY DIVERTED INPUTS) 22 INCORRECT PARAMETER ( EXTRANEOUS CHARACTER AFTER COMMAND) 22 INCORRECT PARAMETER ( INVALID CHARACTER SET QUALIFIER) 35 INVALID FILE SPECIFICATION (WILDCARDS NOT ALLOWED IN FILE SPECIFICATION) 3-46 APL Reference Manual System Commands ) LIB Listing Workspace Names ) L I B Listing Workspace Names Type Query System Command Form ) LIB llfile-specl]l Description ) LIB displays a list of workspace or file names located in the area specified. If you omit file-spec, ) LIB lists all the files on your default device and directory area that have the file type .APL (the default for workspace names). If you use file-spec, APL lists the names of all selected files, not just workspaces, on the selected device and directory. You can identify a particular file, or use the wildcard characters » and +, to substitute all or part of the file name or file type; for the version number, only * 1s a valid wildcard character. In the following example, this command lists all files on the default device and directory that have a file name beginning with the letter w: JLIB W, %% The following command lists the names of all files on the default device in the directory [USER.APL]: )LIB [USER.APL] The file names in the list begin in column 1 and are separated by a Carriage Return Line Feed. The list of file names is preceded by a line identifying the device and directory, and the list is followed by a line that tells how many files were listed. For example: )LIB Directory DEV1:[APLGRP] ALPHA.APL;1 CHAR.APL ;1 GEORGE .APL ;1 PRIME.APL;1 APL Reference Manual 3-47 System Commands ) LIB Listing Workspace Names Total of 4 files. )SAVE WS40 THURSDAY 29-NOV-1990 16:5u4:45.31 3 BLKS )LIB DEV1:[APLGRP] ALPHA.APL ;1 ;1 CHAR.APL GEORGE .APL ;1 PRIME.APL;1 WS40.APL;1 Total of 5 files. YSAVE WS40.VAR THURSDAY 29-NOV-1990 16:54:u45.84 3 BLKS YLIB WS40.x Directory DEV1:[APLGRP] WS40,APL;1 WS40.VAR; 1 Total of 2 files. JLIB x.,x% Directory DEV1:[APLGRP] ALPHA.APL;1 CHAR.APL ;1 GEORGE .APL ;1 LIS«WOR«1,4A45;1 LIS+«WOR«1EX.0QUT;1 LIS+«WOR«1TMP.AAS; 1 PRIME.APL;1 WRITE<«EXAMPLE.COM;7 WS40 .,APL:1 WSu0.VAR;1 Total of 10 files. Note that when you execute the ) L7B command with no argument, APL passes the following command string to VMS for execution: DIRECTORY/COLUMNS=1/HEADING/TRAILING *.APL;* 3-48 APL Reference Manual System Commands ) L I B Listing Workspace Names If you include an argument with )LIB, that argument is substituted for * .APL ; x 1n the command string passed to VMS. The argument may be no more than 95 characters long (after translation to ASCII), not including leading white space (spaces or tabs before the argument begins), but including all other white space within the argument. For example: )LIB/PROTECTION WS40.x Directory DEV1:[APLGRP] WS40.APL; 1 (RWED,RWED,RE ) WS40.VAR; 1 (RWED,RWED,RE, ) Total of 2 files. The )LIB command uses the DCL command DIRECTORY. This is true even if you have a symbol definition for DIRECTORY that has different qualifiers. For more details about the DCL command DIRECTORY, see the VMS DCL Dictionary. Possible Errors Generated 22 INCORRECT PARAMETFER (LINE TOO LONG TO TRANSLATFE) APL Reference Manual 3-49 System Commands ) LOAD Retrieving a Workspace ) LOAD Retrieving a Workspace Type Workspace Manipulation System Command Form )LOAD wsname Qualifiers / PASSWORD [:Ipwill If you use a password when the workspace is saved, you must specify it when you perform a load operation or APL will not retrieve the workspace. A /PASSWORD or /PASSWORD: specification that is not followed by a password 1s ignored. /CHECK The optional /CHECK qualifier causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). If damage is detected, a message is displayed and APL tries to recover as much information as possible from the workspace and continues the load. The recovered workspace may be missing APL variables, user-defined operations, individual lines of user-defined operations, and other APL objects that were damaged. The user must determine what named objects have been removed from the workspace. You must use the )SAVE command if you want to maintain an undamaged version of the recovered workspace. Description ) LOAD makes wsname the active workspace by replacing, and thus destroying, the contents of the currently active workspace. If the workspace named by wsname is larger than the current )MAXCORE setting, APL increases the setting and loads the workspace. The file specification you give for wsname must include at least a file name. APL will assume default values for the rest of the specification; that is, it assumes the file type .4PL, the current user device and directory, and an empty password. 3-50 APL Reference Manual System Commands YyLOAD Retrieving a Workspace When you load a workspace, the ) LOAD system command responds by displaying the word SAVED, followed by the time and date when the workspace was saved, followed by the size (in disk pages) of the newly active workspace. If the newly active workspace contains a suspended operation, APL also prints a star. If the newly active workspace is larger than the current setting for MAXCORE, APL prints the message NEW MAXCORE IS nnnP, where nnn is the new size of maxcore, and P indicates that the size is measured as pages of memory. The )WSID value of the loaded workspace is the value you specified for wsname. The 0QLD system function (see Chapter 2) performs the same operation as the ) LOAD command, but does not display the verifying messages. The verifying messages for the ) L0AD and ) SAVE system commands are very similar. The only difference is that when you load a workspace, the message includes the word SAVED. You can use this difference to distinguish between a workspace that has just been loaded and a workspace that has just been saved. For example: VFRY [1] [2] M « [JXQ 'SAVE ROAR') '"MESSAGE IS ' 3 M [3] v YJWSID FRY WAS CLEAR WS FRY MESSAGE IS THURSDAY 8-NOV-1990 17:12:33.14 16 BLKS YLOAD ROAR MESSAGE IS SAVED THURSDAY 8-NOV-1990 17:12:33.14 16 BLKS M SAVED THURSDAY 8-NOV-1990 17:12:33.14 16 BLKS In this case, the user executes the ) SAVE command from within the function FRY. APL saves the workspace and assigns the verifying message of the ) SAVE command to the variable ¥. Next, the user loads the workspace. APL immediately continues execution of the function and assigns the verifying message of the ) LOAD command to the variable M. When you load a workspace that was saved inside 0 input, APL removes the pendent [J input from the state indicator stack. If the 0 input was executed from within an operation, APL suspends the operation after removing the pendent 0 input from the stack. If the 0LX system variable (see Chapter 2) has a value in the workspace, it is executed when the workspace is loaded, unless the top of the state indicator stack contains an execute function, or unless the workspace was saved in function-definition mode (if it was, you remain in function-definition mode after APL Reference Manual 3-51 System Commands ) LOAD Retrieving a Workspace the workspace is loaded). If the workspace was saved inside [J input, the 0LX expression is executed only after APL removes the pendent 0 input from the state indicator stack. Examples: JLOAD WS35 SAVED THURSDAY _ 8-NOV-1990 17:12:11.52 41 BLKS JLOAD SYS$SCRATCH:TICTAC SAVED THURSDAY 8-NOV-1990 17:11:59.28 u1 BLKS RJEN HAS A SUSPENDED )LOAD JEN SAVED THURSDAY 8-NOV-1990 17:0u4:23.38 OPERATION L2 BLKS~ 11 BLKS )CLEAR CLEAR WS OLX < "' 'USE APL_LASER PRINTER''' )JLOAD SQUARE SAVED THURSDAY 8-NOV-1990 17:03:11.u46 SQUARE YWSID ROOT WAS SQUARE )SAVE ROOT 8-NOV-1990 THURSDAY 17:27:40.51 )LOAD ROOT SAVED THURSDAY 8-NOV-1990 12 BLKS 17:27:40.51 12 BLKSx Possible Errors Generated 3-52 22 INCORRECT PARAMETER 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) APL Reference Manual System Commands Y MAX CORE Determining the Maximum Workspace Size ) MAX CORE Determining the Maximum Workspace Size Type Query/Change System Command Form YMAXCORE [[nll Default in Clear Workspace 1024P / 1048576P Description As an action command, )MAXCORE changes the current setting for the maximum workspace size to the value specified (n) and displays the previous YMAXCORE setting. As a query command, )MAXCORE returns the current maximum workspace size and the system maximum workspace size. You may not set the current maximum workspace size to a value smaller than the amount currentlyin use, or to a value less than 40, whichis the minimum value of n for all new workspaces. Also, you may not set the maximum size to a value larger than the system maximum. Note that, depending on your system resources, you may not have access to the maximum amount of memory. Although the number of pages (P) appears in the display, you do not type P in the command string. For example: YMAXC 1048576P 1024P/ YMAXC 2000 WAS 1024P/ 1048576P YMAXC 2000P/ 1048576P Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 22 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) APL Reference Manual 3-53 System Commands )MINCORE Determining the Minimum Workspace Size ) MINCORE Determining the Minimum Workspace Size Type Query/Change System Command Form YMINCORE [[n] Default in Clear Workspace 40P Description )MINCORE displays or changes the current minimum workspac e size (in pages). As an action command, YMINCORE changes the current setting for the minimum workspace size to the value specified (n) and displays the previous setting. Legal values for the YMINCORE setting are 0 through the current ) MAXCORE value. As a query command, ) MINCORE returns the current minimum workspace size. The YMINCORE system command is useful in dealing with large arrays or in performing operations that require large amounts of intermed iate storage. Such operations can make the workspace continually expand, thus slowing the processing and fragmenting of the workspace. You can improve system efficiency by using ) MINCORE to ensure that a reasonable amount of memory is available at the beginning of the operation. Generally, the )MINCORE setting does not change when you load a workspace. However, depending on the characteristics of the loaded workspac e, the )JMINCORE setting may be greater than the amount of available memory. In this case, )MINCORE is reset to the default when the )L0AD succeeds (no error 1s signaled). Examples: YMINC 32P JMINC 100 WAS 3-54 32P APL Reference Manual System Commands YyMINCORE Determining the Minimum Workspace Size Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEQOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 22 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) APL Reference Manual 3-55 System Commands ) MON Returning to Operating System Command Level ) MO N Returning to Operating System Command Level Type System Action System Command Form YMON Description )MON returns control to operating system command level. It does not save the active workspace, but if 14US is set (see Chapter 2), the workspace is automatically saved. The )0V command does not close open files, but it does flush the file buffers. -When you use )MON to leave APL, you can return to APL by typing the DCL command CONTINUE. If you intend to return to APL, be careful not to destroy your memory image while you are at DCL level. This situation could occur if you issue a command that runs a program. The )#ON command has limited value because most DCL commands do run a program and thus will destroy the APL image. If you want to return to the DCL command level to run other programs, you should use the ) PUSH or )DO command. If you want to return to another process, you should use the JATTACH command. Possible Errors Generated 22 3-56 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual System Commands ) NMS Displaying Names in the Symbol Table ) NM S Displaying Names in the Symbol Table Type Query System Command Form )NMS [[start-stringllstop-string]lll Qualifiers /WSID: wsname Allows you to list the names in a nonactive workspace. wsname specifies the workspace. /PASSWORD: [pw] Specifies the password used when the nonactive workspace was saved. Description )NMS displays all the names in the symbol table in 04V order. The result is a combination of the same information obtained by the ) VARS, )FNS, )OPS, and )GRPS commands. By default, APL displays the names from the currently active workspace. The optional /WSID qualifier allows you to specify a nonactive workspace. If the nonactive workspace was saved with a password, you must also specify the /PASSWORD qualifier. The optional string parameters identify starting and stopping points for the list. When you specify the string parameters, you can use the » and -+ wildcards. The objects are listed in JAV order, separated by tabs. Each output line in the list begins in column 1. Note that the wildcard determines the start-string. There is no wildcard for the stop-string. APL Reference Manual 3-57 System Commands ) NM.S Displaying Names in the Symbol Table The following name classes are possible: Value Meaning 0 Name not in use 2 Variable name 3 Function name i Operator name Ty Group name A symbol has a name class of 0 when it has no value. Such a symbol may be listed in the symbol table because it is currently referenced in a user-defined operation (either a function or operator) or was previously used and has since been erased. For example: )LOAD NAMES SAVED THURSDAY 8-NOV-1990 17:44:43,63 15 BLKS )GRPS LAB1 RECAP REPLACE VERTICAL LAT VET A.2 ADD.3 B.2 DC.0 DONE.O NEW.0 OLD.0 0UT.0 RECAP. 4 ) VARS A B JENS ADD YNMS UP.0 VERTICAL. 4 DOWN.O LAB1. 4 LAT.2 REPLACE. 4 TEST. O VET.2 If you use ) NMS with no parameters, APL displays all the symbols in the workspace. If you use the optional string parameters, you can specify a particular section from the list of symbol names. For example, all the names starting with B through those starting with L 4. If you include just one argument, APL uses Z as the default for the second string. To get a list of all symbol names that begin with a given prefix, use the prefix for both arguments or use a wildcard. For example: 3-58 APL Reference Manual System Commands ) NMS Displaying Names in the Symbol Table YJLOAD NAMES SAVED THURSDAY 8-NOV-1990 17:44:43.63 15 BLKS YJNMS B LA DONE.O B.2 DC.O JNMS R RECAP. 4 - DOWN.0 REPLACE. 4 LAB1.4 LAT.2 TEST.0 UP.O VERTICAL. 4 VET .2 JNMS VE VE 4 VET.?2 VERTICAL. YNMS VEx* 4 VET.2 VERTICAL. Possible Errors Generated 1 FILE NOT FOUND (FILE NOT FOUND) 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (NOT A LETTER) 57 FILE DOES NOT CONTAIN A WORKSPACE APL Reference Manual 3-59 System Commands ) OFF Terminating the APL Session ) OF F Terminating the APL Session Type System Action System Command Form )OFF [HOLD | LOGOUT ] Default in Clear Workspace HOLD Description )OFF terminates an APL session. If you specify the #0LD parameter (HOLD is the default), APL terminates your session and returns you to DCL command level. If you specify the LoGoUT parameter, APL not only terminates your session, but logs you off the system. The ) 0OFF command destroys the currently active workspace, deletes the JAUS file, closes all open files, and resets the terminal characteristics to the system settings. When you use ) OFF, you cannot return to APL by enterring the DCL command CONTINUE. The ) 0FF command displays several lines of information before terminating the session. The lines contain the following: Your terminal identification Current time Current date Length of time connected to APL Amount of computer CPU time used inside APL Number of APL statements executed Number of APL operations executed Number of page faults while inside APL Number of buffered I0 and number of direct IO while inside APL 3-60 APL Reference Manual System Commands ) OFF Terminating the APL Session Examples: JOFF LOGOUT 8-NOV-1990 17:48:59.32 THURSDAY SYS$INPUT: CPU TIME 00:00:00.37 CONNECTED 00:00:00.98 0 STATEMENTS 0 OPERATIONS 170 PAGE FAULTS 21 BUFFERED IO 9 DIRECT IO YOFF HOLD 8-NOV-1990 17:50:13.15 THURSDAY SYS$INPUT: CPU TIME 00:00:00.38 CONNECTED 00:00:00.98 0 OPERATIONS 0 STATEMENTS 154 PAGE FAULTS 9 21 BUFFERED I0 9 DIRECT IO Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIER KEYWOKD) APL Reference Manual 3-61 System Commands ) OPS Displaying a List of Operators ) O P.S Displaying a List of Operators Type Query System Command Form )OPS [start-stringllstop-string]]l Qualifiers /WSID:wshame Allows you to list the user-defined operators defined in a nonactive workspace. wsname specifies the nonactive workspace name. / PASSWORD : pw Specifies the password used when the nonactive workspace was saved. Description )OPS displays a list of the global names used as user-defined operator names in a workspace. By default, APL displays the list from the currently active workspace. The optional / ¥SID qualifier allows you to specify a nonactive workspace. If the nonactive workspace was saved with a password, you must also specify the / PASSWORD qualifier. The optional string parameters identify starting and stopping points for the list. When you specify the string parameters, you can use the * and - wildcards. The objects are listed in 0AV order, separated by tabs. Each output line in the list begins in column 1. Note that the wildcard determines the start-string. There is no wildcard for the stop-string. It you use )0PS with no parameters, APL displays all the global operator names in the workspace: JOPS ALPH 3-62 HILB INVRS APL Reference Manual INVT LS5Q System Commands ) OPS Displaying a List of Operators If you include just one argument, APL uses Z as the default for the second string: JOPS IN INVRS INVT LSq YOPS INV INV INVT INVRS To obtain a list of all user-defined operator names that begin with a given prefix, use the prefix for both arguments or use a wildcard: YOPS INVx INVRS INVT Possible Errors Generated 1 FILE NOT FOUND (FILE NOT FOUND) 29 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 29 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 20 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (NOT A LETTER) 57 FILE DOES NOT CONTAIN A WORKSPACE APL Reference Manual 3-63 System Commands ) ORIGIN Determining the Index Origin ) ORIGIN Determining the Index Origin Type Query/Change System Command Form YORIGIN [[n] Default in Clear Workspace 1 Description )ORIGIN displays or changes the setting of the index origin (0 10). The index origin (n in the form) can be either 0 or 1; its setting determines whether the values of an array are indexed beginning with position 0 or 1. Executing the )ORIGIN in change mode has the same effect as assigning a value to the 0 I0 system variable (see Chapter 2). Examples: 15 12345 JORIGIN 0 WAS 1 15 01234 JORIGIN 0 Possible Errors Generated 3-64 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NUMERIC CONSTANT) 22 INCORRECT PARAMETER (SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) APL Reference Manual System Commands ) 0UTPUT Diverting Output to Another Device YOUTPUT Diverting Output to Another Device Type Query/Change System Command Form yoUTPUT lfilespec [/ character-set]l Qualifiers JAPPEND Specifies that you want to add data to the end of an existing file. If you specify filespec without the /APPEND qualifier, APL creates a new file. /DISPOSE:{ KEEP| DELETE| PRINT| SUBMIT| PRINTDELETE | SUBMITDELETE} Specifies whether the value of filespec is a temporary or permanent file. /DISPOSE : KEEP, which is the default, means the file is permanent; /DISPOSE : DELETE means the file will be deleted when it is closed. /DISPOSE: PRINT sends the file to a print queue (SYS$PRINT) when the file is closed, and /DISPOSE:SUBMIT sends the file to a batch queue (SYS$BATCH) when the file is closed. PRINTDELETE and SUBMITDELETE send the file to the appropriate queue and then delete the file when the job is finished. JLIST This is the query form. Allows you to display the diverted output file on one line and SYS$OUTPUT (the VMS name for your default output stream) on the next line (or just SYS$OUTPUT, if output is not being diverted). /REVERT Causes the return of system output from the diverted destination to your terminal. This is the same as using ) OUTPUT with no qualifiers. /SHADOW Allows you to display the diverted output on your terminal as well as sending it to a file. Otherwise, no system output is displayed except for system prompts and echoed input. If you want to begin shadowing output that is already diverted, you can reenter the original )0UTPUT command and add the /SHADOW and /APPEND qualifiers. If you want to discontinue shadowing while keeping the same diverted output stream, you can reenter the original ) 0UTPUT command with the omission APL Reference Manual 3-65 System Commands )OUTPUT Diverting Output to Another Device of the /SHADOW qualifier and the addition of the /APPEND qualifier. (You can change any of the original arguments or qualifiers at this time. If you omit information that you specified in the original ) 0UTPUT command, APL selects any default values that may be applicable. For example, output diverted from an APL terminal with the /TTY qualifier defaults to the APL character set if you do not reenter the /TTY qualifier.) Description )OUTPUT allows you to change the destination of output to a device other than your terminal. Typically, you send the output to a file or to another terminal. If the output is sent to a file, you can specify that you want to write the diverted output in a character set other than the one you designated for your terminal when you invoked APL. The possible values for character-set are /TTY, /KEY, /BIT, /COMPOSITE, and /APL. )OUTPUT with no arguments or qualifiers causes the system output to return from the diverted destination to your terminal. This is the same as using the /REVERT qualifier. When you use )0UTPUT, the output file has the appearance of a normal terminal display containing input lines and the resulting output. However, at your terminal the display is different. The only output that APL generates at your terminal is echoed input and APL prompts. APL echoes any input, whether it comes from your terminal or a file, and APL displays the usual 6-space prompt to signal the completion of a task. In fact, all APL-generated prompts (such as the 0SF prompt and function editor prompts) are still displayed at the terminal. If you want to see a normal display at your terminal, use the /SHADOW qualifier (see below). Note that )ouTPUT files cannot be nested. If you enter either a weak or strong attention signal while output is being diverted from your terminal, APL responds by displaying output on your terminal as well as in the diverted stream, just as if you had specified /SHADOW. The )oUTPUT system command is also described in the VAX APL User’s Guide along with other I/0 information. 3-66 APL Reference Manual System Commands )OUTPUT Diverting Output to Another Device Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (REDUNDANT KEYWORD OR QUALIFIER) 33 I0 ERROR (INVALID WILDCARD OPERATION) APL Reference Manual 3-67 System Commands ) OWNER Displaying Information About Workspace Creation ) OWNER Displaying Information About Workspace Creation Type Query System Command Form )OWNER Description ) OWNER displays information about the active workspace at the time it was created. A workspace is created when it is saved. The clear workspace is created when the ) CLEAR system command is given. The result of the ) OWNER appears in the following form: CREATED ON day dd-mmm-yyyy hh:mm:ss.tt BY name [uic] AT dev: WITH Iv.u-edit day dd-mmm-yyyy hh:mm:ss.tt is the day, date and time of creation name is the user name of the-creator uic is the user identification code of the creator dev: is the terminal device name used to create the workspace lv.u-edit is the version of APL used to create the workspace (see the description of 0 VERSION in Chapter 2) Examples: ) CLEAR CLEAR WS )OWNER CREATED ON THURSDAY 8-NOV-1990 18:11:49.32 BY (APLGRP,USER] AT WITH V3.2-83H4 )SAVE USER1WS THURSDAY 8-NOV-1990 YLOAD 18:11:49.51 3 BLKS USER1WS SAVED THURSDAY 8-NOV-1990 18:11:49.51 3 BLKS )OWNER CREATED ON THURSDAY 8-NOV-1990 18:11:49.51 BY [APLGRP,USER] AT WITH V3.2-834 3-68 APL Reference Manual System Commands ) OWNER Displaying Information About Workspace Creation Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual 3-69 System Commands ) PASSWORD Workspace Password ) PASSWORD Workspace Password Type Query/Change System Command Form ) PASSWORD [[pw]] Default in Clear Workspace Empty Qualifiers /PASSWORD :[[pw] Specifies the password associated with the active workspace. Description ) PASSWORD displays or changes the password associated with the active workspace. APL passwords are eight characters long, and the password you supply must be a valid APL identifier. Passwords longer than eight characters are truncated on the right; passwords with fewer than eight characters are padded on the right with blanks. If you do not change the password, the form of the ) PASSWORD display is as follows: / PASSWORD : pW If you do change the password, the form of the ) PASSWORD display is as follows: WAS /|PASSWORD: pw If the password is empty, the display is one of the following: /PASSWORD: WAS /PASSWORD: When you use ) PASSWORD to change the password, you can specify the new password directly after the ) PASSWORD, or you can specify it following / PASSWORD. For example: 3-70 APL Reference Manual System Commands ) PASSWORD Workspace Password )JPASSWORD SESAME WAS /PASSWORD: aPASSWORD WILL )PASSWORD BE TRUNCATED TO 8 CHARACTERS [PASSWORD:0PENSESAME WAS [PASSWORD:SESAME )PASSWORD [PASSWORD: WAS [PASSWORD:0PENSESA )PASSWORD /PASSWORD: To load or copy objects from a workspace with a nonblank password, you must include the password for the workspace in the command string. Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMED NAME) APL Reference Manual 3-71 System Commands ) PCOPY Copying from a Workspace with Protection ) PCOPY Copying from a Workspace with Protection Type Workspace Manipulation System Command Form )y PCOPY wsname [list]l Qualifiers /CHECK The optional /CHECK qualifier causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). If damage is detected, a message is displayed and APL tries to recover as much information as possible from the workspace and to continue the copy. The recovered workspace may be missing APL variables, user-defined operations, individual lines of user-defined operations, and other APL objects that were damaged. The user must determine what named objects have been removed from the workspace. /PASSWORD [ :Ipwil Specifies the password used when wsname was saved. Description ) PCOPY (protected copy) is the same as the ) COPY system command, except that ) PcoPY does not replace objects in the active workspace with objects of the same name in the copy workspace. Instead, APL returns the message NOT COPIED: along with the names of the objects affected. When copying groups, the ) PCOPY command does not copy any members of the group that have the same name in both workspaces. If the group name itself is the same as a group name in the active workspace, ) PCOPY does not copy the group name, nor any members of the group. The ) PCcoPY system command performs the same operation as the 0QPC system function (see Chapter 2), but JQPC does not display messages to verify the success of the copy. 3-72 APL Reference Manual System Commands ) PCOPY Copying from a Workspace with Protection Example: )JPCOPY VARS A SAVED TUESDAY FOUND: NOT COPIED: T 6-NOV-1990 18:21:58.41 13 BLKS T A Possible Errors Generated 22 INCORRECT PARAMFETER 22 INCORRECT PARAMETER (ILL FORMED NAME) 27 LIMIT FRROR (ARGUMENT STRING IS TOO LONG) 83 DAMAGED WORKSPACE HAS BEEN CORRECTED (SOME SYMBOLS MAY HAVE BEEN FRASED) APL Reference Manual 3-73 System Commands ) PUSH Interacting with Operating System Programs ) PUS H Interacting with Operating System Programs Type System Action System Command Form Y PUSH [command-string] Qualifiers /NOKEYPAD Specifies that you do not want the keypad characteristics of the current process to be available to the new subprocess. The default is that the characteristics are available. /NOLOGICALS Specifies that you do not want the logical name table from the current process to be available to the new subprocess. The default is that the table is available. /NOSYMBOLS Specifies that you do not want the global and local symbol table (defined at the DCL level) from the current process to be available to the new subprocess. The default is that the symbol table is available. /NOTIFY Determines whether VMS broadcasts a message to your current process when the new subprocess completes or aborts. If you are executing the ) PUSH command from the batch mode, you cannot use the /NOTIFY qualifier. Note that you can use /NOTIFY only when you specify the /nowait qualifier. / PROCESS : process-name Specifies the name for the new subprocess. If you do not use /NOWAIT, and you use the DCL command ATTACH rather than the LOGOUT command to return to APL, you can later use the YATTACH command with the process name that you specify. /NOWAIT Allows you to create a detached subprocess. When you specify /NOWAIT, control returns to APL when the subprocess begins execution, and the subprocess continues to execute in the background. Note that if the subprocess uses any 3-74 APL Reference Manual System Commands ) PUSH Interacting with Operating System Programs terminal I/0, it becomes mixed with any terminal I/O used by your current process. Description ) PUSH interrupts the APL session, creates a VMS subprocess, and puts you at DCL command level without terminating the APL session. You can perform any operation at the DCL command level; when you are finished, you can return to APL at the point you left off. Note that if you use an invalid qualifier when you specify ) PUsH, APL sends the unrecognized characters to the subprocess command level along with the command string. If you want to display the process name of any subprocess owned by the current process, use the DCL command SHOW PROCESS/SUBPROCESSES (for more details, see the VMS DCL Dictionary). When you use ) PUSH without a command string, you remain at DCL command level until you enter LOGOUT to return to APL. When you use ) PUSH with a command string (do not enclose the string in quotation marks), VMS executes the command string and then automatically returns control to APL. The command string must be no longer than 132 characters (after translation to ASCII), not including leading white space (spaces or tabs before the argument begins), but including all other white space within the argument. For example, entering ) PUSH and the DCL command SHOW TIME, and then LOGOUT has the same effect as entering ) PUSH with the command string SHOW TIME: )PUSH $SHOW TIME 23-NOV-1990 13:32:42 $LOGOUT Process USER1 logged out at 23-NOV-1990 13:33:13 YPUSH SHOW TIME 23-NOV-1990 13:33:41 While you are at DCL command level, your terminal is in ASCII rather than APL mode, and your terminal characteristics (such as output line width) revert to the system settings. When you return to APL, the APL character set is restored, and your [ P¥ setting is the same as it was before you executed the ) PUSH command (although the default for 0 Pw changes if you changed your system terminal width (see Chapter 2 for details). However, other terminal characteristics you may have changed at DCL command level (for example, the [0GAG setting, or the ability to input lowercase characters) remain changed. APL Reference Manual 3-75 System Commands ) PUSH Interacting with Operating System Programs APL makes no attempt to recover the output from any of the work you do at DCL command level. For example: TIME « ¢')PUSH SHOW TIME' 23-NOV-1990 13:40:34 11 VALUE ERROR (REQUIRED VALUE NOT SUPPLIED BY EXECUTE) TIME <« ¢'")PUSH SHOW TIME' A Here, APL executes the ) PUSH command, and VMS displays the result of the SHOW TIME command. But APL does not recover the output and cannot assign the value to the variable TIME. For more details about VMS subprocesses, see the VMS DCL Dictionary. Possible Errors Generated 22 INCORRECT PARAMETER (ILLEGAL ASCII CHARACTER) 22 INCORRECT PARAMETER (MISSING ARGUMENT) 22 INCORRECT PARAMETER (NOKEYPAD QUALIFIER REPEATED) 22 INCORRECT PARAMETER (NOLOGICALS QUALIFIER REPEATED) 22 INCORRECT PARAMETER (NOSYMBOLS QUALIFIER REPEATED) 22 INCORRECT PARAMETER (NOTIFY QUALIFIFER REPEATED) 22 INCORRECT PARAMETER (NOWAIT QUALIFIER REPEATED) 22 INCORRECT PARAMETER (PROCESS NAME QUALIFIER REPEATED) 73 SUBPROCESS ERROR (COMMAND BUFFER OVERFLOW---SHORTEN EXPRESSION OR COMMAND LINE) 3-76 APL Reference Manual ) System Commands SAVE Saving a Copy of the Active Workspace ) SAVE Saving a Copy of the Active Workspace Type Workspace Manipulation System Command Form YSAVE [[wsnamel Qualifiers /CHECK The optional /CHECK qualifier causes APL to examine the workspace for possible corruption (damage to the internal structure of the workspace). When / CHECK 1s specified on ) SAVE, APL checks for possible damage before saving the current workspace on disk. If there is damage, APL signals an error and aborts the execution of ) SAVE. If this occurs, use ) SAVE without /CHECK to save the damaged workspace; use ) L0AD with /CHECK to recover as much as possible from the damaged workspace and determine what APL objects have been lost from the damaged workspace. You must use the )SAVE command if you want to maintain an undamaged version of the recovered workspace. /MAXLEN[:n] The optional /MAXLEN qualifier allows you to specify the maximum record length, n (in bytes), to be used to save the workspace. If you omit /MAXLEN (or specify it without an argument), APL uses the value of 01 DML (see Chapter 2) as the maximum record length. /PASSWORD [ :Ipwli] The )SAVE system command allows you to specify a password for your workspace. The default is an empty password (eight blanks). If you save a workspace that has a password — either one you specify with ) SAVE or one specified earlier by the ) PASSWORD or )WSID command—you have to specify the password when you load or copy the workspace. Description ) SAVE saves a copy of the active workspace in a file specified by wsname. If you omit wsname, the file is saved with the name currently returned by ) ¥SID. APL Reference Manual 3-77 System Commands ) SAVE Saving a Copy of the Active Workspace The ) SAVE command displays the time and date the workspace is saved, the number of disk blocks required to store the workspace, and the workspace identification (either the name currently returned by ) ¥SID, or the name you specify as wsname). )SAVE appends a star (x) to the message if the saved workspace contains a suspended operation. When you save a workspace, you have the option of saving it under its current name—the name returned by ) ¥SID—or renaming it. However, APL does not save a workspace under a name that already exists in your storage area, unless the YWSID is that name. If you specify a new name with the ) SAVE command, you not only store your active workspace under that name, but you also change the name of the currently active workspace to the new name specified. If your current ) ¥SID is the same as a workspace you have already saved, APL creates a new version of the file. Both the old and new files are available on the appropriate storage device; however, the new file is considered the current version and has a version number one greater than that of the old file. APL does not save a clear workspace. If your workspace is clear, you must first give it a name with the )¥SID command, or you must use the ) SAVE command with a workspace name. | If you specify a password using ) PASSWORD or )WSID, but then save the workspace using the wsname parameter, the workspace is saved with an empty password (unless you specify a new one with ) SAVE). For example: YWSID MYWS/PASSWORD:SESAME WAS EXAMPLE ACHANGE THE WSID JSAVE MYWS THURSDAY 8-NOV-1990 19:42:58.52 15 BLKS JWSID MYWS aPASSWORD CHANGED TO EMPTY YPASSWORD / PASSWORD: aNO NEED FOR A PASSWORD WHEN LOADING YLOAD MYWS SAVED THURSDAY 8-NOV-1990 19:42:58.52 15 BLKS You can save a workspace while there is a suspended operation on the top of the SI stack. When you load the workspace, the operation is still suspended; it does not continue automatically. You can cause an automatic startup by using the 0LX system variable (see Chapter 2). 3-78 APL Reference Manual System Commands ) SAVE Saving a Copy of the Active Workspace If you execute a ) SAVE command within an operation, for example, with 0x¢ ') SAVE', APL saves the workspace, displays the time and date, and continues executing the operation. The next time you load that workspace, APL displays a slightly different message (see ) L0AD for details) and begins the session by executing that particular operation after the 0xqQ ') S4VE'. It does not execute O0LX, because 0 LX does not execute if the loaded workspace is in functiondefinition mode, or if the operation at the top of the state indicator stack is pendent. Examples: )CLEAR CLEAR WS YWSID CLEAR WS ) SAVE 60 WS NOT SAVED, THIS WS IS CLEAR WS ) SAVE A JWSID WS30 WAS CLEAR WS )SAVE THURSDAY 8-NOV-1990 YWSID WS10 19:u46:08.95 3 BLKS WS30 19:u46:09.24 3 BLKS WS10 WAS W530 )SAVE THURSDAY 8-NOV-1990 YJWSID WS30 WAS WS510 )SAVE WS10 60 WS NOT SAVED, THIS WS IS WS30 ) SAVE WS10 A JWSID WS35 WAS WS30 Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 59 WS NOT SAVED, THIS WS IS CLEAR WS APL Reference Manual 3-79 System Commands ) ST Displaying the State Indicator ) S I Displaying the State Indicator Type Query System Command Form )SI Description )SI displays the state indicator of the active workspace. The state indicator contains the status of the execution of user-defined operations, quad input requests, and execute functions. For user-defined operations, APL displays the operation name followed by, within brackets, the line and statement numbers at which the operation stopped executing. No statement number is displayed if the statement at which execution stopped is the first or only statement on the line. If a statement number is displayed, it is separated from the line number by a diamond (¢ ) character. A star following the bracketed line and statement number indicates that the operation is currently suspended; no star indicates that the operation is pendent. For example: ) ST F[2] = G[302] In this example, the pendent operation ¢ stopped executing at statement 2 on line [ 3] and is currently waiting for operation F, which was suspended at line [2]. Pendent quad input requests are indicated by a 0 character. For example: A<(] U: )SI U 0: First, the ) SI display shows that the quad input request is pendent; then, APL displays (1: to reprompt for quad input. 3-80 APL Reference Manual System Commands ) SI Displaying the State Indicator Pendent execute functions are indicated by the 0XQ or ¢ characters. For example: 0xgQ 0xqQ ')SsI! )ST (There ig no output) In this example, the ) ST display indicates that an execute function is pendent. This occurs because APL executes expressions from right to left, and the output from ) ST is displayed before the execute function is considered to have completed. Afterwards, the state indicator is clear. The order of display in the )SI list is significant; the operation or quad mput request that was most recently active is listed first, the next most recent request is listed second, and so on. Locked operations in the state indicator are flagged with a ¥ character, and no line number is displayed. You can clear individual operations from the state indicator by using the branch function (+) to restart or terminate suspended operations, or you can use the system function ORESET or ) SIC to clear the state indicator entirely. When the state indicator is clear, ) ST returns no result. For more information, see the VAX APL User’s Guide Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual 3-81 System Commands ) SIC Clearing the State Indicator the State Indicator ) S I C Clearing Type APL Action System Command Form )SIC Description )SIC clears the state indicator. Once cleared, the state indicator shows no suspended operations and no pending quad input requests or execute functions. After you use )SIC, the )SI, )SINL, and )SIS system commands do not return a value. The )SIC system command behaves in the same manner as the JRESET system function (see Chapter 2), and they can be used interchangeably. )SIC does not return a value. Possible Errors Generated 22 3-82 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual System Commands ) SINL Displaying the State Indicator and Local Symbols ) SINL Displaying the State Indicator and Local Symbols Type Query System Command Form YSINL Description SINIL displays the same information as )SI. This includes the status of ) the execution of user-defined operations, quad input requests, and execute functions. In addition, ) SINL lists the local symbols of each operation, and displays the argument expression of any pending execute function. Local symbols in locked operations (flagged with a ¥ character) are not displayed. For example: YSINL F[2] ~ G[(302] R A B ~ T C A D Here, the pendent operation ¢ has the local symbols T, C, 4, and D. The suspended operation F has the local symbols R, 4, and B. When the state indicator is clear, ) SINL returns no result. Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual 3-83 System Commands ) SIS Displaying the State Indicator and Executing Lines ) S 1.5 Displaying the State Indicator and Executing Lines Type Query System Command Form )SIS Description ) SIS displays the same information as ) SI. In addition, it displays the line that is currently being executed and the argument expression of any pendent execute functions. For example: ) ST F[2] * 0 G[302] ) SIS F[2] « B+0 s F X G[302] X«Ax2 ¢ Y«o 'F X! Here, the function 7 is suspended at line [2] because of an invalid division by zero. The execute function that called F is pending, and its argument is displayed. Finally, the function G is pending, and its currently executing line, containing the execute function that calls F, is displayed. Note that ) SIS does not display the executing line of a locked operation. When the state indicator is clear, ) SIS returns no result. Possible Errors Generated 22 3-84 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual System Commands ) STEP Executing Lines of a Suspended Operation ) STE P Executing Lines of a Suspended Operation Type APL Action System Command Form )STEPfln] Qualifiers /SILENT Specifies that APL should not display the operation name and the current line that are at the top of the state indicator after the execution of the lines of the operation. /INTO Specifies that you want APL to step into any called operations. /OVER Specifies that you want APL to step over any called operations. This is the default setting. Description ) STEP is a debugging feature that allows you to execute one or more lines of a suspended operation. The ) STEP command is valid only when specified from immediate mode, and when there is a suspended operation on the top of the state indicator. APL Reference Manual 3-85 System Commands ) STEP Executing Lines of a Suspended Operation Examples: - VFRILL [1] "FRILL LINE 1 [2] "FRILL LINE 2! [3] "FPRILL LINE [4] "PRILL 3' LINE 4! [5] "WRILL LINE 5' [6] v [1] FRILL [2]1 'T LINE 2 [31 'T LINE 3 [4] 'T LINE u (51 'T LINE 5 61 v | 1 JSTOP VT 'T! 1 T 77 STOPSET T(1] FRILL A ) SIS T[] * FRILL )STEP 4 FRILL LINE 1 FRILL JINTO LINE 2 FRILL LINE 3 FRILL[4] 'FRILL LINE 4 )SIC T 77 STOPSET T1] FRILL A )SIS T[1] = FRILL FRILL LINE )STEP 4 /OVER 1 FRILL LINE 2 FRILL LINE 3 FRILL LINE 4 FRILL LINE 5 T LINE 2 T LINE 3 T LINE 4 T{5] 3-86 '"T LINE 5 APL Reference Manual System Commands ) P Executing Lines of a Suspended Operation STE )SIC T 77 STOPSET FRILL Tf1] A )SIS I'f1] = FRILL )STEP 4 JOVER/SILENT FRILL LINE 1 FRILL LINE 2 FRILL LINE 3 FRILL LINE 4 FRILL LINE 5 T LINE 2 T LINE 3 T LINE 4 )SIS T[5] = 'T LINE 5! Possible Errors Generated 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) 22 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) 46 OPERATION INVALID IN THIS CONTEXT APL Reference Manual 3-87 System Commands ) VARS Displaying a List of Variables ) VARS Displaying a List of Variables Type Query System Command Form ) VARS [[start-stringlstop-string]l] Qualifiers /WSID: wshame Allows you to specify the nonactive workspace APL uses to develop the list. /PASSWORD : pW Specifies the password used to save the nonactive workspace. Description ) VARS displays a list of global names used as variable names in a workspace. By default, APL displays the list from the currently active workspace. The optional /WSID qualifier allows you to specify a nonactive workspace. If the nonactive workspace is saved with a password, you must also specify the / PASSWORD qualifier. The optional string parameters identify starting and stopping points for the list. When you specify the string parameters, you can use the » and = wildcards. The objects are listed in 0 AV order, separated by tabs. Each output line in the list begins in column 1. Note that the wildcard determines the start-string. There is no wildcard for the stop-string. If you use ) VARS with no parameters, APL displays all the global variable names in the workspace: ) VARS A I J K N If you include just one argument, APL uses Z as the second string: )VARS K K 3-88 N APL Reference Manual System Commands ) VARS Displaying a List of Variables To get a list of all variable names that begin with a given prefix, use the prefix for both arguments or use a wildcard: ) VARS PETER STAN STAN STEVE STUART THOMAS WILLIAM YVARS ST ST STEVE STUART ) VARS ST+ STAN STEVE STUART Possible Errors Generated 1 FILE NOT FOUND (FILE NOT FOUND) 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (FILE SPECIFICATION IS MISSING) 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIEK) 22 INCORRECT PARAMETER (NOT A LETTER) 57 FILE DOES NOT CONTAIN A WORKSPACE APL Reference Manual 3-89 System Commands ) VERSTION Displaying the APL Version Number ) VERSION Displaying the APL Version Number Type Query System Command Form YVERSION Description ) VERSTON displays the APL version number under which the currently active workspace was last saved, followed by a Carriage Return Line Feed, followed by the current version of the APL interpreter and a trailing <CR><LF>. The display is in the following form: Iv.u-edit | [ 1s the support letter v 18 the version number u 1s the update number edit 1s the edit number For example: ) VERS V3.2-834 V3.2-834 Possible Errors Generated 22 3-90 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) APL Reference Manual System Commands )WIDTH Output Width ) WIDTH Output Width Type Query/Change System Command Form YWIDTH [n] Default in Clear Workspace System setting Description YyWIDTH displays or changes the setting of the print width system variable (0 PW) and toggles the video screen between 80- and 132-column mode on some terminals (see below). The print width (n in the form) is the number of characters that can appear in an output line. The legal values are the integers from 35 through 2048. The )WIDTH system command does not affect the allowable length of input lines. However, it does affect the display of error messages. Lines in the error message that are longer than the print width are truncated; they are not wrapped to the next line. If truncating a line would prevent APL from displaying the point in the line where the error was discovered, APL cuts part of the beginning of the line from the display so that the error is visible. Executing the ) ¥IDTH system command in change mode has the same effect as assigning a value to the 0 P¥ system variable (see Chapter 2). When you use )WIDTH to set the print width to above or below 80 on some terminals, APL toggles the video screen between 80- and 132-column mode. For example, setting the width to 80 or less toggles the screen to 80-column mode. Setting the width to 81 or more toggles the screen to 132-column mode. The affected terminals are the VT220, VT240, VT320, VT330, VT340, VT102, DECTERM, HDSAVT, HDS201, and HDS221. Setting [0 P¥ does not cause this behavior. Note that APL uses two font files for the VT240, VT320, VT330, and VT340 support: one for 80-column and the other for 132-column mode. If you suspend the APL session and change the terminal width at DCL level, the screen will be in the new mode and APL will be in the previous mode when you return to APL. Use the appropriate value to )WIDTH to correct it. APL Reference Manual 3-91 System Commands )WIDTH Output Width Examples: YJWIDTH 132 A<'THIS IS A TEST OF THE PRINT WIDTH VARIABLE' A THIS IS A TEST OF THE PRINT WIDTH JWIDTH WAS VARIABLE 35 132 A THIS IS A TEST OF THE PRINT WIDTH V ARIABLE Possible Errors Generated 3-92 22 INCORRECT PARAMETER (EXTRANEOUS CHARACTERS AFTER COMMAND) 22 INCORRECT PARAMETER (ILL FORMFED NUMERIC CONSTANT) 22 INCORRECT PARAMETER (PARAMETER OUT OF RANGE) APL Reference Manual System Commands ) WSID Workspace ldentification ) WS ID Workspace ldentification Type Query/Change System Command Form YWSID wsnamell Default in Clear Workspace CLEAR WS with a blank password Qualifiers /PASSWORD [ :Ipwil Specifies the password associated with the workspace. Description )yWSID displays or changes the name of the active workspace. When you use )WSID to change the name of the active workspace, you must specify the wsname parameter. You can use the password qualifier of ) WSID to change the password associated with a workspace. When you use )¥SID as an action command, the password is changed (but not displayed) either to the password you specify as the argument to /PASSWORD or, if you do not specify a password, to the empty password (eight blanks). The password is never changed when you use )WSID as a query command () ¥SID with no argument). For example: YWSID MYWS/PASSWORD:SESAME WAS EXAMPLE JWSID MYWS ) PASSWORD / PASSWORD : SESAME YWSID YOURWS WAS MYWNS ) PASSWORD / PASSWORD: APL Reference Manual 3-93 System Commands ) XLOAD Retrieving a Workspace The file specification you give for wsname must include at least a file name. APL assumes default values for the rest of the specification; that is, it assumes the file type .APL, the current user device and directory, and an empty password. For more information on 0JLX, see Chapter 2. Possible Errors Generated 3-96 22 INCORRECT PARAMETER 22 INCORRECT PARAMETER (INVALID KEYWORD OR QUALIFIER) APL Reference Manual A System Messages If an error is detected during the evaluation of an expression, APL displays the following: * An appropriate primary error message from the list included in this appendix e The text of the line in which the error occurred * A caret (») approximately underneath the point in the line at which the error was discovered Often the primary error message is followed on the same line by a secondary error message that offers a more specific explanation of what caused the error. Secondary error messages are surrounded by parentheses. (If you do not want to see secondary error messages, set 1TERSE to 1.) When an expression that produces an error is executed by the 0xQ function, the result returned is an empty array with the shape 0 n, where n is an ERROR NUMBER. For example, the APL error number for VALUE ERROR is 11, so when an expression that produces a VALUE ERROR is executed by the 0X¢Q function, the value returned is an empty array with the shape 0 11: C<[0XQ '"4+B' pC 0 11 UERKOR 11 0XQ@ VALUE ERROR A+B A The following pages list the primary error messages and, when appropriate, explain what they mean and what you can do to correct the errors. Some of the secondary error messages that APL may display with the primary messages are also identified. In many cases, no explanation of secondary error messages 1S given, because the message is self-explanatory. APL Reference Manual A-1 System Messages 1 FILE NOT FOUND Explanation: The requested Workspace or file was not foundin the specified disk area. 1 FILE NOT FOUND (FILE NOT FOUND) 2 SYSTEM ERROR Explanation: An internal inconsistency was detected. Please report this error to your Digital software specialist. 3 WORKSPACE FULL Explanation: The active workspace could not retain all the information requested, nor could it expand further. Erase unneeded objects, issue a ) MAXCORE command to enlarge the workspace, or do a ) SAVE, ) CLEAR, and ) COPY sequence on the needed information. 3 WORKSPACE FULL ( FXCESSIVE FRAGMENTATION) 3 WORKSPACE FULL ( MAXCORE EXCEEDED) 3 WORKSPACE FULL ( VIRTUAL MEMORY FXHAUSTED) 4 NOT A VALID SYSTEM IDENTIFIER Explanation: An attempt was made to use a system identifier that is not supported by this APL implementation. 5 DEFN ERROR Explanation: Invalid syntax was detected in a line or command entered in function-definition mode. 5 DEFN ERKOR ( CANNOT DELETE HEADER) 5 DEFN FRROR ( EDIT COMMAND ILLEGAL IN QUAD FX ARGUMENT) 5 DEFN ERROR ( EXPECTING A DOLLAR SIGN) 5 DEFN FRROR ( EXPECTING A NUMBER) 5 DEFN FRROR ( EXPECTING A NUMBER, OR RIGHT BRACKET) 5 DEFN ERROR ( EXPECTING A NUMBER, QUAD, DELTA, OR JOT) 5 DEFN FRROR ( EXPECTING A QUAD, OR RIGHT BRACKET) A-2 APL Reference Manual System Messages DEFN ERROR ( FXPECTING A QUAD) DEFN FRROR ( EXPECTING A.RIGHT BRACKET) Explanation: An error was discovered while the function editor scanned an edit command string. DEFN ERROR ( EXPECTING A STRING DELIMITER) Explanation: Did not find a delimiter for one of the search or replace strings for dollar sign editing. DEFN ERROR ( ILL FORMED LINE NUMBER) DEFN FERROR (ILL FORMED NUMERIC CONSTANT) DEFN ERROR ( LEFT BRACKET FXPECTED) DEFN FRROR ( LINE NUMBER OUT OF RANGE) Explanation: A line number greater than 9,999 was specified. DEFN ERROR ( LINE NUMBER TRUNCATED) Explanation: More than five decimal digits were specified in a line number. | DEFN FRROR ( LOCAL SYMBOL EXPECTED) DEFN FRROR ( NAME IN USE) Explanation: An attempt was made to use the same identifier for both arguments of an operation, or for both a label and a local symbol or argument. DEFN FRROR ( NEGATIVE INTEGER NOT ALLOWED) DEFN ERROR (NO PREVIOUS SEARCH STRING) Explanation: The search string is empty and there was no previous use of dollar sign editing during this activation of the Del editor. DEFN ERROR (NO SYMBOL AFTER OPENING DEL) Explanation: The operation name was missing from the line entered. DEFN ERROR (NO SYMBOL AFTER RESULT ARROW) DEFN ERROR (NOT A SYSTEM VARIABLE) Explanation: An attempt was made to localize a system function. APL Reference Manual A-3 System Messages 5 DEFN ERROR ( NOT AN INTFEGER) Explanation: A print position parameter that is not an integer was entered in superedit mode. 5 DEFN FRROR ( NOT IN FUNCTION DEFINITION MODE) Explanation: An edit command was entered outside of function-definition mode. Edit commands are illegal in immediate mode except when used to display or edit the last executed input line. 5 DEFN FRROR ( OPERATION LOCKED) Explanation: An attempt was made to list or change a locked operation. 5 DEFN FRROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) Explanation: An attempt was made to edit a pendent or monitored operation, or an attempt was made to change the number of lines in a suspended operation or the definition of a local symbol in a suspended operation. | 5 DEFN FRROR ( OPERATION SUSPENDED OR PENDENT) Explanation: For ) EDIT, an attempt was made to end the VAXTPU session with an EXIT command when you are not allowed to modify the function. 5 DEFN KRROR (RIGHT BRACE FXPECTED) Explanation: An error was discovered while the function editor scanned an operation header and found a left brace that was not balanced with a right brace. 5 DEFN FRROR ( RIGHT PARENTHESIS EXPECTED) 5 DEFN FERROR ( RIGHT PARENTHESIS OR SYMBOL EXPECTED) 5 DEFN FRROR ( SEMICOLON EXPECTED) 5 DEFN EFRROR ( SYMBOL EXPECTED) 5 DEFN FRROR (TOO MANY LINES IN OPERATION) Explanation: An attempt was made to close an operation that has more than 10,000 lines. 5 DEFN FRROR A—-4 APL Reference Manual (UNEXPECTED CHARACTER IN HEADER) System Messages LABEL ERROR Explanation: Improper use of a colon was detected, or an improper variable name was entered as a label. LABEL ERROR (DUPLICATE LABEL) LABEL FERROR ( NAME IN USE) Explanation: An attempt was made to use the same identifier for both a label and a local symbol or argument. LABEL ERROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) Explanation: An attempt was made to change a label definition in a suspended, pendent, or monitored operation. SYNTAX FRROR Explanation: Invalid syntax was detected, such as an operation call with missing arguments, or an unmatched parenthesis. SYNTAX ERROR ( ILL FORMED NUMERIC CONSTANT) SYNTAX ERROR (MISMATCHED DELIMITERS) SYNTAX FERROR (MISSING ARGUMENT) SYNTAX ERROR (MISSING LEFT ARGUMENT TO ASSIGNMENT) Explanation: There is no left argument to the specification function (+ ). For example: «2 is incorrect. SYNTAX ERROR (MISSING OPERAND) SYNTAX ERROR ( NO DYADIC FORM OF FUNCTION) SYNTAX ERROR (NO MONADIC FORM OF FUNCTION) Explanation: Inner product and outer product are dyadic. SYNTAX FRROR ( OPERATOR HAS NO OPERANDS) SYNTAX ERROR ( UNBALANCED DELIMITER) SYNTAX ERROR ( BRANCH NOT ALLOWED IN MIDDLE OF AN EXPRESSION) Explanation: The branch (-~ ) function was used when it was not the principal function of a statement. APL Reference Manual A-5 System Messages 7 SYNTAX ERROR (DEPTH ERROR) Explanation: Either there are too many nested parentheses or brackets, or the expression is too complex for APL to parse. 7 SYNTAX FRROR ( ILLEGAL CHARACTER IN EXPRESSION) Explanation: An internal 04V code appeared outside of a literal or comment. - 7 SYNTAX ERROR (NO DYADIC FORM OF DERIVED FUNCTION) Explanation: Scan, reduction, expansion, compression, and replication all derive monadic functions. 7 SYNTAX ERROR (NO MONADIC FORM OF DERIVED FUNCTION) Explanation: Inner and outer product both derive dyadic functions. 7 SYNTAX FERROR (NON-NILADIC FUNCTION HAS NO ARGUMENTS) Explanation: An ambivalent, dyadic, or monadic user-defined operation was invoked without any arguments. 7 SYNTAX ERROR (NOT IN FUNCTION DEFINITION MODE) Explanation: An editing command was entered at the beginhing of a line in immediate mode. 7 SYNTAX FRROR ( SUBSCRIPT NOT ALLOWED) Explanation: An attempt was made to index something that does not have a value. 7 SYNTAX ERROR ( WRONG NUMBER OF ARGUMENTS TO USER FUNCTION) Explanation: A monadic user-defined operation was invoked with two arguments. 8 FRROR RETURNING FROM EXTERNAL ROUTINE 8 FRROR RETURNING FROM EXTERNAL ROUTINE (DOMAIN FRROR) Explanation: A conversion failed when data returned to the workspace. 8 ERROR RETURNING FROM EXTERNAL ROUTINE ( ILLEGAL ASCII CHARACTER) Explanation: A conversion to ASCII failed as character data returned to the workspace. A-6 APL Reference Manual System Messages FRROR RETURNING FROM EXTERNAL ROUTINE ( LENGTH FRROR) Explanation: A Varying string (/ TYPE: VT) returned to the WS is bigger than it was when it was passed to the external routine. (It is allowed to be smaller or the same size.) RANK ERROR Explanation: The ranks of two operands did not conform. RANK ERROR ( ITEMS NOT SCALAR OR ALL THE SAME RANK) Explanation: The items of the right argument of disclose () are neither scalars nor of matching rank. | RANK ERROR ( ITEMS NOT SINGLETON OR ALL THE SAME RANK) Explanation: The items of B must be either singletons or of matching rank. RANK FRROR ( LEFT ITEM NOT VECTOR DOMAIN) Explanation: Either the left argument or an item in the left argument to pick () is not a singleton and its rank is greater than 1. RANK FRROR (MUST BE VECTOR) Explanation: The value and each item in the value, must be vectors. RANK ERROR (NOT A SCALAR, VECTOR, OR MATRIX) Explanation: The rank of an argument to B, ¥ or 4 is greater than 2. RANK FERROR (NOT MATRIX DOMAIN) RANK ERROR ( NOT SINGLETON) Explanation: Deal, and the OWAIT and O0DL functions accept only single numbers as an argument. RANK ERROR (NOT VECTOR DOMAIN) Explanation: An argument or value is not a singleton and its rank is greater than 1. RANK ERROR ( NUMERIC PRIMARY KEY MUST BE SINGLETON) Explanation: A numeric key for a keyed file must be a singleton. RANK ERROR ( RANKS DIFFER BY MORE THAN ONFE) Explanation: The arguments, after singleton extension to catenate or rotate differ in rank by more than one. APL Reference Manual A-7 System Messages 10 LENGTH FRROR Explanation: The shapes of two operands did not conform. 10 LENGTH ERROR ( ARGUMENT MUST BE 1 OR 2 ELEMENTS) Explanation: 8, 8, 0CI9, and 0 c0Q may have at most two items in their right argument. 10 LENGTH ERROR ( ARGUMENT STRING IS TOO LONG) Explanation: The left argument to dyadic 4 or v is greater than 256 characters along any one axis. 10 LENGTH ERROR ( DATA TYPE EXCEEDS DATA LENGTH) Explanation: The data type specified for @ file input or the 0¢7¢ function 1s incompatible with the length of the left argument. 10 LENGTH ERROR ( DATA TYPE MISSING) Explanation: The data type parameter in the right argument to JcIq is required in this case. 10 LENGTH FRROR ( DISPLAY CONTROL ITEM WRONG LENGTH) Explanation: The first item must have length 4. The second item can either be empty or have length 8. 10 LENGTH FRROR (DISPLAY CONTROL VECTOR MUST BE TWO ITEMS) Explanation: The value must have length 2. 10 LENGTH ERROR ( ILLEGAL EMPTY ARGUMENT) Explanation: An empty argument was used with 0FMT, OMAP, 0QCO, O0QLD, 0QPC, or 1SIGNAL. 10 LENGTH ERROR ( INDEX LESS THAN INDEX ORIGIN) Explanation: An index is less than the current setting of [ 70. 10 LENGTH FRROR ( INDEX OUT OF RANGE) Explanation: For pick (), an element of the left argument exceeds the length of the corresponding axis of an item of the right argument. 10 LENGTH ERROR ( ITEM COUNT MISMATCH) Explanation: If the number of variable names specified in the right argument to [ PACK, 1s not equal to the number of packets contained in the left argument. A-8 APL Reference Manual System Messages 10 LENGTH FRROR (KEY VALUFE TOO LARGE FOR KFY SIZFE) Explanation: For /XY files. 10 LENGTH ERROR ( LEFT ARGUMENT LENGTH GREATER THAN RIGHT ARGUMENT DEPTH) Explanation: For pick (=), the length of the left argument is greater than the depth of the right argument. 10 LENGTH ERROR (LEFT ITEM LENGTH NOT EQUAL TO SELECTED ITEM RANK) Explanation: For pick (=), the length of an item of the left argument does not match the rank of the selected item at the corresponding depth of the right argument. 10 LENGTH ERROR ( LEFT LENGTH NOT EQUAL TO RIGHT RANK) Explanation: For +, +, or dyadic &, where no axis has been specified and the right argument B is not a scalar and its rank is not equal to the length of the left argument 4. 10 LENGTH FRROR ( LENGTHS OF INNER AXES DO NOT MATCH) Explanation: For Base, the length of the last axis of the left argument A 1is not equal to the length of the first axis of the right argument B, and neither axis is 1. For Inner product, after singleton extension, the left argument last axis length must equal the right argument first axis length. 10 LENGTH ERROR (NOT SINGLETON) Explanation: The value is not a single item. Dyadic 8 (for /45 files), 7, and the numeric system variables require a single item for their argument or value. For example, the following is incorrect: 070+« 1 3 10 LENGTH FRROR ( NUMBER OF ROWS MUST MATCH) Explanation: The number of rows in the arguments to dyadic § must match. 10 LENGTH FRROR ( SHAPES OFF AXIS DO NOT MATCH) Explanation: For Catenate and Rotate, after singleton extension, the shape of the left argument must match the shape of the right argument except along the specified axis. 10 LENGTH ERROR ( THERE ARE FEWER ROWS THAN COLUMNS) Explanation: The number of rows in the right argument to # must be greater than or equal to the number of columns. APL Reference Manual A-9 System Messages 10 LENGTH ERROR (TOO MANY ELEMENTS IN KEY SPECIFICATION) Explanation: An attempt was made to include elements other than value, key-num, tech, and key-type between the brackets of your file output expression. 11 VALUE ERROR Explanation: A variable name was used and has not been assigned a value, or a user-defined operation that should return a value was executed and it did not return a value. 11 VALUE FRROR ( BRANCH HAS NO RESULT) Explanation: A branch (+) expression was used as a response to [J input. 11 VALUE FRROR (FUNCTION DOES NOT RETURN A RESULT) 11 VALUE FRROR ( FUNCTION RESULT UNDEFINED) 11 VALUE ERROR (NO VALUE TO ASSIGN) Explanation: There is no right argument to the specification function (< ). For example: T« is incorrect. 11 VALUE ERROR ( REQUIRED VALUE NOT SUPPLIED) 11 VALUE ERROR ( SUBSCRIPTED NAME IS UNDEFINED) Explanation: In the form A[X]1+B, 4 is not a defined name. 14 DEPTH FRROR Explanation: For JFMT there are more than eight nested parentheses in A. 14 DEPTH ERROR (LEFT ARGUMENT DEPTH GREATER THAN 2) Explanation: The items in 4 must be simple (vectors or singletons). 14 DEPTH ERROR ( TOO MANY DIVERTED INPUTS) Explanation: Files were nested to a depth greater than 10 with ) INPUT. 15 DOMAIN FRROR Explanation: The values given for the arguments were outside of the function domain. For 0¥, the argument is not Boolean and is nonempty. 15 DOMAIN ERROR ( BUFFER OVERFLOW) A-10 APL Reference Manual System Messages 15 DOMAIN ERROR ( CANNOT MODIFY SEFLECTIVE ASSIGNMENT TARGET) Explanation: The variable being assigned to cannot be modified by the expression forming the left argument of the selective assignment. For example: ( (pA<+12)¢$A)<«"'AB' is incorrect. 15 DOMAIN ERROR ( CANNOT SIGNAL FOF) Explanation: An attempt was made to use 75 as the right argument to O0SIGNAL. OSIGNAL does not accept 756 as a right argument. 15 DOMAIN ERROR ( CHANNEL NOT ASSIGNED) Explanation: The value in the right argument does not refer to an assigned channel. An attempt was made to use OWAIT or JREWIND on an unassigned channel. 15 DOMAIN ERROR ( CHANNEL NOT ASSIGNED TO A KEFYED FILE) Explanation: The file associated with the channel number is not a /KXY file. 15 DOMAIN ERROR ( CHARACTER KEY TOO LONG OR NOT IN VECTOR DOMAIN) Explanation: For /K7 15 files. DOMAIN ERROR ( CONFLICTING QUALIFIERS SPECIFIED) Explanation: More than one of the following qualifiers was specified in the argument to JASS:/READONLY, /WRITEONLY, or /UPDATE. 15 DOMAIN ERROR (DATA TYPE MUST BE UNSPECIFIFED OR ZFRO) Explanation: For 0CIQ. 15 DOMAIN FRROR (DELETION NOT ALLOWED) Explanation: A sequential delete was attempted for a /XY or /A4S file. 15 DOMAIN ERROR (DIVISION BY ZERO) Explanation: Division by zero is attempted. 15 DOMAIN ERROR ( DUPLICATE FMT QUALIFIER) Explanation: A qualifier is used more than once with a particular format phrase. 15 DOMAIN ERROR ( DUPLICATE FMT STANDARD SUBSTITUTION CHARACTER) Explanation: A substitute for a standard symbol character was specified more than once. APL Reference Manual A-11 System Messages 15 DOMAIN ERROR ( EMPTY FMT STRING PARAMETER NOT ALLOWED) Explanation: The O, R, or S qualifier string is empty. 15 DOMAIN ERROR ( ENCLOSED/HETEROGENEOUS ARRAY NOT ALLOWED) Explanation: The argument is not a simple, homogeneous array. For 0Dc, the first item must be a simple homogeneous array. The second item, if not empty, must be simple. 15 DOMAIN FRROR ( ENCLOSED VALUE REQUIRED) Explanation: The value must be an enclosed array. 15 DOMAIN ERROR ( FRROR ACTIVATING IMAGE) Explanation: For J¥4P, the shared image named by B does not exist. For 0TT, ) EDIT, or the initialization stream, there is an attempt to enter V1220, VT240, VT320, VT330, VT340 or DECterm mode when SYS$SYSTEM:APLSHR is not accessible. APL can signal this error when you invoke APL with the /TERMINAL qualifier, when you use ) EDIT with the /TERMINAL qualifier, when you use ) EDIT with an HDS201 or HDS221 terminal, or when you set O TT. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO BLOCK SIZE) Explanation: An error was discovered when parsing the /BLOCKSIZE qualifier in the argument to JASS. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO BUFFER COUNT) Explanation: An error was discovered when parsing the /BUFFERCOUNT qualifier in the argument to JA4S5. | 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO CCONTROL) Explanation: An invalid value was specified for the /CCONTROL qualifier in the argument to 0 ASS. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO DEFAULT FILE SPEC) Explanation: An error was discovered when parsing the /DEFAULTFILE qualifier in the argument to 0455. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO DISPOSE) Explanation: An error was discovered when parsing the /DISPOSE qualifier in the argument to 04S5. A-12 APL Reference Manual System Messages 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO EVENT FLAG) Explanation: An error was discovered when parsing the /EFN qualifier in the argument to JA4SS. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO KEY SPECIFICATION) Explanation: An error was discovered when parsing the /kY qualifier in the argument to JASS. 15 DOMAIN FRROR ( ERROR PARSING ARGUMENT TO MAXLEN) Explanation: An error was discovered when parsing the /MAXLEN qualifier in the argument to 0ASS. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO PROTECTION) Explanation: An error was discovered when parsing the /PROTECTION qualifier in the argument to 0ASS. 15 DOMAIN ERROR ( ERROR PARSING ARGUMENT TO RECORD TYPE) Explanation: An error was discovered when parsing the /RECORDTYPE qualifier in the argument to 0ASS. 15 DOMAIN ERROR ( EXTRANEOUS CHARACTERS AFTER COMMAND) Explanation: There are characters other than spaces following the command. 15 DOMAIN ERROR (FILE IS ASSIGNED WRITE ONLY) Explanation: The file associated with the channel number cannot be rewound because it was assigned with the /WRITEONLY qualifier. 15 DOMAIN FRROR (FILFE SPECIFICATION IS MISSING) Explanation: There is no file specification or default file specification in the argument to JASS. 15 DOMAIN ERROR ( FMT DECORATION OR LITERAL STRING T0OO LONG) Explanation: A text string in the left argument consists of more than 255 characters. 15 DOMAIN ERROR ( FMT RIGHT ARGUMENT DOES NOT MATCH FORMAT PHRASE) Explanation: The data type of a value in the right argument does not match the type called for by a format phrase specification in the left argument. APL Reference Manual A-13 System Messages 15 DOMAIN FRROR ( FONT FILFE COULD NOT BE OPENED) Explanation: For 077 or the initialization stream, there is an attempt to enter VT220, VT240, VT320, VT330 or VT340 mode when the APL font file is not accessible. Possibly, the file does not exist or is associated with a protection code that does not allow access. 15 DOMAIN FRROR (FUNCTION HAS NO FILL ITEM) Explanation: Either each () or outer product (- .r) was applied with a user-defined function to an empty argument. 15 DOMAIN ERROR (FUNCTION HAS NO IDENTITY ELEMENT) Explanation: The inner axes of an inner product or the reduction axis is empty and there is no identity element for the left operand function. 15 DOMAIN FRROR ( FUNCTION MISSING) Explanation: For 1MAP, if function-name is not present or if it is followed by any attributes. 15 DOMAIN ERROR (ILL FORMED FMT PARAMETER) Explanation: An invalid numeric parameter (such as a negative sign with no number) was found. 15 DOMAIN FRROR (ILL FORMED NAME) Explanation: For OMAP, if the left argument has a formal parameter that contains illegal characters, or if the right argument has a value for the /ENTRY or /VALUE qualifier that contains illegal characters. 15 DOMAIN FRROR ( ILLEGAL ASCII CHARACTER) 15 DOMAIN FRROR ( ILLEGAL CHARACTER IN FMT LEFT ARGUMENT) Explanation: An invalid character appears in the left argument of 0 FuT. 15 DOMAIN ERROR ( ILLEGAL COMPOSITE CHARACTER) 15 DOMAIN ERROR ( ILLEGAL DATA TYPE CONVERSION) 15 DOMAIN FRROR (ILLEGAL DEC MULTINATIONAL CHARACTER) 15 DOMAIN FRROR ( ILLEGAL FMPTY ARGUMENT) 15 DOMAIN FRROR ( ILLEGAL FMT FORMAT PHRASE) Explanation: A letter in the left argument of 0 FMT does not represent a valid format phrase or qualifier. A-14 APL Reference Manual System Messages 15 DOMAIN ERROR (ILLEGAL FMT G FORMAT PHRASE PATTERN CHARACTER) Explanation: An invalid character was found in a type G format phrase pattern string. 15 DOMAIN ERROR ( ILLEGAL FMT LITEFRAL STRING DELIMITER) Explanation: A decorator or literal string delimiter was invalid. 15 DOMAIN ERROR ( ILLEGAL FMT S QUALIFIER SYMBOL) Explanation: The first symbol of a substitution pair is not x, ., ,, 0, 9, 7,0r@. 15 DOMAIN ERROR 15 (ILLEGAL IS0 8BIT CHARACTER) DOMAIN FRROR (ILLEGAL LEFT ARGUMENT TO ASSIGNMENT) Explanation: An element of 4 is not an undefined or variable name. 15 DOMAIN ERROR (ILLFEGAL MODE) 15 DOMAIN EFRROR (ILLEGAL NAME CLASS) Explanation: For [ PACK, the right argument is not a variable. For assignment (<), the left argument is neither a variable nor an undefined name. 15 DOMAIN ERROR ( ILLEGAL SELECTIVE ASSIGNMENT FUNCTION) Explanation: The function fis not one of the allowed selection functions. 15 DOMAIN ERROR ( ILLEGAL USE OF FMT QUALIFIER) Explanation: The specified qualifier and format phrase are incompatible. 15 DOMAIN ERROR ( INCORRECT PARAMETER) Explanation: A parameter in the left argument to JMAP 1s incorrect. 15 DOMAIN FRROR ( INCORRECT TYPFE) Explanation: An argument is non-empty and is either numeric, when it should be character, or character when it should be numeric. For example, the following is incorrect: 070« 'G' 15 DOMAIN ERROR ( INDEX LESS THAN INDEX ORIGIN) Explanation: An element of an argument is less than the current setting of 0 I0. APL Reference Manual A-15 System Messages 15 DOMAIN FRROR ( INDEX OUT OF RANGE) Explanation: An element of the left argument exceeds the length of the corresponding axis of an item of the right argument. 15 DOMAIN ERROR ( INTEGER OVERFLOW) 15 DOMAIN FRROR ( INVALID CHANNEL NUMBER) Explanation: A channel number is not between =~ 999 and 999 or is 0. 15 DOMAIN ERROR ( INVALID CIQ HEADER) 15 DOMAIN ERROR ( INVALID EXTERNAL DATA TYPE) 15 DOMAIN FRROR ( INVALID FILE SPECIFICATION) Explanation: There is an error in the shared image file specification in the right argument of OMAP. 15 DOMAIN FRROR ( INVALID FUNCTION IN SELECTIVE ASSIGNMENT) Explanation: The principal function or functions in the left argument is ineligible for use with selective assignment. For example: (A4+B) «3 is incorrect. 15 DOMAIN KFRROR ( INVALID HEADER TYPE) Explanation: An incorrect header type was specified for 15 0C0qQ or 0CIQ. DOMAIN FRROR ( INVALID KEYED FILE PURFE DATA TYPE) Explanation: For /x7Y files. 15 DOMAIN ERROR ( INVALID LENGTH IN PACK HEADER) Explanation: The first item of the value in the left argument to O PACK must equal the length of the left argument. 15 DOMAIN ERROR ( INVALID OBJECT IN INDEXED ASSIGNMENT ) 15 DOMAIN FRROR ( INVALID OBJECT IN SELECTIVE ASSIGNMENT) Explanation: The first object inside the paréntheses of selective assignment must be a variable name. For example: ( 14 2) « 3 is incorrect. 15 DOMAIN ERROR A-16 APL Reference Manual ( INVALID OBJECT IN STRAND ASSIGNMENT) System Messages 15 DOMAIN ERROR ( INVALID PACK HEADER) Explanation: The length of the left argument to 0 PACK must be greater than or equal to 8. The shortest possible packed data has four elements for the 0 PACK header and 4 elements for the shortest 0 C0Q header. 15 DOMAIN ERROR ( INVALID RANK IN PACK HEADER) Explanation: The value of the third element in the left argument to 0 PACK must equal 1 (1 means the packed data is a vector). 15 DOMAIN ERROR ( INVALID RHO VECTOR IN PACK HEADER) Explanation: The length of the left argument to 0 PACK must equal the value of the fourth element in the left argument plus 4. 15 DOMAIN ERROR ( INVALID TYPE IN PACK HEADER) Explanation: The value of the second element in the left argument to 0 PACK must equal 1 (1 means the type is integer). 15 DOMAIN ERROR ( INVALID WATCH MODE) Explanation: An incorrect mode was specified for 15 OVATCH. DOMAIN ERROR ( KEY OF REFERENCE OUT OF RANGE OR NOT A NUMERIC SINGLETON) Explanation: An attempt was made to specify a key of reference that is not a numeric singleton or that is less than O or greater than 254 (inclusive). 15 DOMAIN FRROR ( KEY NOT FOUND IN TREFE) Explanation: For JMAP, if the left argument specifies an entry point that does not exist in the shared image. 15 DOMAIN ERROR ( LEFT ARGUMENT NOT DENSE FROM INDEX ORIGIN) Explanation: For dyadic &, the left argument is not a dense sequence beginning at 0 I0. 15 DOMAIN ERROR (MISSING FMT FORMAT PHRASE SEPARATOR) Explanation: A format phrase separator (such as a comma or parenthesis) was expected but not supplied. 15 DOMAIN ERROR ( MISSING FMT FORMAT PHRASE/QUALIFIER CHARACTER) Explanation: A format phrase or qualifier was expected but not supplied. APL Reference Manual A-17 System Messages 15 DOMAIN EFERROR (MISSING FMT FORMAT PHRASE/QUALIFIER PARAMETER) Explanation: No string was included with a decorator or an S format phrase; no number was included where a width or decimal parameter was required; or no number was included with a K or W qualifier. 15 DOMAIN FRROR (MISSING LITERAL STRING IN FMT LEFT ARGUMENT) Explanation: The text string parameter was missing from a decorator. 15 DOMAIN FRROR ( NAME IN USE) Explanation: For 1¥AP, if the name specified for function-name is already defined as an object other than a function. 15 DOMAIN FRROR (NEGATIVE INTEGER NOT ALLOWED) 15 DOMAIN FERROR ( NEGATIVE NUMBER NOT ALLOWED) Explanation: The value of the argument is less than 0. 15 DOMAIN ERROR (NO DIGIT SELECTOR IN FMT G FORMAT PHRASE PATTERN) Explanation: A type G format phrase pattern does not contain at least one 9 or one Z, or a character that is substituted for a 9 or a Z. 15 DOMAIN FRROR (NO FMT EDITING FORMAT PHRASE) Explanation: The left argument of ] FMT does not contain at least one value editing format phrase, that is, at least one of type A, I, E, F, G, or Y. 15 DOMAIN FRROR (NOT A LETTFR) Explanation: A nonletter was used as the left argument to ONL. 15 DOMAIN FRROR (NOT A SYSTEM VARTABLE) Explanation: The argument is a quad name but not a system variable. 15 DOMAIN ERROR (NOT A VALID SYSTEM IDENTIFIER) 15 DOMAIN ERROR (NOT AN EXTERNAL FUNCTION) Explanation: For (MA4P, if the argument names an illegal identifier, a system identifier, a name with no value, or a name that is not an external function. 15 DOMAIN FRROR (NOT AN INTEGER) Explanation: An argument is not a near-integer. For example, the following is incorrect: 0 I0<«2.5 A-18 APL Reference Manual System Messages 15 DOMAIN ERROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) 15 DOMAIN ERROR ( PARAMETER OUT OF RANGE) Explanation: An attempt was made to use an unavailable value as the argument. For 0DC, Elements 1 and 2 of the first item can only be = 1, 0, or 1. For OFMT, the repetition count, field width, number of decimal places or significant digits, column position, scale factor, or exponent size is out of range. 15 DOMAIN FRROR ( REDUNDANT KEYWORD OR QUALIFIER) Explanation: A keyword or qualifier was repeated in the argument to OASS. 15 DOMAIN ERROR (RIGHT ARGUMENT IS LESS THAN LEFT) Explanation: For dyadic 7. 15 DOMAIN ERROR ( RIGHT ARG TOO DEFEPLY NESTED) Explanation: The right argument to JFMT is not a vector domain of simple arrays. 15 DOMAIN ERROR ( SEMICOLON LIST NOT ALLOWED) Explanation: A semicolon list was used as an argument to a primitive function. 15 DOMAIN ERROR ( SINGULAR MATRIX) Explanation: For B, division by 0 is attempted. 15 DOMAIN ERROR (SYSTEM VARIABLFE MUST BE 0 OR 1 OR 2 OR 3) Explanation: The value of 0GAG must be 0, 1, 2, or 3. 15 DOMAIN ERROR ( SYSTEM VARIABLFE VALUE MAY ONLY BE 0 OR 1) Explanation: 010, 0NG, OTERSE, JTIMEOUT, or O TLE accept only O or 1. 15 DOMAIN ERROR ( TIMEOUT READ UNSUPPORTED FOR CURRENT VALUE OF QUAD TT) Explanation: An attempt was made to set J TIMELIMIT while the current value of 0 TT indicates a VT220, VT240, VT320, VT330, VT340 or DECterm terminal. 15 DOMAIN ERROR ( UNBALANCED PARENS IN FMT LEFT ARGUMENT) Explanation: The parentheses in the left argument of 0 FMT are not nested properly. APL Reference Manual A-19 System Messages 15 DOMAIN ERROR ( UNBALANCED TEXT DELIMITFER IN FMT LEFT ARGUMENT) Explanation: The closing delimiter for a text string was not compatible with the opening delimiter. 15 DOMAIN ERROR (UNPAIRED SYMBOL IN FMT S QUALIFIER) Explanation: The length of the standard symbol substitution string is not even. 15 DOMAIN ERROR ( UNRECOGNIZED SEARCH MODE) Explanation: For /k7Y files. 15 DOMAIN ERROR (UNSUCCESSFUL TRAP IN LOCKED FUNCTION) Explanation: An error occurred while executing the trap expression in a locked function. 15 DOMAIN ERROR (WIDTH TOO SMALL) Explanation: The width parameter for dyadic + is too small to accommodate the data. 15 DOMAIN ERROR ( WILDCARDS NOT ALLOWED IN FILE SPECIFICATION) Explanation: Wildcards are not allowed in the right argument to QM4P. 16 UNBALANCED DELIMITER Explanation: An input line has unbalanced parentheses, or the argument to the execute function contains unbalanced quotation marks or A characters. 17 EDIT FRROR Explanation: An improper character editing request was entered. 17 EDIT FRROR ( COLUMN POSITION OUT OF RANGE) Explanation: The print position number that was entered for superedit was greater than the page width, or was negative. 17 EDIT ERROR (EXPECTING A RIGHT BRACKET) Explanation: An attempt was made to delete the line number during line editing. 17 EDIT ERROR A-20 (ILL FORMED LINF NUMBER) APL Reference Manual System Messages 17 EDIT ERROR ( ILLEGAL CHARACTER IN LINE EDIT COMMAND) Explanation: The command that was entered included a character other than a letter, digit, /, space, or backspace. 17 EDIT FRROR ( LEFT BRACKET MISSING) 17 EDIT ERROR ( LINE FDITING NOT ALLOWED IN EXECUTE) 17 EDIT FRROR ( NONEXISTENT LINE) 17 EDIT ERROR ( PREVIOUS INPUT LINE EMPTY) 17 EDIT ERROR ( OPERATION SUSPENDED, PENDENT, OR MONITORED) Explanation: An attempt was made to make an illegal change to a suspended, pendent, or monitored operation. 18 ATTENTION SIGNALED Explanation: The attention signal was detected during operation execution. 19 DEVICE DOES NOT EXIST Explanation: An invalid device specification was entered. 20 DEVICE NOT AVAILABLE Explanation: The requested device has already been assigned to another process. 21 INCORRECT COMMAND Explanation: A system command was entered improperly. 21 INCORRECT COMMAND ( AMBIGUOUS ABBREVIATION) Explanation: Not enough characters of a system command were entered to distinguish it from other commands. 21 INCORRECT COMMAND (MISSING SYSTEM COMMAND) Explanation: A right parenthesis was entered at the beginning of a line and was not followed by a known system command. 21 INCORRECT COMMAND (NO SUCH SYSTEM COMMAND) 22 INCORRECT PARAMETER Explanation: Invalid syntax was specified for a recognized system command. APL Reference Manual A-21 System Messages 22 INCORRECT PARAMETER ( ARGUMENT STRING IS TOO LONG) Explanation: The argument entered for ) DO or ) PUSH was more than 2096 keystrokes. 22 INCORRECT PARAMETER ( CURRENT WORKSPACE CLEARED) Explanation: APL failed to load the requested workspace. 22 INCORRECT PARAMETER ( EXTRANEOUS CHARACTERS AFTER COMMAND) Explanation: Extra characters were entered after all the required parameters for a system command. 22 INCORRECT PARAMETER ( ILL FORMED NAME) Explanation: In the argument to ) ERASE or ) GROUP. 22 INCORRECT PARAMETER ( ILL FORMED NUMERIC CONSTANT) Explanation: A numeric argument to a system command was entered improperly. 22 INCORRECT PARAMFETER ( ILLEFGAL ASCII CHARACTER) Explanation: An illegal character was used in the argument to ) PUSH. 22 INCORRECT PARAMETER ( ILLEGAL NAME CLASS) Explanation: A label or system object was used in the argument to ) GROUP. 22 INCORRECT PARAMETER ( INVALID CHARACTER SET QUALIFIER) Explanation: An invalid qualifier was used in the argument to ) INPUT or ) OUTPUT. 22 INCORRECT PARAMETER ( INVALID KEYWORD OR QUALIFIER) Explanation: An invalid keyword or qualifier was used in the argument to ) INPUT, ) OUTPUT, ) SAVE, or ) STEP. 22 INCORRECT PARAMFETER (LINFE TOO LONG TO TRANSLATE) Explanation: The argument entered for ) DROP or ) LIB was greater than approximately 2048 keystrokes. 22 INCORRECT PARAMETER ( LOWNERCASE QUALIFIER REPEATED) Explanation: An invalid repetition of /LOWVERCASE was used in the argument to ) DO or ) PUSH. A-22 APL Reference Manual System Messages 22 INCORRECT PARAMETER (MISSING ARGUMENT) Explanation: An argument was not supplied for a system command that should have one. 22 INCORRECT PARAMETER ( NOKEYPAD QUALIFIER REPEATED) Explanation: An invalid repetition of /NOKEYPAD was used in the argument to ) DO or ) PUSH. 22 INCORRECT PARAMETER (NOLOGICALS QUALIFIER REPEATED) Explanation: An invalid repetition of /NOLOGICALS was used in the argument to ) DO or ) PUSH. 22 INCORRECT PARAMETER (NOSYMBOLS QUALIFIER REPEATED) Explanation: An invalid repetition of /NOSYMBOLS was used in the argument to ) DO or ) PUSH. 22 INCORRECT PARAMETER ( NOT A GROUP) Explanation: An attempt was made to display the contents of a nongroup. 22 INCORRECT PARAMETER (NOT A LETTFER) Explanation: The argument to ) NMS, ) VARS, ) FNS, or ) GRPS was not a letter. 22 INCORRECT PARAMETER (NOTIFY QUALIFIER REPEATED) Explanation: An invalid repetition of /NOTIFY was used in the argument to the ) PUSH command. 22 INCORRECT PARAMETER (NOWAIT QUALIFIER REPEATED) Explanation: An invalid repetition of /NOWAIT was used in the argument to the ) PUSH command. 22 INCORRECT PARAMETER ( PARAMETER OUT OF RANGE) Explanation: The numeric argument entered for a system command was outside the legal range of values for the command. The ranges are: For )DIGITS, 1 to 16 For ) wIDTH, 35 to 2048 For ) MAXCORE, the ) MINCORE value to 1048576 For yMINCORE, O to the ) MAXCORE value For ) SAVE/MAXLEN, 512 to 2048 APL Reference Manual A-23 System Messages 22 INCORRECT PARAMETER ( PARENT QUALIFIER REPEATED) Explanation: In the ) ATTACH command. 22 INCORRECT PARAMETER ( PROCESS NAME QUALIFIER REPEATED) Explanation: In the ) PUSH command. 22 INCORRECT PARAMETER ( REDUNDANT KEYWORD OR QUALIFIER) Explanation: A keyword or qualifier was repeated in the argument to ) OUTPUT, ) STEP, or 1ASS. 22 INCORRECT PARAMETER | ( SYSTEM VARIABLE VALUE MAY ONLY BE 0 OR 1) Explanation: In the ) ORIGIN command. 22 INCORRECT PARAMETER (UNRECOGNIZED QUALIFIFR KEYWORD) 22 INCORRECT PARAMETER (WILDCARDS NOT ALLOWED IN FILFE SPEC) Explanation: A wildcard was used in the name of a workspace identifier. 23 WORKSPACE LOCKED 23 WORKSPACE LOCKED ( INCORRECT PASSWORD) 23 WORKSPACE LOCKED ( WORKSPACE HAS NO PASSWORD) Explanation: An incorrect password (or none at all) was given to access a workspace that was saved with a password. 24 NOT GROUPED, NAME IN USE 25 EXECUTE ERROR Explanation: APL signaled an error while executing the argument to the ¢ execute function. 27 LIMIT ERROR Explanation: The result of the operation exceeded some implementation limit; for example, if the argument array to ( 07X has more than 65535 columns. 27 LIMIT ERROR (ARGUMENT STRING IS5 TOO LONG) Explanation: The length of an argument cannot be greater than 255 keystrokes. 27 LIMIT EFERROR (ARGUMENT TOO LARGE) Explanation: The argument to [ SF was greater than 255 keystrokes. A-24 APL Reference Manual System Messages 27 LIMIT FERROR (ARGUMENT TOO LONG) Explanation: For ([(MAP, if 4 contains more than 255 formal parameters (including the result). 27 LIMIT FRROR (AXIS TOO LONG) 27 LIMIT ERROR ( DELAY VALUE TOO LARGE) Explanation: The delay specified for (ODL was larger than approximately 3.4E11 milliseconds. 27 LIMIT ERROR (FLOATING OVERFLOW) Explanation: Arithmetic overflow has occurred. 27 LIMIT EFERROR ( INPUT LINE TOO LONG) 27 LIMIT FRROR ( INTEGER TOO LARGE) Explanation: A value is greater than thec largest allowable integer. 27 LIMIT ERROR ( PARAMETER OUT OF RANGE) Explanation: One of the parameters in the left argument of dyadic s is less than ~ 127 or greater than 127. 27 LIMIT FRROR ( RANK TOO LARGE) 27 LIMIT FRROR ( VOLUME TOO LARGE) Explanation: The result of a primitive function has more elements than the implementation can accomodate. 28 AXIS RANK ERROR (NOT VECTOR DOMAIN) Explanation: The specified axis number argument ([X]) is not a singleton and its rank is greater than 1. 29 AXIS LENGTH FRROR Explanation: The specified axis number argument has more than one 1tem. 29 AXIS LENGTH ERROR ( ARGUMENT RANK AND AXIS INCOMPATIBLE) 29 AXIS LENGTH ERROR ( NOT SINGLETON) Explanation: The axis argument is not a singleton. APL Reference Manual A-25 System Messages 29 AXIS LENGTH ERROR ( LEFT ARGUMENT HAS WRONG LENGTH) Explanation: The length of the axis argument to + or + does not match the length of the left argument. 30 AXIS DOMAIN FRROR Explanation: The specified axis argument value was not a nonnegative integer (except in the case of laminate, which accepts floating-point numbers greater than ~ 1), or the specified function was not in the domain of the axis operator. 30 AXIS DOMAIN ERROR ( ARGUMENT RANK AND AXIS INCOMPATIBLE) Explanation: The axis argument or an element of the axis argument is greater than the rank of the argument with the largest rank. 30 AXIS DOMAIN FRROR (AXIS LESS THAN INDEX ORIGIN) Explanation: The axis argument is less than [ 70. 30 AXIS DOMAIN FRROR ( INCORRECT TYPFE) Explanation: The axis argument is not a number. 30 AXIS DOMAIN ERROR (NOT AN INTEGER) Explanation: The axis argument is not a near-integer. 30 AXIS DOMAIN ERROR (SEMICOLON LIST NOT ALLOWED) Explanation: There is a semicolon inside the brackets that surround the axis argument . 30 AXIS DOMAIN ERROR (AXES NOT IN CONTIGUOUS ASCENDING ORDER) Explanation: The axis argument elements must be in contiguous ascending order for Ravel. 30 AXIS DOMAIN ERROR (DUPLICATE AXIS NUMBER) Explanation: An axis argument element was specified more than once. 30 AXIS DOMAIN FRROR ( ENCLOSED ARRAY NOT ALLOWED) Explanation: The axis argument must be a simple homogeneous array. 30 AXIS DOMAIN ERROR ( INCORRECT OPERATION) Explanation: An operation was specified that was not one of the following: Ravel, Catenate/Laminate, Reverse, Rotate, Expand, Scan, Replicate/Compress, Reduce, Monadic Grade up/down, Take, Drop. A-26 APL Reference Manual System Messages 30 AX1S5 DOMAIN ERROR (RIGHT ARGUMENT HAS WRONG RANK) Explanation: An axis argument value was specified that is greater than the rank of the right argument. 31 PROTECTION VIOLATION Explanation: The protection assigned to the workspace you specified prohibits the access you requested. 31 PROTECTION VIOLATION ( INSUFFICIENT PRIVILEGE OR FILE PROTECTION VIOLATION) 32 INVALID SIMULTANEOUS ACCESS Explanation: More than one user tried to save the same workspace simultaneously, or a user tried to access a nonshared file that is already in use. 32 INVALID SIMULTANEOUS ACCESS (FILE CURRENTLY LOCKED BY ANOTHER USER) 33 10 ERROR 33 10 FRROR ( INVALID WILDCARD OPERATION) Explanation: For ) oUTPUT, a wildcard was specified in place of a value for filespec. 33 I0 ERROR (NULL PRIMARY KFY) Explanation: An attempt was made to specify an empty key value. 33 10 ERROR ( SEQUENTIAL DELETE OPERATION IS NOT ALLOWED FOR KY FILES) Explanation: An attempt was made to omit the entire key specification. 34 COMPONENT ERROR Explanation: An attempt was made to read a component that cannot be read. 34 COMPONENT FRROR ( COMPONENT CROSSES CELL BOUNDARY) 34 COMPONENT ERROR ( COMPONENT IS DAMAGED) 34 COMPONENT ERROR ( RECORD NOT A COMPONENT) 35 INVALID FILE SPECIFICATION APL Reference Manual A-27 System Messages 35 INVALID FILE SPECIFICATION ( WILDCARDS NOT ALLOWED IN FILE SPECIFICATIONS) | Explanation: Wildcards are invalid in the file specifications for ) INPUT and ) OUTPUT. 36 INDEX RANK FRROR Explanation: The rank of the index and the argument are not compatible. 36 INDEX RANK ERROR ( CANNOT INDEX A SCALAR ) 37 INDEX LENGTH ERROR Explanation: In the form A[X]+B B is not a singleton and its shape does not conform to the shape of the selected items of 4. 37 INDEX LENGTH ERROR ( INDEX OUT OF RANGE) 38 INDEX DOMAIN FRROR 38 INDEX DOMAIN ERROR ( INCORRECT TYPE) Explanation: An attempt was made to enter an index array that does not consist of nonnegative integers. 38 INDEX DOMAIN ERROR ( INDEX LESS THAN INDEX ORIGIN) 38 INDEX DOMAIN ERROR ( NOT AN INTEGER) Explanation: A value of the axis argument is not a near-integer. 39 NO SUCH DIRECTORY 40 OPERATOR DOMAIN ERROR (ARRAY OPERAND NOT ALLOWED) Explanation: An array was specified as an operand to an each ( " ) or dot (.) operator. 41 | NO ROOM ON FILE STRUCTURE OR QUOTA EXCEEDED Explanation: The specified file structure was full, or the disk allocation was exceeded. In the latter case, files must be deleted from the user’s disk area before more files can be added. 42 DEVICE IS WRITE-LOCKED Explanation: The specified device (usually a magnetic tape) was physically write-protected. A-28 APL Reference Manual System Messages 43 SYSTEM RESOURCES EXHAUSTED Explanation: The system ran out of space to perform certain functions for the user. See the system manager at your installation. 4y ERROR INVOKING EXTERNAL ROUTINE Explanation: An error occurred while trying to map an external routine or process the actual arguments before executing the external routine. 44y ERROR INVOKING EXTERNAL ROUTINE ( DOMAIN FRROR) Explanation: One of the following situations has occurred: * The data leaving the workspace cannot be converted to the data type expected by the external routine (for example, numbers could not be converted to /TYPE:T). A conversion failed as data passed from the workspace to the external routine. by ERROR INVOKING EXTERNAL ROUTINE ( EXTRANEOUS CHARACTERS AFTER COMMAND) Explanation: Unrecognized input, such as an undefined or repeated qualifier, appeared at the end of the command. 44 KFRROR INVOKING EXTERNAL ROUTINE (ILL FORMED NAME) Explanation: The actual parameter specified for either the /ACCESS:0UT or /ACCESS:INOUT qualifier is not a valid APL name. 4y FRROR INVOKING EXTERNAL ROUTINFE ( ILLEGAL ASCII CHARACTER) Explanation: A conversion to ASCII failed as character data (/TYPE:T or /TYPE: VT left the workspace. 44 ERROR INVOKING EXTERNAL ROUTINE ( ILLEGAL NAME CLASS) Explanation: The actual parameter specified for either the /ACCESS:0UT or /ACCESS:INOUT qualifier is defined, but is not a variable. Uy FRROR INVOKING EXTERNAL ROUTINE ( INCORRECT PARAMETER) Explanation: One of the following situations has occured: The actual parameter specified for either the /ACCESS:0UT or JACCESS :INOUT qualifier is currently undefined and is /TYPE: Z. The parameter must either be defined so an unconverted value can be passed or undefined with a known data type, not /TYPE: Z APL Reference Manual A-29 System Messages e The actual argument is missing when the formal paramter is specified with the /MECHANISM: IMMEDIATE qualifier. Ly ERROR INVOKING EXTERNAL ROUTINE ( INCORRECT TYPE) Explanation: The actual paramter specified for either the /ACCESS:0UT or /ACCESS:INOUT qualifier is not a character. 4y FRROR INVOKING EXTERNAL ROUTINE ( LENGTH FRROR) Explanation: One of the following situations has occurred: e The actual argument has a length greater than 4 bytes when JMAP was specified with the /MECHANISM: IMMEDIATE qualifier. * The actual argument has a length greater than 2+ 2« 16 when dyadic [1MAP was specified with the /MECHANISM:DESCRIPTOR qualifier. e A complex data type is being passed an odd number of items (APL requires two numbers to form each complex number). e The length of a Varying sTring ( /TYPE:VT ) is greater than ~ 1+ 2* 16. 4y ERROR INVOKING EXTERNAL ROUTINE (NOT VECTOR DOMAIN) Explanation: The actual parameter specified for either the or /ACCESS:INOUT qualifier is not in the vector domain. /ACCESS:0UT L4 FERROR INVOKING EXTERNAL ROUTINE (NOT SINGLETON) Explanation: The actual argument is not a singleton (as it should be) when dyadic ( OMAP is specified with the /MECHANISM: IMMEDIATE qualifier. 44 ERROR INVOKING EXTERNAL ROUTINE ( WRONG NUMBER OF ARGUMENTS TO USER FUNCTION) Explanation: More actual arguments were specified than there are formal parameters defined in the formal parameters of the external routine. 45 SIGNAL FROM FXTERNAL ROUTINE Explanation: An external routine signaled the error that is the secondary error message. U6 OPERATION INVALID IN THIS CONTEXT Explanation: An attempt was made to use ) STEP when there was no suspended operation. 47 OUTPUT LINE TOO LONG A-30 APL Reference Manual System Messages 47 OUTPUT LINFE TOO LONG ( BUFFER OVERFLOW) Explanation: A line editing sequence created a line that was too long to fit in the I/0 buffer. 47 OUTPUT LINF TOO LONG ( PAGE WIDTH EXCEFEDED) Explanation: A line editing sequence created a line longer than the page width limit. 48 INPUT LINE TOO LONG 48 INPUT LINE TOO LONG (ARGUMENT STRING IS TOO LONG) Explanation: The argument to ) IELP was longer than APL’s input buffer. 49 FILE CONTAINS A DAMAGED WORKSPACE Explanation: The file specified by ) LOAD, ) COPY, or ) PCOPY contains a damaged workspace. 49 FILE CONTAINS A DAMAGED WORKSPACE ( CURRENT WORKSPACE CLEARED) Explanation: An attempt was made to load a file that contains a damaged workspace. The current workspace is cleared. 50 CHARACTER ERROR Explanation: The user entered an illegal overstruck character. 50 CHARACTER ERROR ( ILLEGAL CHARACTER IN EXPRESSION) Explanation: An internal (J4V code was included outside of a literal or comment. 50 CHARACTER ERROR ( ILLEGAL OVERSTRIKEF) 51 INPUT ABORTED Explanation: The user entered the abort signal to escape from quad, quote quad, or quad del input. 52 FUNCTION EDITING ABORTED Explanation: The user entered the abort signal to escape from the function editor. 53 LINE EDITING ABORTED Explanation: The user entered the abort signal to escape from character editing mode. APL Reference Manual A-31 System Messages 54 INTERNAL ERROR SAVING WORKSPACE Explanation: An internal inconsistency was detected. Please notify your Digital software specialist. 55 NOT A RANDOM ACCESS DEVICE 56 INCORRECT MODF FOR DEVICE Explanation: The I/O mode for the operation requested was improper for the chosen device. 57 FILE DOES NOT CONTAIN A WORKSPACE Explanation: An attempt was made to load or copy a file that does not contain an APL workspace. 57 FILE DOES NOT CONTAIN A WORKSPACE ( CURRENT WORKSPACE CLEARED) 58 DATA TRANSMISSION ERROR Explanation: A data transmission error was detected during input or output. This message is usually associated with a nonrecoverable device error. 59 FILF ALREADY EXISTS WITH GIVEN NAME Explanation: An attempt was made to save a workspace with the same file name as an existing file that is not a workspace. 60 WS NOT SAVED, THIS WS 1S5 wsname Explanation: An attempt was made to save a workspace with the same file name as an existing workspace, without first making that same name the workspace identification (returned by ) ¥SID) . This error message is to prevent inadvertent overwriting of previously saved workspaces. 62 NOT A DIRECTORY STRUCTURED DEVICE 63 FILE ASSIGNED READ ONLY 64 CHANNEL NOT ASSIGNED Explanation: The channel specified in a file operation was not previously associated with a file via a 0 4SS system function. 65 CHANNEL CANNOT DO BOTH INPUT AND OUTPUT Explanation: An attempt was made to do both input and output to a channel assigned to a sequentially organized file. A-32 APL Reference Manual System Messages 66 NOT AN INPUT DEVICE Explanation: The user tried to perform input from an output-only device, such as a line printer. 67 NOT AN OUTPUT DEVICE Explanation: The user tried to perform output from an input-only device, such as a card reader. 68 END OF FILE ENCOUNTERED Explanation: A sequential read operation was attempted when there was no next record or component and when the channel was assigned with /SIGNAL. 69 RECORD NOT FOUND Explanation: A random read operation was attempted on a nonexistent record or component when the channel was assigned with /SIGNAL. 71 DEVICE ERROR Explanation: A file operation attempted to use a mode that is improper for the device specified in the associated 455 function.) 72 SYSTEM SERVICE FAILURE 73 SUBPROCESS FRROR 73 SUBPROCESS ERROR ( COMMAND BUFFER OVERFLOW - SHORTEN EXPRESSION OR COMMAND LINE) 74 BLOCK TOO BIG Explanation: A data-transfer error occurred during I/0. Specifically, the last read attempted to read a block of data that was too large. 75 Explanation: The end of the file was reached when /SIGNAL was not being used. No message is printed and execution continues. 76 RESULT FRROR (BRANCH HAS NO RESULT) Explanation: Branch was used with [] input. 77 STOPSET Explanation: The operation was suspended because a stop bit was set for the current line. APL Reference Manual A-33 System Messages 78 END OF TAPE Explanation: The end of a reel of magnetic tape was reached. 79 SYSTEM FUNCTION ILLEGAL IN EXECUTE Explanation: The ([BREAK system function was used in the argument to the execute function. 80 RETURN TO CALLER OF THIS IMAGE Explanation: The right argument to (0 SIGNAL was 80. 81 BROADCAST RECEIVED Explanation: A broadcast was received when ([JGAG was set to 3. 82 CHANNEL NUMBER IS NOT AVAILABLE 83 DAMAGED WORKSPACE HAS BEEN CORRECTED 83 DAMAGED WORKSPACE HAS BEEN CORRECTED (SOME SYMBOLS MAY HAVE BEEN ERASED) Explanation: A workspace, which previously contained corrupted data, was loaded with the /CHECK qualifier. 86 FILE IS ASSIGNED WRITE ONLY 100 HI FILFE READ EFRROR Explanation: An error occurred while reading the file specified by the /HI qualifier on an APL command line or in an initialization file. 101 INITIAL WORKSPACE NOT FOUND Explanation: The workspace that was specified on the APL command line or in the initialization file was not found by APL. 102 VECTOR PROCESSOR NOT AVAILABLE 103 FRROR IN INITIALIZATION FILE Explanation: APL detected an error while processing the parameters in the initialization file identified by the logical name APL$INIT. 104 NEGATIVE THRESHOLD WITH VECTOR QUALIFIER NOT ALLOWED 105 ERROR INITIALIZING CONSOLE CHANNEL 106 FRROR INITIALIZING WORKSPACE ENVIRONMENT A-34 APL Reference Manual System Messages 108 FATAL INITIALIZATION ERROR 109 FATAL ERROR SETTING UP CLEAR WORKSPACE 110 ERROR READING INPUT FILE 111 EDIT COMMAND ERROR 111 EDIT COMMAND ERROR (xx QUALIFIER REPEATED) Explanation: For ) EDIT, the same qualifier was specified more than once. xx is the name of the repeated qualifier. 111 EDIT COMMAND ERROR ( ARGUMENT TO xx IS OUT OF RANGE) Explanation: For ) EDIT, a numeric value that is outside the acceptable range was specified for a qualifier. xx is the name of the qualifier. 111 EDIT COMMAND ERROR ( BAD ARGUMENT TO xx) Explanation: For ) EDIT, an invalid value was specified for a qualifier. xx is the name of the qualifier. 111 EDIT COMMAND ERROR ( CANNOT EDIT SYSTEM SYMBOL) 111 EDIT COMMAND ERROR (EDIT COMMAND UNAVAILABLE DURING FUNCTION DEFINITION) | 111 EDIT COMMAND ERROR ( ENCLOSED ARRAY NOT ALLOWED) Explanation: An attempt was made to edit an enclosed array. 111 EDIT COMMAND FRROR ( EXECUTE QUALIFIER ARGUMENT IS TOO LONG) Explanation: For /EXECUTE, the string specified for tpucommand is too long. 111 EDIT COMMAND FRROR ( ILL FORMED NUMERIC CONSTANT) Explanation: For ) EDIT, there is nonnumeric data (data unacceptable to 0 vI) inside a numeric array that is returning from VAXTPU. 111 EDIT COMMAND ERROR ( ILL FORMED NUMERIC MATRIX) Explanation: For ) EDIT, a record or records in the matrix returning from VAXTPU have either more or fewer values than the number of values in the first record. 111 EDIT COMMAND ERROR ( ILLEGAL ASCII CHARACTFER) APL Reference Manual A-35 System Messages 111 EDIT COMMAND ERROR (ILLFEGAL NAME CLASS) Explanation: For /NC, either a value other than 2, 3, or 4 was specified, or the specified value does not match the current name class value for objectname. 111 EDIT COMMAND ERROR ( INCORRECT PARAMETER) Explanation: For ) EDIT, an unknown parameter was specified. 111 EDIT COMMAND ERROR (MISSING ARGUMENT) Explanation: For ) EDIT, an attempt was made to edit a system function or variable. 111 EDIT COMMAND ERROR ( OPFRATION LOCKED) Explanation: For ) EDIT, an attempt was made to edit a locked function. 111 EDIT COMMAND ERROR (OPERATION SUSPENDED, PENDENT, OR MONITORED) 111 EDIT COMMAND FRROR (UNBALANCED DELIMITER) 111 EDIT COMMAND FRROR (UNRECOGNIZED QUALIFIER KEYWORD) 111 EDIT COMMAND FRROR (UNSUPPORTED TERMINAL TYPE) 111 EDIT COMMAND FRROR ( VOLUME TOO LARGEF) 112 ERROR PROCESSING HELP 112 FRROR PROCESSING HELP ( INVALID KEY) 112 FRROR PROCESSING HELP (TOO MANY HELP KEYS SPEC'IF‘IED) 112 ERROR PROCESSING HELP ( ERROR OPENING AS INPUT) Explanation: The file that was specified as the argument to the ) HELP command did not exist. 112 FRROR PROCESSING HELP ( ERROR PARSING ARGUMENT TO LIBRARY) Explanation: The value for filespec on the /LIBRARY qualifier was either not specified or specified incorrectly. 113 WATCH POINT ACTIVATED 113 WATCH POINT ACTIVATED ( VARIABLE HAS BEEN MODIFIED) A-36 APL Reference Manual System Messages 113 WATCH POINT ACTIVATED ( VARIABLFE HAS BEEN MODIFIED BY INDEX) 113 WATCH POINT ACTIVATED ( VARIABLFE HAS BEEN REFERENCED) 114 ERROR PROCESSING ATTACH Explanation: An error occurred when APL attempted to process the ) ATTACH command. 114 ERROR PROCESSING ATTACH (ATTACH REQUEST REFUSED) Explanation: The value specified for process-name is the name of a nonexistent process. 114 FRROR PROCESSING ATTACH ( NONEXISTENT PROCESS) 114 FRROR PROCESSING ATTACH ( INVALID LOGICAL NAME) 115—499 are reserved for VAX APL 500—999 are for user-defined error messages. Explanation: For more information, see [ SIGNAL. APL Reference Manual A-37 Glossary abort input signal A technique for escaping to immediate mode when APL is waiting for input. Different terminals form the abort input signal differently. Consult the index to find more information on this subject. ambivalent function A function that may be monadic or dyadic, depending on how many arguments are supplied when it is invoked. APL terminal A terminal that has an APL keyboard, that is, a terminal that can be set up to use the APL key-paired (typewriter-paired), APL bit-paired, or APL COMPOSITE character set. argument An array that is manipulated by a function. APL functions take zero, one, or two arguments. array Any number (including O or 1) of items treated as a unit. assignment A method for associating a name with an array. atomic vector An array, returned by the system function JAV, that contains all the characters in the APL character set. Glossary-1 attention signal A technique for suspending the execution of an operation and escaping to immediate mode. The weak attention signal (formed by pressing (Ctrl/C) once) means suspend execution of the current operation after executing the current statement, and return control to immediate mode. The strong attention signal (formed by pressing (Ctrl/C)) twice, means suspend the current operation as soon as possible, even in the middle of the statement, and return control to immediate mode. axis A dimension along which items in an array are arranged. Boolean A numeric item that has the value 0 or 1. branch Within a user-defined operation, a change in the normal order of statement execution. canonical representation A character matrix with rows consisting of the original lines of a user-defined operation. channel L The logical path through which the APL file system interacts with external files and mailboxes. character-editing mode While in function-definition mode, a mode of editing in which you can edit individual characters in a line. \ command line The line that contains the DCL command APL. You enter the command line in response to the DCL prompt ($). comment Ignored characters appearing to the right of (and on the same line as) the a symbol; you can place a comment at the end of a line containing APL statements or on a separate line. Glossary-2 comparison tolerance An amount used by APL when it calculates how much two numbers can differ and still be considered equal. The system variable 0 CT contains the comparison tolerance used by APL. component In an external file, a record that contains an APL object. constant An item whose value is literally the constant itself. dense sequence For some functions, APL requires that an argument of nonnegative integers must form a dense sequence, beginning at 1 70. This means that the smallest element in the argument must be 070, and that an integer N from the argument domain may be included only if ¥-1 is also included. For example, if the argument domain is the integers from 1 to 3, the arguments 21 3, 1 2 2, and 1 1 1 form dense sequences, but the arguments 1 3 1 and 3 2 3 do not. depth The degree of nesting of an array. derived function A function that results from the combination of an operator and its operand or operands. domain The permissible type, shape, and values of a function’s argument arrays or the permissible objects of an operator’s operands. dummy argument In the header of a user-defined operation, an identifier that serves as a placeholder for the actual argument, operand, or result that is supplied when the operation is called. dyadic function A function that takes both a left and a right argument. enclosed array An array that includes one or more arrays. Glossary-3 empty array An array that has a type and shape but no items. The length of the array along at least one axis is O. error trapping Techniques to find and react to errors that occur during the execution of user-defined operations. event flag A shareable indicator, accessible through the APL file system, intended to aid 1n synchronizing access to shared files or mailboxes. execute-only APL The DCL command APL/EXECUTE_ONLY [parameters] invokes the run-time support version of VAX APL called QAPL. QAPL can execute applications written in VAX APL but does not contain the features to develop applications. QAPL can be copied to any valid VMS system free of charge. expression An identifier or constant standing alone, a function or operator and its arguments, or an expression enclosed in parentheses. external data Data created outside of APL. external routine A routine (not written in APL) that exists outside the APL environment. APL can call library routines and other external routines that support the VAX Procedure Calling and Condition Handling Standard. APL cannot call VMS system services routines. fill element A scalar data element (either a space or a 0) inside a fill item. fill item An array (consisting of spaces, zeros, or a combination of both) that APL inserts into another array. The shape and contents of a fill item are based on the prototype of the array that APL is using as a model for the array being built. Fill items are used by Take, Replicate, Expand, Disclose, and ]B0OX. Glossary—4 function An operation that applies to arrays and produces an array as a result. function-definition mode An operating mode in which the lines of APL you enter are not executed immediately but rather are stored for later execution. Function-definition mode begins when you type a v and ends when you type a second v or #. This mode is used when creating user-defined functions and operators. global symbol A symbol that has the same value inside and outside a user-defined operation. header The initial line of a user-defined operation. See operation header for more information. heterogeneous array An array that contains both character and numeric data. high minus The symbol (T) used to represent the negative sign in APL. homogeneous array An array that contains either character or numeric data, but not both. identifier A variable name, label name, group name, or user-defined operation name. See also system identifier. identity element A value (if one exists) to a dyadic function which, when used as one argument to the function, does not change the value of the other argument. For example, for any identity element i applied to a dyadic function f and an argument a, a does not change: i fa<—~>a identity function A function that APL applies to the prototype of an array when performing the reduction (f/B) of an axis that has length zero. Note that the inner product (f.g) derived functions imply the use of reduction. The identity function is applied to the prototype of the argument array in place of the specified function. Glossary-5 immediate mode An APL operating mode in which lines are executed immediately after they are entered. index A notation used to specify the position of items within an array that you want to reference. The index appears immediately to the right of an array and consists of two brackets enclosing values that correspond to axes in the array. Index is synonymous with subscript. indexed assignment The assignment of values to selected items of a variable. The indexed variable 1s positioned to the left of the assignment arrow (+), and the index specifies the items in the array where the assignment is applied. Indexed assignment is synonomous with subscripted assignment or indexed specification. index origin The starting point for the index values of an array. The index origin may be 0 or 1. The system variable 0 I0 contains the current index origin value. indexing The use of an index to access particular items from an array. initialization file A file, referenced by the VMS logical name APLS$INIT, that contains parameters that are processed when APL is initialized. initialization stream Either the DCL command line that invokes APL, or the initialization file referenced by the VMS logical name APL$INIT. Either or both of these streams may contain parameters to be processed when APL is initialized. integer Any of the positive and negative integers, or zero. internal data Data stored in one of the four APL internal data type formats. Glossary—6 key A field defined by its location and length within each record and used to sort the records. At least one key, called the primary key, must be defined for a keyed file. Optionally, additional keys, called alternate keys, may be defined. key of reference The specific key used in a sequential or random read of a keyed file. keyed file A file in which records are organized by fields, called keys, inside the records. The VAX RMS term is indexed sequential file organization (ISAM). The keys of the file define the order in which the records are retrieved; you can retrieve records sequentially by one of the sorted orders or randomly by one of the record’s key values. A keyed file must contain at least one key. label An identifier associated with a line in a user-defined operation. latent expression A character vector representing an APL expression; the expression 1s associated with a workspace and is automatically executed when the workspace is loaded. The system variable 0LX contains the value of the workspace’s latent expression. line The statement or statements you enter beginning after an APL input prompt and ending when you press Return to enter the line. local symbol A symbol that has significance only during the execution of a particular user-defined operation. locked operation An operation definition that cannot be changed or displayed. logical name A symbolic name for any portion or all of a file specification. mailbox A virtual device useful for sending messages to other processes. Glossary—7 matrix An array consisting of any number of items arranged along two axes, commonly called rows and columns. matrix domain A matrix, vector, or singleton. monadic function A function that takes one argument. monitored operation A user-defined operation that has some of its lines being monitored via [IMONITOR. multikey file A file in which records are organized by fields, called keys, inside the records. The RMS term is indexed sequential file organization (ISAM). The keys of the file define the order in which the records are retrieved: you can retrieve records sequentially by one of the sorted orders or randomly by one of the record’s sort values. A multikey file must contain at least one key. near-integer A numeric item whose floor is equal to its ceiling; this includes all numbers sufficiently close to an integer as determined by the APL comparison tolerance. nested array A synonym for enclosed array. next record pointer An internal mechanism that keeps track of the next record to be processed by a sequential input function. niladic function A function that takes no arguments. non-APL terminal A terminal that does not have an APL keyboard. On such a terminal, APL characters must be represented by ASCII mnemonics. nonnegative integer Any of the positive integers or zero. Glossary-8 operation Either a function or an operator. Occasionally, operation refers to a mathematical action (such as the addition operation) or to an action taken by the APL interpreter. operation body The executable lines of APL that appear in a user-defined operation definition. operation header The first line you enter when you define an operation. It names the operator; indicates whether the operation returns a value; indicates whether the operator i1s monadic or dyadic; indicates the use of an axis argument; and identifies the operation’s local symbols. operator An operation that is applied to either arrays, or functions, or both and produces a derived function as a result. In VAX APL, there are user-defined operators and primitive operators. operator sequence A sequence of functions and operators whose result is a derived function. overstruck character An APL character formed by combining two other APL characters. For example, the § symbol is formed with the 0 and < symbols. Different terminal types form overstrikes in different ways. Some terminals allow you to enter the first character, use Backspace, and then enter the second character on top of the first. Other terminals allow you to use a Compose Character key (or Ctrl/D) and then to enter the two characters. On these terminals, only the resulting overstrike character is displayed. panic exit A technique for immediately suspending the execution of an operation and giving control to the operating system. The panic exit is formed by pressing Ctrl/Y once. After a panic exit, you can return to where you left off by executing the DCL command CONTINUE. If you enter the panic exit while an operation is executing, the operation is suspended; if you then enter CONTINUE, the operation resumes execution at the point where it was interrupted. Glossary-9 pendent operation A user-defined operation that has called another operation and is waiting for that operation to return. pervasive operation An operation that acts at all depths (levels of nesting) of an array. PID Process Identification, an integer value that uniquely identifies a VMS process. positive integer The integers greater than zero. print precision The maximum number of significant digits displayed in floating-point output. The system variable [ PP contains the current print precision value. print width The maximum number of characters that APL can display on a terminal output line. The system variable [J P/ contains the current print width value. process The basic entity scheduled by VMS software that provides the context in which an image executes. process identification An integer value that uniquely identifies a VMS process. prototype An array that APL uses to determine the shape and contents of fill items. The prototype of an array B has the same shape as the first item of B and has character blanks and zeros in positions corresponding to characters and numbers, respectively, in the first item of B. pure data record A record that is a vector of values, with none of the embedded format information that APL includes within component data records. quiet function A function that does not return a value unless one is needed; that is, a value is returned only if it is not the leftmost function. Glossary-10 random link The current value used by the APL random number generator. The system variable JRL contains the current random link value. range The permissible type, shape, and values of a function’s result array. rank The number of axes along which an array’s items are arranged. recursive operation A user-defined operation that calls itself. reshape A function used to change the number of an array’s axes or to change the length of one or more of its axes. row-major order An ordering of the items of an array so that the last subscript value varies most rapidly. For example, the row-major order of a 2 by 3 matrix would be [1;1], [1;21, [1;3], [2;1], [2;2], [2;3]. scalar A rank 0 array (an array with no axes) containing a single numeric or character or enclosed item. scalar extension An implicit operation that reshapes a scalar argument to match the shape of a non-scalar argument. scalar product An implicit operator that applies a dyadic scalar function over each corresponding pair of items in the two arguments. selective assignment A method for replacing selected items of an array. Glossary-11 shadow The act of localizing a name when a user-defined operation is activated so that the old value of the name is saved and the name becomes undefined in the context of the newly activated user-defined operation. The old value of the name is restored when the user-defined operation exits to its calling environment. shape The way an array’s items are arranged; specifically, a numeric vector that describes the length of each of the array’s axes. signal A term often used in the description of what APL does when it detects an error; APL signals an error. simple array An non-enclosed array whose depth is less than 2. simple scalar A scalar that contains only a single character or number. singleton A one-item array of any rank (includes scalars). singleton extension An implicit operation that is applied to a dyadic scalar function when one or both of the function’s arguments are singletons. This implicit operator reshapes the singleton argument to match the shape of the nonsingleton argument, allowing the single value from the singleton to be applied to each item of the other argument. When both arguments are singletons, the argument with the smaller rank is reshaped to match the rank of the other singleton. specification A method for associating a name with an array. state indicator A vector that reports the status of user-defined operations, quad input requests, and execute functions. Glossary—12 statement One or more expressions executed as a unit. stop bit A setting associated with a line in an operation definition that causes the operation to be suspended before the line is executed. strand Two or more juxtaposed arrays (including scalars) which form a vector. Also known as vector notation. strand assignment The process of associating a strand of values with a set of names. subprocess A process created by and subordinate to another process. The subprocess shares the resources of the creating process. subscript A notation used to specify the position of items within an array that you want to reference. The subscript appears immediately to the right of an array and consists of two brackets enclosing values that correspond to axes in the array. Subscript is synonymous with index. subscripted assignment An assignment that modifies only the items that are specified by an index list. Subscripted assignment is synonymous with indexed assignment or subscripted specification. suspended operation A user-defined operation that has stopped executing but still has lines of APL to be processed. symbol table A data structure inside the APL interpreter. The symbol table keeps track of the names of all objects in a workspace. system identifier Any system-provided name that always begins with the quad (0) symbol. System identifier refers to system variables and functions. Glossary-13 Index ASCII A character set system variable, Abbreviations for system commands, Absolute value, 3-2 1-14 Accounting information system function, 2—13 Accumulating data system function, Addition function, 1-16 2-14 2-14 2-16 Ambivalent system functions, And function, 2-7 1-21 APL character set, 247 exiting from, 34, 3-13, 3-60 34 2-17 scalar function, Array corner, 1-219 1-2 1-10 1-59, 1-156 Arrays displaying, sorting, 1-178 Base function, 2—-18 1-27 BETA function, 1-20 1-31 Break system function, Breakpoint, 2-47 2-35 2-38 2-38 Brief error messages, 2-183 Buffer resetting bare output, 2-18 2-62 1-34 matrix product of, shape of, Backslash operator, Branch function, Arithmetic functions, 2-28 B Box system function, multiple in user-defined ops, 1-203 2-32 1-212 Bit-paired character set, Arguments rank of, 1-221 1-218 resetting buffer, interrupting, joining, strand, Bare output APL session Arbitrary output, selective, 2-44 Axis, 2-15 2-20 Assignment Automatic save system variable, system function, underscored, 2-17 Assigning files system function, Atomic vector system function, Alphabetics lowercase, output, 2-19 2-58 Associative argument with scan, Alphabetic characters vector of, control characters, 1-209 1-150 1-138 1-87, 1-90, 1-96, 1-99 Index-1 C Canonical representation, system function, 2-54 Catenate function, 1-34 assigning files to, status of, ASCII, Controlling output, 2-40 Copy 1-79 protected, 2-35 CPU time, 2-47 2-32 2-197 Current time, 2-197 2-47 composite, 2-47 D key-paired, 2-47 Data 2-47 packing, Character string selecting numbers from, 2-89, 2-203 2-35 2-197 command execution, 2-58 Deal function, converting to numbers, 2-88 3-19, 3-74 1-45 Debugging 2-135 stepping through operations, 1-179, 1-196, 2-86, 2-161 nonprintable, Decode function, 2-32 2-14 1-17 Clear event flag system function, 2-77 Clear workspace characteristics, in clear workspace, 3-11 of system variables, 2-2 Delay system function, DELETE command 3-11 VMS, Closing files system function, Combinations function, Comparing numbers, Comparison tolerance, system variable, 1-27 Defaults vector of alphabetic, 2-52 1-19 2-56 1-12, 1-13 2-56 Composite character set, 2-47 3-21 Depth function, 1-47 Derived functions compression, expansion, 1-179 1-196 inner product, 1-208 outer product, 1-205 reduction, Index-2 2-54 2-46, 2-138 DCL Characters Circle function, unpacking, Date, from character matrix, 2-93 treating a function as, Character vector fill, 2-46, 2—-138 reformatting, 1-70, 2-221 1-569, 1-156 2-13 Current date, bit-paired, digits, 3-72 Corner of an array, Character set ASCII control, 2-58 1-82 Convert characters system function, from character vector, executing, 2-58 Control characters system function, Character matrix TTY, 3-13 Control characters 2—-20 atomic vector table, 1-43 CONTINUE workspace, Character arrays APL, 1-10 2-13 Contains function, 241 converting to, 1-32 Connect time, 2-40 system function, 1-179 Conditional branching, Conjugate function, 2-98 Channels listing active, Compresssion function, 1-185 2-70 3-85 2-88 Derived functions (cont’d) replication, Error messages, 1-179 brief, 1-201 scan, secondary, Device displaying characteristics of, mailbox number of, Diagonal slice, 3-49 1-49 Display control system variable, 2-62 2-221 monitoring, 2-62 3-68 Distinguished names, 2-2, 2-4 Division 1-16 matrix, 1-116, 1-119 Division function, 3-19, 3-74 of VMS commands, 3-74 status of, 3-84 Expansion function, 1-196 Expansion system function, automatic execution of, executing, 1-1 1-178 Drop function, 1-58 defining to APL, 2-111 querying APL definition, Dyadic format function, Dyadic functions, 2-108 2-221 External routines 1-120 Dot operator, 2-85 1-11 Expressions 1-16 Domain of functions, scalar, 2-192 of DCL commands, Exponential function, by zero, 1-22 1-70 Execution Displaying workspace information system Domino, 2-172 Executing expressions system function, 1-79 Displaying enclosed arrays, command, 2-173 Exclusive OR operation, 2-142 Display format, Error number, Execute function, DIRECTORY, DCL command, Disclose function, 2-183, A-1 2-80 signaling, 1-16 2-135 significant, text of, Errors 1-165 Difference (subtraction), Digits, 2-74 2-120 A-1 2-183 1-82 F 1-1 1-3 Factorial function, Dyadic grade down function, 2-111 1-90 1-14 File assignments, listing, 2-20 Dyadic grade up function, 1-99 File organization qualifiers, Dyadic transpose function, 1-164 File status, 2-21 241 Files closing, E Each operator, 1-191 Editing with VAXTPU, Enclose function, Enlist function, 3-22 1-63 Encode function, 1-135 1-69 /ENTRY qualifier, 2-118 Equal to function, 1-22 Erasing global names, 2-52 deassigning, 3-28 Erasing named objects system function, deleting, 2-60 3-21 organization of, sharing, Fill character, Fill items, 2-41 2-91 1-179, 1-196, 2-86, 2—-161 1-155 First function, 1-77 Fix function system function, Floor function, 2-98 1-12 2-83 Index-3 Functions, APL primitives (cont’d) Form character matrix system function, expansion (derived), 2-35 Form character vector system function, Format of output display, 1-79 Format function dyadic, 2-7 Function characteristics domain, 3-31 2-131 1-16 Functions, APL primitives addition, 1-21 base, 1-27 1-20 branch, 1-31 ceiling, circle, deal, 1-22 1-12, 1-17 magnitude, 1-14 1-113 1-19 1-179 monadic transpose, 1-161 multiplication, depth, 1-47 nor, 1-21 not, 1-21 dyadic format, not equal, or, 1-90 dyadic grade up, 1-99 dyadic transpose, 1-164 1-63 encode, 1-135 enlist, 1-69 equal to, 1-22 execute, 1-70 Index—4 1-12 1-11 1-22 1-21 outer product (derived), 1-82 dyadic grade down, enclose, 1-16 1-21 negative, 1-58 1-87 1-96 1-27 1-16 1-79 natural logarithm, 1-45 division, 1-121 1-18 monadic grade up, nand, 1-43 1-49 1-119 1-18 monadic grade down, decode, drop, 1-116 monadic format, 1-10 disclose, 1-22 logarithm, membership, compression (derived), contains, 1-34 less than, minumum, 1-13 1-208 1-110 laminate, maximum, 1-17 combinations, 1-22 1-105 1-107 matrix divide, 1-34 conjugate, index generator, matrix inverse, BETA, catenate, 1-22 greater than or equal, match, 1-16 and, 1-14 less than or equal, Functions, APL quotient, 1-12 intersection, Function names list of, floor, inner product (derived), 1-1 displaying, 1-14 1-77 index of, 1-1 1-196 1-11 greater than, 1-79 Format system function, range, factorial, first, GAMMA, 1-82 monadic, 2-35 exponential, overtake, 1-154 pi times, 1-12 pick, 1-205 1-123 power, 1-16 ravel, 1-130 reciprocal, 1-11 reduction (derived), 1-185 replicate (derived), 1-179 Functions, APL primitives (cont’d) replication (derived), represent, 1-138 residue, 1-18 reverse, 1-141 1-149 signum, 1-11 specification, 1-22 displaying, 1-201 3-35 Group names displaying, erasing, 3-36 328 Groups adding to, 1-152 1-16 1-154 union, 1-22 Group members 1-215 subtraction, take, 1-96 Greater than or equal function, scan (derived), shape, 1-99 Greater than function, 1-145 subset, dyadic, monadic, 1-14 rotate, Grade up function 1-135 reshape, roll, 1-179 3-33 copying, 3-16, 3—72 defining, 3-33 dispersing, 1-170 unique, 1-172 without, 1-174 3-33 H High minus sign Functions, system see System functions printing, 2—-129 Functions, types of arithmetic, dyadic, 1-10 1-1 dyadic scalar, locked, logical, 1-21 mixed, 1-1 monadic, pendent, 1-2 1-22 2-8 1-22 3-93 Identification number, VMS process, 2—120 Identifier assigning a value to, Identity items, 1-215 1-187 /IMAGE qualifier, 1-1, 1-2 suspended, 2-13 of workspace, 3-80 relational, 1-75 of users, 1-1 primitive mixed, scalar, mode, Identification monadic scalar, quiet, /O 1-3 3-81 2-118 Index generator function, 3-80 Index Of function, Index of records, G 1-105 1-107 1-75 Index origin, 364 Gag system variable, GAMMA function, 2-100 1-14 Global names, erasing, 3-28 Grade down function dyadic, 1-90 monadic, 1-87 Index origin system variable, Inner product function, 2-102 1-208 Inner product operator, 1-29 Input prompt, 2-170 Input prompt system variable, 2-170 Input time limit, 2-188 Index-5 Integer random, 1-14, 1-45, 2-168 Interpreter, APL version of, 2-202 Magnitude function, 2-100 Map system function, preventing, 1-14 Mailbox system function, Interruptions Intersection function, Match function, 1-110 1-113 Matrix divide function, Matrix division, J 2-120 2-111 1-116 1-116, 1-119 Matrix inverse function, Job number, user, Matrix operations, 2-201 1-119 1-116, 1-119 Matrix product of arrays, Maximum function, K Membership function, Key-paired character set, 2-47 1-209 1-18 1-121 Messages displaying during load, error, L preventing, Labels list of, Laminate function, shorter error, 1-34 signaling a, Latent expression system variable, 2-108, 3-51 Left context system variable, 2-104, 2-215 Length of output lines, 2-144 Less than function, 1-22 Less than or equal function, 2-172 2—80 Minumum function, 1-18 Minus sign, 1-11 primitive, 1-22 2-183, A-1 2-183 text of last error, Mixed functions, Limit time, 2-100 secondary error, 2-131 2-109 A-1 1-1 1-22 Monadic ceiling function, 1-13 Monadic format function, 1-79 Monadic functions, 2-185 Line scalar, 1-2 system, 2-5 1-1 | length of output, 2-144, 3-91 Monadic grade down function, wrapping output, 2-145 Monadic grade up function, 1-96 Monadic transpose function, 1-161 Line counter, 2-106 Line counter system function, 2-106 Multiple arguments in user-defined ops, Local symbols status of, 1-219 3-83 Multiplication function, Logarithm function dyadic, monadic, 1-17 Logical operations, 1-21 1-22 Lowercase alphabetics system function, 2—-15 1-16 N 1-12 Logical functions, Name classification system function, Name list system function, 2-131 Names classifying, 2-126 directory of workspace, Index—6 1-87 3-47 2-126 Operation execution (cont’d) Names (cont’d) displaying functions, 3-31 interrupting, displaying operators, 3—62 monitoring, distinguished, 2-2, 24 stopping, erasing global, 3-28 suspending, of group members, types of, 2-179 2-38, 2-179 2-192 tracing, 2-131 lists of, 2-179 2-192 Operations, types of 3-35 logical, 2-127 1-22 Operations, user-defined workspaces, 3-93 Nand function, 1-21 2-122, 2-179, 2-192 debugging, 1-12 Natural logarithm function, Negative function, 1-11 displaying names, establishing, 3—62 2-98 Negative numbers recognition of, 2-89, 2-129, 2-204 listing names, Negative sign restarting suspended, output representation, 2-129 tracing, Niladic system functions, 2—4 Nonprintable characters, 2-32 dot, 3-71 Null password, 1-178 each, 1-191 inner product, Numbers comparing, slash, 2-56 2-88 converting characters to, selecting from character string, Numbers system function, 2-135 2-201 3-80 3-80 1-21 OR operation, 1-22 Origin 1-106 index, Numeric input validating, pendent, Or function, 2—173 user job, 3-81 locked, suspended, Numeric empty vector, 1-29 1-178 Operators, types of 2-89 Numbers, types of error, 1-176 1-178 backslash, 1-22 1-21 Not function, 2-54 Operators APL operators, Not equal function, 2-108 2-192 treating as data, 1-21 Nor function, 2-131 2-122 2-179 stopping, 2-165 Next-record pointer, monitoring, 3-64 Outer product function, 2-203 1-205 Output arbitrary, O ASCII, Objects erasing named, 2-83 Om system function, 2-136 controlling, 1-82 formatting, 2-7 untranslated, Operating system 2-17 Output lines 3-19, 3-74 interacting with, returning to command level, Operation execution delaying, 2-17 2-17 3-56 length of, 2-144 wrapping, 2-145 Output precision, 3-17 2-70 gathering data, 2-122 Index—7 Overtake function, Qualifiers, APL (cont’d) 1-154 /LOWERCASE, /MAXLEN, P 3-19 3-77 /MECHANISM, Pack system function, /NOKEYPAD, 2-138 2-116 3-19, 3-74 Password /NOLOGICALS, 3-19, 3-74 null, /NOSYMBOLS, 3-19, 3-74 3-71 workspace, 2-147, 2-151, 2-154, 3-50, 3-70, 3-77, 3-93, 3-94, 3-95 Pervasive functions, Pick function, PID, /TYPE, 1-123 3-15, 3-50, 3-95 2-114 /VALUE, 2-113, 2-118 qualifiers, file organization, 2-165 Polynomials, evaluating, Query system commands, 1-29 2-21 3-3 Query/Change system commands, Power function 1-11 Precision of output, 3-17 Primitive mixed functions, 2-147 2-154 definition, 2-129 list of, 3-17 system variable, system function, with protection, Quiet functions 1-22 Print high minus system variable, Print precision, 2-142 3-91 Print width system variable, Product, of array matrix, 2-8 2-8 Quiet load system function, 2-151 Quotient function (division), 1-16 2-144 Process identification number, Product (multiplication), 2-120 1-16 1-209 R Random integer, 1-14, 1-45, 2-168 Random link system variable, Prompts quad input, Range of functions, 2-170 terminal type, 2-198 Protected copy, quiet, Pseudo-terminal, 2-154 2-185 1-46, 2—168 1-1 Rank of arrays, 1-150 Ravel function, 1-130 Read event flag system function, Reciprocal function, 1-11 Records Q index for, 1-75 releasing locked, 2-159 Qualifiers, APL Reduction function, 1-185 /ACCESS, 2-114 Relational functions, 1-22 /CHECK, 2-147, 2-151, 2-154, 3-15, Release system function, Quad input prompt, 2-170 3-50, 3-72, 3-77, 3-95 Remainder, 2-113, 2-118 Renaming a workspace, /IMAGE, 2-118 Replication function, Index-8 3-85 2-159 1-18 /ENTRY, /INTO, 3-3 Quiet copy 1-16 Print width, 3-8 /PASSWORD, 2-29, 2-201 monadic, 3-74 3-85 /PARENT, 2-120 1-12 Pointer, next-record, dyadic, 3-74 /OVER, 1-4 Physical device number, mailbox, Pi times function, /NOTIFY, /NOWAIT, 3-78 1-179 2-77 Replication system function, 2-161 Report formatter system function, Represent function, Signal system function, 2-93 1-135 Representation 2-142, 3—-17 Signum function, 1-11 Singleton, of an object, 2-207 1-3 Sink output system variable, of canonical form, 2-98 Size, workspace, of negative sign, 2-129 maximum, 3-53 minimum, 3-54 Reset system function, 2-164 1-138 Slash operator, Residue function, 1-18 Specification function, Reverse function, 1-141 Squish quad, Rewind system function, 2-165 Right context system variable, 1-145 Row-major order, 1-130, 1-138 3-82 displaying, 3-80 resetting, 2-164 Status channel, S 2-41 241 function, Saving workspace system function, arguments to, dyadic, 1-1, 1-2 1-5 Stopping programs, 1-2 1-201 Selective assignment, Session variables, tle, 2-190 tt, 2-198 1-221 Sum (addition), 1-138, 1-149 1-149 2-129 2-183 3-80 executing, 3-85 restarting, 2-106, 2-108 Symbols status of local, form of, 1-145 printing, 2-174 Suspended operations, 3-83 3-1, 3-5 abbreviations for, 1-145 Sign, high minus 2-77 1-16 1-16 System commands, Shift right, 1-152 Subtraction function, Shape Short error messages, 2-177 3-19, 3-74 See Arrays Indexing $SEVERITY, global symbol, array, 2-210 1-218 String search system function, Subprocess, VMS, Subset function, 2-205 function, 2-179 Subscripted assignment 3—4 Set event flag system function, left, 1-203 2-183, A-1 2-174 2-179 Storage available in workspace, Strand assignment, with associative argument, 2-100 3-84 Stop system function, Secondary error messages, gag, 3-83 $STATUS, global symbol, 1-2 Scan function, 3-80 local symbol, of executing lines, Scalar product, definition of, vpe, 2-28 1-3 monadic, 1-215 2-32 clearing, file, Scalar functions, 1-178 State indicator 2-157, 2-215 1-14 Rotate function, 2-176 2-210 Reshape function, Roll function, 2-172 Significant digits, query, 3—2 3-2 3-3 query/change, types of, 3-3 3-2 Index-9 System commands, APL (cont’d) System commands, APL xload, 3-8 attach, 3-10 charge, 3-11 clear, clearing the state indicator, continue, 3-13 3—82 3-15 copy, 3-17 digits, displaying function names, 3-31 displaying group members, 3—395 displaying group names, 3-36 displaying information about workspace creation, 3—68 displaying operator names, 3—62 displaying state indicator, 3-80 displaying state indicator and executing lines, 3-84 displaying state indicator and local symbols, 3-83 displaying symbol table, 3-57 displaying variables, 3—88 displaying version number, 3-90 do, 3-19 drop, 3-21 edit, 3-22 3-45 3—47 3-50 maximum workspace size, 3-53 minimum workspace size, 3—54 mon, off, 3-56 3-60 origin, 3-64 output, 3-65 output width, owner, 3—68 save, 3—77 3-85 3-91 workspace identification, 3-93 workspace password, 3-70 Index—-10 2-54 2-77 clear event flag, 2-52 closing files, 2-58 control characters, 2-88 convert input, 2-60 deassigning files, delay, | 2-70 device characteristics, 2-74 erasing named objects, 2-83 executing expressions, 2-221 2-85 expansion, file sharing, 2-91 fix function, 2-98 form character matrix, 2-35 form character vector, 2-35 2-7 2-136 2-120 name list, 2-131 numbers, 2-135 2-46, 2-138 packing data, quiet copy, 2-147 quiet load, 2-151 quiet protected copy, release, 3-74 step, canonical representation, 2-41 channel status, read event flag, protected copy, 3-72 push, 2-32 map external routine, 2-111 name classification, 2-126 listing workspace names, load, 2-20 atomic vector, mailbox, 3-38 Input, assigning files, indexing Booleans, 3-33 group, help, 2-13 alphabetics, 2-14 arbitrary output, 2-17 format, 3-28 erase, 3-95 System functions, APL accounting information, 2-159 replication, 2-161 report formatter, reset, 2-154 2-77 2-93 2—-164 saving workspaces, 2-28 set event flag, 2-77 string search, 2-177 time stamp, 2-197 underscored alphabetics, 2-16 System functions, APL (cont’d) unpacking data, user load, 2-46, 2-138 validating input, 2-203 visual representation, workspace available, ambivalent, dyadic, 2-3, 2—4, 2-9 2-7 width, Terse error messages system variable, 2-5 connect, CPU, System variables, 2-1, 2-9 ASCII character set, 2-19 2-183 current, 2-197 2-185 input, 2-2 2—-13 2-13 Time limit, 2-2 2-188 Time limit system variable, 2-185 maximum record length, types of, 2—-190 2-198 Time 24 form of, 2-145 Terminal line edit system variable, Terminal type system variable, 2-6 niladic, 1-154 Terminal 2-210 2-4 monadic, list of, Take function, 2—-207 System functions, types of, form, T 2-201 2-72 2-2 Time out system variable, System variables, APL automatic save, TPU editor, 2-28 2-56 display control, 2-62 dyadic, 2-80 monadic, 2-102 input prompt, 1-164 2-108 Truth table, print high minus, 2-129 TTY 2-144 random link, 2-168 sink output, 2-176 terminal type, 2—-190 2-198 terse error messages, trap expression, 2—183 watched variables, 2-205 2-104, 2-157, 2-215 System variables, APL primitives 1-46 247 output of high minus, 2-129 Unconditional branching, 1-31 U Underscored alphabetics system function, 2-16 2—-195 vector process control, 1-17 1-21 character set, 2-142 print width, 2-195 Trigonometric functions, latent expression, terminal line edit, 1-161 Trap system variable, 2-170 print precision, 2-192 Transpose function error message, index origin, 2-197 3-22 Tracing programs, comparison tolerance, random link, 2-188 Time stamp system function, Union function, Unique function, 1-170 1-172 Untranslated output, User identification, 2-17 2-13 User load system function, 2-201 Index-11 Workspace (cont’d) 3-11 clearing, V copying objects from, Validating input system function, /VALUE qualifier, copying objects to, 2-203 displaying information about creation, Variables catenating different types of, displaying, list of, 3-21 deleting, 2-118 3-15, 3-72 2-147 3—68 2—44, 2-138 expression executed when loading, 3-88 loading, 2-131 session, 3—4 owner, system, 2-1, 2-9, 2-102 password, renaming, 3—4 saving, VAXTPU editor syntax form, 3-22 size, . Vector process control system variable, 2-205 3-50, 3-70, 3-77, 3-93, 3-94, 3—78 3-13, 3-77 2-210 maximum, 3—53 minimum, 3-54 storage available in, Version number displaying, 3-68 3-95 see also System variables workspace, variables, 3-90 Version of APL interpreter, 2-202 Version system command, 3-90 Version system function, 2-202 2-210 3—4 version saved under, 2-202, 3-90 Workspace available system function, Workspace names directory of, Visual representation system function, displaying, 2-207 3-47 3-47 VMS command execution, signaling to, 2-174 subprocess, 3-19 VMS subprocess, 3-19, 3-74 as argument in division, W Wait system function, Watch modes, 2-211 2-216 Watch system function, Watchpoints, 2-215 White space, 3-2 Width, output, Wildcards, 2-214 2-145, 3-91 3-47 Without function, 1-174 Workspace APL CONTINUE, 3-13 Automatic saving, 2-28 automatically saving, backup, Index—12 2-28 Z Zero 3-74 2-28 2-108 2-151, 3-50, 3-95 1-16 2-210 How to Order Additional Documentation Technical Support If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing your electronic, telephone, or direct mail order. Electronic Orders To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). Telephone and Direct Mail Orders Your Location Call Contact Continental USA, Alaska, or Hawaii 800-DIGITAL Digital Equipment Corporation P.O. Box CS2008 Nashua, New Hampshire 03061 Puerto Rico 809-754-7575 Local Digital subsidiary Canada 800-267-6215 Digital Equipment of Canada Attn: DECdirect Operations KAO2/2 P.O. Box 13000 100 Herzberg Road Kanata, Ontario, Canada K2K 2A6 International Local Digital subsidiary or Internal! USASSB Order Processing - WMO/E15 approved distributor or U.S. Area Software Supply Business Digital Equipment Corporation Westminster, Massachusetts 01473 1For internal orders, you must submit an Internal Software Order Form (EN-01740-07). Do Not Tear - Fold Here and Tape i)l ————————————"/——"—"——"—"———"————————————— I No Postage Necessary If Mailed in the United States BUSINESS REPLY MAIL FIRST CLASS PERMIT NO. 33 MAYNARD MASS. POSTAGE WILL BE PAID BY ADDRESSEE DIGITAL EQUIPMENT CORPORATION Corporate User Information Products PK03-1/D30 129 PARKER STREET MAYNARD, MA 01754-9975 DoNotTear - Fold Here e ——————— — — e
Home
Privacy and Data
Site structure and layout ©2025 Majenko Technologies