Xerox APL - The XDS Sigma 9 Computer

Xerox APL - The XDS Sigma 9 Computer
Xerox APL
Xerox 560 and Sigma 6/ 7/ 9 Computers
Language and Operations
Reference Manual
90 1931C
XEROX·
Xerox APL
Xerox 560 and Sigma 6/7/9 Computers
Language and Operations
Reference Manual
90 19 31C
June 1975
File No.: 1 X23
© Xerox Corporali on, 1975
Printed In USA
REVISION
This publication, 90 19 31C, is a major revision of the Xerox APL L~/OPS Reference Manual, 90 19 31B, dated
October 1973. Additions to this edition of the manual incillde: Appendix D, "Designing and Creating APL Indexed
Files"; Appendix E, "APL/EDMS Interface"; and Appendix F, "APL Symbols". Changes to the previous manual are
indicated by a vertical line in the margin of the affected page. These changes document the COO version of the
AP L system for CP-V.
RELATED PUBLICATIONS
Publication No.
Xerox 560 Computer/Reference Monual
903076
Xerox Sigma 6 Computer/Reference Manual
90 17 13
Xerox Sigma 7 Computer/Reference Manua I
900950
Xerox Sigma 9 Computer/Reference Manua I
90 1733
Xerox Control Program-Five (CP-V)/TS Reference Manual
900907
Xerox Control Program-Five (CP-V)/TS User's Guide
90 1692
Xerox Control Program-Five (CP-V)/BP Reference Manual
90 1764
Xerox Extended Data Management System (EDMS)/Reference Manual
9030 12
Xerox Extended Data Management System (EDMS)/User's Guide
903037
Manual Content Codes: BP - batch processing, LN - language, OPS - operations, RP - remote processing,
RT - real-time, SM - system management, TS - time-sharing, UT - utilities.
The specifications of the software system described in this publication are subiect to change without notice. The availability or performance of some features
may depend on a specific configuration of equipment such as additional tape units or larger memory. Customersshouldconsult their Xerox sales representative
for detai Is.
ii
CONltNTS
.~.
1.
INTRODUCTION
2.
USING APL
3.
/--"'-
4.
~
5.
4
APL Log On/Log Off Procedures
Logging On
Logging Off
APL Terminal Keyboard
General APL Input
Character Set
Names
User Input Versus Computer Output
Line Corrections During Input
Execution and Definition Modes
Prompts
Comments
Control Keys
Statements and System Commands
Variables and Operators
Defined Functions
4
4
6
6
7
7
7
8
8
9
9
10
11
11
11
12
COMMON ELEMENTS IN APL
13
Constants
Numeric Constants
Text Constants
Names
Name Format
Name Usage
Variables
Local and Global Variables
Arrays and Indexing
Operators and Arguments
Function References
Assignment
Simple Assignment
Multiple Assignment
Indexed Assignment
Input/Output
Input/Output Devices
General Input/Output
Types of Input
Output
13
13
14
15
15
15
16
17
19
24
39
40
6.
40
41
41
42
42
42
42
7.
APL OPERATORS
52
Scalar Operators
Arithmetic Group
Relational Group
Logical Group
Composi te Operators
The d/Operator (Reduction)
The d\ Operator (Scan)
The d.d Operator (Inner Product)
The o.d Operator (Outer Product)
Mixed Operators
The? Operator (Roll and Deal)
The I Operator (Index Generator and
Index Of)
The, Operator (Rave I and Catenation
and Lamination)
The p Operator (Dimension and Reshape) _ _
The ¢ Operator (Reversal and Rotation)
The (I;> Operator (Transposition)
The 4 Operator (Grade Up)
The 'f Operator (Grade Down)
The .L Operator (Base Value or Decode) _ _ _
The T Operator (Representation or Encode) __
The / Operator (Compression)
The \ Operator (Expansion)
The t Operator (Take)
The} Operator (Drop)
The E Operator (Membership and Execute) _ _
The III Operator (Matrix Inversion and
Matrix Divide)
I-Beam Functions
T-Bar Functions
53
54
63
65
68
68
70
71
73
74
74
APL STATEMENTS
95
74
75
77
78
79
82
82
82
83
84
85
86
86
87
90
92
93
Comment Statements
Branch Statements
Statement Labels
Assignment and Nonassignment Statements _ _ _
Compound Statements
95
96
98
99
100
DEFINED FUNCTIONS
101
User-Defined Functions
Creating User-Defined Functions
Directives
Editing User- Defined Functions
Issuing System Commands
Function Execution
State Indicator
Locking Functions
Intrinsic Functions
lIFMT, PAGE, NUNES, HEADER,
VFCHAR, and lIXL
DELAY
DI GITS, ORI GIN, TABS, and WIDT H
101
101
105
107
115
116
118
119
120
44
EXPRESSION EVALUATION
48
Order of Evaluation
Right to Left
Precedence of Operators
Parentheses
The Value of a Variable Versus Its Name _ _
Syntax Considerations
Default Terminal Output
Errors and Breaks
48
48
48
48
48
49
49
50
120
120
120
iii
SET FUZZ
SETUNK
£10
£IOE
ERRN, ERRF, and ERRX
lIGRF
liTE, lICR, and lIWM
8.
9.
120
121
121
121
121
121
121
SYSTEM COMMANDS
122
Workspace Concept
Active Workspace
Saved Workspace
CONTINUE Workspace
User Accounts
Passwords
Commands
)CATCH
)CLEAR
}CONTINUE and }CONTINUE HOLD
)COPY
}DIGITS
}DROP
}ERASE
}FNS
}GROUP
}GRP
}GRPS
}LIB
}LOAD
}OBSERVE
}OFF and }OFF HOLD
}OPR and }OPRN
}ORIGIN
}PCOPY
}QLOAD, }QCOPY, and }QPCOPY
}SAVE
}SEAL
}SET
}SYMBOLS
}TABS
}TERMINAL
}VARS
}WIDTH
}WSID
123
123
123
123
124
124
124
128
130
130
131
133
133
134
134
135
136
136
137
137
138
139
140
140
141
141
141
142
142
147
148
149
150
150
151
REPORT FORMATTING
152
lIFMT
Format Specifications
Format Specifications Versus
Data Types
The Format Statement
(Left Argument)
The Data List (Right Argument)
Operation of lIFMT
Scalar Arguments
Vector Arguments
Matrix Arguments
Forms of Output Values
Qualifiers and Affixture Codes
152
152
Use of Result
Error Ex its
Other Output Formatting Aids
lIXL
10. EXECUTION STOPS
Normal Stop
Execution Break ___
Stop for User Input
Stop Control Vector
Error Stop
159
159
159
159
160
161
163
11. GRAPHICS
163
User Graphi c Functions
163
Plotting Functions: DRAW, VS, INT
Scaling Functions: SCALE, NOSCALE,
164
CENTER, WHATSCALE
Window Functions: WINDOW,
165
WHATWINDOW
Auxiliary Plotting Functions: AXES, BOX,
165
DASH, SET, PUT, ERASE, HOME
Graphic Input Functions: Imnput,
165
WHATC HAR, WHATCOORD
Other Functions: SIN, COS, EXP, STRAPIS_166
166
Direct Control of Graphic I/O
166
DlOutput
167
lIGRF Intrinsi c
169
Unscaled Graphic I/O
169
Unscaled Output
170
Unsca led Input
12. WORKSPACE MANAGEMENT FUNCTIONS
Namelists and linelists
Canonical Representation
Workspace Management
Text Editing
171
171
171
172
175
231
INDEX
iv
157
157
157
158
153
APPENDIXES
153
153
153
153
154
155
155
156
A.
ERROR MESSAGES
179
Sidetrocking on Errors and Breaks
Setting Sidetracks
T he Dynamics of Sidetracking
Considerations After Gaining a Sidetrack _ _
Aids for Sidetrack Users
184
186
187
187
188
B.
NONSTANDARD IN PUT /OUTPUT
189
D. DESIGNING AND CREATING APL
INDEXED FI LES
Standard and Nonstandard Devices __
189
Using Nonstandard Input/Output
189
Terminal Declaraction
189
Changing Terminal Declaration
189
Input/Output Translation __________ 190
_" __________ 192
Teletype Usage ________
ESCAPE Key Sequences and APL __
192
Operational Differences_
193
Batch Operation ___
193
Intended Usage ___
193
Input/Output Device Assignments
194
Card Input Format _ _ __
194
Error Response _________
195
Operational Differences
195
_ _ 195
Tektronix 4013 Usage __
ASCII Mode
195
APL Mode - - - - - - _ .__._-- -195
Logging On ___________
196
Line Editing __________ 196
Strapping Options_
197
Data Transmission Rates _______
197
Non-APL 2741 Terminals ______
197
Applications __________________
197
Operatiol'lOl Considerations _
197
Blind I/O
198
Using Blind I/O ___ - - - - - - - 198
Blind I/O on a Device ___
198
Blind I/O for Files _____
199
File Input/Output
200
Creating the Set of File I/O Operators _ _ 200
Structure of APL Fi les
201
Opening and Creating Fi les
202
Closing Files
203
Maintaining Component Range and
Current Component Value
204
204
Key Values Versus Component Values
Writing APL Records ___
205
Writing Non-APL Records
205
Reading APL Records
206
207
Reading Non-APL Records
207
Deleting Records or Components
Sequential Access to Existing APL Fi les _ _ 207
208
Sequential Access to Non-APL Files
208
Converting Data Types
Controlling Access to Shared APL
Indexed Fi les _____
209
209
Listing File Names and Numbers
210
Error Reporting
211
Generation of File I/O Subsystems
-~
;,---"""
C.
INTRINSIC FUNCTIONS
216
217
Limits and Trade-Offs
Fi Ie Structure
Efficiency Considerations _____
Procedure for Creating APL Indexed Files
217
218
219
E.
APL/EDMS INTERFACE
223
F.
APL SYMBOLS
226
220
FIGURES
I-
Example of Logging On and
Logging Off APL System
5
2.
APL Terminal Keyboard _ _ _
3.
Example Showing Effect of Shadowing
19
4.
Summary of Formats for Branching
98
B-1.
EBCDIC and APL Codes
-----
7
191
TABLES
1.
APL Operators
25
2.
I-Beam Functions
93
3.
Examples of Defined Functions
102
4.
Displaying and Editing Defined
Functions
108
5.
Summary of System Commands
124
6.
!\GRF Calls
168
A-I.
Error Messages
179
A-2.
Items Subject to Sidetracking
185
B-1.
Xerox Line Printer Graphic Codes
192
B-2.
Examples of Problems with False
Terminal Declaration
192
Translation Equivalences for
Nonstandard Devices
211
E-l.
EDMS Interface Functions
223
F-l.
APL Symbols and Names
226
B..,.3.
v
1. INTRODUCTION
This manual describes Xerox's implementation of the APL language - hereafter referred to as Xerox APL, or simply
as APL. t It defines the language and the general operations of the processor under control of Xerox 560 and
Sigma 6/7/9 Control Program-Y (CP-Y). This manual is intended primarily for use as a reference document
by experienced APL programmers. Beginning APL users may find it useful to consult some good APL primers tt to augment this manual.
APL is an interpretive, time-sharing, problem-solving language. As an interpretive language, APL does not wait
until a program is completed to compile it into object code and execute it; instead APL interprets each line of input
as it is entered to produce code that is immediately executed. As a problem-solving language, APLrequires minimal
computer programming knowledge; a problem is entered into the computer and an answer is received, all in the
APL language.
Because APL is powerful, concise, easy to learn, and easy to use, it is widely used by universities, engineers, and
statisticians. It also has features that make it attractive for business applications where user interaction and rapid
feedback are key issues. One of APL's major strengths is its ability to manipulate vectors and multidimensional
arrays as easily as it does scalar values. For example, a matrix addition that might require a number of statements
and several loops in other languages can be accomplished as A+B in APL. This type of simplification exemplifies
APL's concise power.
Xerox APL is compatible with other APL systems (such as APL/360) and incorporates a broad range of improvements.
Many of these improvements are unavai lable on other APL systems.
•
On-Line and Batch Operation - Complete flexibility of operation is provided. Programs may be developed
and executed in either mode. The batch mode is advantageous for either long execution times or voluminous output, while the an-I ine mode is more advantageous for interactive program development and
moderate amounts of execution times and output.
•
Operation from Terminals and Teletypes without APL Characters - APL characters may be represented by
combinations of alphanumeric and special characters in order to allow programs to be created or modified
at any terminal or teletype supported by CP-Y.
•
Input/Output Assignment Control -An APL system command, )SET, has been added to allow the assignment
of normal and 'blind' (see below) I/O to files and devices such as the line printer or magnetic tapes, and
to establish format control of printed output.
•
Fast Formatted Output - A user-specified format description can be used in lieu of the default automatic
formatting. This facilitates the preparation of reports and tables. ttt
•
Fi Ie Input/Output - A program-controlled mechanism is offered for internal and external fi Ie input/output.
Any variable in an APL workspace may be wri tten to a fi Ie and later retri eved for subsequent processing, permitting an APL program to operate on more data than can be contained in a workspace. APL
entities may also be written as data records without their APL attributes, and non-APL data records can
be read.
The APL file I/o system operates with either CP-Y keyed files or 'indexed' filps (using CP-Y random file
access). Keyed file access may be with numeric keys (compatible with Xerox lDIT, BASIC, etc.) or text
keys (a I lowing access to any CP-Y keyed fi Ie). Indexed fi les may be accessed in shared update mode,
using the CP-Y Enqueue-Dequeue feature to support shared access control.
tAPL is an acronym for .6.frogramming !:.anguage, the language invented by Kenneth Iverson.
ttTwo such publicati;ns are: APL/360 An Interactive Approach by Leonard Gilman and Allen Rose (John Wiley
and Sons Inc, New York, 1970); and APL User's Guide by Harry Katzan, Jr. (Van Nostrand Reinhold Company,
New York, 1971).
ttt This feature was invented and introduced by I.P. Sharp Associates Ltd, Toronto, Canada.
In trod uc ti on
•
APL -EDMS Interface - Insta Ilations supporting Xero) Extended Data Management System may now access
structured shared EDMS data bases via APL. A workspace with a set of 57 user functions supports EDMS
operations via APL.
•
Compound Statements - More than one statement cun be included on the line, using semicolon; for separation. Since an element of a compound statement can be a branch, this feature permits conditi::mal execution control within a single statement of a function.
•
I Blind I Input/Output - Blind input/output is a form of term ina I input/output that permits untranslated input
and output of character data. It is designed to facilitate the use of graphics terminals or other special
devices with APL. By the use of the )SET command, blind I/O may also be used to create or access
sequential files or routed to devices such as the line printer or magnetic tapes.
•
Unequally Spaced Tabs - Tab settings can be unequolly spaced as well as equally spaced.
•
Easy Function Copying - An entire function can be copied simply by changing the name of an already
defined function.
•
51-Damage Protection - Limited protection is provided against SI damage during function definition.
•
Expansion of Identity Operator - The identity operator (that is, monadic +) is legal for all domains, not
just numeric domains.
•
Expansion of Indexing - An indexed argument can itself be indexed.
•
Easy Function Line Appendage ~ In a function edit directive that uses both line number and column number, a column number of zero is taken to mean that the user wishes to append to that line. The line will
be displayed with the carrier positioned after the la:;t character, awaiting further characters for that line.
•
Enhancements to System Commands •
The )SEAL command has been added, to provid,~ protected workspaces. When )SEAL is e)(ecuted, the
current workspace is saved in a special mode with all user functions locked. A sealed workspace cannot be saved or copied by APL and cannot be accessed by processors other than APL except by the
ori gi nator.
•
The )SET command has been added for on-line control of normal and 'blind'
•
The )TERMINAL command has been expanded to allow independent setting of input and output terminal
translation tables.
•
If the following commands are issued without a new value being specified, the current value (i.e., "IS
value") is displayed:
I/o,
described earlier.
)ORIGIN
)WIDTH
)DIGITS
)TABS
)WSID
)TERMINAL
Similarly, a )SYMBOLS command that does not specify a new value produces a display of the form
"x UN USED OF y", where x is the number of unused entries in the symbol table whose size is y. The
)WIDTH command accepts a new width setting in the range from 30 to 254.
2
Introduction
•
Quiet load and copy commands )QLOAD, )QCOPY, and )QPCOPY have been added to Xerox APL.
These commands suppress the "SAVED" message when loading or copying successfully.
•
Options have been added to )SI or )SIV commands to allow immediate clearing of the state indicator
and also to control function suspension due to enors.
•
The )FNS, )VARS, and )GRPS system commands have been extended to allow a range of names to be
listed.
•
The )COPY and )PCOPY commands have been Extended to allow copying a list of objech as well as
a single object.
•
Autostart. An option on the )SAVE command permits saving workspaces such that execul'ion of specified statement is initiated automatically when the workspace is loaded.
•
Avai labi Iity of Other CP-V Faci Iities - Most competitive versions of APL are offered primari Iy as dedicated
APL-only 1'ime-sharing systems. A subscriber to Xerox APL may use other CP-V processors such as Edit,
PCL, and BASIC from the same terminal during the same run.
•
The 'execute' Operator - Monadic E allows execution of text strings as though they were evaluated input.
The most significant aspect of this feature is that sy~tem commands may be formed and executed from within
a user-defined function.
•
Function Editing in Evaluated Input and 'Execute' Modet- Permits listing or modifying a function while
in evaluated input mode or in an 'execute' operation.
•
Graphics Capabi litl- Xerox APL supports the Tektronix 4013 terminal for standard APL processing. In
addition, the APL processor contains features and a function for the specific purpose of accommodating
the graphics input and output capability of that terninal.
•
Observation of Intermediate Results - The )OBSERVE command has been added to Xerox APL.
the user to view intermediate results while APL interprets a statement.
•
Catching Assignments - A debugging aid, the )CATCH command, has been incorporated in Xerox APL.
This command permit; the user to catch (or intercept momentari Iy) every assignment to a named variable
immediately following each assignment. The assignment is "caught" by means of a function defined by
the user according to his debugging requirements.
•
Error and Break Control - Xerox APL has a faci lity to allow the user selective and dynamic control over
errors and breaks. Sin~e this facility permits bypassing of standard APL handling of breaks and errors, it
is called the "sidetracking" capabi lity.
•
Text Editing Functions - A set of five functions has been added to faci litate manipulatio'n of text strings in
APL.
•
Canonica I Representation Functions - Functions have been added to convert user-defined functions into
APL text strings and to convert text strings into user-defined functions. This facilitates program-controlled
display and editing of user functions.
•
Workspace Management Functions - A set of nine functions provides a wide variety of information concerning the user workspace in the form of APL results, which can be used to display and manage workspaces
under program control.
This permits
t This feature was originally developed at the University of California, Irvine, under the direction of Dr. Alfred Bork.
Introduction
3
2. USING APL
APllog On/log Off Procedures
The procedures described in this chapter are for operation on a standard APL terminal (that is, a terminal with an
APL typeball).t See Appendix B for procedures on other terminals.
Logging On
Before the user can communicate with APL, he must prepare the APL terminal for use, establish a connection with
CP-V, and then establish a connection with APL. He does this as follows:
1.
Preparing the APL terminal for use:
a.
Position the keyboard ON/OFF switch at ON.
of the keyboard (Figure 2).
This switch is usually located in the lower right corner
b.
Position the LOCAL/REMOTE switch at REMOTE. Th is opens the commun i cations I ine between the
terminal and the computer. When this switch is positioned at LOCAL, the terminal is not connected
to the computer and functions as an ordinary typewriter.
c.
Establish communications with the computer via a telephone line connected to the terminal as follows:
(1)
If the telephone has an ON/OFF switch, position it at ON.
(2)
Pick up the telephone receiver and listen for a normal dial tone. (Some telephones may have
a button labeled TALK; for these telephones, press the TALK button before picking up the
receiver. )
(3) Dial the telephone number for the computer.
(4) When a high-pitched tone is heard, place the receiver in the receptacle provided. (Some telephones may have a button labeled DATA; for these telephones, press the DATA button and hang
up the receiver.)
These operating procedures apply to a typical APL terminal. Operating procedures for other terminal
models may differ slightly, and so may the names of the switches described above. In addition, some
terminal models do not have telephone equipment attached, and require only steps a and b above to
establish a direct-line communication between the terminal and the computer. For most terminal models,
however, connection with the computer is established via a telephone line as described above.
2.
Logging on to CP-V (refer to Figure 1 for an example of each of the following steps):
a.
Type an asterisk and then strike the RETURN key.
sage at the terminal:
The computer responds by typing the following mes-
XEROX CP-V AT YOUR SERVICE
ON AT time and date
LOGON PLEASE:
where "time and date" are the actual time and date, and the last line is a prompt for the user to key
in identifying code words.
tThe APL typeball can be used with several terminal models.
DURA 1021 and 1051, the NOVAR 5-50, and the TST 707.
4
Using APL
Among these are the IBM 2741, the DATEL 20-31, the
The user ca lis the CP-V system.
XEROX CP-V AT YOUR SERVICE
ON AT 08:52 AUG 15.'72
LOG ON PLEASE: 356256 .REJ073453421~")
The CP-V system identifies itself, states the
time and date, and requests that the user log
on. In response, the user types in his account number (356256) and user identification
(REJ073453421). He does not use a password
in this example.
8:52 03/31/72 356256 18-36
A page heading is printed by the sy:;tem; the
items of information in the heading are, in
order: time, date, account number, and two
internal identifiers.
~APL\,";;
t
CP-V TEL types a prompt character, and the
user requests the APL processor. APL acknowledges control and prints the current
version of APL and the workspace status.
APL 07/27/73
CLEAR WS
APL program
The user logs off both APL and CP-V. Any
information in active workspace is destroyed.
Also see the )OFF HOLD, )CONTINUE,
and )CONTlNUE HOLD commands in Chapter 8.
CPU
=
.0124 CON; :02 INT = 5 CHG = 0
Note: All characters typed by the system are shown underlined.
In addition, the
symbol indicates the RETURN key.
e
Summary information for session: the user
has used. 0124 minutes of central processor
ti me (C PU = • 0124); he has been connected
to the terminal (from dialing up to the end of
summary) two minutes (CON = :02); he has
interacted with the system five times
(INT = 5); the charge is 0 charge units, an
installation-dependent value (CHG = 0).
Everything else has been typed by the user.
tAn option is now provided for entering APL with a statement appended to the APL call, for examples:
~APL
)QLOAD MYWORKSPACE
Loads the specified workspace (see Q LOAD, Chapter 8).
!.APL
)TERMINAL 13
Identifies user terminal as type 13 (see "TERMINAL",
Chapter 8).
Figure 1. Example of Logging On and Logging Off APL System
APL Log On/Log Off Procedures
5
b.
3.
Type identifying code words -account number", USN identification, and possibly a password, in that
order, separated by commas -and strike the RETU~N key. The account is the billing number, the
user identi fi cati on is the persona I or group i denti fi cati on, and the password is an account-protection
feature assigned by the system manager or the user (see the PASSWORD command in the XeroxCP-V/TS
User's Guide, 90 1692). The account number and password (if present) each consist of from 1
to 8 alphanumeric characters (any combination of the letters A-Z and the numbers 0-9), and the
user identification consists of from 1 to 12 alphanumeric characters. (See the log-on example in
Figure 1, where 356256 is the account, and REJ073453421 is the user identification.) The code words
must be the same as in the computer's list of authorized users. If they are not the same, the computer
wi J I request that the user reenter them. If the user's log-on code is accepted, the computer wi II print
a page heading, skip several lines, and then print a " symbol to prompt for input (at the TEL level
of CP-V).
Calling the APL system:
Type the command APL and strike the RETURN key to access the APL system. APL acknowledges control by typing the message APL 07/27/73 (the version of APL being used), and a message indicating
whether a clear workspace is avai lable or the CONTINUE workspace has been loaded. The user is
now in the APL system and can enter any APL assignments, statements, function definitions, system
commands, etc. An example of calling APL is shown in Figure 1.
4.
Calling from other load modules:
APL can also be called from other CP-V load modules, in which case, normal exit from APL is a return
to the calling module. (See M:LINK in CP-V BP Reference Manual, 90 1764.)
Logging Off
The user can log off the APL system via any of the following APL system commands:
)OFF
)CONTINUE
)OFF HOLD
)CONTINUE HOLD
The first two commands, )OFF and )CONTINUE, end the terminal session. That is, they log the user off both APL
and CP-Vand printa summary-of-accounting message (a summary of the terminal and computer time for the session).
After this summary message the user may turn off the terminal and all associated equipment and hang up the telephone receiver.
The last two commands, )OFF HOLD and )CONTINUE HOLD, log the user off the APL system and return control to
theCP-VTELsubsystem (which prompts for input with the" symbol). To end the terminal session after returning control to CP-V, enter the TEL command OFF (which produces a summary-of-accounting message and disconnects the
terminal from the computer).
Both forms of the )OFF command cause any information in active workspace to be lost, while both forms of the
)CONTINUE command cause any information in active workspace to be saved under the name CONTINUE (in the
account number used when logging on). These commands are described in more detail, with examples, in Chapter 8,
"System Commands".
APl Terminal Keyboard
The APL terminal keyboard arrangement is shown in Figure 2. This keyboard is similar to a standard keyboard in
that alphabetic and numeric characters are in the standard positions. (Alphabetic characters print in italic capital
letters.) Most of the remaining characters, however, are APL symbols and will not be the same as on a standard
keyboard. In addition, some familiar characters are located in different positions on an APL keyboard:
-+?'();:*=
6
APL Terminal Keyboard
IMARI
REL
D
O
LR
N
SET
OFF
Figure 2. APl Terminal Keyboard
The SHIFT key is used for uppercase characters the same as it is on standard terminals. The RETURN key indicates
that the user has entered something and is ready for the APL system to respond. Notice that most of the APl special
symbols are included as uppercase characters. Some even appear to have a relationship (often phonetic) to the
corresponding numeral or alphabetic letter (to facilitate remembering where they are). For example, tl over A,
.L (for base) over B, f; over E, \ (for index) over I, , (for quote) over K, I (for magnitude) over M, 0 (for circle
symbol) over 0, * (for power) over P, ? (for query) over Q, p (for rho) over R, r (for ceiling) over 5, and
w over W.
General APL Input
Character Set
One of APl's most unique characteristics is the richness of its character set. An APl keyboard (Figure 2) normally
has 88 printing graphics. All of these are legal characters. In addition, backspacing may be used to create the
following overstrikes, all of which are legal APl characters:
Other legal characters are blank (the space bar), tab (the TAB key, treated as one or more blanks), and carriage
return (the RETURN key). Two other characters are also accepted for control purposes: the INDEX key (present
on some terminal models) and the ATTN key discussed below under "line Corrections During Input" and "Control Keys".
Names
Names are used to identify certain APl constructs. All variables, functions, groups, workspaces, and statement
labels have names; the following restrictions apply to these names:
1.
All names except workspace names can contain from 1 to 77 characters. Workspace names can contain
from 1 to 11 characters. More characters may be used, but they will be ignored.
2.
Names may be composed of letters, numbers, !::', underlined letters, and underlined
fl.
General APL Input
7
3.
Names cannot begin with a number or SII or Til.
4.
There must be no blanks embedded within a name.
Some examples of names are
8111
81234
1'8M ['11'R ATURE
User Input Versus Computer Output
The user can enter input whenever a keyboard is unlocked. (One way to determine if the keyboard is unlocked is
to depress the SHIFT key; if it is unlocked, the typeball will rotate slightly.) As soon as the user has typed his
input and depressed the RETURN key, the APL system takes control and locks the keyboard. The keyboard remains
locked to the user until the APL system has processed the input, printed any result, and prompted for more input,
usually by indenting six spaces from the left margin. (A six-space indentation is an APL system prompt for user
input. See "Prompts" later in this chapter.)
User input and computer output are easily distinguished. Computer output usually begins at the left margin while
user input is usually indented six spaces. For example:
)DIGITS 2
WAS 10
3f9
0.33
2+2
4
4+2
2
Everything at the left margin in this example was typed by the I\PL system, while everything indented was typed by
the user.
Line Corrections During Input
A line can be corrected during input as long as the RETURN key has not been struck. Simply backspace to the error
(via the BACKSPACE key)t and strike the ATTN key. This produces an inverted caret below the character reached
by backspacing, and it signifies that everything from that point on has been deleted from system memory. The user
can then type the correction. For example, suppose the user mistakenly types 30~20 instead of 20+20. He can correct this as follows:
30+20
v
20+20
40
A variation of this scheme is available for terminals having the INDEX key (line-feed only). The procedure is to
backspace to the error and strike the INDEX key. The platen rolls up one line, and the user can immediately type
the correction. This is a quicker correction method than the ATTN key scheme. The computer does not need to
respond (that is, no inverted caret is displayed). An example follows:
20+20
+20
40
tA word of caution about the BACKSPACE key: it should be struck gently since on some terminals it may repeat if
depressed fully. The repeat feature of this key is, of course, useful when desiring a lengthy backup; for instance,
when deleting an entire line.
8
General APL Input
~.
A~oth~t correction method can be employed if the user discovers that he has omitted a character and that there is
room enough to insert it. As long as the RETURN key has not been struck, the user can simply backspace to where
he wcin~ to~insert the character and type it. For example, suppose the user types the following line and notices
that ~e:le{t parenthesis is missing:
He can simply backspace and type the required left parenthesis:
This illustrates that it is not always necessary to enter characters in order. The user can leave blanks in a line
and then backspace and fill them in. As a rule, APL interprets what the user sees at the terminal; this rule is known
as visual fidelity.
Execution end Definition Modes
From the user's viewpoint, the APL system operates in two modes - execution mode and definition mode. In execution mode, the system responds to each line of input by taking a specified system action or by performing requested
calculations and printing a result. In the following printout, for example, the first line is a system command that
causes the system t.o take some action and to respond with a message, and the third line (3+9) performs a calculation, printing the result on the fourth line:
)DIGITS 2
WAS 10
3t9
0.33
System commands can be entered during execution mode or definition mode.
execution mode.
Calculations are performed only in
In definition mode, statements (that is, calculations) are saved as part of a defined function instead of being executed immediately. System commands issued in this mode, however, are executed immediately. After functions
are defined, they can be referenced in other defined functions or in statements entered during the execution mode.
The user must type the del symbol V to begin definition mode, and another V to return to execution mode. See
Chapter 7, "Defined Functions", for a detailed description of definition mode.
Promp1l
The APl system has four ways of prompting for (that is, requesting) input: direct line prompt, function line prompt,
evaluated input prompt, and quote-quad prompt. These are described below.
Direct-Line Prompt
When the APl system is ready for user input in execution mode, it automatically moves six spaces in from
the left margin. This is a signal to the user to enter a statement or system command. Direct-line prompts are shown
in the following example:
2+2
4
2
General APl Input
9
In this example, the APLsystem indented six spaces to prompt for user input, and the user entered the statement 2+2.
The system then printed the result of the calculation at the left margin, moved to the next line, and again indented
six spaces to prampt far more input.
Function-Line Prompt
Within definition mode (that is, whenfunctionsare being defined) the APL system prompts for user input by printing
a line number in brackets at the left margin. After printing the line number, it moves up to three spaces to the right
and waits for user input. \ As an example, look at the following portion of a function definition:
[1]
VSQUARE
A+(BxB)
[2]
In this example, the user entered a function header (VSQUARE), and the APL system typed the [lJ and moved three
spaces to the right to prompt for user input. The user then entered the statement A ,- (B x B), and the APL system
typed the [2J to prampt for more user input. This continues until the user ends the function definition with another
del symbol V.
Quad Prompt
The quad symbol Ll can be used in a statement to indicate evaluclted input. When APL encounters the quad on exefution of the statement, it halts and requests input by printing the symbols fJ:, moving to the next line, indenting
six spaces, and unlocking the keyboard. The user can enter an:, valid APL expression, and this expression will be
evaluated and its value substituted for the quad (contained in the statement). Execution of the statement then resumes. Examples of the quad prompt are shown below:
A+Ut8
0:
7x2x4
A
7
ANSWER+LJ
LJ:
ygS
'YES'
ANSWgR
Quote-buad Prompt
The quote-quad symbol ['] (a quad symbol overstruck with a quote) is used to enter literal character data. It is
executed similarly to the quad symbol except that no input symbol is printed to signal the user cind no six-space indentation takes place. The user enters his character data without enclosing it in quotes. For example:
Al+1.!l
YES
Ai
YES
Comments
Comments can be written on separate lines or can follow (that is, be tacked onto) statements. They may be included
on any line except a system command line or a function edit control line. To enter a comment, type the symbol PI
10
General APL Input
and follow it with the comment. This symbol is produced by typing a n symbol (upper shift C) and overstriking it
with a symbol (upper shift J). Any val id APL characters may appear to the right of the A symbol. The A and any
characters to the right are ignored inAPLexpression evaluation but will be printed if the line is displayed. Examples
of comments are shown below:
0
Pt1'/JIS IS A COMMl!:NP.
[3]
A+8x8
ASl!:P A = B-SQUAREU.
X+Y+5
PtCOMMEN1':
X IS SET TO Y+5
Control Keys
As mentioned earlier, the APL system accepts two "characters" for control purposes - the ATTN key and the INDEX
key. The ATTN key is used to interrupt execution and to initiate editing. The INDEX key (present on some
terminal models) is used to initiate editing, as an alternate to the ATTN key.
Statements and System Commands
Each completed line of input in APL is classified as either a statement or a system command. Statements specify the
operations to be performed by the APL system, such as calculations, branching, and assignment of values or expressions. Some examples of statements are
4+2
8+At2
/"--"".,
[3J
"START
VA PLUS B
'[<;NTER VALUES FOR A'
System commands are used to communicate directly with the APL system itself. They are concerned primarily with
the mechanical aspects of the system, such as logging on and off, saving, loading, and deleting workspaces. System commands always begin with a right parenthesis. A few examples of system commands follow:
)SA VE NEWJOB
)LOAD OLDJOB
)OFF HOLD
)DIGITS
Statements and system commands are described in detail in Chapters 6 and 8, respectively.
Variables and Operators
Data (numeric or literal) can be assigned a name and stored in the active workspace. The name and the associated
value are collectively known as a variable. The value may be a single data item (scalar) or a group of data items
(array), and may be changed as needed during the course of a program. Examples of assignments of variables are
shown below:
A+5
B2+1 2 3
ABC+5+4
B3+A+B2
Some character symbols indicate that basic APL operations, such as addition or multiplication, are to be performed. These symbols are called operators. (Some APL programmers refer to these as "primitive functions", but
Statements and System Commands/Variables and Operators
11
such terminology is not used in this manual in order to avoid confusion with "defined functions" described in
Chapter 7.) Some operators can be monadic (have one argument) or dyadic (have two arguments). Some examples
of operators are
x
+
r
The domain and range of operator arguments and a list of all the operators are presented in Chapter 3 under "Operators". Chapter 5 is devoted to a detailed discussion of each operator.
Defined Functions
In addition to the mathematical functions included as APL operators, the APL system permits the user to define a
function, name it, and store it in his active workspace. The fUllction can then be referenced by name in subsequent
statements, either as a program by itself or as a mathematical operation used in a formula. To define a function,
the user enters it statement by statement while the APL system is in the definition mode. This mode begins when
the user types a del symbol V and ends when he types another v. For a detailed description of defined functions,
see Chapter 7.
12
Defined Functions
3. COMMON ElEMHITS IN APl
Constants
Numeric Constants
Numeric constants can take the form of integer or real numbers. An integer is a whole number, requiring neither
decimal point nor exponential form. A real number is a number, usually with a decimal point, expressed in either
exponential form or decimal form. The user need not generally be concerned with whether a number is inf·eger or
real, or exponential or decimal, since the APL system automatically takes care of any necessary conversions and
alignment of decimal points. The representation of numeric dato is accomplished with the following characters:
o
1 2 3 456 789.
E
The numbers are the ordinary keyboard di gits, and the decima I point is the keyboard period. The character, ca"ed the
negative sign, is found over the digit 2 on the standard APL keyboard and is used to indicate negative numbers. It
should be distinguished from the - character, which is found over the I symbol and is usedforsubtraction. t The negative sign is only valid for numeric constants; it is not validin an:, other context. TheEisthe letter Eon the keyboard
and is used to indi cate an exponent. Embedded blanks, commas, and other punctuation are not allowed in APL numbers.
Practically any size nllmber can be entered in decimal form (as ')pposed to exponentid form), the only limit being
the length of an APL line. (Internal computations are carried O'Jt with at most 16 digits precision, however.) The
AP L system ignores I eadi ng and trai ling zeros, so that the user need enter on Iy the parts of numbers requi red for ca 1culations. Thus there is no need for the user to enter data as all integer or all fractional. For example, the user
may enter the number one as 1.00, 001.0, I, etc. Examples of numeric constants entered in decimal form are
shown below:
5
,/--~
5.55
t
.
10.55
o • 34
6.8
20
The negative symbol ( - ) can be used only with a numeric constant to indicate a negative number; it can never be
used with an identifier (or name). The symbol immediately precedes the applicable number; that is, no blanks are
allowed between the symbol and the number. The use of the negative symbol is shown below:
2
2
4
5
t
9
4 -
3
7
It is often easier to enter very large numbers in exponential form rather than decimal form. Exponential representation is written as a number, followed by the letter E, followed by an integer indicating a power of 10. (E can be
interpreted as "times 10 to the following power".) The exponent - the number following the E - can be a positive
or negative number. Following are some examples of numeric data in exponential form:
APL Exponential Notation
-8. 37E 14
. 99E5
Mathemati ca I Notation
-8.37 x 10 14
10-6
4.2
x
.99
x 105
3.8
x 10- 60
t
The negative sign and the minus sign should not be confused with another similm character, the underscore, found
over the letter F on the keyboard.
Common Elements in APL
13
The maximum and minimum representable numbers in Xerox APL, eXfJressed in exponential form, are
7.237005571E:75 t
-7. 237005577E75
A numeri c constant can consist of a single number (as a II t!ady ill ustrated) or a vector of numbers wi th blanks separati ng each number. (Olle or more blanks may be used on i npllt.) A vector of numbers used as a constant wi II be
treated as a single entity. Examples of numeric vectors (lie ,Illlwn below:
')
~
'2.5
'2 • 7 1 n 2 fl
"/;'>61','12
:J • l~ 1 l~ 1 £;
.7071l~
0
It should be noted that noninteger values are handled internally as "double precision floating" numbers. Fractions
that are representable exactly in decimal notation, such as. 1, are not exactly representable in this internal form.
In some instances this wi II cause results of operations to deviote from expected results, particularly if the anticipated
result is displayed to 16 decimal places or is a near-zero value.
Text Constants
Text constants - commonly called literals - are enclosed in quote symbols and can contain any keyboard character
including a legal overstrike and the space character. The quote symbols are used to distinguish a text constant
from a number, the name of something, or a construct in the longuage. They are not printed in the display of the
Iiteral. For e>tample:
A+' ABCDl:,'F12 345 G'
A
AlJCDEF123 1156
In this example the name A has been assigned the value of the text constant.
the value of A.
The next line is a request to display
If a quote character is used within a literal, it must be represented by a double quote.
is shown below:
"A"
A ... ' THE
Use of the quote character
CHARACTER IS USED FOR COMMENTS'
A
'A'
THE
CHARACTER IS USED FOR COMMENTS
One character enclosed in quotes is a scalar. More than one character in quotes is treated as a vector. Text vectors may be generated, compared for equality, indexed, and catenated just like numeric vectors. The characters
in a text vector are printed without spaces when the vector is displayed. Some more examples of the use of text
vectors are shown below (the operators used below are described in Chapter 5):
A .... ' ABCDE FCll'
ABCCBBCII'
A=B
[1""
1
1
1
0
101
1
'SYMBOL'='SYMBOL'
1
1
1
1
0
1
Al""ABCDBFGHIJKLM'
4pAl
ABCD
A1f2 ]
B
t If a number is created with magnitude greater than 7.23705469E75, comparison operations with that number wi II
give DOMAIN ERR because of the 'fuzz' concept in APL.
14
Constants
A text constant can contain one or more carriage returns. If a carriage return occurs before the closing quote is
given, APL "prompts" by accepting the next line of input beginning at the left margin. This occasionally confuses
the user who forgets to issue a closing quote; for example:
/1+-' T/\'XT CON8TAN'[,
WHY AM [ AT Tllg LA'PT MARGIN?
OH. PORGOT THE CLOSING '
A
TEX~1'
CON81'AN7'
WHY AM [ AT THE LEFT MARGIN?
OH. PORGOT THE CLOSING
Names
Name Format
All of the following constituents of the APL language have names (sometimes known as identifiers) so that they may
be easily referenced: variables, functions, groups, statement labels, and workspace~, A name can only include
Ietters, digits, and the 6 character, and except for digits these characters can be underscored. A name cannot
start with a digit or the combination 56 or T 6.
Lengths of names vary, depending on their use. The names of variable~t functions, groups, and statement labels can
be of any length up to 77 characters. t Workspace names - also known as fi lenames in Xerox APL - can be of any
length but on Iy the fi rst 11 characters are retai ned by AP L.
Name Usage
The uses of APL names are described below:
1.
A variable refers to the name given to scalar or array values by the assignment symbol (the choracter " ..- ")
described later in this chapter under "Assi gnment".
2.
Function names are treated briefly later in this chapter under "Function References", and in detail in
Chapter 7, "Defined Functions".
3.
A collection of names can be referenced all at one time by giving the group a name. Included in the
group can be the names of variables, functions, and other groups. See the )GRCUP command in Chapter 8.
4.
A statement label is a name given to a statement within a user-defined function so that it may be referenced by other statements of that function. Statement labels are used mainly as branch reference points.
5.
A workspace name is the name used to identify an active workspace so that it can be saved and later recalled. Workspace names are referenced in system commands which are described in Chapter 8. (Also
see item 8.)
tThe high limit on name lengths allows great latitude in naming items. The user should be aware, however, that long
names expend a user's workspace and should be avoided if space is a consideratbn. Names of four characters or
less requi re no space outside the user's symbol table.
Names
15
6.
A password is assigned to a workspace to prevent othel users from <lccessing that workspace. The password
must be used in order to access the workspace. Passwords are desci ibed in Chapter 8 (also see item 8, below).
Passwords need not be names.
7.
An account is the identifier of a recognized user's account. The accaunt must be specified when
logging on to UTS and when accessing a workspace in another user's account. The use of accounts is described inChapter 8 (also see itelll 8, next). Accounts may be, but are not restricted to, names or numbers.
8.
In Xerox APL a saved workspace is treated as a logicol file. Alli~dentii1~ (FID) refers to the information needed in a system command to save a workspace or to reference it nfter it has been saved. A file
identifier can take either of the following forms:
[acctnumJ workspace [:password]
.acct
workspace [ .. password
]
. acct.password
where
acctnum
is an integer specifying the number of a recognized user's account.
up to eight digits and must be followed by a blank.
acct
is the identifier of a recognized user's account.
workspace
It can consist of
It can consist of up to eight characters.
is the name assigned to the workspace, or file.
It can consist of up to 11 characters.
password
is assigned to a workspace, or file, in order to restrict user access.
up to eight characters.
It can consist of
The bracketed items in the above forms indicate optional items. File identifiers are used in the following
system commands, all of which are described in Chapter 8: )LIB, )COPY, )DROP, )LOAD, )PCOPY,
)QCOPY, )QLOAD, )QPCOPY, )5AVE, )5ET, and )W5ID.
Account (acct) and Passwords may include any characters except the period, comma, semicolon, or embedded blanks. It is advisable, however, to avoid use of special APL characters.
Variables
A variable must be assigned a value before it can be used. The value assigned can be either numeric or I iteral and
can be a scalar or an array (a vector, a matrix, or a higher-order array). The user can display the value of a variable at any time simply by typing the variable name. Examples of the assignment and use of variables are shown
below:
A-<-2
8+2 3
A+B
4
5
6
'I
5
7
C+4 5p 120
C
1
1
16
Variables
3
8
13
18
6
2
7
11
12
16
17
D+B72
D
1.5
2
2.5
4
9
14
19
5
10
15
20
A variable can be respecified at any time simply by assigning a new value to the variable name.
value specification wipes out the previous value. For example, notice the following:
The most recent
/--
AB C.... 1
ABCxO 1 2 3
0
1
2
3
4
ABC+2
ABCxO 1
0
2
4
6
8
4
5
5
2
3 4 5
10
In this example, ABC is first assigned a value of 1 and calculations are performed with that value.
ABC is then assigned a value of 2 and the calculations are performed using this new value.
The variable
Another way of respecifying a variable value is to decrease or increase its value by a certain amount. For example,
suppose variable A has a value of 5 and the user wants to increclse this value by 1. This can be accomplished as
follows:
A+A+1
A
6
Notice that the calculation 511 is performed first, and then the result 6 is assigned to a variable A. This type of
operation is particularly useful for setting up a counter to test the number of occurrences of an event, such as the
number of passes through a program loop. Each ti me through the loop the counter can be increased or decreased
by 1 and then tested against a desired value to determine further action.
Local and Global Variables
Local variables exist while user-defined functions (Chapter 7) are active, that is, while the function is pendant or
suspended. Local variables, described below, are classified as follows:
Dummies
Result
Locals
Labels
Dummies, result, and locals are indicated by their presence in the header of a defined function.
cated o.n statements within a defined function.
Labels are indi-
At a given point in time if a variable is not local then it is global. It is possible (in fact useful) to allow global
variables to be identified by the same name as local variables (or !ocal variables for one function to use the same
name as local variables for another function). This concept is useful in APL because it allows a defined function
to be formed without r.;gard to name conflicts. Its local variables are totally independent of any previously assigned
variables. Furthermore, if the function calls itself, a new set of variables exist - independent of the original local
variables. As each such function call exits (that is, becomes inactive again), the current set of local variables
disappear and the earlier values associated with their names once more become lCcessible.
Variables
17
When a function call occurs, its local variables are said to "shcdow" previous definitions for the names used by the
local variables. Shadowing can be repeated extensively as functions are called. As these functions exit .. their
shadowing effect is removed. Only globals will exist when no function is active. Global variables also exist if
their names are not shodowed by any current active functions (for example, the local variables use uniquE) names).
Shadowing is illustrated in Figure 3.
Local Variables
The following local variables are named in a function header: result, dummies, and locals.
a function is not required to use any local variables. Notice the following example:
These are all optional;
VR+Y F X;A;B;C
In this example the function F names the following local variables in its header line:
R (result) - note that R is followed by a
*.
symbol, which designates that R is the result name.
X (dummy)-one name to the right of F, separated by blank(s), designates the right dummy. When F is called,
the right argument's value is automatically assigned to local variable X.
Y (dummy)-one name to the left of F, separated by blank(s), designates the left dummy.
the left argument's value is automatically assigned to local variable Y.
When F is called,
A, B, andC (locals) -note that each local name is preceded by a semicolon.
The remaining type of local variable is the label.
[3]
Its name appears in a function line as in the example below.
L:ATHIS LINE IS LABELED.
Notice that the label's name, L, follows the I ine number, [3 J, and is in turn followed by a colon. Although labels
are classified as local variables, it is more appropriate to consider them local constants. They cannot be assigned
values; that is, the following expression is a syntax error when L is a label:
L+4
The value of a label is the line number of its function line (which, of course cannot change during execution of the
functi on).
Shadowing
The example in Figure 3 illustrates the effect of shadowing as functions Fl and F2 become active and inactive.
18
Variables
)CLEAR
CLEAR WS
V+' V=GLOBAL '
W+' W= GI,ORAL '
X+'X=GLORAL '
Y+'Y=GLOBAL '
VP1;X:Y
[1]
, ••••.• 1"1 CALLF.D •••••• '
[2 ]
V
[ 31
W
[4]
+X+'X=LOCAL (1"1)'
+Y+'Y=LOCAL (1"1)'
P2
ACALI, 1"2
, •••••• P1 EXITS •••••• ' V
VP2 ;W:X
, •••••• P2 CALLED •••••• ,
[ 5]
[61
[71
[1]
[2]
}
Set V, W, X, Y to be globol vodoble.,
Define Fl, naming X and Y as its locals.
V
[3]
+W+'W=LOCAL (P2)'
[4]
+X+'X=LOCAL (1"2)'
[5]
Y
[6]
' .••••. 1"2 EXITS .••••• 'V
V;W;X;Y
V=GLOBAL W=GLOBAL X=GLORAL Y=GLOBAL
P2
• ••• •• 1"2
Define F2, naming Wand X as its locals.
Verify V, W, X, Yare still global.
Call F2.
CALLED ••••••
V=GLOBAL
W=LOCAL (P2)
X=LOCAL (1"2)
Y=GLORAL
• ••••• P2 EXITS ••••••
V;W;X;Y
V=GLOBAL W=GLOBAL X=GLOBAL Y=GLORAL
P1
••••• • 1"1 CALLED ••••••
V=GLOBAL
W=GLOBAL
X=LOCAL (P1)
Y=LOCAL (P1)
••••• • P2 CALLED ••••••
V=GLOBAL
W=LOCAL (P2)
X=LOCAL (1"2)
Y=LOCAL (Pi)
• ••••• P2 EXITS ••••••
•• • • •• P1 EXITS ••••••
V;W;X:Y
V=GLOBAL W=GLOBAL X=GLOBAL Y=GLOBAL
Figure 3.
}
V and Yare still global.
Wand X are local to F2.
V, W, X, Yare global again.
Call Fl •
}
V and Ware still global.
X and Yare local to Fl.
Fica lis F2 .
}
V is still global.
Wand X are local to F2.
Y is still local to Fl.
V, W, X, Yare again global.
Example Showing Effect of Shadowing
Arrays and Indexing
Description of Arrays
~"
As mentioned earlier, a variable may represent a scalar or an array.
being a character or number. One example of a scalar is
A scalar is always a single element -an element
SCLR+33
SCLR
33
Variables
19
Although an array is usually made up of more than one element, it can also consist of a single element or even no
elements. An array with no elements is called an empty army.
In addition, arrays can be classified as vectors, matrices, or hi:~her-order arrays. A vector is an array of one
dimension, and is displayed as a collection of elements arranged on one line. As a typical example, notice the
vector named VECT which has four elements:
VECT
7
5
q
11
A matrix is an array with two dimensions t , and is displayed as c collection of elements arranged in a rectangular
pattern. An examp Ie of a two-di mensi ona I matri x, named MAl, is shown be low:
1
2
6
7
11
12
345
8
9
10
13
14
15
Notice that this matrix has three rows and five columns.
columns.
It is two-dimensional because it is made up of rows and
A higher-order array is an array with three or more dimensions, displayed as a collection of elements in a set of
rectangular patterns. An example of a higher-order array is
CUBE
1
6
11
2
7
12
3
8
13
16
21
26
17
22
27
18
23
28
4
5
9
14
10
15
19
24
29
20
25
30
This higher-order array is three-dimensional.
It has two planes, and each plane has three rows and five columns.
The user can find out if a variable is a scalar, a vector, a matrix, or a higher-order array by using the pp operation
to test for the rank (that is, number of dimensions) of the variable. For example, testing the previous variables
SCLR, VECT, MAT, and CUBE will give
ppSCLR
0
ppVECT
1
ppMAT
2
ppCUBE
3
A 0 indicates a scalar, a 1 indicates a vector, a 2 indicates a two-dimensional array, a 3 indicates a threedimensional array, and so on, up to a maximum of 63 dimensions.
The user can also determine the size of each dimension in an array (that is, the "shape" of the array) by using the
p operator. For example, testing the same variables SCLR, VECT, MAT, and CUBE wi II gi ve
pSCLR
pVECT
4
pMAT
3
5
2
3
pCUBE
t
20
5
Note that a dimension is sometimes called a coordinate.
Variables
Since a scalar has no dimensions, p of a scalar produces an empty (vector) result; nothing is displayed (other than
the next input prompt). The above example confirms that SCLR is a scalar (no dimensions); that VECT is a vector
with four elements; that MAT is a two-dimensional matrix with three rows and five columns (15 elements); and that
CUBE is a three-dimensional array with two planes, each with three rows and five columns. One other situation
should be noted. An empty vector wi II return the va lue zero, cmd an empty array wi II return one or more zeros
depending on which dimension or dimensions have length zero.
Indexing of Arrays
Referencing a Single Element. An element of an array is refere,nced by its position within the array, which is indicated by one or more numbers called indices. One number is used as the index of an element in a vector arraYi two
numbers, as the index of an element in a two-dimensional matrix array; three numbers, as the index of an element
in a three-dimensional arraYi and so on, with one number for each dimension.
The indices of all arrays start with 0 or 1, depending on the index origin. When the user first logs on to APL, the
index origin is 1 by default. It can be set to 0 with the system command )ORIGIN 0, and reset to 1 with command
)ORIGIN 1. An example of the effect of origin setting upon indexing follows.
V+'ABCDE'
)ORIGIN 1
WAS 1
V[2J
B
~'AS
) ORIGIN 0
V[2J
1
C
V[lJ
B
The indices of a two-dimensional matrix also start with 0 or 1, depending on the origin, but two numbers are used
in each index. The first number selects the element from a row, and the second number selects the element from a
column. The indices are ordered with the rightmost position varying the fastest, then the next rightmost, and so on.
For purposes of ill ustrati on, consi der the matri x named MA T3:
MAT3
3
13
6
1
15
10
11
4
7
2
B
9
12
14
5
The indices for this matrix, with index origin 1, will be
[1; 1]
[2; 1]
[3; 1]
[1;2]
[1;3]
[1; 4]
[2;2J
[3;2]
[2;3]
[2;4]
[3;4]
[3;3]
[ 1; 5]
[2; 5]
[3;51
Thus MAT3U; 1J is 3i MAT3C1;2] is 1i MAT3[1;3J is 11; Mat3C1;4J is 2; and so on.
used to separate the numbers of each dimension.
Notice that semicolons must be
An element of an array of more than two dimensions is selected in the same way as an element of a two-dimensional
array, except that more numbers are included in the index. An index contains one number for each coordinate of
the associated array. For example, consider the following three-dimensional array:
MAT4
1
15
4
13
14
2
7
B
11
12
5
3
6
9
16
10
To reference the value 8 in this array, one uses the index MAT4Cl;2i4Ji where 1 denotes the first plane, 2 denotes
the second row, and 4 denotes the fourth column. Notice that each additional coordinate always adds a number to
the beginning of an index. The rightmost number of an index always refers to a column; the next rightmost to a
row; the next rightmost to a plane; the next to a panel of planes; and so on.
Variables
21
Referencing More Than One Element. To reference more than one element of a vector, one simply includes the
index of each desired element in brackets after the array name. For example, notice the following vector:
4
A+5
A[1
1
2 7 4
I, and 3 from this vector (assuming an index origin of 1), one uses the expression
To select the elements 5,
A [] 3 4J as shown here:
5
1 3 9
3 4]
3
Other examples of referencing several elements of vector A are shown below.
indexing can be used to create larger and differently shaped arlclYs:
AU
4
5
5
4
Notice in the second example that
1 8 8 8J
4
A[3 2p1 3 4 2 6 5]
5
1
3
2
4
9
There are a variety of ways to reference several elements of a matrix.
Consider the following matrix:
MATS
1
2
15
10
15
3
9
4
12
8
5
13
11
6
7
Examples of referencing several elements of this matrix are shown below.
of 1.
MA 'I' 5 [ 1 ; 4
8
11
MA7'5[1
10
9
2
15
MAT5[1
10
9
15
5
10
15
3
11
5
b
5
G
2 3; 4]
13
2; 4 5]
11
6
,'fATS [ ; 2 4]
R
5
13
MA'l'5[1
10
15
3
8
2 ; 1 2 :l 4 5J
8
11
4
MAT5[1
8
5
2; ]
4
MAT5[1
8
2]
10
1
1
2
5
These examples assume an index origin
2
3; 2 4J
8
5
13
Several elements of a three-dimensional array are referenced similarly toa matrix, except that the third coordinate
must also be added to the index. Consider the following three-dimensional array:
MAT6
22
Variables
1
6
2
7
3
8
4
9
5
10
11
16
12
17
13
18
14
19
15
20
Examples of referencing several elements of this array are shown below. These examples assume an index origin of 1.
MAT6[1;2;5]
/~---.....
10
MAT6[;2;]
6
16
7
17
8
18
9
19
10
20
MAT6[;2;1 3]
6
16
8
18
MAT6[1 1 2;1 2 1;1 2 4]
1
6
1
2
7
2
4
9
4
1
6
1
2
7
2
4
9
4
11
16
11
12
17
12
14
19
14
Assigning a Value to an Array. One or more elements of an already existing array can be assigned values via the
assignment symbol -<-. The user simply places the variable name and the index designation to the left of the symbol,
and the new value to the right. Examples follow, all of which assume an index origin of 1.
Example of vector:
V
4
5
6
7
8
9
10
3 5]+1 0 1
11
12
13
7
1
9
10
3 5 7 9]+0
11
12
13
V[1
V
1
5
0
V[l
V
~-
0
5
0
7
9
0
WHOOPS+IV[
0
11
0
13
]+2
V
2
2
2
2
2
WHOOPS
2
2
4
9
5
10
2
2
2
2
Exam~le
of matrix:
MAT7
1
6
2
7
3
8
MAT7[2;5]+0
MAT7
1
6
7
1
6
2
7
2
2
2
2
5
0
MAT7[ 1 2;3 5]+-1
3
8
4
9
MAT7
-1
1
1
MAT7 [ ; ]+2
1
4
9
MAT7
2
2
2
2
2
2
2
Notice from examples above (MA T6[;2;] ,V[]-<-2, and MA Tn;]-<- 2) that if an index position is not fi lied, a II index
values for that position are assumed to be applicable. Assigning a new value to an indexed variabledoe~ot change
the rank or shape of the variable, it merely changes one or more elements of the variable.
The value that is assigned to a variable or indexed variable is also the "result" of the assignment. This is illustrated
by the example WHOOPS-<-V[]-<-2. Since V was a lO-element vector, all 10 index values received the element
value 2. But the result, as far as the assignment operation is concerned, is sti II just the scalar 2. Thus, WHOOPS
Variables
23
becomes a scalar variable having the value 2. In analyzing APL expressions, it is helpful to imagine that assigments
are "invisible". For example,
3+M[;l+J+5
can be analyzed as if the assignment were not present, i. e. ,
3+
5
making the resu It (8) apparent.
Indexing an Indexed Argument.
In Xerox APL an indexed argument may itself be indexed.
For example:
A[1;][2]
which is equivalent to the expression (AU;J)[2J and is intel'preted as follows, Obtain the first row of matrix A.
This row temporarily forms a vector, call it T, whose length is rhe number of columns originally given for A. Select
the second element from vector T, and (in this case) display the value of that element.
Only arguments can be followed by multiple indices.
a syntax error:
Specifications and coordinates cannot; thus the following is
A[1;)[2]~X
The user instead is advised in this case to use
A[1;2]+X
Operators and Arguments
APL expressions are derived from two fundamental entities - functions and arguments. Functions are formed by the
user (see Chapter 7, "Defined Functions") or are included as an inherent part of the language. In the latter case
they are called operators (some programmers refer to them as primitive functions, but that term is not used in this
manual in order to avoid confusion with defined functions). Most operators are represented by a single character.
A general treatment of these operators is given in this section; for a detai led treatment, see Chapter 5, "APL
Operators" .
An argument is a value - the value of an expression. Arguments have certain attributes: domain, rank, and length
or shape. The domain of an argument may be text type or numeric type. There are three numeric type domains:
logical, integer, or real; however, the user seldom needs to be concerned with this distinction. Logical data represents 1's or D's and is stored in bit form. Integer data represents positive and negative numbers (usi ng neither
decimal point nor exponential form) whose ranges are limited to the size of one computer word. Real data is stored
in doubleword form (that is, in floating-point form). Text or character data is stored in byte form. An argument
cannot be of mixed domain; it is either all text, all logical, all integer, or all real. If a numeric argument contains numbers that could fit in more than one domain, it is made to uniformly contain numbers in the largest size
domain necessary. Thus the following vector argument has integer domain since that is necessary to represent the 2:
10102
The rank of an argument is the number of its dimensions (or coordinates). A scalar has a rank of zero, a vector has
a rank of one, a matrix has a rank of two, and so forth. The maximum allowed rank is 63.
The length of a vector is its number of elements, or components (zero for an empty vector). The shape or dimension
of an array (including a vector) is an ordered vector - containing the lengths of its coordinates, Single-element
vectors and single-element arrays of higher order (for instance, a 1 1 1 reshape of 5 is a single-element threedimensional array) are not equivalent to scalars but may be used interchangeably with scalars in many operations.
Vectors and arrays may also be 'empty'. This is the case when the length of any coordinate is zero.
Operators are classified as monadic or dyadic according to their number of arguments. A monadic operator has one
argument to the right of the operator. A dyadic operator has two arguments, one to the right of the operator and
one to the left.
In many cases the same operator symbol can be used both monadically and dyadically, but the resulting operations
are different, although usually related in a natural way. Each operation has its own domain, rank, and length or
shape requirements, and the result of an operation may have a new set of these characteristics.
24
Operators and Arguments
Certain operators are coordinate-dependent. For example, a matrix rotation can occur about the first coordinate
(rotation of rows) or about the second coordinate (rotation of columns). For such operations, the user has the option
of specifying this coordinate in the form of a bracketed expression to the right of the operator. The value of this
expression must be an integer of appropriate range. These coordinate specifi cations are considered to be part of
the operator - they are not arguments. The following operations may use a coordinate specification:
Reduction
Reversal
Rotation
Compression
Expansion
Catenation
Note: Catenation may also use a real-valued coordinate specification.
This form of catenation iscalled lamination.
Table 1 is a summary treatment of the standard APL operators, indicating their dyadic and monadic operations, if
any, and giving simple examples. Notice that the operators in this table ore divided into three categories:
standard scalar dyadic operators, other standard operators (that is, nondyadic scalar and mixed operators), and composite operators. For a detai led treatment of these operators see Chapter 5, "APL Operators".
Table 1.
Type of
Operator
Scalar Dyadic
Operators
Opera tar
+
APL Operators
Monadic Operation
Dyadi c Operati on
Identity: leaves argument unchanged.
Examples:
Addition: adds two arguments.
Example:
10+20
+10
30
10
+'ABC'
ABC
Mi nus: negates the argument thot
follows it. Example:
-15
-(10+5)
10-5
5
Signum: returns a-I, 0, ar 1, depending
on whether its argument is negative,
zero, or pasitive. Example:
Multiplication: multiplies the left
argument by the ri ght argument.
Example:
10x15
-1
150
Reciprocal: divides 1 by the value af
its argument. Example:
t1
1
Subtraction: subtracts the right argument
from the left argument. Examp Ie:
Division: divides the left argument
by the ri ght argument. Example:
3 5
0.3333333333
0.2
2
5
10+5 2 1 0.5
10
20
Nate that this is equivalent to the
dyadic use of lfl 3 5.
*
Exponential: raises eO. e., the base
of a natural logarithm, having the value
2.71828... ) to the pawer of its argument. Examples:
*1
2.718281828
*10
22026.46579
*2.2
9.025013499
Exponentiati on: raises the left argument
to the power indicated by the right
argument. Examples:
100
1El0
8
Operators and Arguments
25
Table 1.
Type of
Operator
Operator
Scalar Dyadic
Operators
(cant. )
APL Operators (cont.)
Monadic Operation
Dyadi c Operati on
Natural logarithm: computes the natural
logarithm of its argument (that i" loge
of argument). Examples:
Logari thlll_:_ computes the logarithm of
the right argument to the base indicated
by the left argument; that is, computes
the power to whi ch the left argument
must be roised to equal the right argument. [xomples:
81
o
82
0.6931471806
.3
1. 09 8612289
810
2.302585093
108100
2
0
1
1081 10 100 1000
2
3
284
2
281
0
--~~- --+~--~
1
~~~~~~~~- --~---------- ------~~~~~--------I
Floor: returns the greatest integer less
than or equal to its argument. EX·Jmples:
!v'IillimurT1.:. compares two arguments and
returns the va I ue of the sma Ilest argument.
Examples:
L1 0.7
5 I. 2
10
2
4
-L 92 4.1
-2
8. 9
'11.3118210
2
~---~--r-----------~
11
5
-8 -2
3
9
R
5 4
3
3
3
-2
'J
3 213
2
---1-----------------------1
Cei ling: returns the least integer greater
than or equal to its argument. Examples:
2
2 4 8
3
2
- 8. ') - 2
Absolute value: returns the absol ute
val ue of its argument. Example:
Maximum: compares two arguments and
returns the va I ue of the largest argument.
Examples:
5r 2
5
~r3
9
11
5
4
9
-
2 10
11 8
10
9
5 4 3 2r3
3
3
Residue: returns the rema i nder from dividing the
right argument by the left argument. Examples:
214
0
10
General ized factorial: for integer
arguments, returns the factoria I of its
argument. The argument may not be a
negative integer. (See Chapter 5 for
explanation of ! with nonintegel
arguments.) Examples:
!3
0
1
1
1
5115 16 17 18
2
3
2 317
Gen,Ell(]li.zed combination: for positive integer
arguments, the ri ght argument represents a
population size and the left argument representsasamplesize. Theresultisthe number of
different samples that can be drawn from the
popu lati on (see Chapter 5 for explanati on of !
with noninteger arguments.) Examples:
6
!0 1 2
112
13! 52
6.350135596El1
2!10
45
3! 10
120
26
Operators and Arguments
Table 1.
Type of
Operator
Scalar Dyadic
Operators
(cont. )
Operator
()
APL Operators (cont.)
Monadic Operation
Dyadic Operation
Pi times, multiplies the value of pi
(3. 14159265353589793) times its argument. Examples,
Circular: returns the result of any of a number
of trigonometri c functions. The left argument
specifies the type of trigonometric function,
and must be one of the integers from -7
to 7, as follows:
01
3.141592654
02 .1
6.283185307
-7
0.3141592654
-6
-5
-4
-3
-2
-1
0
1
2
3
4
5
6
7
arctanh X
arccosh X
arcsinh X
(-1 t X*2)*. 5
arctan X
arccos X
arcsin X
(I-X*2)*.5
sine X
cosine X
tangent X
(HX*2)*.5
sinh X
cosh X
tanh X
where X is the right argument, and may be a
scalar, a vector, or an array. For the sine,
cosine, and tangent functions, X must be
expressed in radians. In addition, the permitted value range of X is limited for various
circle functions (for instance, with an arcsine,
X must be in the range -1 to 1). Examples:
20(10x2.5)
0.9912028119
102 4
0.9097974268
0.7568024953
-
Less than/ tests if the left argument is less
than the right argument. Returns a 1 if the
test is true, and a 0 if the test is false.
Examples:
2<3
3<4 1 ;>
100
5
1
Less than or equal to/ tests if the left
argument is less than or equal to the right
argument. Returns a 1 if the test is true, and
a 0 if the test is false. Examples:
2S:3
1
o
1
2S1 2 3 4
1
1
tSee Chapter 5 for effect of "fuzz" on relational operators.
Operators and Arguments
27
Table 1.
Type of
Operator
Operator
APL Operators (cont.)
Monadi e Operation
Dyadi e Operoti on
Greater than: t tests if the left argument is
greater than the ri ght argument. Returns a 1
if the test is true, and a 0 if the test is false.
Examples:
Sea lar Dyadi e
Operators
(cant. )
2>3
o
1
r - - - - - - - - j - - - - - - - - - - - - - - - --- - - -
1
2> 2 0 1 2 3
1
0
0
---- ---- - - - - - - - - - - - l
--------
Greater than or equal toot tests if the left
argument is greater than or equal to the right
argument. Returns a 1 if the test is true, and
a 0 if the test is false. Examples:
2~3
o
22:
2
0
2
3
4
11100
r - - - - - - - - t - - - - - - - - - - - - - ---
-l---------------------
Equal to'! tests if the left argument is equal
to the right argument. Returns a 1 if the test
is true, and a 0 if the test is false. Examples:
1=0
0
0
0
0
1
2=0 1 2 3
1
0
'A' =' CANALJA'
0
1
0
1
Not equal to'! tests if the left and right
arguments are unequal. Returns a 1 if they
are unequa I, and a 0 if they are equa I.
Examples:
1
3"'-3 0 3 6
110
1
'A' '" '-CANADA'
1
010
1
0
And: tests if the Ieft argument and the ri ght
argument each have a value of 1. (The arguments must be 0 or 1.) Returns a 1 if both arguments are 1, and a 0 for any other combination
of arguments, as shown be Iow:
~ I~ :
1
0
Examples:
1
OAO
o
(1=2)A(3<4)
o
o
(1<2)A(3<1
0
(1=1)A(3<4)
1
t
28
.
See Chapter 5 for effect of "fuzz" on relational operators.
Opemtors and Arguments
3)
Table 1.
Type of
Operator
Scalar Dyadic
Operators
(cont. )
Operator
v
Monadic Operation
APL Operators (cont. )
Dyadic Operation
Or: tests if either the left argument or the
right argument has a value of 1. Returns a 1
if either or both arguments are 1, and a 0 if
neither argument is 1, as shown below:
v
0
1
0
0
1
1
1
1
Examples:
OVl
1
(1=2)V(4<3)
0
(3<4)v(4<5)
1
---
"
Nand: tests if both arguments are 1. Returns
a 0 if both arguments are 1, and returns a 1
for all other combinations, as shown below:
".
0
1
0
1
1
1
1
0
Examples:
0"0
1
(2<1)"( 5<1)
1
(1<2)"(1<5)
0
""
Nor: tests if both arguments are O. Returns
a 1 if both arguments are 0, and returns a 0
for all other combinations, as shown below:
1
""
0
0
1 0
1
0
0
Examples:
0"'0
1
0"'1
0
(1=2)"'(2<1)
1
(1=1).(2<3)
0
Operators and Arguments
29
Table 1.
Type of
Operatar
Operator
APL Operators (cont.)
Monadic Operation
Dyadi c Operati on
°
Nondyadic
Scalar and
Mixed
Operators
Not: returns the value
if the following argument is 1, and returns a 1 if
the argument is 0. Examples:
-0
1
-1
0
-(6)4)
0
-(6<4)
1
0
?
1
-1
0
0 1 0
1
~
{also known as monadic random}:
returns an integer pseudorandomly
selected t from 1 through the integer
specifi ed in the ri ght argument.
Examples:
Deal {also known as dyadic random}:
returns the number of integers specified in
the left argument, each pseudorandomly
selected t from the integers specified in the
right argument, and with no repetition of
numbers in the result. Examples:
75
1
478
73 3 3
3
2
1
2
2
1
75 8 11 13
8
9
4
2
6
474
324
1
Note that this operator is modified by index origin. If the origin is 0, the pseudorandom selection is from zero to the argument minus 1. If the origin is 1, selection
is from I to the argument.
Index generator: generates a vector
whose length is the value of the argument. If the ori gin is I, the vector wi II
contain -the positive integers 1 through
the value of the argument. If th.e
the ori gin is 0, the vector wi II contain
the posi ti ve integers through the
value of the argument minus 1.
Examples:
°
1
2
\5
3
4
Index of: returns the position of the
ri ght argument in the left argument.
If the ri ght argument is not found
in the left argument, it is given a
value of the length of the left argument
pi us 1. Examples:
6 4 3 2\6
1
1
4
5
) ORIGIN 0
5
\5
WAS 1
)ORIGIN
WAS 1
0
1
2
3
6 4 3 2\6 2 5 4 3
5
2
3
6 4 3 2\1
II
0
3
0
6 II 3 2\6 2511 3
II
1
2
t Pseudorandomly selected means that numbers are chosen by means of an algorithm which eventually produces repeating
results. In other words, a random sequence is, at best, only approximated.
30
Operators and Arguments
Table 1
Type of
Operator
Nondyadic
Scalar and
Mixed
Operators
(cont. )
Operator
AP L Operators (cont )
Monadic Operation
Dyadi c Operati on
Ravel: generotes a vector from either
a scalar or an array of hi gher dimension. Exomples:
Catenotion: chains together scalars (or
arrays of conforming dimensions. Excmples:
A+1
1i+4
A,B
A
1
5
2
5
3
4
8
7
1
2
2
3
4
5
5
7
8
3
B
ABCD
EFGF!
5
7
5
7
3
Note: See Chapter 5 for further exornples
(including "lamination").
,B
ABCUEFGlI
Shape: returns an empty vector if the
argument is a scalar, the length (or
number ar elements) if the argument
Reshape (restructure): generates an array
whose dimensions are the left arguments and
whose elements are taken from the right
argument. Examples:
is a vector, and a vector containing
the length of each dimension if the
argument is a higher-order arroy.
Examples:
A+2
B+1
C+3
4
3
6
C+3
(C,1),C X 3-2
,A
1
3
2
5
1
1
8
8
5 5 7
3p I 9
pA
1
pB
5
5p1
1
1
1
2 4p8
8
8
8
8
8
8
2 4pl8
2
3
4
5
7
8
4
pC
3
3
1----------1-------------Grade up: ranks the components of its
argument in ascending order, and returns
the positions (i. e., indexes of the components). If the origin is 0, the rJnking
will start with 0. Similarly, if the origin
is 1, the ronking will start with 1. The
argument must be a vector. Examples:
A+l
4A
1
3
6
4
4
1
3
2
5
)ORIGIN
1
2
7
1
6
5
0
WAS 1
4A
0
2
5
4
3
I-------~---------
-
-
-------
Grade dawn: simi lar to grode up, except
that it returns the indexes in descending
order. Example:
A+l
7
2
'fA
5
4
4
1
2 3 1
1
)ORIGIN
3
6
2
:,
5
0
WAS 1
5
1
'fA
4
3
0
/~
Operators and Arguments
31
Table 1.
AP L Operators (cont. )
r---------~--------~-----------------------.----------------------------,
Type of
Operator
Operator
Dyadic Operation
Monadic Operation
Bose value: allows the user to switch from
one number system to another. The Ii ght
argument cOlltai ns the numbers to be converted, and the left argument contains the
increments needed to convert from one unit
to another. The left argument, usually
co lied the rodi x vector, can be thought of
as the bose of the number system. Examples:
Nondyadic
Scalar and
Mixed
Operators
(cant. )
10 10 101.5 6 5
555
0
60J.l0 20
620
2 2 2 2J.l 0 0 1
9
2-1-1
0
0 1
9
~resentation:
converts a number to some
predetermi ned representation. It works in
reverse of the base value operation above.
The following shows how to reconvert to the
initial arguments used above in the base
value examples:
10 10T565
10
5
6
5
0 60T620
10
20
2
1
0
2
0
2
2T9
1
I--------I~--~~--~--~~-- ------~-t--~~--~~~---~~~-~~--j
Take: selects the number of components
indicated by the left argument, from the
right argument. If the left argument is
positive, selects the components from the
beginning of the right argument. If the
left argument is negative, t selects the
components from the end of the ri ght
argument. Examples:
A~2
4 6 8 10
4tA
246
B
4tA
4
6
B
10
-
------
}
----~--- -------~-------__l
Qr~ si mi lor to toke except that the
indicated elements are dropped instead of
selected. Examples:
A~2
HA
32
Operators and Arguments
6
8
2
4
10
- 2fA
6
4
6
8 10
Table 1. APL Operators (cant. )
Type of
Operator
Operator
Nondyadic
Scalar and
Mixed
Operators
(cont. )
Monadic Operation
Dyodi c Operati on
Execute: treats its argument (a text
string) as if in response to on evaluated input request. Example:
~~r:':!bership:
t:'2 ... 3'
5
f!')CLEAR'
CLEAR JlS
yields a 1 if a given element
to the right is an element of a specified
vector to the [eft of the membership ~ymbol,
and a 0 if it is not. The result will have the
same dimensions as the left argument.
Examples:
t:'VF XV'
t:' )FNS'
p
t:'VF[l]X+XV'
F
\4
246
8
/[...: 1
b+-2
1
2 J
4
4
G 8
5 6
liE/!
1
0
(,'+ 'Ill? 1.'1'£ FGII I JK '
0+3 3p'llOWAREYOU'
IIcC
1
1 0 0
1 0 1
0 0 0
-~---
[:1
Inverse: used to invert matri xes.
Example:
A
4
5
2
- 42
2
-5
- 204
)DIGITS 2
WAS 10
OOA
0.17
0.26
0.043
- 0.029
- 0.072
0.17
- 0.0097 - 0.099
0.063
-
-------~~----------I
Matri x Divide: used for solving systems of
linear equations. For example, suppose the
user wants to find the values of X, Y, and Z
in the following linear equations (using
conventional algebraic notation):
4X + 2Y - 5Z = 22
5X - 4Y t 4Z = -7
2X + 2Y - 20Z =, 80
He can set up the coefficients as motrix A
and the constants as vector B:
A
4
5
- 24
2
2
-7B
22
-5
- 204
80
and then obtain the solutian by taking
B matrix divide A:
BillA
114
-
Thus in the linear equations given above,
X has a value of 1, Y has a value of -1,
and Z has a value of -4.
Operators and Arguments
33
Table 1.
Type of
Operator
Operator
Nandyadic
Scalar and
Mixed
Operators
(cant. )
APL Operators (cant.)
Monadi c Operati an
Dyadi c Operati an
Manadi c transpose: performs row col umn
transposi ti on on its matri x argumen t.
Example:
Qitadic transpose: returns an array similar
to the ri ght argument except that the
coordi nates (di mensi ons) are changed
according to the left argument (that is,
the left argument specified the new
positions of the original coordinates).
Example:
A
1
'2
~)
7
3
8
II
G
11
IJ
III
12
13
1q
1 ~i
lilA
1
(j
11
2
3
'I
B
12
'i
Y
:,
1t)
/3
13
14
1"
1
2
3
4
7
5
G
8
9
10
11
12
13
lit
17
1 :,
16
19
20
21
22
23
24
2 1 31i1B
2
3
1',
1S
1
13
Reversal: reverses the order of the components of a vector, or the components
of each roW of a matrix. Examples:
A+1
<\>A
6
4
5
4
18
4
5
G
16
17
18
7
8
9
19
20
21
10
<'2
11
23
12
21t
Rotation: rotates the elements in the
right argument as specified by the left
argument (i. e., according to the number
of places specified in the left argument).
Examples:
4 6
2
2
1
<\>15
3
2
A+1 2
14>A
1
2
4
4
6
1
6
24>A
D+MAT+3 4pl12
1
5
2
6
9
10
3
Ii
7
11
12
8
12
34
Operators and Arguments
6
8
¢>MAT
4
4
3
7
2
6
1
5
11
10
9
1
2
O+MAT+3 4pl12
1
5
9
2
6
3
4
7
11
12
10
1 <\>MAT
8
2
3
6
7
4
8
1
5
10
11
12
9
Table 1. APL Operators (cont. )
Type of
Operator
Nondyadic
Scalar and
Mixed
Operators
(cant. )
Operator
Monadic Operation
Dyadic Operation
Reversal along the first coordinate: some
as above, except along the first coordinate instead of the lost. This is equivalent to <1>[ 1 J. Example:
Rotation along the first coordinate: s<lme
as above, except along the first coordinate
instead of the lost. This is equivalent
to q,["jJ. Examples:
O+MAT+3 4P112
O+MAT+3 4P112
4
1
2
B
6
10
11
12
5
9
3
7
4
6
3
7
10
11
12
11
7
3
12
1
2
5
9
laMAT
eMAT
9
10
5
1
6
2
8
B
5
9
4
1
6
10
2
7
11
3
8
12
4
2eMAT
1
10
2
5
6
9
11
3
7
12
4
B
Compression: suppresses some elements of a
vector and retains others. Elements of the
ri ght argument correspondi ng to ali n the
left argument ore retained, while those corresponding to a 0 are dropped. If either argument contains just one element, it applies to
all elements of the other argument. Examples:
A+5 7 9 11
B+'ABCD'
1 0 1 llA
r-~
5
9
11
1 0 1 liB
ACD
1
5
9
1
5
9
O+MAT+3 4P112
2
3
4
6
7
8
10
11
12
1 0 1 O/MAT
3
7
11
Compression can also be used as a logical
test and branch situation (like the IF statement in FORTRAN). In this case, if the argument on the left returns a val ue of 1, APL
branches to the statement i ndi cated by the
argument on the ri ght. If the left argument
returns a 0, program flow falls through to
the next statement. Examples:
+(2)3)IEND
falls through
to the next
statement.
+(2<3)/END
causes a branch
to statement
labeled END.
Operators and Arguments
35
Table
Type of
Operator
Nondyadic
Scalar and
Mixed
Operators
(cant. )
Operator
I
1.
Monodic Operation
AP L Operators (cant. )
Dyad; c Operati on
Compression along the first coordinate:
same as above except that compression is
along the fi rst coordinate instead of the
last. Equivalent ta 111 J. Example:
U+MA1'+ 3
2
1
5
9
5
3
7
4p t12
4
8
5
12
10
11
0 1 O-IMAT
B
7
6
Expansion: inserts additional elements into
an array. For each 0 in the left argument,
a blank (for literals) or a zero (for numbers)
is inserted in the result, which otherwise is
the same as the right argument. Examples:
A+l 2 3 4
B+'ABCD'
1
1 0 1 0 l\A
4
3
0
1 0 1 0 1 0 1\B
1
2
0
0
0
A B C D
O+M+3 4p'ABCDEFGHIJKL'
ABCD
EFGH
IJKL
1 0 1 0 1 0 1\M
ABC D
E F G H
I
------------+----------
J
K L
---------------------------~------------------------------~
Expansi on a long the fi cst coordi na te:
same as above, except expansion occurs along
the first coordinate rather than the last.
Examples:
O+M+3 4p'ABCDEFGHIJKL'
ABCD
EFGH
IJKL
1 0
ABCD
EFGH
IJKL
36
Operators and Arguments
1 0
1 ",M
Table 1. APL Operators (cant.)
Type of
Operator
Composite
Operators t
Operator
fl
Dyadic Operation
Monadic Operation
Reduction: inserts the symbol (APL
operator) specified to the left of the I
between each element of the right
argument, performs the operation
from right to left, and returns a
single value. Examples:
+/1
2
3 4
5
15
-Ii 2 3 4 5
3
O+N+3 4p\12
1
2
5
3
4
678
10
11
12
9
+IN
10
26
-2 - 2
ff
42
-IN
2
Reduction a long the first coordinate:
same as above except reduction occurs
along the first caordinate rather than
the last (equivalent to f/r]I). Examples:
O+N+3 4p \ 12
4
2
3
7
e
6
10
11
12
1
5
9
+fN
15
18
21
24
-fN
5
6
7
8
fog
Generalized inner product: This operator
is a generalized form of the inner product
of matrix multiplication. The particular
form that correspor,ds to traditional matrix
multiplication is A". xB, where the second
dimension of matrix A is the same as the
first dimension of B. The result has the
same first dimension as A and the same
second dimension as B.
In the conventional matrix inner product,
each element of the result is the sum of
products of elements from A and B (see
Chapter 5 for detailed description).
The APL generalized inner product allows
different forms such as the sum of equality
tThe letters f and g stand for any dyadi c scalar operator: + - x
Operators and Arguments
37
Table 1. APL Operators (cont.)
Type of
Ope rotor
Operator
Composite
Operators
(cont. )
Monadic Operation
Dyadic Operation
tests, the maximum of sums, etc.
Examples:
A+2 3Pl6
B+3 2P-16
A
1
2
5
4
3
6
- 1 - 2B
- - 53 - 46
- 22 - A+.xB
28
- 49 - 64
A+.=B
0
0
0
3
0
0
- 1 A. r . +B
2
The general form is Af. gB, where f and g
represent any dyadic scalar operators. A
and B may be vectors, matrices, or higherorder arroys, subject to conformobil ity
rules described in Chapter 5.
o •
f
Generolized outer product: This operator is
a generolization of matrix outer product,
Au., B. The conventionol form multiplies
each element of A by each element of B.
The shope of the result is the catenotion of
the shapes of Aand B. In the generalized
form, multiplication may be replaced by
ony dyadic scalar operation. Examples:
A+ - 1+16
A o. +A
0
1
2
3
4
5
2
3
4
5
6
7
1
2
3
4
5
6
3
'+
'+
5
6
7
8
9
5
6
7
8
5
6
7
8
9
10
A o. xA
0
0
0
0
0
0
0
0
0
38
Operators and Arguments
1
0
0
0
0
0
0
0
0
0
0
2
1
2
3
'+
6
8
10
'+
5
A o. <A
1
1
1
1
0
1
0
0
0
0
3
6
9
12
15
0
0
0
1
1
1
1
1
1
1
0
1
1
0
0
0
4
0
8
10
15
20
25
12
16
20
5
Tabl e 1.
Type of
Operator
Operator
f\
Composite
Operators
(cant. )
APL Operators (cont. )
Monodic Operation
Dyadic Operation
Scan: returns value of some shope as
argument. For vectors, i' th resu I tel ement is formed by taking the first i argument elements, placing f between them,
and evaluating right to left. For
instance:
1
4
+\1 3 5 7 9
9
16
25
3
2
-\3 1 1 5
3 -2
A coordinate specification I K I moy be
used; if omitted, the lost coordinate will
be assumed.
+\[1]
2 3
p
16
123
579
Scan along the first coordinate: some
as f \ 11 J. Thus, as above,
+1,2
3 p 16
123
579
FunctiLn References
Functions are used in the same way as operators, but most functions must first be formed by the user instead of being
an inherent part of the language. Once a function has been formed, or "defined", it is referenced by its userassigned name. (Naming conventions are described earlier in this chapter under "Names".) A general treatment
of functions is gi ven in this section; for a detai led treatment, see Chapter 7, "Defined Functions".
Like operators, defined functions can have arguments whi ch in turn have attributes of domain, rank, length, and
shape (see "Operators and Arguments" above). Functions are classified as monadic, dyadic, or niladic, according
to their number of arguments. A monadic function has one argument to the right of the function name. A dyadic
function has two arguments, one to the right of the function name and one to the left. A .1i ladi c functi on has no
arguments; the function name is referenced by itself.
The right argument is the value of the largest, complete APL expression immediately to the right of a function.
the example below, F is a function whose right argument is 2 + \3.
F
2+13;
For
'POUNDS'
In this case, the text vector 'POUNDS' is not included in the argument since the semicolon splits the example into
two distinct expressions.
The left argument is the value of the smallest complete APL expression immediately to the left of a function.
example below, D is a dyadic function whose left argument is (\3).
2+ (I 3)
In the
D 4
Operators and Arguments
39
In this case, the parenthetical expression (\3) is the smallest complete APL expression immediately to the left of D.
2+(13) is also an APL expression, but it is larger. Therefore, the above example is interpreted as
2+ result
where "result" is the result supplied by the function reference
(\3)
D 4
In addition, any of the classes of defined functi ons may specify an impl i cit or expli cit result. Thus there are actua IIy
six types of defined functions:
With
explicit
result
With
no
result
monadic function
x
x
dyadi c function
x
x
niladic function
x
x
The class is determined by the way a function is defined (that is, the function header), and it affects the way a
function is referenced in an expression. Defined functions with explicit results may appear in compound expressions,
much like operators. Defined functions without results may appear alone; they cannot appear in compound expressions except as the last function to be executed.
A defined function may reference itself; that is, it may be recursive.
itself in the process of its execution.
A recursive function is one that references
When a function is invoked, it may complete execution and return a result or it may become suspended or pendant
during execution. A suspended function is one in which execution has been stopped before completion (the reasons
for stopping execution are given under "Suspending Execution" in Chapter 7). A pendant function is usually one
that has referenced a suspended function and is unable to complete execution because of the suspended function.
Suspended functions are always stopped "between" lines, but a pendant function is stopped in the process of executing a line. A function can be both suspended (stopped at some point) and pendant (in execution at some point).
For instance, if a recursive function is stopped after it calls itself, it is suspended (at the stop) and pendant (where
it called itself).
Assignment
Simple Assignment
The assignment symbol, denoted by a left-pointing arrow, is used to assign values to named variables or to a quad.
(Some programmers may refer to this symbol as the specification symbol or the replacement symbol, but the term
assignment symbol will be used throughout this manual.) It is the assignment that causes a variable to be a scalar,
a vector, a matrix, or a higher-order array. The assignment of a value or an expression to a quad displays the
value. Examples of assignments are shown below.
Assigns the value of the expression 5,.2x4 to variable A.
8+1
8+\ 5
40
Assignment
2 3 4 5
Indicates that B is to be a vector with the values 1, 2, 3, 4, and 5.
Another way of assigning the numbers 1 through 5 to variable B.
(The 15 assumes an index origin of 1.)
4Pl3
C+2
Indicates that C is to be a matrix (with two rows and four columns)
and that it is to be made up of the values 1 through 8 (assuming an
index origin of I), as shown here:
1
2
3
567
3p5 6 1 2 8 9
0+2
4
8
Indicates that D is to be a matrix (with two rows and three columns)
and that it is to be made up of the values 5, 6, I, 2, 8, and 9, as
shown here:
561
289
E+D
Indicates that the value of D is assigned to E.
Multiple Assignment
APL allows repeated use of assignment, or multiple assignment, in a single statement.
ment are shown below:
5
6
5
7
2
3
Examples of multiple assign-
A+5.B+6
A.B
6
Z+2+Y+2+X+5
X.Y.Z
9
[]+C+2 3 4 5
I~
5
Indexed Assignment
One or more elements of an already established array may be assigned new values. This is done by placing the
variable name and the index designation(s) to the left of the operator, and the new value(s) to the right, as shown
below (these examples all assume an index origin of 1):
:J+A+l 5 4
3 2
15432
A[l 2]+2 3
A
2
J
4
3
2
o
0
A[
A
]+0
0
0
lJ~-ii+2
0
3p 16
123
4
4
5
G
iJ[1;2]+Lj
B
4
3
S
6
8[;J+O
13
o
o
0
0
0
0
Assignment
41
Input/Output
Input/Output Devices
The Xerox APL system allows the user a choice of six input/output methods:
•
Standard APL terminal input/output: a standard terminal with an APL typeball. t
•
APVASCII terminal input/output: a terminal with either of two APVASCII character mappings.
•
Nonstandard terminal input/output: a standard terminal with non-APL typeball, or a device equivalent
to a Teletype Model 33 to 37.
•
Batch input/output.
•
File input/output.
•
'Blind' input/output.
The input/output described in this chapter refers to terminals with the APL character set.
batch, blind, and fi Ie input/output are discussed in Appendix B.
Nonstandard terminal,
General Input/Output
After logging on to the APL system, the user is in execution mode and can enter input whenever the keyboard is
unlocked. The fundclmental item of input to APL is the line. A line is a collection of characters that does not
include the carriage return. Striking the RETURN key completes a line, and APL attempts to interpret it and perhaps output data. An incomplete line can be corrected as described in Chapter 2. User input and computer output
are easily distinguished at the terminal; computer output usually begins at the left margin while user input
is usually indented six spaces from the left margin. An input line is limited to 130 characters, not counting the
carriage return (overstrikes count as single characters).
Types of Input
The Xerox APL system acknowledges four kinds of input: direct, evaluated, quote quad, and blind. Direct input
results when APL is not executing the user's program, evaluated input results from quad execution, quote-quad
input results from quote-quad execution, and blind input results from quad-1 or quad-2 execution. Direct input,
evaluated input, and quote-quad input are described below and are considered to exist only after input translation
and current-line editing. Blind input is covered in Appendix B. (See also Chapter 11 for discussion of graphics
'quad-zero' input. )
Direct Input
Direct input is entered during the execution mode.
skips to a new line, indents six spaces, and unlocks
and the response is either printed at the left margin
variable (if the input was an assignment statement).
The APL system is ready to accept direct input whenever it
the keyboard. Evaluation of direct input occurs immediately,
(if the input was a nonassignment statement) or assigned to a
Examples of direct input follow:
0.625
A+A+5
10
1
5
9
0+B+3 4 p\12
4
2
3
6
10
7
11
8
12
tAs noted in Chapter 2, the APL typeball can be used with any terminal model that is operationally equivalent to
an IBM 2741.
42
Input/Output
Evaluated Input
The quad symbol D can be used as an argument in a statement, todenote that input is desired. In this context it can
appear anywhere except to the immediate left of an assignment arrow. When APL encounters the quad during statement execution it halts execution and requests input by printing the symbols [1: at the left margin. A response of
any valid APL expression causes execution to continue, using the value obtained in response to the quad symbol.
Examples:
BtD
D:
2
4
5xD
D:
5
10
1 2 3 4
15 20
If the quad symbol is built into an input loop, the user can terminate the input request by entering the symbol -.. (not
followed by an argument). Simply entering nothing and pressing the RETURN key is not sufficient to terminate the
input request; it wi II merely cause the D: to reappear at the left margin. An example of escaping from an input
request is shown below:
[3]
[4]
VCUBE;A
LOOP: A.... D
A.... AxAxA
A
-..LOOP
[5]
V
[1 ]
[2 ]
~,
CUBE
0:
3
27
0:
64
0:
5
125
D:
-+-
Entering any of the following system commands will terminate an input request: )CLEAR, )LOAO, )OFF, )OFF HOLD,
)CONTINUE, or )CONTINUE HOLD. Entering other system commands merely causes the D: to reappear after the
command is exe5~' Entering a )SAVE, )CONTINUE, or )CONTINUE HOLD command causes the workspace to
be saved in th~D st(lt!t; and causes a D: to be printed when that workspace is eventually loaded. This can be useful in attaching a-'message to a workspace. For example:
'NOTE:
r-;
WORKSPACE HAS ORIGIN 0'; opD
0:
}CONTINUE
CONTINUE
SAVED
lB:07 JUN 27.'72
oAPL
APL 07/27/73
CONTIN~E
D:
SAVED
18:07 JUN 27.'72
1
NOTE:
WORKSPACE HAS ORIGIN 0
Input/Output
43
Functions can be defined during evaluated input. This is simil.Jr to function definition during normal (direct) input
except that at the conclusion of the definition APL re-requests evaluated input. This is to be expected since when
APL originally requested evaluated input it needed a value, end defining a function provides no value. This enhancement is not limited to just providing definition capability. The full range of function definition mode features
are available during evaluated input:
•
Creating a new function.
•
Revising an existing nonpendant t function: inserting a line, deleting a line, replacing a line, and editing
characters of a line.
•
Displayi ng one or more I ines of the open functi on.
Entering an )SI or )SIV command in response to an input request will cause the state indicator to contain a D.
example:
For
fl:
)SI
lJ
0:
2
5
Quote-Quad Input
The quote-quad symbol I!J (except when to the left of an assignment arrow) denotes I iteral input. When APL encounters this symbol during statement execution, it skips to the beginning of the next line, unlocks the keyboard,
and awaits user input (no symbol is printed to prompt for input). Literal character strings are entered without beginning and ending quote symbols, and a quote within a string is represented by one quote instead of two. Entering
~,O characters produces an empty vector, entering a single character produces a scalar, and entering a string of charucters produces a vector. To terminate a request for literal input, enter the following sequence of characters:
o backspace U backspace T, which appears at the terminal as Ill. Examples of quote-quad input are
pA
o
B+!.'J
QUOTES AREN'T NEEDED
B
QUOTES AREN'T NEEDED
X+' C!lLIFOR.'lIA' €I!l
ABCDEFCHI~TK[.M
X
1
1
1
1
1
boo
1
Output
As previously mentioned, the display of most computer output begins at the left margin.
teristics are described below.
1.
Width of I ine. Unless the user specifies otherwise, up to 120 characters can be displayed per line. The
user can change the number of characters displayed to any number from 30 to 254, via the )WIDTH system
command (see Chapter 9) or the WIDTH function (see Chapter 8). Output processing always assumes that
the left and right margin stops are placed full left and full right.
tlf a function makes an evaluated input request, the function becomes pendant.
opened during the evaluated input request.
44
Important output charac-
Input/Output
Therefore, that funCtion cannot be
2.
Fractional number. A fractional number is displayed with one leading zero to the left of the decimal point,
even if the number was entered without the zero. Examples of fractional numbers are
.2
+ .4
0.6
2t3
0.6666666667
.123
0.123
3.
Exponential notation. The APL system usually uses exponential form for printing numbers less than 1 C5,
or greater than lEn (where n is the number of significant digits displayed) or 23L 1. Decimal form is used
for other cases. Numbers printed in exponential form always have a magnitude between one and ten followed by an appropriate exponent.
When a vector is displayed, some numbers may be printed in exponential form and some in decimal form,
depending on the size of each number. Numbers in a vector are printed with two spaces between each
number, as shown below:
1234567.89
1234567890
1.23456789E10
When a matrix is displayed, the numbers are printed all in exponential form or all in decimal form. One
number requiring exponential form will cause all the numbers to be printed in exponential form. Numbers
in a matrix are printed with decimal points aligned, as shown below:
A
0.0100003
12.3456703
A*11
1.000330050E-22
1.015456727E12
4.
251.8767434
-0.09873201
2 • 5 8 8 6 2 2 7 6 :? E 26
8.690359926E-12
1.99032
7.76767676
1.941565195E3
6.211587288E9
Significant digits. The APL system carries out all calculations to approximately 16 significant digits
(i.e., to 16 digits to the right of a decimal point), clnd displays the result rounded off to 10 significant
digits. Any trailing zeros are suppressed in the display. Examples are shown below:
4*3
1. 333333333
5+2
2.5
The user can use the )DIGITS system command (see Chapter 8) to change the number of significant digits
displayed, with the number ranging from 1 to 16 digits. Examples are shown below:
) DIGITS 4
WAS 10
1.333
5*2
2.5
If )DIG ITS 16 is selected (this is not recommended, however), decima I fractions wi II tend to be displayed
in forms such as .5999999999999999 because of roundoff in internal computatior,:;. With )DIGITS 15, this
value will print as .6. In performing some calculations (particularly tests of equality), the user should remember that the number of significant digits printed may be less than that retained by the system, and that
the significant digits retained by the system may be less than the number originally entered by the user.
5.
Fuzz. When comparing noninteger numbers, the question is how close the numbers must be to be considered
equal. This tolerance, known as fuzz, is approximately 1. OE-13. The results of some floor and ceiling
operations and comparison operations are affected by this fuzz. Examples of comparison tests illustrating
fuzz are shown below:
2.2222222222222222=2.222222222222222229
1
12
11
Input/Output
45
6.
Numeric and character vectors. Numeric vectors are displayed with two blanks between elements, while
character vectors are displayed with no blanks between elements, as shown:
2"1"16
345
6
7
8
'ABCXYZ'
ABCXYZ
7.
Arrays of two or more dimensions. The components of a two-dimensiona I array (i. e., a matri x) are displayed in a rectangular arrangement. The components of an array of more than two dimensions (i. e., a
higher-order array) are displayed as a set of rectangles. Numeric arrays of two or more dimensions are
indented two spaces. Character arrays of two or more dimensi ons are displayed with no spaces between
columns. Ir. addition, arrays of more than two dimensions are displayed with extra blanks separating
planes. Examples are shown below:
4
9
3 5p 2"1"115
0
2
1
5
6
7
10 11
12
13
2 3 4p4"1"124
6
7
8
10
12
11
14
15
16
17
21
25
18
22
26
5
9
19
23
27
3
8
13
20
24
28
3 4p' NOWISTHETIME'
NOWI
STHE
TIME
ABCDE
F CHI
2 2 5p'ABCDEF GHIJKL MNOPQR'
JKL M
NOPQR
8.
Empty arrays. An empty array - an array of no components - can take the form of a vector ar an array of
two or more dimensions. An empty array produces no display (just another prompt for input). An empty
vector (also known as a null vector) can be entered in one of the following ways: 10 or" or Op2. Similarly, examples of entering empty arrays of two or more dimensions are 0 2p4 and 00 OpO. The display
of an empty vector and an empty matrix are shown below:
\0
o
2p6
2"1"2
4
Note that an empty numeric vector is represented by the expression lO and an empty character vector is
represented by the expression ". These expressions cannot a Iways be used interchangeably. An example
is in their use as the right argument in an expansion operation:
0\ ' ,
o
0\10
Empty vectors are useful in initializing vectors and in branching.
46
Input/Output
It should be noted that the use of an empty array as the argument of a scalar function wi" resu It in an
empty array:
34+pO
0;t2 OpS
9.
Mixed output. Numeric and literal expressions can be intermixed for output, as long as they are separated with semicolons. The output will be displayed on one line, unless one of the expressions is a
nonemptyarray. Display of a nonempty array value begins on a new line. Examples of mixed output are
'THE SUM OF 20+2+4 IS ',20+2+4
THE SUM OF 20+2+4 IS 26
'SUM IS ',S+10,', PRODUCT IS ',Sx10,'.'
SUM IS lS, PRODUCT IS so.
'Till<.' REPLY IS';
THE REPLY IS
YES
1
0 O/[lJ
3 Sp
'n's
NO
UNSURE'
In this context, the semicolons are said to separate the "compound statement" into a series of substatements.
Any valid statement can be used as a substatement (even branches); however, a compound statement cannot
contai n system commands. Consider the following statements:
'AMT
= ,
AMT
A+2Sx8+100
, DOLLARS'
DOLLARS
Noti ce that the second statement (A+25xB+ 100) produced no display since it ended on an assignment
to A. Statements that end (in an evaluation sense) Oil assignments are called "assignment statements".
Nonassignment statements automati cally produce display, whi Ie assi gnment statements do not. The same
is true for substatements in Xerox APL (unlike some other versions of APL). Thus if the above statements
are combined, the resulting mixed output is as shown:
AMT
=
'AMT = ',A+2S xB+l00;' DOLLARS'
DOLLARS
To make the second substatement into a nonassignment substatement is easy; simply insert a + (identity
operator) as its first character, as shown here:
AMT
=
'AMT = ';+A+2Sx8+100;' DOLLARS'
2500 DOLLARS
The second substatement value (2500) is displayed because it is a nonassignment substatement now.
ends on the identity operation (+), not on an assignment.
10. Blind output.
It
Blind output - treated in Appendix B - is output as one record of text (literal) data.
11. Stopping a display. The user can stop display of output by depressing the ATTI-.I key. This use of the
ATTN key is more fully described in Chapter 10, "Execution Stops". A small amount of data may still be
output after depressing the ATTN key. This results because CP-V has already prepared to display that data
before APL is notified that ATTN was issued.
12. Graphics output.
See Chapter 11 for discussion of graphics "quad-zero" output.
13. Quad output. When 0 appears immediately to the left of an assignment arrow, the value of the expression
to the right of the arrow is output. Example:
D+A+2+3
S
Input/Output
47
4. EXPRESSION EVALUATION
Order of Evaluation
Right to Left
The APL system evaluates compound expressions from right to left, not from left to right as in most programming
languages. Each function or assignment symbol in a compound expression operates on the entire expression to the
right of it, with the rightmost expression evaluated first, then the next rightmost, and so on. In illustration, notice
the following compound expression:
130
In this expression the result of 5~2 is added to 4, and the result of that is multiplied by 20, thereby yielding the
value 130.
Precedence of Operators
Unlike most programming languages (and unlike common algebraic usage) no APL operator has precedence over
another operator. A division operation, for example, is not performed before an adjacent addition unless, of
course, the division appears to the right of the addition. Note that in the example cited above the conventional
algebraic operator hierarchy would have treated the expression as equivalent to (20 x 4) + (5,2), which would have
resul ted in the value 82.5.
Parentheses
Parentheses can be used in a compound expression to depart from the right-to-Ieft rule for execution. They are used
just as they are in mathematics for grouping expressions. APL evaluates everything withina pair of parentheses
(from right to left) before evaluating the expression of which they are a part. There must be an equal number of
left and right parentheses. The beginning APL user will find parentheses convenient to avoid confusion over the
difference between APL and conventional algebraic notation. Some examples of the use of parentheses are
shown below:
12
15
(3+\5)X2+1
18
21
24
( (6f2)x5 x 4)t3+12
6f2x5x4f3+12
2.25
(20x4)+(5t2)
The Value of a Variable Versus Its Name
When Xerox APL encounters a variable name, it obtains the associated value immediately. This value becomes an
argument, and the argument will not change value even if the named variable is assigned a new value. The following example illustrates this evaluation procedure:
K+1
(K+2)+K
3
48
Expression Evaluation
The K to the right of the plus sign was evaluated to the argument having, at that time, value 1. This argument did
not change even though K's value changed before the addition was completed. (Some APL systems retain the name
rather than the value of an argument. These systems would obtain a result of 4 in the above example.)
Syntax Considelltions
Any two variables, constants, or quads cannot appear adjacent _0 each other. They must be separated by a dyadi c
operator or a dyadic function reference. Some valid and invalid examples are shown below.
Valid
Invalid
(3t4)x2
(3t4)2
2xA
2A
4+ - 1
4-1
1 2 3
(1
2) 3
Notice in the last example that" 1 2 3" is actually only one constant - a numeric vector.
Two dyadic operators cannot appear next to each other, but a dyadic operator and a monadic operator can.
the expression
is legal, since the * and r operators are used as monadic operators, and the I operator is dyadic.
expression is illegal, however, because v is a dyadic-only operator preceded by an operator:
Thus
The following
AI\VB
Default Terminal Output
Default terminal output occurs when a nonassignment statement is evaluated. That is, the result defaults to the
terminal instead of being stored in memory. For example, 2x4 gives default output:
8
Default output is killed by assignment.
For example, the expression A+-2x4 prints no output at the terminal:
Instead, the value 8 is assigned to variable A and stored in computer memory.
When a compound statement (Chapter 6) includes both nonassignment and assignment expressions, the nonassignment
expressions produce default output at the terminal while the assignment expressions do not. However, anyassignment expression can be transformed into a nonassignment expression by placing a plus sign (that is, identity
operator) at its extreme left. Some examples are
4;4
44
4
.
4· ,
4
, ;4
4+2;A+-5+2;4+2
66
1
2
X+\5;Y+-2+4
+X+\5;+Y+-2+4
4
56
3
Default Terminal Output
49
Noti ce from these examples that separating spaces must be designated by spaces within quotes (see the 4; I ';4
example), or else the default output from several expressions will run together. Also notice in the following example that the monadic + may be used to force default output even if the result is not numeric:
+X+-'TEXT'
TEXT
Errors and Breaks
If the user discovers an error in a statement before the RETURN key is depressed, the user can backspace to
the error, strike the INDEX key or the ATTN key, and retype the rest of the line as described in Chapter 2. An
example (using the ATTN key) is: t
11+-5x8+8"
v
t4
A
10
If the user has entered a line and APl detects an error or break during statement execution, execution of the statement is terminated. If the statement in error contains multiple assignments or is a compound statement, the assignments and expressions to the right of the error (denoted by a caret) wi II be completed. The current expression and
any expressions to the left of the error, of course, wi II usually not be completed. If a dyadi c operator or function
is indicated, however, its left argument expression (possibly containing assignments) will have been completed
before the function or operator was invoked. Examples are shown below (it is assumed that sidetracking, see Appendix A, is not applicable in these examples):
C+4+(D+O)"Z+5
DOMAIN ERR
C.... 4t(D+-0)"Z+5
A
C
UNDEFINE'D
C
A
D
o
Z
5
EtF;E+4t2+1iF+Oi4t2*.5
DOMAIN ERR
EtFiE+4t2+1iF+Oi4f2*0.5
A
E
1.333333333
o
F
In both of these examples the user has attempted to divide by zero, thus producing a DOMAIN ERR message. In the
first example the error is detected before variable C is assigned a value, so C remains UNDEFINED as shown. In
the second example, both variables E and F have the values assigned to them before the error was detected.
t
On API/ASCII terminals, the standard CP-V input line editing devices are applicable.
Reference Manual, 900907, Chapter 2.
50
Errors and Breaks
See CP-V Time-Sharing
If the user has entered a line and APL detects a simple error before any part of the line is executed, APL returns
the following: the message LINE-SCAN ERR, a caret at the error point, and that portion of the line it found acceptable. The user can then complete that portion in the usual manner (as if he were entering it for the first time),
correcting the problem. For example:
A+234+( 13)0*3
LINE-SCAN ERR
u:
A
A+234+(13)xD*3
4
298
A
362
426
where the underlining indicates the portion of the line typed by APL.
Errors and Breaks
51
5. APL OPERATORS
An APL operator is a symbol indicating that a basic APL operation, such as addition or division, is to be performed.
A symbol denoting an APL operator is either a nonalphanumeric character or a combination of such characters. For
example, addition is denoted by the + symbol and division is denoted by the f symbol.
Some of the basic APL operations are "monadic" and others are "dyadic". That is, some require a singleargumentand
others require two. For example, the reciprocal operation is monadic (e.g., ~A) and the division operation is dyadic (e.g., A:B). MJst of the symbols denoting APL operators are used for both monadic and dyadic operations.
APL distinguishes between the monadic and dyadic use of any given operator by testing for the absence or presence
of a left argument.
•
Syntax Conventions
Syntax conventions used throughout this chapter are as follows:
denot~s the resulLof an operation.
R
denotes the replacement of any previous value of the symbolic variable to the left of the arrow.
A
denotes a left argument.
B
denotes a right argument.
m
denotes a monadic operator.
d
denotes a dyadic operator.
Following are some examples of the use of these conventions:
R+mB
•
R+AdB
Argument Characteristics
In discussing operators, certain argument characteristics will be referenced frequently.
scribed below.
The terms used are de-
Domain - In general, the type of data element such as integer data, character data, floating-point data.
For some operators the domain of an argument may be especially restricted (see the example for the
circular operator later in this chapter).
Rank -
The number of coordinates in an array argument.
Length Shape -
•
(A rank of zero indicates a scalar. )
The number of elements in a coordinate of an argument.
The vector made up of the lengths of all coordinates of an argument.
Domain Tables
In the tables listing the domains of the results for various types of argument data, the following symbology is
used:
N
denotes numeric data.
C
denotes character data.
L
denotes logical data (l or 0).
A?L Operators
denotes integer data.
F
denotes floating-point data.
DE
denotes a domain error.
RE
denotes a rank error.
Scalar Operators
APL operators vary considerably in how they reference the elements of array arguments and in the characteristics
(rank and dimensions) of the result compared with those of the arguments. A group of operators called scalar
operators follow 0 common set of rules with respect to choracteristics of arguments and results. These operators,
comprising the arithmetic group, the relational group, ond the logical group, are so nomed because they are defined
in terms of scalar arguments. Extensions of scalor operations to orray arguments are equivalent to performing
companent-by-companent scalar operations.
•
Monadic Scalar Operators
The argument used with a monadic scolar operator may have any rank and dimensions. The result has the rank
and dimensions of the argument. The domain of the result may be different than that of the argument.
•
Dyadic Scalar Operators
If the rank and dimensions of the arguments used with a dyadic scalar operator ore the some, the operation is
performed on corresponding components of the two arguments and the result has the some rank and dimensions.
If the arguments have different ranks or dimensions and both contoin more than single elements, a rank or
Iength error wi II be reparted.
If one argument has multiple elements and the other is a scalar or single element array, the operation is performed on the single element with each component of the multiple element argument. The result has the rank
and dimensions of the multiple element argument. If neither argument has multiple elements but they are not
both scalars, the result is given the shape of the higher ranking argument. The shapes of results of scalar operations for various arguments are tabulated below.
Right Argument
Left Argument
S
VI
Ml
HI
V
M
H
S
S
VI
MI
HI
V
M
H
VI
VI
VI
Ml
HI
V
M
H
Ml
Ml
Ml
Ml
HI
V
M
H
HI
HI
HI
HI
HI
V
M
H
V
V
V
V
V
Vt
RE
RE
M
M
M
M
M
RE
Mt
RE
H
H
H
H
H
RE
RE
Htt
Result
where
S
denotes a scalar.
V
denotes a vector.
M
denotes a matrix.
H
denotes a higher order array.
t
tDimensions of arguments must be identical.
tt Rank and dimensions of arguments must be identiCal.
Scalar Operators
53
RE
denotes a rank error.
VI
denotes a single element vector.
MI
denotes a single element matrix.
HI
denotes a single element higher order array.
Arithmetic Group
Each operator in the arithmetic group has a monadic and dyadic form. If any argument is in the character damain,
a domain error is reported. If an argument is in the logical domain, however, it is considered to be a special case
of the integer domain. Results are always inthe numeric (integerorfloating)domain. (An exception is the monadic +
which is valid for any argument, including character data. The result is unchanged in domain.)
The + Operator (Identity and Addition)
•
The monadic + is the identity operator.
It is essentially "no operator".
R++B
Domain Table:
~I--~----~-------:~
Examples:
+5
5
-
3
2
1
0
2 1. 1)
+( 3
1.1
+0 1
0
+ 'A'
0
A
•
The dyadic + is the addition operator.
R+A+B
Domain Table:
t
54
~
C
L
I
F
C
DE
DE
DE
DE
L
, DE
I
I
F
I
DE
I
I/F t
F
F
DE
F
F
F
The sum of integers is floating-point if the result exceeds the integer range.
Scalar Operators
If a floating-poin!' result exceeds the range of floating-point numbers, DOMAIN ERR is reported.
Examples:
~'.
2 3 1+5
7
2
1 0
1
2.5+1 2 3
4.5
5.5
2.5 3.5+1 2 3
3.5
LENGTH ERR
2.5 3.5+1 2 3
1\
The - Operator (Negation and Subtraction)
•
The monadic - is the negation operator.
R~--B
Domain Table:
L
F
F
Examples:
-5
•
The dyadic - is the subtraction operator.
R+A-B
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
I
I
F
I
DE
I
I/F t
F
F
DE
F
F
F
1
R
Examples:
2 3 1-5
1 0
1
2.5 -1 2 3
- 0.5
1.5
0.5
1 2 3 - 2.5
1 .5
0.5
0.5
3
4
tThe sum of integers is floating-point if the result exceeds the integer range.
Scalar Operators
55
The
x
Operator (Signum and Multiplication)
•
The monadic
x
is the signum operator.
R+-xB
If B is positive, R is 1.
If B is zero, R is O.
If B is negative, R is -1.
Domain Table:
I : I~E
L
F
Examples:
x
2 3.5 0 .0001
101
1
•
The dyadic
is the multiplication operator.
x
R+-A xB
Domain Table:
I~
c
L
I
F
C
DE
DE
DE
DE
L
DE
I
I
F
I
DE
I
11Ft
F
F
DE
F
F
F
}.
Examples:
5
5
-1. 5
5xl
1 7
35
1 2 Oxl.5 2.5 3.5
5
0
2.5 3xl.7 12 .01
LENGTH ERR
2.5 3xl.7 12 0.01
1\
The
f
•
The monadic
t
56
Operator (Reciprocal and Division)
f
is the reciprocal operator.
The product of integers is floating-point if the result exceeds the integer range.
Scalar Operators
Domain Table:
L
F
F
F
F
If B is zero, the error DOMAIN ERR is reported.
Examples:
1
0.5
T1 2 5
0.2
t • 01
100
•
The dyadic
t
is the division operator.
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
F
F
F
I
DE
F
F
F
F
DE
F
F
F
j.
If B is zero and A is other than zero, the error DOMAIN ERR is reported. If B and A are both zero, R is l.
If R exceeds the range of floating-point number, DOMAIN ERR is reported.
Examples:
3.5
7 8 9t2 10 18
0.8
0.5
Ot12
o
1
The
* Operator (Exponential, Exponentiation)
•
The monadic * is called the exponential operator.
The monadic
with e (base of natural logarithms) supplied as a left argument.
2.7182818284590451.
* is the equivalent of the dyadic form
The value used for e is approximately
Domain Table:
F
L
F
F
F
If B exceeds 174.6730895, DOMAIN ERR is reported.
If B is less than -179.8716889, R is O.
Scalar Operators
57
Examples:
*1 .50
190
2.71H281828
1.648721271
•
1
0
The dyadic * is the exponentiation operator.
Domain Table:
~,
DE
L
I
F
C
DE
DE
DE
DE
L
DE
F
F
F
I
DE
F
F
F
F
DE
F
F
F
If both A and B are zero, R is 1. If A is zero and B is less than zero, DOMAIN ERR is reported. If A is less
than zero and B is not an integer, DOMAIN ERR is reported. If R exceeds range of floating-point numbers,
DOMAIN ERR is reported.
Examples:
1
1
o 1 2 2*0 5.3 0.5 3
1.414213562
8
2*-.3
DOi'1AIN ERR
2* 0.3
/\
The ~ Operator (Natura I Logarithm, Logarithm)
•
The monadicQlis Ihe natural logarithm (base e) operator.
R+en
Domain Table
~+I-~-E---~----F---F-F~
If B is not a postiive number, a DOMAIN ERR is reported.
Example:
Ql2.7182818284
103
•
1
.04978706837
The dyadiceis the generalized logarithm (base A) operator.
R+AQlB
If A or B is not a positive number, a DOMAIN ERR is reported.
DOMAIN ERR is reported.
58
Scalar Operators
If A is 1 and B is other than I, a
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
F
F
F
I
DE
F
F
F
F
DE
F
F
F
Examples:
o
3
1
The Land
•
2 3 16.1 27 .25
0.5
10.10 .1 250
1
2.397940009
r Operators
(Floor and Ceiling, Minimum and Maximum)
The monadic Land
r are
the floor and ceiling operators.
R+-LB
For L, R is the algebraically greatest integer such that R~B+FUZZ.
R+-rB
For
r,
R is the algebraically smallest integer such that R~B-FUZZ.
FUZZ is approximately lE-13 unless modified by SETFUZZ intrinsic function.
Domain Table:
B
C
L
I
F
R
DE
I
I
}t/F
Examples:
L 2.9
•
2
2
3
3
Dyadic Land
r are
3
r 2.1
2
2
2.99
2.99
2.99999999999999
2.01
2.01
2.00000000000001
3
the minimum and maximum operators.
R+Ar B
R+AlB
For each element pair of A and B, R is the algebraic minimum or maximum.
t Result is floating-point if the value exceeds the range for the integer domain .
.'
Scalar Operators
59
Domain Table:
~,
C
L
I
F
C
DE
DE
DE
DE
L
DE
I
I
F
I
DE
I
I
F
F
DE
F
F
F
R
Examples:
SL12
S
Sf12
12
5
1
(
5
5
-
S 7
1
SL
5
1
5 7) f 5
7
1 2
7.1
1
- 2 7.1
3.Sf-3
The I Operator (Absolute Value and Residue)
•
The monadic I
is~the
absolute value operator-.
R+IB
Domain Table:
I : I ~E
L
F
F
Examples:
2.15
2
•
4.3
1-2
S
4.3
7.2
S
7.2
The dyadic I is the residue operator.
H+-AIB
The result is B modulo A expressed as a nonnegative value; that is, the smallest nonnegative value R such
that R=B+n><A for an integer n.
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
I
I
F
I
DE
I
I
F
F
DE
F
F
F
j.
If A is zero and B is less than zero, DOMAIN ERR is reported. If A is zero and B is greater than or equal to
zero, B is assigned to R. DOMAIN ERR is also reported if the ratio of B to A or either value is too large for
meaningful modulo operation within the precision range used in computing real values.
60
SC(,I'.lr Operators
Examples:
2341575
122
3.216.57.417
0.1
1
1
The
•
0
Operator (Pi Times and Circular)
The monadic
is the pi times operator.
0
R+oB
The result is 3.141592653589793 times B.
Domain Table:
F
L
F
F
F
Examples:
01
3.141592654
02
.5
5.283185307
•
The dyadic
0
1.570796327
is the circular operator .
R+AoB
The value of A determines the computed function of B according to the following convention.
A
R
Domain of Bt
-7
-6
-5
-4
-3
-2
-1
0
Arctanh
Arccosh
Arcsinh
C1+B*2)*.5
Arctan
Arccos
Arcsin
(1-B*2)*.5
Sine
Cosine
Tangent
(1+B*2)*.5
Sinh
Cosh
Tanh
IB:<;1
h B:<;Max *. 5 tt
IB:<;Max*.5 tt
1:<;IB
1
2
3
4
5
6
7
Range of Rt
-18.36840028 to 18.36840028
88.02969193
-88.02969193 to 88.02969193
o to
- rr/2 to rr/2
IB:<;1
IB:<;1
IB:<;1
IB:<;7.074237752E 15
IB,,7 .07 4237752E 15
IB:<;7 .074237752E 15 ttt
IB:<;175.3662366
IB,,175.3662366
o to rr
-TI/2 to TI/2
1
-1 to 1
-1 to 1
-2.86708057EI5 to 1.146832228E16
o to
1 to Max
-1 to 1
tt
tThe domains of B and ranges of R are narrower than those theoretically possible. The limitations
reflect the precision with which real number data are represented and with which computations are
made in the computer.
tt Max = 7 . 237005577E75 .
Max *.5 = 8.507059173E37.
ttt
For tangent, DOMAIN ERR results if B is indistinguishable from an odd integer multiple of TI/2.
Scalar Operators
61
The value of B is in radians for the trigonometric functions.
For the inverse trigonometric functions, the value
of R is in radians. The domain of the result is always floating-point.
Examples:
1002
1.046360549t,'-n
304 5 li
1.157821282
3.380S15006
70.5
0.5493061443
0.2910061'31[1
Notice in the firsT example that the result (the sine of 2TT) :;hould actually be zero.
the effect of computing with approximately 16 decimal-place precision.
The actual result reflects
The ! Operator (Factor ia I and Combination)
•
The monadic! is the generalized factorial operator.
R+!B
The result is B factorial for nonnegative integral values of B.
function of B+ 1.
If B is not an integer, the result is the gamma
Domain Table:
C
B
I
R
I
L
F
DE
F
Examples:
!7
5040
! .66
0.9016683712
•
The dyadic
.75
0
3.625609908
1
is the genera Iized combination operator.
R+A!B
If the arguments are positive integers and A is less than or equal to B, the result is the number of combinations
of B things taken A at a time:
R=( !B)f(!A)x !B-A
The generalized form A!B is related to the Beta function as follows.
fBx(A-1) !A+B-1
Domain Table:
,
62
Sea lor Operators
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
I
I
F
I
DE
I
I/F
F
F
DE
F
F
F
)R
f3(A,B) is
Examples:
1!2
2
1. 5! 2
1.697652726
1.5!205
2.5
5! 52
2598960
Relational Group
The six relational operators are used to compare two values and (eturn a value of 1 if the relation is true or a value
of 0 if the relation is false. The truth value can be used in calculations in the same way asany other value of 1 orO.
The relational operators are strictly dyadi c, requiring a Ieft argument.
The
<
Operator (Less Than)
R+A<B
The result is 1 if (A-B)s-FUZZxIB, and is 0 otherwise.
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
3<3
2
I'
Examples:
2<4.5
1
1
100
2
1
The s Operator (Less Than or Equal To)
R+A5,B
The result is 1 if (A-Bl,,;FUZZxIB, and is 0 otherwise.
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
R
Scalar Operators
63
Examples:
1
~2
1
1
1
1
0
2
353
2
1
The ~ Operator (Equals)
R+A=H
The result is 1 if (IA-Bh;FUZZxIB if A and B are numeric, and is 0 otherwise. If A and B are characters, R is 1
where A and B are the same, and 0 where they are not. If one argument is character and the other numeric, Ris O.
Domain Table:
~
C
L
)
F
C
L
L
L
L
L
L
L
L
L
I
L
L
L
L
F
L
L
L
L
3=3
2 1
].
Examples:
1
2
o
1
0
"l'HIS':'THAT'
1
1
0
0
'A'=5
o
The" Operator (Greater Than or Equal to)
The result is 1 if (A-B»-FUZZxIB, and is 0 otherwise.
Domain Table:
~
C
L
)
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
Examples:
o
64
Scalar Operators
}.
The> Operator (Greater Than)
R+A>B
The result is 1 if (A-B»FUZZ)(IB, and 0 otherwise.
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
}.
Examples:
2>3.4
o
1
2
3>3
2
1
001
The
;<
Operator (Not Equal To)
R+A;<B
If A and B are numeric, the result is 1 if (IA-B»FUZZ)(IB, and is 0 otherwise. If A and B are characters, R is 0
where A and B are the same, 1 where they are not. If one argument is character and the other numeric, R is 1.
Domain Table:
~
C
L
I
F
C
L
L
L
L
L
L
L
L
L
I
L
L
L
L
F
L
L
L
L
.
}
Examples:
1
0
1 2 3 .. 3 2 1
1
0
0
1
'THIS';<'THAT'
1
'A' ;<5
1
~,
Logical Group
The five logical operators are used to perform logical operations, returning a result of 0 or 1.
ators are strictly dyadic, and the last (the "not" operator) is strictly monadic.
The first four oper-
Scalar Operators
65
The
II
Operator (And)
I
!I <-A liB
I
The result is 1 if A and B are both 1, and is 0 otherwise.
Doma~R-
Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
A domain error results if both A and B are not equal to either lor 0 (within FUZZ limits).
Examples:
1111
1
(1<2)11(3=4)
o
1
1
000
0
0111
0
1
0
The v Operator (Or)
H'-A vB
The result is 1 if A or B, or both, are 1, and is 0 otherwise.
Domain Tobie:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
A domain error results if both A and B are not equal ta either lor 0 (within FUZZ limits).
Examples:
1 vl
1
(1<2)v(3=4)
1
1
66
1
1
110
Scalar Operators
0
OVl
0
1
0
The,., Operator (Nand)
R+-A 1<B
The result is 0 if A and B are both I, and is 1 otherwi5e.
Domain Table:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
],
A domain error occurs if both A and B are not equal to either 1 or 0 (within FUZZ limits).
Examples:
o
(1<2)1«3=4)
1
1
1
1
Oil
The
'I'
0
01<1
0
1
0
Operator (Nor)
R+-A'IB
The result is 0 if A or B, or both, are 1, and is 1 otherwise.
Domain Tabl e:
~
C
L
I
F
C
DE
DE
DE
DE
L
DE
L
L
L
I
DE
L
L
L
F
DE
L
L
L
],
A domain error results if both A and B are not equal to either 1 or 0 (within FUZZ limits).
Examples:
I'll
~-
0
(1)2)'1'(3=4)
1
.1
0
0
0
1
1
0
0'11
0
1
0
Scalar Operators
67
The ~ Operator (Not)
The result is 1 if B is 0, and is 0 if B is 1.
Domain Table:
F
l
l
l
l
A domain error results if B is not equal to either 1 or 0 (within FUZZ limits).
Examples:
~1
o
-0
1
-(2.5-1.5)
o
Compos ite Operators
The three composite operators extend dyadic scalar operations to arrays. In the following descriptions of these
operations, the bracketed value K represents that coordinate of the argument array along which the specified operator is to act. If K is unspecified, the last coordinate of the array is assumed. The symbol d represents anydyadic
sca lor operator.
The dl Operator (Reduction)
R<-d/[K]B
The result is an array having a dimension vector equal to that of array Bexcept that the Kth component is not present.
If f is used instead of I, the first coordinate is assumed and [KJ may not be speci fi eel.
For a vector argument, the value of the result is that produced by placing the operator d between each pair of adjacent components of vector B. A minus reduction results in an alternating sum and a divide reduction results in an
alternating product.
For a scalar or an array comprising a single component the result has the same value as B.
result has the value of the identity element of operator d, as shown in the table below.
d
Identity
Element
x
1
+
0
1
-
0
*
1
v
0
None
None
0
/\
1
'"
None
I
e
0
68
Composite Operators
Comment
d
¥
Right identity only.
Right identity only.
Right identity only.
left identity only.
Identity
Element
1
r
Minimum
Maximum
0
1
0
1
>
~
<
5:
Comment
None
:
L
For an empty array the
::
1
>'
0
left identity only.
-7.237005469E75
7.237005469E75
Right identity only.
Right identity only.
left identity only.
left identity only.
Domain restrictions fur operator d apply. If B includes more than one element, the domain of the result is the same
as indicated in domain tables for the dyadic scalar operators.
Examples:
O+R++/2 4 6 8
20
O+R+-/2 4 6 8
4
O+R+!/10
10
A+2 4p l8
A
1
3
7
2
6
5
4
8
+/A
10
26
+fA
6
8
10
12
+/+/A
36
B+2 3 4p 124
B
1
5
9
2
6
10
7
11
4
8
12
13
17
21
14
18
22
15
19
23
16
20
24
3
+/B
10
58
26
74
42
90
+/[2]B
15
51
18
54
21
57
24
60
18
26
34
20
28
36
+fB
14
22
30
16
24
32
+/+/B
222
+/+/+/B
78
300
+/,B
300
4 p1 1 1 0 1 1 0 0 1 0 0 0
C+3
C
/---',
1 1 1 0
1 1 0 0
1 0 0 0
A/C
0
0 0
AfC
1
0
0
0
Composite Operators
69
The d \ Operator (Scan)
R+d\[KJB
The result has a dimension vector the some as that of B.
and r KI may not be specified.
If' is used instead of\, the first coordinate is assumed
For a vector argument, the result will be a vector of the samo length with values as follows:
R[1 ]+8[1]
R[2]+B[1] d B[2]
R[3]+B[1] d Rr2] d B[3]
Thus the last component of the result will equal d/B.
For a scalar or a one-component array, the result is the some as B. For an empty argument, the result will beempty.
Domain restrictions for operator d apply. If B has more than one element, the result domain is that indicated in the
domain table for d.
Examples:
+\1 3 5 7
9
16
+\-5 0 7 0 1
5
2
2 3
5
-\3 9 5 1
3
6
1
2
"\1 2 3 4 5
24 120
1
2 6
*\1 2 3 4 5
1 0.5 1.5 0.375
~\7 9 5
4
7 1
0 0
.
1
-
1.875
Scan generalizes to higher ranked arguments in the some way reduction does, by doing the operation along the k'th
coordinate as shown by the example below:
8+2 3 4
\24
p
B
9
2
6
10
3
7
11
12
13
17
21
14
18
22
15
19
23
16
20
24
3
7
11
4
8
12
18
26
34
218
:?
3
8 10
18 21
20
28
36
1
5
4
B
.. \8
1
5
9
14
22
30
1
6
15
13
30
51
1
5
9
13
17
21
70
2
6
10
16
24
32
.. \ [
4
12
24
14
32
54
.. \B
3
11
19
15
34
57
16
36
60
G
18
30
10
26
42
27
35
43.
42
54
66
58
74
90
Composite Operators
----~
The d.d Opelltor (Inner Product)
~
The result is an array having a dimensian vector equal to all except the last dimensian of array A catenatE~d with
all except the first dimension of array B. The dimension of the last component of A must be the same as that of the
first component of B, or one of those dimensions must be 1. The domain of the result is indicated by the operators d 1
and d 2 . Operators d 1 and d 2 may be any dyadic scalar operators. For example, R-<-A+.xB gives the conventional
matrix inner product.
For vector arguments, the result is
For example:
4+.x56
224
+/4"56
224
1 2 3+.x4 5 6
32
+/1 2 3x4 5 6
32
1 0 1 0+.A1 1 0 0
1
0 1 0+.v1 1 0 0
3
-~
If A is a vector and B a matrix, the Ith component of the result is
For example:
A+2 4
B+2 4p3 2 6 8 5 4 9 4
B
268
549 4
A+. xB
48 32
26
20
3
B[;l]
3
5
2
4
6
9
8
4
B[ ; 2]
B[; 3]
B[ ; 4]
+/A x 3
5
26
+/Ax2 4
20
+/Ax6 9
48
+ / A xB[ ; 4]
32
42
68
12 3+.!3 3Pl9
102
Composite Operators
71
If A is a matrix and B is a vector, the Ith component of the resull is
For example:
C+1 2 3 4
B+.xC
57
56
B [1; ]
2
3
6
B
B[2;J
5
4
9
4
+/B[i;JxC
57
+/B[2;J x C
56
For matrix arguments, the JiJth component of the result is
For example:
4pIB)+.x4 2Pl8
(2
50
114
60
140
X+3
3p 'CANDIDATE'
Y+3 3p'DRAMATIZE'
XII.=Y
0 0 0
0 0 0
0 0 1
X
CAN
DID
ATE
Y
DRA
MAT
IZE
Xv. =Y
0 1 0
1 0 0
0 0 1
XII
.~Y
1 0 1
0 1 1
1 1 0
72
Composite Operators
Inner product also applies to higher order arrays. For the example below, the arguments are each three dimensional
and the result has four dimensions. The IiJiKiLth element of the result is +/AUiJiJxB[;KiLJ
/-------,
A+2 2 3pl12
A
1
4
7
10
2
5
3
6
13
15
8
9
11
12
O+B+3 2 2p12+t12
14
16
17
19
18
20
21
23
22
24
A+. xB
110
122
116
128
263
293
278
308
416
464
440
488
569
635
602
668
+IA[l;l;]xB[;l;l]
~
110
+IA[1;1;]xB[;1;2]
116
+IA[1;2;]xB[;2;2]
308
The o.d Operator (Outer Product)
R+A 0 .dB
The result is an array having a dimension vector equal to that of A catenated with that of B. The scalar dyadic
operation d is performed for each. component of A with respect to all components of B. The domain of the result
is determined by the rules for the operator d.
For vector arguments, the IiJth component of the result is
AU]dB[J]
For example:
1
2
3
1 2 3 o .xl 2 3 4
234
4
6
8
6
9
12
Composite Operators
73
Outer product is valid for arguments of higher rank.
of the result are defined by:
R[I;J;K;L;MJ
is
If, for example, A has rank 3 and B has rank 2, the elements
A[I;J;KJdB[L;MJ
Mixed Operators
Operators not categorized previously as monadic or dyadic scalars or composite operators are called mixed operators.
Rules for shapes and domains of the arguments and results vary and are described for the individual operators.
The? Operator (Rolland Dell)
•
The monadic? is the roll operator.
R+?B
B must be in the integer domain (maximum value of 2, 147,483,647). Each element R[I] of the result is an integer
selected pseudorandomly from lB. The range of the resul r depends on the value of the index origin (see the deal
opera tar below). The shape of the result is the same as that of the right argument.
Examples:
?5
4
1
4
3
3
?2 4 6
5
?3 3 3 3
3
2
The dyadic ? is the deal operator.
•
R+A?B
The result is a vector of integers comprising A components pseudorandomly selected from lB withoutmplacement,
preventing the duplication of integers in R. The range of the result depends on the index origin. If the origin
is 0, the range is 0 through B-l. If the origin is I, the range is 1 through B.
A may not exceed B, and both must be single numeric elements.
Examples:
2?4
1
2
4
236
6 ?6
5
1
A[4?aJ;A+l0 20 30 40 50 60 70 ao
30
The
l
•
The monadic
60
40
80
Operator (Index Generator and Index Of)
1
is the index generator operator.
R+lB
B must be a single numeric element, within FUZZof an integer. The result is a vector comprising B components,
beginning with the index origin and incremented monotonically by 1. Normally the index origin is 1, but the
command )ORIGIN 0 can be used to change the origin to O. If B is 0, the result is the empty vector.
74
Mixed Operators
Examples:
1
O+R+t4
::J
4
2
)OR!fGIN 0
WAS
o
•
The dyadic
I
1
....
O....R+t4
2
3
is the index of operator.
R+A IB
The v.alue of each element of the result is the smallest inde.,< I such that A[J] equals the corresponding element
in B. The left argument must be a vector. The right argument may have any rank. If no match for an element
of B is found in A, then that element of the result is set to' + I'. , •.. The shape of the result is the same as the
shape of the righf argument. The result is in the integer domain.
Note that A may be an empty vector but must not be a scalar, and the value of the result depends on whether the
index origin is 1 (the default case) or O. A and B may be of any domain. Note, however, that if A is character
data, for example, and B is numeric, the result will be entirely "no match" values.
Examples:
2 4 6 813
5
'XYZ't'W'
4
'DOG'I'COT'
4
2
4
The, Operator (Ravel, Catenation al'd tamil_tion)
•
The monadic. is the ravel operator.
R+,B
The result is a vector comprising the components of the argument B in index sequence.
any shape and dimensions.
The argument can have
Examples:
;\I
B+2 2pl4
B
2
4
1
.. 3
,B
1
2
3
4
O+C+24p'SIGMASIX'
SIGM
ASIX
,C
SIGMASIX
•
The dyadic, is the catenation and lamination operator.
R+A,B
If A and B are vectors or scalars, the result is a vector comprising all components of A followed by all components
of B. Both A and B must be ei ther numeric or text.
Mixed Operators
75
Examples:
A+1
2 3
8+4 5 6
A,B
1
2
3
4 5
C+'STR'
6
D+'AND'
C,D
STHI. ND
Catenation - If A and B have conformable shapes and one or both are of higher rank than vector, catenation
joins A and B along an existing coordinate. If no coordinate is specified, catenation occurs along the last
coordinate. Scalar arguments are extended for catenation in this case.
Examples:
O+M+4 7p'M'
MMMMMMM
MMMMMMM
MMMMMMM
MMMMMMM
X+2 7p'X'
Y+ '123'f567'
Z+'1234'
W+'o'
M, [1]X
MMMMMMM
MMMMMMM
MMMMMMM
MMMMMMM
XXXXXXX
XXXXXXX
M, [1]y
MMMMMMM
MMMJ.dMMM
MMMMMMM
MMMMMMM
123 /j567
M, Z
MMMMMMM1
MMMMMMM2
MMMMMMM3
MMMMMMM4
M,[1]W
MMMMMMM
MMMMMMM
MMMMMMM
MMMMMMM
0000000
M,W
MMMMMMMo
MMMMMMMo
MMMMMMMo
MMMMMMMo
Lamination - If a noninteger coordinate value is indicated in catenation, and its value, relative to current
origin, is within 1 of a valid coordinate, the operation performed is termed lamination. In this case the variables A and B are joined on a new coordinate. The length of the new coordinate is always 2.
In the following examples, origin is 1. If a coordinate of zero or less, or three or more, were specified, RAN K
ERR would be reported.
76
Mixed Operators
Examples:
M,r .5JW
MMMMMMM
MMMMMMM
MMMMMMM
MMMMMMM
0000000
0000000
0000000
0000000
M,[1.25]W
MMMMMMM
0000000
MMMMMMM
0000000
MMMMUMM
0000000
MMMMMMM
0000000
lvI, [ 2 • ::J ] Iv
Mo
Mo
MO
Mo
Mo
Mo
Mo
Mo
Mo
Mo
Mo
Mo
Mo
Mo
Mo
Mo
MO
Mo
Mo
;-10
Mo
Mo
Mo
Mo
Mo
MO
Mo
Mo
pM
4
7
2
4
pM, [ • 5] W
7
pM,[1.5]W
4
2
7
pM.[2.5jW
4
7
2
The p Operator (Dimension and Reshape)
•
The monadic
p
is the dimension operator.
R+-pB
Mixed Operators
77
The resultis an inh"gervector comprising the number of components each index ofB contains. That is, R: contains
the highest index in each coordinate of B. Thus, the expression 00B, represents the rank of B, assuming an index origin of 1. If B is a scalar, pB results in the empty vector.
Examples:
1l+2 4
pB
(7+2
6
8
3p 'PI!'PLE'
pC
2
•
3
The dyadic p is the reshape operator.
R+ApB
The result is an array of the dimensions specified by vector A and the contents of B, if any, in index sequence.
Elements of A may be positive integers or zero. If any component of A is zero, R is empty. If A is empty, R is
a scalar. If B is empty, it may not be reshaped except to an empty result. If the reshape requires fewer elements than B contains, only the required elements are in the result. If the result requires more elements than B
contains, B is reused as required. B may be of any rank or domain.
Examples:
2p3
3
4 5 6
4
2
4p\5
123
5
1
2
4
3
The $ Operator (Reversal and Rotation)
•
The monadi c ~ is lhe reversa I operator.
The resul t is a reversal a long the Kth coordinate of B. If K is omi tted, the last coordinate is assumed. (If e
is used instead of~, the first coordinate is assumed and r KJ may not be specified.)
Examples:
<jJ 'EMIl' ,
1'1 ME
¢[ 1]3 3p \ 9
7
4
1
8
5
2
3
2
6
9
5
9
6
3
<jJ3 3p 19
•
8
1
4
7
The dyadic ~ is the rotation operator.
R+A¢[KJB
The result is a cyclic rotation of B by the number of components determined by A. If A is positive, rotation is to the left; if A is negative, rotation is to the right.
Rotation is performed along the Kth coordinate
of B. If K is omitted, the last coordinate is assumed. (Ife is used instead of~, the first coordinate is assumed and [KJ may not be specified.)
78
Mixed Operators
Examples:
3cj)'LEAP'
~'.
PLEA
2cj)3 '+pl12
'+
1
2
8
5
6
12
9
10
-11jl3 '+pl12
1
2
3
5
6
7
9
10
11
193 '+pl12
6
7
8
10
11
12
2
3
'+
3
7
11
'+
8
12
5
9
1
The it Opemtor (Tmnsposition)
•
The monadic transposition operation has the following syntax.
The resu It is an array compnsmg the elements of B with the order of all coordinates reversed. For any
B, (p <j> B) =<,¥pB. If B is a matrix, for example, the result is a matrix whose rows are the columns of Band
whose columns are the rows of B. Monadic transpose of a scalar or vector yields R+B.
Examples:
O<-A+3
5p'AGENTVIGORAGONY'
AGENT
VIGOR
AGONY
~A
AVA
GIG
ZGO
NON
TRY
1
5
9
0+B+2 3 '+p( 112).100+112
2
3
It
7
8
6
10
11
12
101
105
109
102
106
110
103
107
111
10'+
108
112
p~B
'+
2
3
IQB
9
101
105
109
2
6
10
102
106
110
3
7
11
103
107
111
'+
8
12
10'+
108
112
1
5
Mixed Operators
79
•
Dyadic transposition operations have the following syntax.
R+A~J3
The result is an array similar to B except that the coordinates of B are permuted according to A.
shape of A and B must be related by
The
(pA)=ppB
There are two cases of dyadic transposi tion:
Case 1: A is a permutation of lppB (the coordinates of B). A is then described as the inverse permutation
vector. The A[)Jth component of pR is the Ith component of pB, and thus the A[JJth coordinate of
the result is the Ith coordinate of B. Examples:
2 111/2
1
3P16
4
5
6
2
3
3 2
1~2
2
ER
SI
3p'EXASPERATION'
XA
PO
AT
EN
Case 2: A satisfies the relationship (tr/A)e:Aj that is, A is a dense set of the first k coordinates of B, permuted, with some coordinates duplicated. If B is a matrix, the only possible form for A is (1 I), and
the result is the principal diagonal of the matrix. Example:
O+X+3 3p'GETEARTRY'
GET
EAR
TRY
1 ill/X
GAY
If B has rank 3 or mare, the rule is that the rank of R equals the highest value in A. If 1<+Am=A and
N+ (A[I]e:A)/lpA, then the A[N[IJ] th coordinate of R is made up of those components of B whose Nth
coordinate indi ces are the same. All other coordinates of the result are structured as in Case 1.
For higher order arrays, the generalized "diagonal" case of dyadic transpose is varied and somewhat
difficult to visualize. The examples below show some forms for Case 2:
Z
ABeD
EFGH
IJKL
MNOP
QRST
UVWX
pZ
2
3
4
A+l- 1 11!/Z
A
AR
pA
2
80
Mixed Operators
Examples: (cont. )
B+l 2 21S/Z
B
.~~
AFK
MRW
pB
2
3
C+2
C
AM
FR
KW
1 ll5!Z
pC
2
3
D+2 1 2l5!Z
D
AN
ER
IV
pD
3
2
E+l 2 ll5!Z
E
AEI
NRV
pE
2
3
F+2 2 l/s1Z
F
AQ
BR
CS
DT
pF
4
2
G+l 1 2l5!Z
G
>~
ABCD
QRST
pG
2
4
X+2 3 4 Spl120
1 1 1 ll5!X
1
87
1
86
1
2
3
4
5
1
81
1
7
13
19
1 1
2
87
2 2
86
87
88
89
90
1 1
7
87
2 2
81
87
93
99
1 2
1
2l5!X
3
4
88
89
2 ll5!X
5
90
2 2/s1X
13
19
93
99
1 ll5!X
2
3l5!X
1
26
51
2
27
52
3
28
53
4
29
54
5
30
55
61
86
111
62
87
112
63
88
113
64
89
114
65
90
115
~
Mixed Operators
81
Examples: (cont. )
1
26
51
3 2 2 16:?X
61
86
111
2
27
52
62
87
112
3
28
53
63
88
113
4
29
54
64
89
114
5
30
55
65
90
115
lila +O,.ratu (Grall. Up)
R~4.B
The result of the grade up operation is a vector of indexes (relative to the index origin) of components of 8 ranked in
ascending order of magnitude. 8 is a numeric vector. Identic(!1 components are ranked in index order. Note that
the result of 8[4.8J is a "sort" of 8 in ascending sequence. Thus, "grade up" provides indices for sorting.
Examples:
1
2
1
2
2
4
.5 10 15 20
3 4
.5 10 10 15
3
4
.3 1 4 1
3
1
The;- Operator (Grade Dawn)
R~VB
The result of the grade down operation is a vector of indexes of components of 8 ranked in descending order of magnitude. 8 is a numeric vector. _Identical components are ranked in index order. The values of the result
depends on the index origin. (8["'8] is a "sort" of 8 in descending sequence.)
Examples:
4
3
4
2
3
1
V5 10 15 20
2 1
':5 10 10 15
3' 1
'f3 1 4 1
2 4
lhe 1 Operator (Base Value or Decade)
R~AJ.B
The argument A is referred to as the radix or radix vector. If A is a scalar, it is conceptually expanded to a
vector. A and 8 must be numeric, and R is numeric.
82
Mixed Operators
The argument A is used internally to generate a set of weights, W, to operate on B as follows.
of B. Then:
Let I be the length
W[I]+l
WrI-1]+A[I]xW[I]
W[I-2]+A[I-1]xW[I-l]
W[ 1] +A [ 2 ] x W[ 2 ]
Note that Am has no effect on the result.
Example:
A+O
is
is
is
W[3]
W[2]
W[]J
MJ
1
6O.L1
2
3
lxA[3], or 60
W[2]xA[2], or 3600
The result is formed by W+. xB:
WxB
A
!~~~
3600
is
is
3723
If A is a vector and B is an array, eTA must be the same as the length of the first coordinate of B. If
for example, B must have the same number of rows as the length of A. Each column of B is decoded
element of the result. If A is also an array, each row of A represents a different radix vector. The
the catenation of the shape of all but the last coordinate of A with all but the first coordinate of B.
for A, B, and R are the same as for inner product. )
B is a matrix,
to provide one
shape of R is
(Structure rules
Examples:
2.11 0 1 1
11
4.13 2 1 0
228
10.19 8 7
987
1 2 3.145 67 89
560
A
A
K IS A TABLE OF TIMES REPRESENTED IN DAYS(ROW i),
HOURS(ROW 2),MINUTES(ROW 3),AND SECONDS.
K
o
o
o
0
0
0
1
11
0
0
2
3
13
1
16
46
46
46
40
40
40
40
40
A EACH COLUMN OF K REPRESENTS A TIME VALUE.
10
A
10
IF K IS OPERATED ON BY THE 'BASE VALUE' OPERATOR,
SECONDS.
A THE RESULT IS A VECTOR OF TIMES IN
A THE RADIX VECTOR IS-- 365 24 60 60
365 24 60 60.1K
100
1000
10000
100000
1000000
The T Operator (Rlpresenlltion or Encode)
R+ATB
R is a "base A" representation of B. R satisfies the relationship ((x/A)IB-AJ.R)=O. A and B must be numeric, and R
is numeric. Note that the T and J. operators are "opposites". Note also that since Encode carries out a modulus
operation, it is subject to the DOMAIN ERR conditions for that operation.
Mixed Operators
83
If vector A contains too few elements for B to be represented, the most significont digits of the result are truncated.
If AU] is 0, any unencodable portion of B will be displayed as R[l] rather than being truncated. Note that A and
B may be negative or noninteger values. In this case the result is as well defined but not as intuitively clear as for
positive integer values.
B may be an array rather than a scalar, and the dimension of the result will be the catenation of the shapes of the
arguments. (The structure rules for R, A, and B are the same as for outer product.)
Examples:
A
BINARY REPRESENTATION
(8p2)T75
01001
011
A
OCTAL REPRESENTATION
(3p8)T75
113
A
3
DECIMAL REPRESENTATION
(5p10)T31415
4
1
5
1
A
VARIED UNIT REPRESENTATION
24 60 60T75432
57
12
20
A
EXAMPLE OF TRUNCATION
10 10T31415
1
5
A
1
THE ARGUMENTS FOR REPRESENTA'],ION NEED NOT BE INTEGERS:
(8p1.5)T32.75
0.5
1
0
0 0.5
A
0
1.25
H IS A VECTOR OF TIME VALUES IN SECONDS.
H
10
100
A
o
o
o
10
1000
10000
365 24 60 60TH
0
0
0
1
0
0
2
3
1 16
46
46
40
40
40
40
A
A
A
100000
1000000
H CAN BE ENCODED IN TERMS OF DAYS ,HOURS ,MINUTES , AND SECONDS.
11
13
46
40
IN THE RESULT, EACH COLUMN REPRESENTS ONE ELEMENT OF H.
ROW 1 IS DAYS, ROW 2 IS HOURS, ROW 3 IS MINUTES, AND ROW 4 IS
SECONDS.
The / Operator (Compression)
R+-AI[K]B
The result includes all components of B that correspond to a 1 in A. Those corresponding to a
either argument is scalar, it is applied to all components of the other operand.
°
are suppressed. If
Compression is performed along the Kth coordinate of B. If K is omitted, the last coordinate is assumed.
used instead of I, the first coordinate is assumed and [KJ may not be specified.)
(If I is
A may be a logical scalar or vector, and B may be of any rank or domain. If A consists of more than one element,
its length must be the same as that of the coordinate of B being compressed.
Examples:
B+-2 2P14
1 OIB
1
3
84
Mixed Operators
The \ Operator (Expansion)
R-+-A\[KJB
A must be a vector of l's and D's and must include the same number of l's as the length of the coordinate 1"0 be expanded. B may be of any rank and domain. Expansion occurs along the Kth coordinate of B. If K is omitted, the
last coordinate is assumed. If, is used instead of \, the first coordinate is assumed and [K] may not be specified.
Thus the difference between \ and, is
R+-A \ B expands along the last coordinate of B.
R+-A,B expands along the first coordinate of B.
Expansion consists of extending the length of the affected coordinate of B by insertion of zeros (or blanks if B is
text) in pasitions indicated by zeros in the argument A. The process is best described by example.
1
1 0 1 0 1\13
203
0
THE FOLLOWING EXAMPLES SHOW EXPANSION ON EACH OF THE
COORDINATES FOR A RANK 3 ARRAY,
B-+-2 2 2P18
1 0 1,B
A
A
1
3
2
4
o
o
0
5
7
6
8
1
o
2
0
3
4
5
6
0
8
0
1 0 1\[23B
o
7
1 0
1
l\B
2
3
0
0
4
5
7
0
0
6
8
A-+-2 2 2p'ABCDEFGH'
1 0 1,A
AB
CD
EF
GH
1 0 1\[2]A
AB
CD
EF
GH
:l
0 l\A
A B
C D
E F
G H
Mixed Operators
85
The
t Operator (Take)
R+AtB
A must be an integer scalar or vector, and the Iength of A must equal the rank of B! Each element
"take" from a coordincte of B. R has the same rank as B. The dimension vector of R is IA.
0
f A controls the
If A[IJzO, then the Ith coordinate of R is the first A[IJ elements of the Ith coordinate of B. If A[I]<O, the last Am
elements are used. If AUJ indicates more elements than are present in the coordinate of B, R is padded with O's
(or blanks if B is text).
Examples:
3
4
1
2
3t15
5
7h5
3
4
5
0
0
B
2
4
1
3
5
6
7
8
1
3
2
4
1
2
3tB
0
0
The t Operator (Drop)
R+A4-B
A must be an integer scalar or vector, and the length of A must equal the rank of Bt. Each element of A controls
the "drop" from a coordinate of B. R has the same rank as B. The dimension vector of R is {pB)-IA. If a dimension
in the result thus created would be negative it is set to zero.
If A[lJ20, then the Ith coordinate of R is all but the first Am elements of the Ith coordinate of Bi that is, the
first A[IJ elements are dropped. If A[IJ<O, the last Am elements of the Ith coordinate of B are dropped.
Examples:
34-15
1
2
4
5
34-15
B
1
3
5
7
2
4
6
8
1 2 24-B
2 2 HB
(Note: Result may be an empty array)
1 1 HB
8
t If B is a scalar it is treated as ,though it were a 1 element array whose rank is the length of A.
86
Mixed Operators
The
•
E
Operator (Membership and Execute,
The dyadic
is the membership operator.
E
R.... AEB
If a given component of A is contained in B, the corresponding component of R is equal to 1; otherwise, it is O.
The result has the same shape as A and is in the logic domain. B may have any rank. If A and B are numeric
FUZZ is used in the equality test.
I
Examples:
A.... 'ALPHABET'
B.... 'ABCDE'
C.... 2 4pt8
A€B
1
0
0
0
1
110
1 5 10€C
110
ANOTE THAT MEMBERSHIP MAY BE USED WITH NUMERIC VERSUS
TEXT ARGUMENTS--THE RESULT IS ALWAYS ZEROS.
A
A€C
000
0
0
0
0
0
C€A
000 0
o 0 0 0
1 2 3€'1 2 3'
000
•
The monadic
E
is the execute operator.
R.... €B
B must be a scalar or vector whose length does not exceed 512. The domain of B must be character type unless B is
an empty vector. Ordinarily, the argument B will be a small text vector.
Once the argument has met the above requirements, an execute operator departs from the mold of the other operators.
An execute operation becomes a variation of evaluated input. That is, the characters in its argument, if any, are
treated much as if they were input after an eva I uated input prompt.
Thus, it is possible to execute system commands within a function or even in the midst of an arithmetic expression.
Execute operations can be applied so that an APL workspace can define or revise functions, create its own variable
names, or compose new formulas and evaluate them.
The execute operator is a powerful tool. It can, however, be costly in execution time. The cost stems from the
translation process when accepting its argument as if freshly input. This translation is repeated each time the same
execute operation is performed; a function line, on the other hand, is translated only once regardless of the number
of times it is invoked. Thus, 'execute' should be used sparingly in iterative or recursive processes.
As stated previously, the execute operator permits formula evaluation, function definition, or system command
execution in the midst of an arithmetic expression. As with evaluated input, the. esult of (;xecuting a formula is
the value resulting from evaluating that formula. The following examples illustrate this:
€'
2+2'
e'Z .... 2+2'
e'"AB'''
AH
3+e '2+ 2'
7
X.... ' 2+'
Y""'2'
3+t:X .1
7
Note: Since branching is not permitted in evaluated input, the form
t'
-n'
is not allowed.
-,: '.'!' is permitted.
Mixed Operators
87
Executing an empty vector yields an empty (numeric) vector result.
o
o
An empty numeric vector also results when executing most system commands.
f3.~I)DIGITS
4
1
;,AS 10
0.3333
As far as the execute operation is concerned, a system command either yields an empty result or it yields no result
whatsoever. For example, the following commands yield no result: )OFF, )OFF HOLD, )CLEAR, and )LOAD.
Also no result occurs when executing a suspension-clear. This corresponds to the use of a suspension-clear during
evaluated input. As illustrated below, the state indicator has the same appearance for an execute operation as for
evaluated input.
l~
.IJ
lJ:
)S1
LJ
*
FUNX[2]
[J:
10
4
4 •(
LJ
PUNX[2J
4
Ii
U:
1
)8I
1
*
.lJ
-+
)5I
PUiiX[2]
*
6.~1-+1
)::I
FU!!X[21
*
The execute operator can also be used to access function definition mode, but certain limitations are imposed. A
basic limitation exists since only one "statement" (text string) can be the argument of an execute operator. This
means that if a function is opened by such a statement it must also be closed by the same statement. In other words,
only "single-line" function definition operations are possible with the execute operator. (All or any portion of a
function can be created or revised by utilizing multiple execute operations.)
To enter function definition mode via an execute operator, the operator's argument (text vector) must have a del
(or locked del) as its first nonblank character. Since only single-line definitions are possible, APL does not
require the closing del. However, the argument can include a closing del if the user so desires, except on line
deletions. (The line deletion feature is described below). As usual for function definition, the opened function
cannot be locked or pendant. This means that a function cannot modify itself, since the function is pendant when
it performs an execute operation. It is possible for one function to modify another.
An execute operation produces a result, if successful. The result of executing function definition mode is always
an empty integer vector. This is the same result produced when executing system commands.
If an error (for example, DEFN ERROR) is detected during an "executed" function definition, the original definition
remains intact with one exception; SI DAMAGE errors perform the revision dictated by the execute operator's argument. In all other error cases, the function is not changed.
Executing function definition mode consumes substantial execution time. When can this capabi I ity be used to
best advantage? The optimum candidate for an executed function revision is a highly iterative or recursive
function. Based on initial conditions (or input supplied by a user), a new function line can be embedded in the
heart of a loop. The time consumed in making the change can be inconsequential if this allows the loop to run
88
Mixed Operators
faster than would have been possi ble without the functi on change capabi I ity. The primary characteristi c to watch
for is a very repetitive loop containing a process that may vary for different runs of that loop.
The ability to enter function definition mode via an execute operation is not limited to revising a function line.
Any definition statement that could include an opening and closing del can also be used as the argument of an execute operator. This covers every defi niti on statement except those that allow deleti ng a line or edi ting characters
of a line. An APL program can effectively edit characters of a line by altering the argument of an executed replacement line. Line deletion is easily accomplished by catenating the INDEX character to the line number designation
(see example below).
Simple examples illustrate various features of executed function definition mode.
in the examples is optional except for line deletion, where it must be omitted.
Note that the closing del shown
Function Creation
VF X V'
VF'[ 1 JX+X V'
€' VF[ 2]X-X V'
€'
€'
Line Replacement
10'
vF[2]XtXV'
Li ne Insert ion
10'
VF[1.5]XxXv'
Display All Lines
VF[[J]
10 '
V
F X
[1]
X+X
[2]
XxX
[3]
v'
XfX
'V
Display Starti ng at Line 2
10' VF[02]
XxX
XH
[2]
[3]
v'
Display Old Line and Replace
€ ' VF[2lJJX*XV'
XxX
[2]
.J
Display Single Line
€'
VF[ 2U] V'
X*X
[2]
Line Deletion
INDEX+2T32
€ ' IlF[ 2 J ' ,INDEX
To verify the deletion, the function is displayed below
,F[U] V
11
F X
X+X
[1]
[2]
XtX
Ii
Mixed Operators
89
tv10difi cation of a Character in a Line
A+-' liF'["2]X-X'
E:A
VP[llJ'Y
'Y P X
X+X
X-X
[lJ
[2]
V
11 [ (; ] +- , Iv
£A
W[lJ] 'Y
V F X
X+X
iv-X
'
'\
The foregoing discussion indicates things that can be done using the execute operator. Things that cannot be done
include
•
An executed argument cannot contain an unbalanced quote mark (the error message "OPEN QUOTE" is issued
in such cases).
•
The executed argument cannot translate into a "super long" line (despite the fact that the argument can contain 512 characters). If the translated "input" exceeds 130 columns, the "TRUNCATED" error message is issued.
Error handling is unique in the case of the execute operation. Recall that for evaluated input, the user is prompted
to reissue a correct version of the erroneous input. This is not possible for an execute. Furthermore, the argument of
one execute operator may contain another, and so on. For the sake of clarity in such cases, after a diagnostic
message (such as "DOMAIN ERROR "), the path leading to that diagnostic is displayed until a normal suspension
point is reached. The following example illustrates error handling during an involved execute operation.
'YZ+-Y F X
[1]
[2]
[3]
[4]
[5 J
A+' Y+ '
8+-' X'
C+ltA,B'
Z+100+E:C
\'
5 P 4
109
F 'FOUR'
5
DOI·fAIN ERR
Y+X
A
t:A,8
A
F[4]
Z+100+t:C
A
The Ii! Operator (Matrix Inversion and Matrix Divide)
This operator is used to solve systems of linear equations and to invert matrixes. The monadic form is equiva lent to
the dyadic form with an identity matrix as a left argument, and the operation can best be explained in terms of the
dyadic form. The right argument must be a matrix with at least as many rows as columns; that is, l=p:jpB). The
first coordinate of the left and right arguments must have the same length; that is, (ltpA) = ltpB. A vector argument is treated as though it were a one-column matrix, and a sea lar is treated as though it were a one-by-one
matrix, in terms of validity tests and computations. The shape of the result is (pR) = (liPB). Note that if A or B
is a vector or scalar, the true shape is used to determine the shape of the result. For example, if A is a scalar and
B is a 1 element vector, R is a scalar. R+-AIilB produces R such that the expression +/(,A-B+. xR)*2 is minimized, that
is, a least-squares solution (or solutions) to a system (or systems)of linear equations.
If B is a nonsingular square matrix, the minimum is (except for computational round-off errors) zero, and R is the
solution of a set of simultaneous equations. If, in addition, A is an identity matrix, R is the inverse of B. That is
90
Mixed Operators
equivalent to R<-[~B. If A is a vector, R is the solution to one system of simultaneous eCjuations. If A is a matrix,
each column of A represents the constants for a linear system with coefficient matrix B, and each column of R is the
corresponding solution.
If B is nonsquare, the minimum of +/(,A-B+. xR)*2 is not generally zero, and R represents a solution in the leastsquares sense.
If B is singular, that is, has fewer linearly dependent rows than columns, SING ERR is reported.
If B is nonsquare and A is an identity matrix, the result is a left inverse of A and the operation is equivalent
to R<-lllB.
Examples:
AINVERSE OF A SQUARE MATRIX
0+B+3 3p3 1 4 1 5 9 2 6 5
314
159
265
[J+R+ffJB
0.3222222222
0.1444444444
0.04444444444
0.2111111111
0.07777777778
0.1777777778
0.1222222222
0.2555555556
0.1555555556
)DIGITS 5
WAS 10
VERI FY THAT THE INNER PRODUCT OF RAND B IS
AESSENTIALLY THE IDENTITY MATRIX
P.
R+.xB
1.0000EO
5.5511E-17
6.9389E-17
6.9389E-17
1.0000EO
5.4991E-16
6.6613E-16
4.4409E-16
1.0000EO
ALEFT INVERSE OF A NONSQUARE MATRIX
3
1
2
3
8
1
5
7
5
7
[J+8+5 3p3 1"4 1 5 8 2 7 4 3 5 9 8 7 6
4
8
4
9
6
O+R+OOB
0.074106
-0.10492
0.061261
-0.082157
0.011612
0.06862
-0.072245
0.17084
0.073814
0.015323
-0.048546
0.085902
0.13129
0.013386
-0.04531
AAGAIN, VERIFY THAT THE INNER PRODUCT OF RAND B IS
ATilE IDENTITY MATRIX
R+.xB
4.1633E-17 -1.2490E-16
1.0000EO
1.0000EO
1.6653E-16
1.2490E""16
1.0000EO
-1.5266E-16 -3.8598E-16
ASOLUTION OF A SINGLE LINEAR SYSTEM
B IS TIlE COEFFICIENT MATRIX
A
A IS THE VECTOR OF CONSTANTS
A
0+B+3 3p3 1 4 1 5 9 2 6 5
314
159
265
O+A+35 89 79
35
89
79
O+R+AIiJB
2.1444
8.2111
5.0889
Mixed Operators
91
Examples: (cont.)
RVl!..'HIFY
(B+.)(8) APPROXU'ATFLY=A
~"JIAT
A-B+.)(R
2.4869E-14
1.0G58E-14
7.1054E-15
AJOLUTION OF A SET OF LINEAR SYSTEMS
A
B IS A COEPFICIENT MATUI X.
A
A IS A lJATRIX; EACH COLUMN IS A SET
A
OF CONSTANTS FOR B.
A
l!..'ACH COLUMN OF R. WHl eli IS A MATRIX. IS
A
TION FOR TJIE CORRESPONDlNG COLUMN OF A.
THE
SOLU-
U·-A+3 2p35 36 89 88 79 75
3G
35
89
8E1
75
7']
R+-AOOB
R
2.1444
8.2111
5.0889
2.1889
7.1222
5.5778
ACHECKING THE RESULT:
A-B+.)(R
1.0G58E-14
2.4869E-14
7.1054E-15
1.0658E-14
204869E-14
7.1054E-15
AA LEAST+SQUARES SOLUTION
1
1
1
1
1
1
[J+8+6 2p1 1 1 2 1 3 1 4 1 5 1 6
1
2
3
4
5
6
A+12.03
8.78
6.01
3.75
.31
2.79
R· .. Al!lB
R
14.941
2.9609
A.TIIE RESULT GIVES THE INTERCEPT AND SLOPE OF THE LINE
ATHAT IS THE LEAST-SQUARES BEST FIT TO THE POINTS OF A.
B+.)(R
11.98
9.0196
6.0588
3.0979
0.13705
2.8238
A-B+.)(R
0.049524
-0.23962
0.048762
0.6521
0.44705
0.03381
I-Beam Functions
The I-beam functions are a group of system-dependent functions providing information about the workspace or system
environment.
R+18
The I symbol is formed by the T overstruck with the.1. The argument must be a single integer element in the range
19 through 29, or -1 through -3. The result is as indicated in Table 2.
92
I -Beam Functions
Table 2. I-Beam Functions
B
Information Given
19
Session connect time, in 60ths of a sllcond.
20
Time of day, in 60ths of a second.
21
APL execution time (CPU time since APL was invoked), in 60ths of a second.
22
Remaining available workspace, in bytes.
23
Numbe of on-line users.
24
User's log-on time, in 60ths of a second.
25
Today's date, mmddyy, in base 10 (where mm is month, dd is day, and yy is year).
26
Current value of line counter.
the line being executed.
27
Vector of line numbers in the state indicator.
28
Terminal type (value set by TERMINAL command.):
1
Standard APL (on-line default)
2
Non-APL2741
3
Teletype
4
Card reader and/or line printer (off-line default)
13
29
In executing a defined function, this is the number of
Tektronix 4013
User's account as a character vector,
Shows overhead time (starting from the point at which APL was invoked) in 6Ql-hs of a
second. This is primarily an indication of the time taken by the monitor to process
input and output.
Results 'in an integer scalar whose value is the number of unused entries in the symbol
table. This represents the maximum number of new names acceptable for the current
workspace.
Results in an integer scalar whose value is 1 if this is an on-line APL operatioll, or
batch run.
o if this is a
T-Bar Functions
The T-bar operator, i' (the encode operator, T, overstruck by the negative sign, -) is provided for certain system interfaces. Most of these interface functions are of concern only to installation personnel, and should be avoided by
APL users. (Indiscriminate use of the T-bar operator is likely to cause damage to the user's workspace - see the SYS
ERR message in Appendix A. )
The monadic use of T-bar results in an integer code for the type of its argument:
code
type of argument
Logical
~
2
Text (I.e., charader data)
3
Integer
4
Real
5
Index Sequence
6
List
T-Bar Functions
93
The first four types are fami liar to APL users and were discussed in Chapter 3. An index sequence (code 5) represents
integer data; it is a compact representation of a regularly spaced sequence of integers whose fundamental source
is the index generator (monadic iota). List type data (code 6) results when parentheses enclose two or more APL expressions that are separated by semicolons. A list has length (the number of such expressions), but instead of values
a list has pointers (pointing to the value of each expression in that list). The use of lists is restricted to certain specified intrinsic functions in Xerox APL. Their use in other contexts will result in a SYNTAX ERR or LIST ERR message.
The T-bar operator is also used dyadically. Installation personnel use dyadic T-bar operations when generating
workspaces that contain intrinsi c functions (such as WSF NS). Essentially, this associates a name, such as DELAY,
with a portion of the APL processor (see also Appendix C). Subsequent use of the name DELAY is interpreted as a
function reference to that part of the processor. Users need not be concerned with this use of T-bar; usually they
will copy or load workspaces having intrinsic functions.
Thereisonedyadicuse of T-bar that is of interest to many APLusers; this isthe charactergeneratorfunction. Itconverts integer data into corresponding character data, and thus allows the user to generate special characters, possibly unrecognized by APL. The relationship between an integer (between 0 and 255) and the generated character
can be determined by examining Figure 8-1 in Appendix B. The integer n corresponds to the nth character in the
table of APL Codes. A word of caution, however; the table shows characters in their hexadecimal position; the user
must remember to convert this to a decimal position. For example, the INDEX character corresponds to the decimal
integer 32 (the hexadecimal value is 20) according to the table.
To generate the nth character, the following form is used.
The left argument must be the scalar integer 2; this designatt3S that the T-bar operator is to be used for character
generation. The right argument may have any shape, but its domain must be integer, with values between Oand 255.
The result has a shclpe identical to the right argument, but is text data.
For convenience, users may assign generated characters to an easily remembered name. A common example is
INDEX+2T32
Another character that is commonly generated is the backspace. In the following example, this is created and then
used to display overstrike characters not recognized by APL:
BKSP+2T8
'A' .BKSP.,H,
if
AYe
T~ST
94
T-Bar Functions
'ABC'.BKSP.BKSP.'--'
'TEST'.BKSP.BKSP.BKSP.'- H,
6. APl STATEMENTS
As mentioned in Chapter 2, each completed line of input is clas5ified as either a statement or a system command.
Statements specify the operations to be performed by the APL system, such as calculations, branching, and assignment of values or expressions. System commands - treated in Chapter 8 - are concerned with the mechanical
aspects of the system, such as logging on and off, and saving, loading, and deleting workspaces. Statements can
be entered when the system is in either execution mode or function definition mode. The user indicates the end of
a statement by depressing the RETURN key. In execution mode, the computer then interprets and executes the
operations contained in the statement. In definition mode, the computer stores the statement until the entire
function is executed. Blanks may appear anywhere in a statement except embedded within a number or a name.
In general, an APL statement cannot be continued on another I ine. A text constant, however, may include one or
more carriage returns, thus allowing multiline statements. The user is cautioned that if he opens a text constant
with a 'luote and forgets the closing 'luote, APL considers all subse'luent input to be part of that text constant until
an ending 'luote is reached. For example:
A.'LVNG
COMM~NT.
CLOSING
QUOT~
FORGOTTEN
A
A
)CLEAR
tI
LONG COMMENT. CLOSING QUOTE FORGOTTEN
A
A
)CLE'AR
)CLRAR
CLEAH WS
In this example the first two requests to display A and the first )CLEAR command were ignored because APL
considered them to be part of the text assigned to A. The ending 'luote allowed resumption of normal input. The
display of A now shows the multiline text vector, and the )CLEAR command now works.
For all practical purposes there are four kinds of statements in Xerox APL: comment, branch, assignment and nonassignment, and compound.
Comment Statements
To enter a comment statement, the user types the symbol A at the beginning of a line and follows it with his
comment. The A symbol is produced by typing a n symbol (upper shift C) and overstriking it with a symbol (upper shift J). This symbol signals APL that the line is a comment and is not to be executed. Any valid APL
characters may be incl uded in a comment; inval id APL characters will produce an err'.)r message. If a comment extends over several I ines, each I ine must begin with the A symbol. Some examples of comments are shown
below:
0
R
ROOM AREA
ROUTIN~.
A
A
A
R
EACH LINE OF A MULTIPLE-LINE
COMMENT MUST BEGIN WITH A A.
A comment statement can be entered as a direct I ine (during execution mode) or it can be entered as part of a defined function. If a comment statement is entered as a direct line, it is not retained in the user's workspace. If
a comment statement is used in a function definition, however, the statement will have a line number, will occupy
workspace, and will be displayed like any other function line. A function cannot be closed on a comment line,
APL Statements
95
because the closing V symbol will be treated as just another symbol in the comment.
a function definition is shown below:
An example of a comment in
VA+H TRIAREA B
ACALCULATES AREA OF TRIANGLE.
A+H)(Bt2
V
[1]
[2]
[3]
In Xerox APL any executable statement .may include a comment to its right. Everything to the left of a
is considered executable. Everything to the right is considered comment. Some examples are
[10]
A
character
CO:J1'+HOURS)(RATE
RCOST FOR S1'HAIGHT-TIME LABOR.
OCOS1'+-1.5xHOURS)(RA1'E
R COS,]' POR OVERTIME LABOR.
[15 ]
There is also another way for a user to enter remarks at his terminal. Instead of first typing the A symbol, the user
can type the comment and then backspace to the beginning of the line and strike the ATTN key. This method
allows the user to type remarks (including illegal overstruck characters) for his own annotation. In effect, an empty
line is produced. An example of this method is shown below:
THIS
v
IS A KMM
REMARK.
Branch Statements
Branch statements are generally used within function definitions to alter the sequential execution of statements. t
A branch statement has the general form
4exp
where exp stands for an integer value. The value determines the statement number of the statement to be executed
next, as follows:
1.
If the value is a statement number of a statement within the current function, then that statement will be
executed next. Thus the statement
[5]
4(2)A))(3
where A has a value of zero, will cause a branch to statement 3 of the current function. (The value 3 is
derived as follows: the expression (2)A) returns a value of 1; and this value is multiplied by 3.)
2.
If the value is a statement number outside the function being executed, then execution of that function
terminates. For example, the statement
[4]
+0
indicates a branch to statement 0, which is outside the function. Since functions begin with statement 1,
branching to statement 0 is an effective way to terminate a function.
tAnother form of branch statement is covered later - the branch arrow that is not followed by an expression. A
branch arrow by itself can be used to terminate execution of a suspended function and the functions that invoked it,
thus effectively clearing the state indicator to the next suspension (if any). This application of the branch arrow is
described in Chapter 7.
96
Branch Statements
3.
..
~
If the value is an empty vector, then no branch occurs and the next sequential line is executed. If there
are no more lines, execution of the function is terminated. An empty vector can be created in ClnY of the
following ways:
O/s
Ops
SX\O
where 0 is the result of a comparison expression, and s represents a statement number. (If the result of the
comparison statement is 1 instead of 0, the next statement executed will be the one indi cated b~' the statement number.) Substituting the comparison expression A=4, which produces a value of 0 or 1, and the
statement number 2 in the above expressions Illustrates ,the simpl icity of this type of branching:
[5]
[5]
+(A=4)/2
+(A=4)p2
[5]
+2 x dA=4)
In each case if the value of A equals 4 (that is, the comparison expression returns a 1), then line 2 is
executed next. If A is any other value, then the comparison expression returns a 0, yielding an empty
vector, and statement 6 will be executed next if it exists; otherwise execution of the function terminates.
The expression indicating the statement numbers can be a scalar or a vector. In other words, the user can specify
branching to one statement, to one of two statements, or to one of any number of statements. Branching to one
statement is described above. Branching to one of two statemer,ts can take either of the following forms:
+(sl,s2)[l+x op yJ
+((x op y),-x op y)/sl,s2
where
sl
is the line number to be branched to if the comparison expression yields a O.
s2
is the line number to be branched to if the comparison expression yields a 1.
is a comparison expression; x and yare the values to be compared, and op is any of the fc)llowing
x op Y
operators: < S = ~ > If: V A 'If ,. €
Both of these forms cause execution to branch to the first line I'umber if the comparison operation yields a 0, or
to the second line number if the comparison operator yields a 1. In illustration, the second form is used in a function definition and then executed with values for x and y:
VX F Y
[1]
[2]
+«X<Y).-X<Y)/Al.A2
Al:'STEP Al'
[3]
+0
[4]
A2:'STEP A2'
[5]
+0
[6]
V
1 F 2
STEP A 1
2 F 1
STEP A2
Clearly the second form can be expanded to include more statement numbers.
statements can also take the form
Similarly, a branch to one of several
where
is a counter.
is the rotation function.
v
is a vector of statement numbers, the first of which must be a positive integer or zero.
. Branch Statements
97
Compound Statements
Using semicolons for separation, all of the preceding kinds of statements can be combined in "compound II statements.
Compound statements hoJve the following characteristics:
1.
A series of nonassignment statements produces the displ(]y action described in Chapter 3
output statement). Example:
W+l0
L+20
'DIMENSIONS ARb' ';W;' lJ Y '.L;';
DIMENSIONS ARE 10 BY 20; ARE,1 IS 200
2.
(see the mixed
AREA IS 'iWxL
An assignment statement produces no display. Note, however, that any assignment statement becomes a
nonassignment statement by simply placing a plus sign (that is, identity operator) at its extreme left.
Example:
5x4t2
;A+4
10
5 X 4t2;+A+4
104
Notiee in the last example thot the results of a compound statement are printed without intervening spaces
unless the spaces are specifically designated. Spaces are designated as shown below:
, ;+A+4
10
3.
A comment statement can have no statement to its right. All characters from the comment symbol PI up to
the end of the line are considered to be commentary. The semicolon preceding a comment is optional. Example:
1
4.
r2
3
fIlSHOWS MAX
OPFR.4 TOR;
Tfl IS
T8
STILL A COMMENT.
A-brqnch statement implies no special display. In the no-branch case, statements to the left of the branch
will be interpreted; they are ignored if a branch occurs. This provides conditional execution c(lpability.
Example:
VVERACITY X
[1]
~0;'TRUE';~2x\X~1
[2]
~O;'FALSE';~3xIX~0
[3]
'NEITHER TRUE NOR FALSE'V
VERACITY 4::2+2
TRUE
VERACITY 2+2=4
NEITHER TRUE NOR FALSE
2+2=4
2
VERACITY (2+2 )=4
TRUi!.'
5.
Suppose a branch statement has one or more nonassignment statements to its right. If a branch occurs, the
appropriate display is produced before control is passed to another line. In the no-branch case, the display
remains pending until completion of the compound statement. Example:
[1]
VLOGIC X
'NOT ';~OX\X=O;'ZERO OR
LOGIC
1~2
ONE
LOGIC 3>4
ZERO OR ONE
LOGIC 2+2
NOT ZE:RO OR ONE
100
Compound Statements
';~oxIX=l;'ONE'V
7. DEFINED FUNCTIONS
As mention~d in Chapter 3, defined functions are used in the same way as operators, but most defined functions must
first be formed by the user instead of being an inherent part of the APL language. In addition, there are some defined functions in Xerox APL that are intrinsic to the processor; that is, they calion code that exists in the processor. Bo:th user-defined functions and intrinsic functions are referenced by name and are treated in the same way,
but intrinsi,c functions are usually faster than functions that the user can define. (Intrinsic functions are always
locked; the user can neither modify nor display them.)
User-Defined Functions
The folloW'ing tasks are handled in function definition mode:
Creating user-defined functions
Displaying user-defined functions
Editing user-defined functions
Once created, most functions can be edited and displayed. Once a locked function is created, however, it cannot
be edited-or displayed (see "Locking Functions" later in this chapter). Locked function lines cannot even be displayed for error diagnosis. It is possible, however, to erase a locked function.
Function c:lefinition mode begins when a function is opened and continues until a function is closed or abandoned.
(It is possi:ble to close a different function than was originally opened by revising the name of the function.) A
function ~ay be "opened" during direct input or evaluated input (see Chapter 3), and it may be opened briefly
during execution (see the "execute" operator, monadic E, Chapter 5). A function cannot be opened during any other
form of input, such as quote-quad input or blind input; and a different existing function cannot be opened while
still in function definition mode. Until a function is closed during function definition mode, APL execution is impossible except for system commands (which are executed and do not become part of the function being defined).
Most system commands leave the currently open function intact and return the user to definition mode; however,
some system commands cause a function definition to be abandoned (see "Issuing System Commands" later in this
chapter).
Creating User-Defined Functions
A del symbol, v, followed by a function name specifies a change from the execution mode to the function definition
mode. A second V symbol ends function definition mode and declares a change back to execution mode. No execution of statements occurs during function definition, and no errors are reported except fe line-scan errors, character errors, and definition errors. Instead, each statement is stored as part of the function.
Each defined function has a header and a body. The function header is the opening line of a function and declares
the name (the identifier used to reference the function) and type of a function. The body of a function is the rest
of the function. After the user enters a function header, APL responds with a statement number as follows:
I
VCUBE
The line number [1] signifies that the first line of the function program may be entered. Each line thereafter is
numbered sequentially until the function is completed. The statements are stored and are not executed unti I the
entire function is called and executed.
Defined Functions
101
Syntax of Defined Functions
A defined function can be niladic, monadic, or dyadic; that is, it can have zero, one, or two arguments. In addition, a defined function may return an explicit result or no result. Thus, there are actually six types of defined
functions as illustrated by the following function header syntax possibi I iti es:
Function Header Syntax
No Explicit Result
Niladic function
Ilname
Ilr
Monadic function
Ilname y
Vr' name y
Dyadic function
Vx name y
Vr
+
+
name
x name y
where
name
is the user-assigned function name.
is a variable to which the result is returned.
x and y
are dummy variable names.
The syntax of the function header affects the way a function is referenced in a statement; that is, whether the function requires zero, one, or two arguments for execution. Defined functions with explicit results may appear in compound expressions, much like operators. Defined functions with implicit results must appear alone; they cannot
appear in compound expressions except as the last function to be executed. Examples of the creation and use of
each function type are shown in Table 3.
Table 3.
Function Type
Header Syntax
Niladic function with
explicit result
Ilr
-<-
Examples of Defined Functions
Examples of Definition and Use
~'RE'[JULT+PI
name
[1]
lIESULT+o1
[2]
~'
PI
3.141592654
[3]
vRESULT+TRIANGLE
AREA+0.5xBASExHEIGHT
DIAGONAL+«HEIGHT*2)+BASE*2)*O.5
RESULT+AREA.DIAGONAL
[4]
V
[1]
[2 ]
BASE+5
HEIGFlT+8
TRIANGLE
20
102
User-Defined. Functions
9.433981132
Table 3.
Exomples of Defined Functions (Cont.)
Function Type
Header Syntax
NiladiC function with
no explicit result
vname
Examples of Definition and Use
[1]
'fJPI
X+Ol
[2J
X
[3J
V
PI
3.141592654
[2]
[3]
[4]
'fJTRIANGLE
AREA+0.5xBASExHEIGHT
DIAGONAL+«(HEIGHT*2)tEASE*2)*0.5
'AREA IS 'iAREA
'DIAGONAL IS 'iDIAGONAL
[5 J
V
[lJ
BASE+5
HEIGElT+8
TRIANGLE
ARgA IS 20
DIAGONAL IS 9.433981132
Monadic function with
explicit resu It
vr
~
vRETURN+EXPAND INPUT
RETURN+((2xpINPUT)pl O)\INPUT
name y
[1]
[2 ]
v
E'XPAND 'COPY COMMAND'
COP Y
COM MAN D
VRETURN+DESCENDINGSORT IllPUT
RETURN+INPUT['IllPUTJ
[lJ
[2]
'7
DESCENDINGSORT -5 -3 10 5 6 8
10
Monadic function with
no explicit result
8
6
5
-3
-5
VEXPAND INPUT
X+((2 x pINPUT)pl O)\INPUT
Vname y
[1]
[2]
[ 3]
X
V
EXPAND 'COpy COMMAND'
COP Y
COM MAN D
[1]
VDESCENDINGSORT INPUT
X+INPUT['INPUT]
[2]
[3]
X
V
DESCENDINGSORT -5 -3 10 5 6 8
10
8
6
5
-3
-5
User-Defined Functions
103
Table 3.
Examples of Defined Functions (Cont.)
Function Type
Header Syntax
Dyadic function with
explicit resu It
Vr
+-
Examples of Definition and Use
x name y
VRESULT+BASE TRIANGLE HEIGHT
AREA+0.5 xBASExHEIGHT
[1]
[2]
[3]
[4]
20
Dyadic function with
no explicit result
DIAGONAL+«HEIGHT*2)~BASE*2)*0.5
RTJ:SULT+ARTJ:A ,DIAGONAL
V
5 TRIANGLE 8
9.433981132
Vx name y
VBASE TRIANGLE HEIGHT
AREA+0.5xBASExHEIGHT
[1]
[2]
[3]
DIAGONAL+«HEIGHT*2)~BASE*2)*0.5
'AREA IS '.AREA
'DIAGONAL IS '.DIAGONAL
[4]
[5]
~
5 TRIANGLE 8
AREA IS 20
DIAGONAL IS 9.433981132
[1]
[2]
vx PLUS Y
ANS+-K-tY
AtIS
[3]
V
2 PLUS 5 10 15 20
7
12
17
22
Variables Local to a Defined Function
Three types of variables that can be local to a defined function are
Dummies
Locals
Labels
Dummies and locals are named in the function header, while labels are named in the body of the function.
Dummies. Dummies are used in the header of a defined function to indicate the syntax of a function.
notice the header of the following simple function (this function calculates the area of a triangle):
[1]
For example,
VA+H TRIARF:A B
A+HxBt 2V
The dummies A, H, andB in the function header indicate that the function named TRIAREA returns an explicit result
and that the function operates on two arguments which must be furnished by the user. For example, suppose the user
calls this function with the statement
AREA+l0 TRIA REA 5
The dummy H in the function is assigned the value 10, and the dummy B is assigned the value 5. The result is returned in the dummy A, and is finally assigned to the variable AREA in the calling statement. Dummies possess
values only within the function. That is, the use of A, H, and B as dummies does not affect their use as variables
outside the function. If variables A, H, and B had values assigned to them before the function was called, they
104
User-Defined Functions
will have the same values after the function is executed. For example, suppose the variable A (with value 21) had
existed in the program before function TRIAREA was called. A display of variable A after the execution of function
TRIAREA will demonstrate that A still has the value 21:
A+21
AREA+10 TRIA REA 5
AREA
25
A
21
Body of a Function. After the opening statement, in which the user creates the function header, the process of
creating a function consists of inputting function statements and, finally, closing function definition. The user is
prompted with a function line number each time the system is ready for further input. The process is ended by typing
a closing V followed by a RETURN key.
Locals. Locals are variables that retain their values only within the function in which they are defined. While a
function is active, its local variables take precedence over any externally defined variables of the same name. A
list of a function's local variables are added to the end of the function header, with each variable in the list preceded by a semicolon. For example, the function header
VR~A
CIRCLE B;X;Y;Z
indicates that the function named CIRCLE has locals X, Y, and Z. The values for these variables are assigned within
the function; if these variables are referenced without having a value assigned within the function, an UNDEFINED message will be produced. If variables X, Y, and Z had values assigned to them before the function was
called, they will revert to those values after the function is executed.
Labels. Function lines may be labeled to allow symbolically controlled branching (if a function is edited, line
numbers may change). A labeled line has the form
[nJ
name: statement
where n ,is the line number, name is the label, and statement is the content of the line.
[4]
ERREXIT:
~O;'ERROR
For example,
EXIT'
In this e~<omple, the label ERREXIT has the value 4. If an attempt is made to assign a value to ERREXIT during function execution, a syntax error message wi II be reported. If the functi on is edited and the Iine number changes
to [5J, ERREXIT will then have the value 5.
Changing Suspended Functions. APL permits the user to change a function while it is in one or more suspended
states (but never while pendant). This is seldom advisable. It is almost always preferred practice to clear out such
suspensions before modifying the function to avoid possible confusion.
At the time a function is suspended, its (current) local variables have been determined by APL, and its labels have
already been assigned their values. Changing the suspended function does not alter these determinations. Resuming execution of a suspended function will cause the determined items to take effect again - regardless of how
the function was altered.
Directives
During function editing the user issues directives to transfer APL control to a line or to display one or more lines.
A directive may take any of the following forms:
[1J
Directs APL to a line - here line 1.
[ lOJ
Directs APL to display a line and then to stay at that line for further editing - here line 1.
[02J
Directs APL to display from a line to the end of the function - here beginning at line 2.
[OJ
Directs APL to display an entire function.
[106]
Directs APL to a line to edit, starti ng (approximately) at a given col umn -here line 1 at col umn 6.
User-Defined Functions
105
A directive always starts with a left bracket and ends with a right bracket. Only quads, digits, and decimal points
are acceptable within the brackets, and no directive can have more than one decimal point and one quad. In addition, blanks are not allowed. The following are examples of illegal directives:
[1 2]
[1.21.]
[010]
[ 1£'1 J
The last directive, which may appear as 10 to someone familiar with constants, is in error; E is not allowed within
a directive. Any erroneous directive will cause an error message to be printed. In addition, any characters to the
right of the error detection point are disregarded - even a closing del.
Several directives may be used on one line, with the rightmost directive overriding any directives to the left of it.
For example, notice the following portion of a function:
'lJFF
X+Y
[lJ
[2]
[lJ Y+X
[2]
[5]
A+B
The [lJ directive on the second-to-Iast line overrides the [2J directive to its left and causes the statement on line 1
to be replaced with Y+-X; notice that the next line prompt is [2]. (It should be obvious by now that a function line
prompt is a form of a directive.) Similarly, the [SJ directive on the last line overrides the [2J directive to its left
and causes the expression A B to be assigned to line 5; the next line prompt will be [6J.
Displayi ng User-Defined Functions
Once the user has defined a function, he can display it in any of the following ways:
Display all lines of the function.
Display one line.
Display from a specified line to the end of the function.
To display a function, the user opens the function with a del symbol, names the function, and specifies what he
wants displayed, all on the same line. He can then either close the function with another del symbol (if no editing
is to be done) or leave the function open for further editing.
If the user wants to display all of a function - say function TRIA NG LE for example - the procedure is as follows:
VTRIANGLE
[0]9
V BASE TRIANGLE HEIGHT
AREA+O.5 x BASExHEIGHT
DIAGONAL+«HEIGHT*2)+BASE*2)xO.5
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
[lJ
[2J
[3J
[4J
V
If the user wants to display only one line of a function -say line 3 of function TRIANGLE -the procedure is
[3J
VTRIANGLE [3DJV
'AREA IS ';AREA
finally, if the user wants to display from one line to the end of a function - say from line 2 on of function
TRIA NG LE - the procedure is
[2J
[3J
[4J
106
VTRIANGLE [02JV
DIAGONAL+«HEIGHT*2)+BASE*2)xO.5
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
User-Defined Functions
The user can stop the display of lengthy functions at any point by pressing the A;T',J key This is e~,>ecially useful
when'the user wants a range of lines displayed. For example, suppose he wants to display lines 10 through 15 of a
20-line function. He can request the display to start at line 10 and then press the ATTN key after line 15 has been
displayed. If the display command was closed with a del symbol, APL will be in the execution mode after the interruption; if the closing del was omitted, APL will be in the function definition mode after the interruption.
Notice that the display commands in all of the above examples were closed with a del symbol. This symbol causes
control to be returned to the execution mode as soon as the display is complete. If the user wants instead to remain
in function definition mode and edit the function, he merely omits the closing del in the display command. See
how the above examples appear without a closing del in each display command.
[1]
[2]
[3]
[1+]
"TRIANGLE [OJ
" BASE TRIANGLE HEIGHT
AREA+O.5 x BASExHEIGHT
DIAGONAL+«HEIGHT*2)+BASE*2)xO.5
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
[ 5]
[3]
"TRIANGLE [3OJ
'AREA IS ';AREA
[ 3]
[2]
[3]
[1+]
[5 ]
"TRIANGLE [U2]
DIAGONAL+«HEIGHT*2)+BASE*2)xO.5
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
Notice that after a single-line display, APL reprompts with the same line number; and that after a multiple-line
display, APL prompts with the next available line number. The user can then edit the function as described below
or he can type another del symbol to close the function. Closing the function definition with a del symbol does
not alter the content of that line. For example, the following operation does not change the value of line 3; it
will still be 'AREA IS ';AREA:
[3]
"TRIANGLE [3OJ
'AREAIS';AREA
[3]
"
In summary remember that
[OJ
displays all of a function.
[ 20J
displays a sing Ie Iine (here 2).
[02]
displays from a line (here 2) to the end of the function.
Editing User-Defined Functions
The editing of user-defined functions is oriented to line-at-a-time editing capabilities:
Delei'ing a line
Inserting a line
Replacing a line
Modifying a line
The first three capabilities can be performed as shown in Table 4. The last capability - modifying a line - permits
character editing (that is, deletion, insertion, and replacement of characters), adding to a line, and overstriking
existing characters on a line. All of these capabilities are detailed below.
User-Defined Functions
107
Displaying and Editing Defined Functions t
Table 4.
~-.---,.-
Perform Action and Stay
in Definition Mode Function Already Open
Action to be Taken
-
.
Perform Action clnd Leave
Open Function, Perform
Defini tion Mode Function Already Open
Action, and Stay in
Defini tion Mode
Open Function, Perform
Action, and Leave
Definition Mode
,-,
Display all of a Function
[2 J
[2]
[l]J
9
III
[ ? I
p-
[[J ]9
A
.4
[ J ]
[II
A
121
B
[11
En
-
- -- ----
[ 4I
[2 I
[2 J
1---- . _ . ----
--
Display a I ine and change it
f---- - - -
-- -
121
In
---
----
:1\'
[4 I
[21
E3]
r 21
--
--
[2LJJli+X!J
-[4 ]
[ 2J
B
--
'l
Wll
B+X+Y
c
Note: The user cannot delete line
zero. Also note that the
ATTN, INDEX, and RET
symbols in the examples stand
For the ATTN, INDEX, and
RETURN keys respectively.
[ 2l<§J:iJ
8+-X+Y
[4 I
[2J~
[ 3J
-
or
[4 ]
[4J
[2 J
3J
[ 4]
r
[3]
[2]
OF[20]B+X+YO
B
9 P[ 112 J9
B<-XtY
[2]
[ 3J
C
-
[3J
B+X;:Y---
c
OFE2]@!)
[ 3]
or
-
VF[ 2 J@l
v
-
OFE2l@l
v
Q
~
[ 3J
~
~
-or
[2 h' "1
~
:?l'JJ!?+-X +--.r
1"
9F[2JGB
,
-~
[3J
---
"-
or
[2]<9
v
OF[2nJ 0
a---
- -
U[[]2]
c
~
:~-r
-
-
r [Ie] 9
[4J
[ 2J
[ 3]
~,,\
-
---
c,'
I 2J
I J]
[ 2]
B
-- - - - -
12CJl.B+X+YO
['I]
[4 J
C
c------OF[ 2[ll
[ 2]
[i
--- -----
[ 3]
B
9
-1------
---
[4 I
-
-
Delete a line
C
9
-
[ 2[ II
jj
[4J
[2J
[J I
Display a function, beginning with
a specified line
F
A
[4J
- - - - - - -------- t-
Display a line
"ruJlI'
9
[1]
[ 2]
[3]
B
r3 ]
V
[4 I
-
p-A
9
c
[ J I
9
OP[IJJ
p-----
O
[ 3I
~
-Insert a line
Replace a line
Override a line number
Change the function header (this
example adds a local variable to
[ 3J
[0.6]
~
[4J
[3J
~
[4 ]
[41
[ 2]
LU
[4]
[2]
~
[4J
[1]
[OJ
[4 J
[0 J
[3 J
[0. s J
XV
9FEO.S]
X
VF[0.5]
F;B
~
VF[2]Z9
VF[2JZ
[3J
9F[4J[2]
[2 I
[ 2]
F;BV
VF[4l[2J
[2 J
VF[OJ
F;B
~
VF[OJ
F;BV
[1]
the function header)
I
Erase the current function
[4J
)ERASE
- -F
-
I
[4J
[4]
Erase another function
) ERASE G
[L]
[4 J
)rRASE G
-
I
I
tUser input has been underlined throughout this table to distinguish it from APL output. The underlining does not actually appear at the terminal. In
addition, a simple three-line function named F has been assumed in the examples in this table (see the first display entry in the table for the original
content of function F).
108
User-Defined Functions
XV
[0.6 J
Deleting a Line
A statement in a defined function can be deleted by striking the ATTN key followed by the RETURN key, or by
striking the INDEX key followed by the RETURN key immediately to the right of the line number. (See al50 the
notes followiing Table B-3 concerning terminals other than the standard ones assumed in this section.) Use of the
INDEX and RETURN keys, however, is a faster and more convenient delete sequence because the computer does
not have to react by printing a caret symbol. As an example, suppose the user wants to delete line 2 of the following function:
VBASE TRIANGLE HEIGHT
ATHIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE
ABASE AND HEIGHT CANNOT EXCEED 5 AND 15 RESPECTIVELY
AREA+O.5xBASExHEIGHT
[1]
[2]
[3]
[4]
[5]
[6]
DIAGONAL+«HEIGHT*2)~BASE*2)xO.5
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
[7]
V
First the user opens the function and directs the system to line 2
VTRIANGLE [2]
APL responds with a [2J, indicating that control is at line 2. The user strikes the INDEX key and then the RETURN
key to delete the line, and APL responds with the next line number as shown:
[2]
Notice that the INDEX and RETU RN keys do not cause anything to be printed at line 2.
keys are used instead, the sequence appears at the term ina I as
If the A TTN and RETURN
[2]
1\
[ 3]
The user can now either close the definition mode with a del symbol or proceed with fllrther editing (including deleting the next line). t A display of the function at this point illustrates that line 2 has been deleted:
[OJ
[3]
V BASE TRIANGLE HEIGHT
[1]
[3]
[4]
[5]
[6]
ATHIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE
AREA+O.5xBASExHEIGHT
DIAGONAL+«HEIGHT*2)+BASE*2)xO.5
'AREAIS';AREA
'DIAGONAL IS ';DIAGONAL
[7]
The definition mode can now be closed with a del symbol
[7]
V
Once definition mode is closed, APL renumbers the lines in sequential order, as illustrated by another display of
the function
VTRIANGLE [mv
V BASE TRIANGLE HEIGHT
[1]
[2]
[3]
ATHIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE
AREA+O.5 x BASExHEIGHT
DIAGONAL+«HEIGHT*2)+BASE*2)XO.5
'AREA IS ':AREA
'DIAGONAL IS ';DIAGONAL
[4J
[5J
V
tHe can also press the RETURN key if he doesn't want to do anything to the line. APL will simply respond with
the line number - in this case [4J. Another RETURN key will cause APL to prompt with [5J, and so on.
User-Defined Functions
109
Inserti ng a Li ne
A new line can be inserted
described below. The user
printing the line number of
function, the user can now
in a defined function simply by reol)ening the function and entering the statement as
reopens the function by typing a del and the function name, to which APL responds by
the next statement to be entered. If the new line is to be inserted at the end of the
enter the new statement and c lose the function as shown:
[6]
'flTRIANGLE
ATHIS FUNCTION IS USED IN ROUTINES 1 AND 2.
[7J
'fl
If the new line is to be inserted between any two lines, however, the user must specify a line number between those
two lines -any line number as long as it is between the two line numbers (see "Line Numbers" below). APL responds with that line number and the user can enter the new statement. For example, suppose the user had wanted
to add a comment as the first line of function TRIANGLE instead of as the last line. He could have done this as
follows:
'flTRIANGLE
[6]
[0.5]
[0.5] ATHIS FUNCTION IS USED IN ROUTINES 1 AND 2.
[0.6]
Notice the [0.6] prompt in this example. After an insert statement is entered, the APL system adds a 1 to the last
place of the number chosen for the insert, and prompts wi th the new number. (The next prompt after [0. 6J wi II be
[0.7J; the next, [0.8]; and so on.) This allows the user to insert several lines.
A display of function TRIANGLE illustrates that line 0.5 has been added
[0.6] [O]'fl
V
[0.5]
[ 1]
BASE TRIANGLE HEIGHT
ATHIS FUNCTION IS USED IN ROUTINES 1 AND 2.
ATHIS FUNCTION CALCULATES AR~A AND HEIGHT OF TRIANGLE
[2 ]
[ 3]
AREA~0.5xBASExHEIGHT
[4 ]
[5]
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
DIAGONAL~«HEIGHT*2)+BASE*2)xO.5
After the function is closed, APL automatically renumbers the lines, as illustrated by the following display:
V
[1]
[2]
[3]
[4]
[5]
[6]
'flTRIANGLE [DJV
BASE TRIANGLE HEIGHT
ATHIS FUNCTION IS USED IN ROUTINES 1 AND 2.
ATHIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE
AREA~0.5xBASExHEIGHT
DIAGONAL~«HEIGHT*2)+BASE*2)xO.5
'AREA IS ':AREA
'DIAGONAL IS ';DIAGONAL
V
Line Numbers. APL allows the user to type a line number with up to four numbers to the left of the decimal point
and up to three numbers to the right. As noted above, after each insert line is entered, APL adds a 1 to ~he last.
place of the insert. As illustrated in the following pori-ion of a printout, the next prompt after an .88 Insert wi! I
be [.89]; the next, [.9]; the next, [1]; and so on:
[7]
'flF
[.88J
[0.88J
[0.89]
[0.9J
[1]
110
User-Defined Functions
The highest integer line number printed by APL is [9999J; thus the highest possible line number is [9999.999]. If
the user is prompted with [9999. 999J and he issues a legal statement (say X+Y), APL will prompt him with the same
line number since it cannot go any higher.
Replacing a Line
A line in a defined function can be replaced simply by reopening the function, directing control to the statement
that is to be replaced, and entering the desired statement. For example, suppose the user wants to replace line 1
of function TRIANGLE with another statement. He reopens the function by typing a del and the function name and
directs control to line 1 by typing that line number in brackets. After the RETU RN key has been struck, APL responds to this entry by printing the specified line number at the left margin, as shown:
VTRIANGLE [1]
Any statement the user enters at this point wi" replace what previously existed at that line. Suppose he now enters
the following comment statement:
[1]
AINPUT MUST BE IN FEET
[2]
Notice that the next prompt is at line 2.
tion by entering another del
[2J
If the user does not want to do any more editing, he can close the func-
'V
Notice that this action has no effect on line 2; it merely closes the fundion once more.
function TRIANGLE illustrates the change to line 1:
'V
[1]
[2]
[3]
[4]
[5]
[6]
The following display of
'VTRIANGLE [OJ'V
BASE TRIANGLE HEIGHT
AINPUT MUST BE IN FEET
ATHIS FUNCTION CALCULATES AREA AND HEIGHT OF TRIANGLE
AREA+O.5xBASExHEIGHT
DIAGONAL+«HEIGHT*2)+BASE*2)xO.5
'AREA IS ';AREA
'DIAGONAL IS ';DIAGONAL
V
Doing Several Things at Once
APL allows the user to open a function, change a line, and close the function all on one line.
For example,
'VG[1][2]2.2V
In this case the user opens function G, issues a directive to line 1, notices he really wanted to change line 2,
changes the directive to line 2, replaces whatever exists on that I ine with the value 2.2, and then closes the function. This shortcut operation allows the user to change a function without having to interact extensively with the
computer. Another example is shown below:
VG[lOJ1.11V
1.1
[1]
[1]
[2]
'VG[OJ'V
'V G
1.11
2.2
'V
User-Defined Functi ons
111
The fi,rst line requests that line 1 of function G be displayed, and the contents of that line changed to the value 1.11.
The display of function G shows that line 1 has indeed been changed from 1. 1 to 1. 11. It should be noted that the
user can display one line and change it at the same time, but he cannot display an entire function and change something at the same time.
Modifying a Line
As mentioned earlier, modifying a line involves character editing (that is, deletion, insertion, and replacement of
characters), adding to a line, and overstriking existing characters in the line. Modifications to a line can be specified by overriding the present line number with the expression
[n
0 c]
where n is the number of the line to be edited (0 for a function header), and c is the approximate column at which
to begin editing (the column position is the number of spaces from the left margin). APL wi II normally display the
specified line, return to the next line, and space to the designated column. t If the typing element is still not in
the proper position, the user can backspace or space forward until the desired position is reached.
Deleting Characters. To delete characters, type a slash beneath each character to be deleted
VG
[3]
[2]
[208]
2.2
I
In this case the user is deleting the decimal point. After the RETURN key is depressed, APL will display the corrected line, squeezing out any blanks left by the correction
[2]
22
Since APL waits at the end of the displayed line, the user can continue editing this line as if he had just typed it in
or he can depress the RETURN key to end the line.
Inserting Characters. To insert one or more characters between two adjacent chararacters, type a single digit below
the second character, indicating the number of blanks to be inserted (from 1 to 9) between the two characters. For
example,
[3]
[2]
[208]
22
3
This example inserts three spaces between the two characters on line 2. After the RETURN ~ey is depressed, .APL
will display the edited line with the blanks and will backspace to the leftmost blank and walt for the user to Insert
something. An insertion of Ofl will appear at the terminal as
[2]
20H2
where 0 f 1 has been typed by the user.
tUnless the designated line happens to be a line that does not fit on a single line of paper, in which case no character editing can be done. APL will simply display the line and then reprompt the user with the same line. The
following is an example of such a line:
[2]
'A
8'
112
User-Defined Functions
/~
If the user wants to insert more than nine characters, he can type any of the letters A through Z instead of a digit
to indicate the number of blanks to be inserted. The letter A inserts 5 blanks; the letter B, 10 blanks, and
so forth.
The user is cautioned to leave enough room for an insertion.
struck characters as shown below:
[3]
[2]
[2]
Not leaving enough room may result in illegal over-
[20a]
22
2
20*2
BAD CHAR
[2]
20+
Any mistakes made in typing an insertion can be corrected with the BACK$PACE-A TTN key sequence ordinarily
used for correcting errors. This sequence will erase everything from the point of correction to the end of the line,
and the user can then enter the rest of the line as it should be. For example, suppose the user wants to insert the
expression 01>< instatement 2 and instead types the expression 01>< (notice that the first expression means "pi times",
while the second expression means "I times"). He can correct this as shown below:
[2]
[2010]
20+12
[2]
20+01><12
[3]
3
"
01><12
[ 3]
A display of line 2 illustrates that the correction has been made
[3]
[20]
[2]
20+01><12
Replacing Characters. To replace one character with one or more other characters, type a slash below the character
and a digit or letter to the right of the slash indicating the number of characters in the replacement. After the
RETURN key is depressed, APL wi II type the line with the specified number of spaces and will then backspace to
the leftmost blank and wait for the user to type the replacement. For example, suppose the user wants to replace
the leading character of statement 2 with the expression A-+-3. This operation will appear at the terminal as
[3J
[207J
[2]
20-:-01x12
/3
A+30-:-01x12
[2J
where A+3 is the replacement typed by the user.
Adding Characters to End of Line. To add one or more characters to the end of a line, specify a zero as the column
at which to begin editing. APL will then display the line unaltered and wait at the end of the line for the user to
add something. An example of adding local variables to a fLlnction header is shown below:
[3]
[0]
[000]
R~TURN+FUNC
X;A;B
[1]
In this case APL typed the header as RETURN+FUNC X and waited at the end of the line, and the user typed the
expressi on ;A; B.
User-Defined Functions
113
Overstriking a Character. To edit a line and create a legal overstrike, specify a zero as the column at which to
begin editing. APL will display the line and wait at the end of it; the user can then backspace to the character
to be overstruck, and type the second character. An example of overstriking a character is shown below:
[8J
[SOOJ
[sJ
A+~
In this case the first line caused statement 5 - consisting of the expression A-+- 0 - to be displayed and APL to wait
at the end of the line. The user then backspaced to the quad and typed an apostrophe, thus creating the legal
overstrike rl.
Another method of creating a legal overstrike is shown below:
[8 J
[S J
A+O
[S]
A+I!J
[S09
J
o
This method directs APL to just below column 9 insteacl of to the end of the line. The user then types a zero below
the letter to be overstruck, and then depresses the RETURN key. APL displays the line, backspaces to where the
zero was typed, and waits for the user to type something. Typing an apostrophe will now. create the legal
overstrike rl.
Editing a Line Number. Line numbers may be edited in the same way that the content of a line is edited. One
application of editing line numbers is in repeating a statement at several different lines. For example, the following procedure can be used to repeat the contents of line 2 at line 4. 1:
'YG[202 ]
[2]
/3
A+30~o1x12
[4.1J
A+30~o1x12
In this case the user directs that line 2 is to be displayed and that editing is to begin at column 2. In response to
the user entry of /.3, APL displays the line, with three spaces replacing the line number, and then backspaces to the
leftmost space where the user types the new line number 4. 1. Now both lines 2 and 4.1 will contain the same
statement.
Quitting Line Editing. To terminate line editing, simply type a period or any other unexpected (but valid) character, as shown below:
[1]
[2]
ABFG
[1]
ABFG
[ 1D7J
II.
[1]
[OJ
'Y F
ABFG
[1]
'Y
[2]
Changing a Function Header
There are four changes the user can make to a function header (that is, to line zero).
1.
Change the name of the function. Suppose the user reopens an existing function called FFI and changes
only the name of the function to G 1 as shown below:
[0]
[1J
'YFF1[OJ
RETURN+G1 ARG
This example assumes that G 1 does not already exist. (If it did, a DEFN ERR message would occur.)
114
User-Defined Functions
Changing the function name has no effect on function FF 1 - the function sti II exists as it did before the
reopen. Of course, FF 1 is no longer the open function - G 1 is. G 1 is effectively a copy of FFl with
any modifications that the user may have made while function definition mode was in effect. This feature
even allows synonymous function names as long as only the header is revised. It is possible for a user to
make a locked version of an unlocked function in this manner, retaining the unlocked version only until
he is satisfied that the locked version is error-free. Erasing the original function will not affect a synonymous function, nor will subsequent revision of the original. A synonymous function will retain the stop
and trace vector supplied with the original function when it was copied.
1
I~. .
2.
Change the name of the result, change a function with a resurt to a no-result function, or change a noresult function to a function with a result. The following illustrates the change of function FF1's result
from RETURN to R:'
'VFF1[oJ
R+FFl ARG
[OJ
[1]
3.
Change the nalne of the argument. An example is shown below, where function FF1's argument is changed
to X:
IlFF1[ 0 J
R+FFl X
[oJ
[1]
4.
Change the names of locals, insert locals, or delete locals.
Xerox APt does not allow the user to delete a function header. Any user attempt to do so will cause APL to print
an error message and reprompt the user with Iine zero. If the user wants to get rid of the function he is working
on, he must issue an )ERASE command.
Issuing System Commands
Xerox APL allo~s the .user to enter any system command whi Ie he is in function definition mode. Most system commands keep the user in function definition mode, while some system commands (described below) return the user to
execution mode or even take the user out of the APL system. After commands that keep the user in definition mode,
the APL system will prompt with the same line number at which the command was given. For example, suppose the
user is at line 5 of a function and wants to find out the names of variables in the workspace:
[5J
AAA
[5J
)VARS
BAT
DDD
The system commands that take the user out of function definition mode are )CLEAR, )LOAD, )COPY, )PCOPY,
)QLOAD, )QCOPY, )QPCOPY, )CONTINUE, )CONTINUE HOLD, )OFF, )OFF HOLD, )SAVE, and an )ERASE
of the current function. All of these commands force a close of the definition mode as though the user had closed
it himself, but the resulting disposition of that function depe'lds on the command. The )CLEAR, )LOAD, )QLOAD,
)ERASE, )OFF, and )OFF HOLD commands, of course, cause the function to be destroyed; the)SAVE, )COPY,) PCOPY,
)QCOPY, )QPCOPY; )CONTINUE, and )CONTINUE HOLD commands cause the function to be automatically reopened by APL after the command action has been taken. In the last situation, as soon as the work on these commands is finished, APL signals the user of the reopening by printing the function name (with an opening del) and
prompting him with the next available line number. With the )CONTINUE and )CONTINUE HOLD commands, of
course, the function is not opened until the next terminal session. The user should probably display the function
before doing any more editing since renumbering may have occurred 'Jecause of the forced close.
•
1
User-Defined Functions
115
1
1
Function Execution
Recursive Function
Xerox APL permits recursive functions - a recursive function being a function that references itself in the body of
its definition. As an example, notice the following function which returns the factorial of its argument:
[1]
VZ+-FAC N
Z+-NxFAC N-1;~OxtN~1;Z+-lV
FAC 0
1
FAC 1
1
FAC 4
24
Tracing Execution
Function execution can be traced by displaying the values of statements (some or all) as execution of the function
progresses. The user specifies the trace of a function by typing an expression of the form
Tllname + line
where
name
line
is the name of the function to be traced.
is an integer or vector of integers that specify the line numbers for which values are to be displayed.
Only the integers that correspond to line numbers in the named function are significant.
When any of the specified line numbers is executed, the value of its statement is printed. If the specified line contains a branch s.tatement, the value of the expression to the right of the branch arrow is printed. Specifying a trace
vector of 0 or to discontinues the trace; for example, TLlFAC+-O or TLlFAC+-tO will stop a trace of function FAC.
Shown below is an example of tracing the execution of a function.
identified by function name and line number.
[1]
VZ+-FAC N
Z+-l
[2]
~oxtNSl
[3]
Z+NxFAC N-1
[4]
V
TllFAC+1
FAC 0
FAC[ 1]
FAC[2]
1
FAC[l]
FAC[2]
1
0
FAC 1
1
0
1
FAC 4
FAC[ 1]
FAC[ 1]
FAC[ 1]
FAC[1 ]
FAC[ 2]
FAC[3]
FAC[ 3]
FAC[3]
1
1
1
1
0
2
6
24
24
TllFAC+-O
116
User-Defined Functions
2 3
Notice that all output resulting from a trace is
The s~me function written as a compound statement will produce the following trace output:
'iJZ+FAC N
Z+NxFAC N-l;~OX1Nsl;Z+1'iJ
Tb.FAC+l
FAC 0
FAC[l]
01
1
FAC 1
FAC[l]
01
1
FAC 4
FAC[l]
01
FAC[1]
21
FAC[1]
61
FAC[1]
241
24
T IlFAC+O
A trace vector can also be included as part of a defined function. For example, if the statement TL'lFAC<-l is included within the above function, line 1 will also be traced each time the function is invoked. Of course, more
complex expressions can be used to produce conditional tracing. In such cases, 'the condition produces one or more
values (line numbers) that are assigned to Tb. FAC. This general ization also applied to the stop vector described
below.
The )OBSERVE command, described in Chapter 8, extends the tracing facility. It permits the user to see not only
the final result of a traced statement, but every intermediate result occurring as APL interprets a traced statement.
Stopping
~ecution
A planned suspension of function execution - called a function stop - can be estab lished via a stop control vector.
This vector is set in the same way that a trace control vector is set for a function trace (see "Tracing Execution"
above). The user specifies a function stop by typing an expression of the form
SL'lname+line
where
name
line
is the name of the function.
is an integer or vector of integers that specify the line numbers at which the function is to stop. Of
course, only the integers that correspond to line numbers in the named function are significant.
When each specified line number is reached, APL stops function execution, does a line feed, prints the line number,
and unlocks the keyboard. Function execution is now in a normal suspended state, and can be terminated or resumed by appropriate branching (see "Suspending Execution" below). Specifying a 0 or a to discontinues the stop
control vector; for example, 51'> FAC+O or SIlFAC+tO discontinues any function stops on function FAC.
Shown below is an example of stopping execution of a function named CIRCLE:
SflCIRCLE+2
CIRCLE
CIRCLE[2]
5
suspension activities
~2
13
10
30
CIRCLE[ 5]
Like the trace control vector, the stop control vector can also be used within a defined function -to stop execution
after a certain number of loops, for instance. Editing a line that has a trace or stop control set for it removes the
control for that line. Delel"ing a function also deletes trace control and stop control vectors associated with that
function.
User-Defined Functions
117
Suspending Execution
Execution of a function will be stopped before completion if any of the following occurs: the ATTN key is depressed, an error is encountered (unless sidetracking occurs, see Appendix A), or a user-set stop control is reached
(see "Stopping Execution" above). When a suspension occurs, the APL system prints the name ot the suspended
function and the line number at which the stop applies, and then unlocks the keyboard. At this point, APL is in
execution mode. Anything can be done during function suspension that can be done in the execution mode. As
long as a function is suspended, its local variables are active and can be examined.
The user can resume execution of a suspended function by specifying a branch: entering a branch arrow followed by
a RETURN key will clear that suspension, while specifying a branch to a particular line will resume execution at the
beginning of that line (that is, at the right end of that line). Branching to a line outside a functions' range of line
numbers will terminate the execution of that function.
As a general rule it is best not to leave a function suspended, because the information about that function occupies
space which is precious to the APL user (see "State Indicator" below). In addition, each time the user attempts to
execute an already suspended function, even more information about that function is added to computer memory.
Thus, if the user has no specific reason to leave a function suspended, he shou Id c lear it before proceeding with the
rest of his program. (See also the lSI CLEAR command in Chapter 8.)
State Indicator
The APL system contains a "state indicator" that gives a list of all suspended and pendant functions (that is, a"
"active" functions). A suspended function is one where execution is stopped before completion (see "Suspending
Execution" above). A function is pendant unless specifically suspended. Most commonly, this is observed when one
(pendant) function has called a suspended function. As a rule, suspended functions are stopped between lines, while
pendant functions are stopped in the middle of a line. Note, however, when a function is suspended due to an
error, the error marker may indicate the middle of the line; nevertheless, the function is stopped between that line
and its predecessor. A display of pendant and suspended functions can be obtained via the system command lSI,
with the most recent active function displayed first.
)SI
Z[2]
X[4]
Y[ 3]
Z[2]
X[2]
W[5]
*
*
*
*
An asterisk after an entry indicates a suspended function; absence of an asterisk indicates a pendant function. The
bracketed number after a function name is the number of the next Iine to be executed. If there are no suspended or
pendant functions in the state indicator, no report will result from the lSI command. The number of items in the
state indicator can be determined by typing the expression PI27.
Unlike suspended functions, pendant functions cannot be erased, copied over, or edited. As an example, look at
the state indicator list shown above. Functions Z and W can be edited but functions X and Y cannot. Notice that
function X is I isted as both pendant and suspended; it cannot be edited because it is pendant in one of its states.
Also notice that function Z has been suspended twice.
There is one instance in which a pendant function will not be listed in the state indicator. Suppose a dyadic function is about to be executed, pending resolution of its left argument. Assume that argument is obtained as the result
of some function, say F, and F is ~uspended. Then the dyadic function is pendant, because it is ready to execute as
soon as F is resumed. But the dyadic function is not listed in the state indicator because it has not yet entered a
state of execution. Fortunately, this situation is rare and seldom will confuse the user.
118
User-Defined Functions
The system command )SIV lists the contents of the state indicator, including a list of variables local to pendant and
suspended functions. Using the command )SIV might give the following:
)SIV
Z[2]
X[4]
Y[3]
Z[2]
X[2]
W[S]
*
*
A
AA
B
*
A
AA
B
*
As with the )SI command, the most recent active function is displayed first. This example indicates that variables A
and B are local to function Z and that variable AA is local to function X. Only the local variables of the most
recent acti ve functions can be accessed by the user. Thus, the user can access local variables A and B of the last
invocation of function Z or local variable AA of the last invocation of function X, but not local variables A and B
of the first ~nvocation of function Z or local variable AA of the earlier invocation of function X (see X[2J).
I
The user can clear the state indicator by using the branch arrow (that is, ->-). Eachbrancharrowclearsonesuspended
function and its associated pendant functions; thus, to clear the entire state indicator, the user enters a branch
arrow for each asterisk in the list. For example, the user can clear the previous state indicator like this:
...
)SIV
X[4]
.Y[ 3]
Z[2]
X[2]
*
AA
*
A
AA
B
A
AA
B
W[5]
...*
Z[2]
X[2]
W[S]
*
)SIV
*...
...
)SIV
The )SIV commands in this example show what is left in the state indicator after each branch arrow.
also have cleared the same state indicator by entering four successive branch arrows.
The user could
)SIV
In this case, the )SIV command shows that nothing is left in the state indicator. The easiest way to clear the state
indicator is to issue an lSI CLEAR command.
Xerox APL provides limited protection against "SI DAMAGE". As an example, suppose the user opens function F
and modifies the header, changing the function's type (e.g., monadic to dyadic, result to no-result). He then
attempts to close function F. If F is not suspended, the c lose occurs as usua I. If F is suspended, APL issues a warning (to the effect that references in the state indicator will be damaged by the change to the header) and requests
a response from the user. The user can either order the close to occur with SI DAMAGE or cancel the close in order
to revise the function further, hopefully correcting the header. Only a type change requires this protection. It is
perfectly permissible to make other changes to the header, such as adding locals or renaming the result or dummy
arguments; however, this is seldom advisable (see "Changing Suspended Functions" above).
Locking Functions
A function can be locked during definition or editing by using an opening or closing'" (r:; overstruck with a ~) instead of 9 r:;. A locked function can be executed, copied, or erased, but it cannot be displayed or altered. After a
function is locked, any associated tra~ control or stop 7ontrol cannot be changed. Examples of locking functions are
'iHH
[8]
V
VHH
[8]
'i
[ 8]
User-Defined Functions
119
Intrin$ic Functions
Xerox APL provides the following set of special intrinsic functions (that is, predefined functions that exist in the
A P L processor):
t.FMT
DELAY
DIGITS
ORIGIN
SETFUZZ
SETLINK
TABS
WIDTH
FlO
FlOE
ERRN
ffiRF
ERRX
t.GRF
PAGE
NUNES
HEADER
VFCHAR
t.XL
t.TE
t.CR
These special functions exist in a locked state, normally in workspace WSFNS, (t.GRF normally exists in workspace
GRAF) under account 1. (If the user does not find them under account 1, he should check with the installation manager to determine the correct account). As locked functions, they can be copied, executed, or erased from the
user's program, but they cannot be Ciltered or displayed. (See also Appendix C for information about associating a
particular name with an intrinsic fU"nction. )
t.FMT, PAGE, NLINES, HEADER, VFCHAR, and t.XL
These functions are used to format output reports and are described in Chapter 9.
DELAY
Function DELAY delays execution for a designated number of seconds. It has the syntax
DELAY
x
where x is the approximate number of seconds execution is to be delayed.
by a break; this is treated as an ordinary break in execution.
The DELAY function may be interrupted
DIGITS. ORIGIN. TABS. and WIDTH
Functions DIGITS, ORIGIN, TABS; and WIDTH are each similar to the system command of the same name, except
that each is a function rather than a command and may therefore be used with other functions. The arguments for
the functions are subject to the same restrictions as for the corresponding commands; for example, ORIGIN may only
be set to 1 or O. Each function has an explicit result that is the previous value of the relevant system parameter.
For instance, consider the following function:
"IF
[lJ
[2J
[3]
X
X+ORIGIN X
G
X+ORIGIN X'V
This example will cause APL to execute function G with whatever index origin is specified by the argument of F, and
to restore the index origin to the vaJue that it had before the execution of F.
SETFUZZ
Function SETFUZZ specifies the fuzz value to be used in comparisons (that is, the number of low-order bits to be
ignored in comparisons). It has the syntax
y .... SETFUZZ x
where
120
y
is the previous value of fuzz.
x
sets the current value of fuzz and can be an integer between 0 and 31.
Intrinsic Functions
SETUNK
Function SETLINK sets the va lue of the link in the chain of numbers generated in the use of the roll and deal functions. It has the syntax
y+SETLINK x
where
Y
x
is the previous value of the link.
sets the current value of the link and must be a positive integer (if even, it is also converted to an odd
number).
The results produced by the roll and deal functions are not the links themselves, but rather some function of them.
The length of the chain (before repetition) is 231.
£10
Function tlO is a file input/output primitive; a detailed description is given in Appendix B under "File Input/
Output" .
£IOE
Function FlOE is an alternate file input/output primitive (see also Appendix B, "File Input/Output"). Unlike FlO,
the APL p70cessor deals with errors encountered when using FlOE. This means that certain standard file I/o error
messages result or that sidetracking (see Appendix A) is possible.
ERRN,ERRF, and ERRX
ERRN, ERRF, and ERRX are niladic functions. They are discussed in Appendix A under "Sidetracking on Errors or
Breaks". Briefly, they return the following results:
ERRN
latest error number and line number of that error (2-element integer vector).
ERRF
name of the function containing the error indicated by ERRN (text vector).
ERRX
hexadecimal value of the latest I/O error or abnormal condition (4-element text vector).
f.GRF
L\GRF is the graphic-services primitive used, for instance, to set scaling and window. See the description in Chapter 11 of Xerox APL graphics capability for details.
ATE, .6.CR, IIId.6.WM
These intrinsic functions have varied use in workspace management and are described in detail in Chapter 12 •
.6.TE - performs text editing functions •
.6.CR - permits conversion of user functions to text form and the reverse process •
.6.WM - provides varied information about the user's workspace in the form of APL results.
Intrinsic Functions
121
8. SYSTEM COMMANDS
System commands allow the user to control the mechanical aspects of the APL system, and can be divided into three
categories:
1.
Workspace Control Commands - commands that affect the state of active and saved workspaces.
2.
Inquiry Commands - commands that supply information about the active workspace.
3.
Communications Commands - commands that send messages to the computer operator and commands that
log the user off the APL system.
System commands always begin with a right parenthesis and can be entered when the system is in execution mode or
definition mode. By using the Execute operator (see Chapter 5), system commands can be embedded in APL expressions and can be embedded in a function line. Thus, a system command can be placed under the control of such expressions or functions. Only the first four letters of command names are significant. Name characters after the
fourth are ignored. Thus ")CLEA" and ")CLEAVAGE" are both interpreted to be the ")CLEAR" command. Note
that a blank must separate the command name and any following parameters; for example, )WIDTH 30 is not the
same as )WIDTH30. A number of conventions are used in this chapter to describe the command formats.
1.
Uppercase letters and special symbols must be typed exactly as they appear (except that only the first four
letters of a command are required, as noted above).
2.
Lowercase letters are employed to indicate where in a command to substitute a name or numerical value.
The meanings of the notations in lowercase letters are as follows:
account
User account.
fname
Name of a function.
grpname
Name of a group.
list
List of names (of functi ons, vari ab les, groups).
message
Actual message to computer operator.
n
An integer value.
objname
Name of a function, variable, or group.
password
Assigned to a workspace name to restrict user access to the workspace; can consist of from
one to eight characters.
string
Any sequence of characters not including a blank or carriage return. If a string includes more than 80 characters, those past the 80th are ignored. Strings are used for
range demarcation in certain commands.
vname
Name of a variable.
wsname
A workspace name; can consist of up to 11 characters {letters, underlined letters, numbers,
and t:. and t:. ), as long as the first character is not a number. If longer names are used,
the characters after the fi rst 11 are ignored.
The actual system commands are detailed later in this chapter, but first it is necessary to describe the concept of a
workspace in order to understand how certain commands are used.
122
System. Commands
Workspace Concept
Active Wo...,.c,
Each terminal hooked up to the APL system is considered to be active. Associated with each active terminal is
a storage area in the central computer known as an active workspace. This active workspace contains the
following:
1.
All control information entered by the user during the terminal session •
2.
The variables, functions, and groups entered for calculations during the terminal session.
3.
A state indi cator that keeps track of the names of suspended and pendant functions and at what point they
were interrupted.
4.
Parameters that control several features of the APL system, such as indexing origin, seed for random number generation, line width, and number of significant digits (decimal places) printed. These parameters
all assume default values when the user first signs on to the APL system, but he can respecify most of them
with certain system commands.
•
When the user first signs on to the APL system, the active workspace is clear (that is, there is nothing in it except
the default values of the parameters mentioned above in item 4. An active workspace can also be cleared with the
system command )CLEAR.
SlVed Workspace
The user can save - or rather, store - h is active workspace for future use (via a SAVE command). A workspace can
be saved only in the account in which the user logged on under UTS. Once a workspace has been saved, any user
who knows its name, account, and password (if present) can load it as an active workspace (via a LOAD command);
copy its vcri ables, functions, and groups into active workspace (via a CO PY command); ordrop itfrom his own account
(via a DROP command). (It should be noted that a user cannot drop a workspace from another user's account.) In
addition, the user can list all of the names of saved workspaces in his or other accounts (via a LIB command).
CONTINUE Workspace
An inadv~rtent line disconnect or any of the following commands causes the user's active workspace to be saved
under the name CONTINUE in his account:
)SAVE CONTINUE
)CONTINUE
)CONTINUE HOLD
The CONTINUE workspace is automatically loaded as an active workspace the next time the user logs on, unless
it was created with a )SAVE CONTINUE command. In general, the CONTINUE workspace can be used almost
like any other named workspace. It can be saved, copied, loaded, etc. However, it should only be used
for temporarily saving a workspace, since another )CONTINUE command or line disconnect will save the then
active workspace over what was previously saved. That is, the previous CONTINUE workspace will be wiped out.
)
.
Since the CONTINUE workspace is part of the user's account, it is subject to the granule restrictions imposed by an
installation. If the user's account is near that limit, the CONTINUE workspace may not be saved, and the information in the active workspace may be lost (see "User Accounts", next).
Workspace Concept
123
User Accounts
Each APL user is assigned an account in which workspaces can be saved. The capacity of this user account depends
on the granule restrictions imposed by an installation. If near that limit, the user may not be able to save an additional workspace without dropping sOilething else. When a save is disallowed, the APL system will print a diagnostic, if possible. The user specifies the account when logging on (to CP-V)and when accessing information saved in
another user's account. . He does not have to specify the account when accessing information in h is own account.
The names of saved workspaces in an account can be listed with the )LIB command.
Passwords
The user account number and a workspace name offers some protection against other users accessing a workspace.
To provide even greater protection, a user can assign a password to a workspace when it is saved with the )SAVE
command. The password assigned to a workspace must be specified each time the user references that workspace in
a system command. A password may contain up to eight characters without blanks, semicolons, periods, or commas.
Commands
The system commands are detailed below in alphabetical order, and are summarized by category in Table 5.
Table 5. Summary of System Commands
Command
Meaning
Workspace Control Commands
124
)CATCH
Removes any current catches (i. e., intercepts of assignments to specified variable names).
)CA TCH vname VIA fname
Designates that assignments to vname are to be "caught"
(intercepted immediately after the assignment) and that
the test functi on fname, a ni ladic function with no result, is to be entered. This is a debugging aid.
)CLEAR
Clears active workspace and restores defau It width, digits,
origin, fuzz, random number link, etc.
)COpy wsname
Copi es a" functions, variables, and groups from saved
workspace. Any password must be included, and so must
the account if different than the user account.
)COpy wsname objname
Copies named object(s) - function(s), variable (s),
group(s) - from saved workspace. Any password must be
included, and so must the account if different than the
user account. If more than one object is named, the
object names are separated by blanks.
)DIGITS
Displays current setting for significant digits for output
(i.e., number of decimal places).
)DIGITS n
Specifies significant digits for output (i. e., number of
decimal places), where n can range from 1 through 16.
Also displays the old value of n.
)DROP wsname
Removes a saved workspace from the user's account. Any
password must be included after the workspace name.
)ERASE objname
Removes named object - function, variable, or groupfrom active workspace. More than one object can be
specified, with blanks used as separators.
Commands
Table 5. Summary of System Commands (cont.)
Command
Meaning
Workspace Control Commands (cont.)
)GROUP grpname list
Groups objects and names the group.
)GROUP grpname
Disperses the named group.
)LOAD wsname
Moves a replica of saved workspace into active workspace. If the workspace name is protected with a password, that password must be specified. Also, if the
saved workspace is in another account, that account
must be specified.
)9BSERvE
Specifies that the next (direct input) statement and any
traced function statements executed thereby are to be
"observed". This displays a number of abservatiansshawing intermediate results as APL interprets those
statements.
)ORIGIN
Displays the current index arigin (either 0 or 1).
)ORIGIN n
Sets the index origin, where n can be 0 or I, and displays the previous index origin.
)PCOPY
Same as )COPY, except that an object is not copied if
active workspace contains an object with the same name.
)QCOPY
Same as )COPY, except that the "SAVED" message is
suppressed, i. e., quiet copy.
)QLOAD
Same as )LOAD, except that the "SAVED" message is
suppressed, i.e., quiet load.
)QPCOPY
Same as )PCOPY, except that the "SAVED" message is
suppressed, i.e., quiet protected copy.
Saves active workspace that already has an assigned
name (see )WSI D).
)SA vE wsname
)SEAL wsname
t
Saves active workspace under the specified name. To
save a workspace and protect it with a password, follow
the workspace name with two periods and the password
name (i. e., )SAvE wsname •• password).
t
Saves current workspace as a sealed 'execute-only' workspace with the designated name. All functions in the
workspace are locked and the workspace is saved on file
with the attributes, READ access, NONE, WRITE access,
NON E, EXECUTE access, ALL, under APL.
)WIDTH
Displays the current width of a line of output.
)WIDTH n
Changes the width of a line of output, and displays the
old width. The width parameter, n, can range from 30
to 254; however, values above 130 are meaningless for
normal operations on a standard APL terminal.
)WSID
Displays the name and account (if different than current
user account) of active workspace.
)WSI D wsname
Assigns a name to active workspace, or changes the name
if one already exists and displays the old name.
••
•
)WSID wsncime •• password
A password may also be designated.
tMay include an AUTOSJART statement.
Commands
125
Table 5. Summary of System Commands (cont.)
Command
Meaning
Inquiry and Communications Commands
)CONTINUE
Ends terminal session, and saves active workspace under
the name CONTINUE.
)CONTINUE HOLD
Returns control to CP-V TEL subsystem, and saves active
workspace under the name CONTINUE.
)FNS
Alphabetically lists all defined function names in active
workspace. t
Alphabetically lists the defined function names that
match or exceed the string. t
)FN S string string
Alphabetically lists the defined function names that
match or lie between the strings. t
)GRP name
Lists objects in named group.
)GRPS
Alphabetically lists all group names in active workspace.t
)GRPS string
Alphabetically lists the group names that match or
exceed the string. t
)GRPS string string
Alphabetically lists the group names that match or lie
between the strings. t
)LIB
Lists names of saved workspaces in current user's account.
)LI B account
Lists names of saved workspaces in another account.
)OFF
Ends the terminal session and clears active workspace
(information is lost).
)OFF HOLD
Returns control to CP-V TEL and clears active workspace (information is lost).
)OPR message
Sends message to computer operator, with reply expected; locks keyboard until the user strikes the ATTN
key.
)OPRN message
Sends message to computer operator, with no reply
expected.
101010] [;ophon]
. •••
tape 10
device
file
(
)SET I/O stream pack
Allows routing of regular output, input, and/or 'blind'
I/O channels to files or various devices, and specification of formatting options for device output. Analogous
to the SET command in CP-V TEL.
)SI
Lists the contents of the state indicator -a list of
suspended and pendant functions.
)SI CLEAR
Clears the entire state indicator.
tXerox APL uses the following collating sequence in the process of alphabetizing:
blank or end of name
"
"Kunderlined alphabetic letters <A. through 1)
alphabetic letters without underlines (A through Z)
digits
126
Commands
Table 5. Summary of System Commands (cont .)
I
I~-
Command
Meaning
Inquiry and Communications Commands (cont.)
)S10FF
)S10N
Prevents an error from suspending an active function
containing the erroneous statement.
..
Restores normal state indicator control. If an error
occurs in an active function line, APL suspends the
function at that line (assuming sidetracking does not
occur, see Appendix A).
)S1V
Lists the contents of the state indicator - a list of
suspended and pendant functions and the local variables named by those functions.
)S1V CLEAR
Same as )S1 CLEAR.
)SIV OFF
Same as )S1 OFF.
)SIV ON
Same as )S1 ON.
)SYMBOLS
Displays the current length of the symbol table (that is,
the number of names allowed in it) and the number of
un used entri es.
)SYMBOLS n
Sets the length of the symbol table to no less than the
number of names indicated by n (the maximum n allowed
is 2001). Also displays old value. This command will
be executed only if the current workspace is clear.
)TABS
Displays the current tab settings.
)TABS n
Sets tabs. The n parameter indicates column positions
and can be a scalar (for equally spaced tab settings) or
a vector of up to 16 numbers in increasing order (for unequally spaced tab settings).
)TERM1NAL n
Identifi es to the A PL system the input/output devi ces
being used, where n can be any of the following
values:
)TERMINAL INPUT n
)TERMINAL OUTPUT n
1 for 2741 terminal (or equivalent) with standard
APL typeba II.
2
indicates 2741 terminal (or equivalent) with
non-APL typeball.
3
for Teletype Model 33 or equivalent.
4
for I ine printer format output or card reader
format input.
13
for typewriter-paired APL/Ascn terminals
(e.g., Tektronix 4013).
14 for bit-paired APL/ASCII terminals.
Commands
127
Table 5. Summary of System Commands (cont.)
Command
t
Meaning
)VARS
Alphabetically lists all global variable names in
active workspace. t
)VARS string
Alphabetically lists the global variable names that
match or exceed the string. t
)VARS string string
Alphabetically lists the global variable names that
match or Ii e between the strings. t
Xerox APL uses the following collating sequence in the process of alphabetizing:
blank or end of name
1:1
1:1
underlined alphabetic letters (6. through~)
alphabetic letters without underlines (A through Z)
digits
)CATCH
Debugging Aid for Intercepting Assignments
The )CATCH command is primarily a debugging tool. It permits the programmer to "catch" (or intercept) each assignment to a specified variable name, immediately after that assignment has been executed. The format of the command invoking a catch is
)CA TCH vname VIA fname
where vname is the name of the variable (which may be local or global) and fname is the name of a "test" function. The test function is defined by the user according to his debugging needs. The only restriction is that this
function must be niladic with no result. This restriction isolates the test function from the statement or statements
assigning values to the specified variable. If the fname is undefined or does not indicate a niladic, no-result function, no error message occurs - the catch is simply ignored (this can be used to advantage - see Example 3).
Suppose the programmer has invoked the following catch,
)CATCH V1 VIA F1
then all assignments to the name V1 cause test function Fl to be called. This includes indexed assignments. F1 is
called regardless of whether V1 is a local or global variable. The programmer can modify this catch whenever he
wishes to enter a different test function. For example,
)CATCH V1 VIA FTWO
After the above modification, assignments to V1 cause test function FTWO to be called (instead of F1).
The programmer can also invoke a second catch. For instance,
)CATCH VAR2 VIA FOTHER
He cou Id have both catches enter the same test function as in the next exampl e.
)CATCH VAR2 VIA FSAME
)CA TCH V1 VIA FSAME
He cannot, however, invoke a third catch; this attempt produces a "BAD COMMAND" error.
The programmer can remove any current catches by issuing the command.
)CATCH
Following this removal, he is free to invoke one or two new catches.
128
Commands
Catches are not saved when a workspace is saved, so loading a workspace does not auto mati cally reinstall catches.
The )CLEAR command also removes any current catches.
The simplicity of the catch command may obscure its power as a debugging aid. This power is brought to bear by
the test function. A few hypothetical examples are given below to suggest the potential of catch capability.
Example 1. Using a catch to display values assigned to vname.
)CATCH X VIA SHOW X
'JSHOW X
IX IS ';XV
[1]
As long as this catch is in effect, every assignment to X wi II cause the new value of X to be displayed.
Example 2.
Using a catch to stop execution when a particular value is assigned to vname.
(Assume that X is a scalar and 77 is the value of interest.)
)CATCH X VIA
'JCHECK
CHECK
+Ox\X~77
[1]
[2]
[3]
SI::. CHECK+STOP
STOP: V
As long as this catch is in effect, each assignment to X will be tested at line 1 of the CHECK function. If X is
not 77, line 1 resumes execution (branching to line 0, causing CHECK to exit). When X receives the value 77,
line 2 is executed. line 2 sets the stop-vector for the CHECK function so that when the line labeled STOP is
reached, CH EC K wi II suspend execution.
Example 3.
Using a catch to change the value of vname.
(Note that this does not affect the value used by the statement making an assignment to vnamej the catch is isolated.)
[1]
)CATCH X VIA CHANGE
VCHANGE ; CHANGE
X+O V
As long as this catch is in effect, each assignment to X that occurs "outside" the CHANGE function will causeXto
be set to O. The assignment at liRe 1 of the CHAN GE function wi II not be "caught" because calling the function
temporarily declares the name CHANGE to be a local variable (shadowing the definition of CHANGE as a test function); see the function header line.
Suppose the following statement is executed with the above catch in effect.
x
+ 100 + X+55
The answer of 155 results in the following way.
1.
The va lue 55 is obtained.
2.
X is assigned the value 55.
3.
The catch occurs.
4.
X is set to 0 by the CHANGE function.
5.
Execution of the original statement resumes, undisturbed (so far, at least) by the catch. This means that the
value 55 is the right argument of the next addition.
6.
100 plus that argument yields 155.
Commands
129
7.
This value, 155, becomes the right argument of the next addition.
8.
The value of X is obtained; it is now 0".
9.
0 plus 155 yields the final result.
)CLEAR
Clearing Workspace
This command deletes all groups, functions, variables, and the state indicator from active workspace. Furthermore,
it resets:
•
Random number link.
•
Fuzz setting.
•
Origin (1).
•
Width (120 for terminals equivalent to an IBM 2741; otherwise, 72).
•
Significant digits (10).
•
Symbol table size (261).
•
Workspace identification (CLEAR WS).
•
State indicator control (ON); see also the )SI or )SIV command description.
•
Current catches (none), see the )CATCH command descriptoion.
•
Error number (0); see "Sidetracking on Errors and Breaks" in Appendix A.
•
Error location (line number 0 and function name an empty text vector); see also Appendix A.
It does not change the latest tab setting that was specified by the user during the current APL session.
session begins, an initial tab setting of zero is assumed.) The form of this command is
(When an APL
)CLEAR
The APL system responds to this command by printing the message CLEAR WS.
Example
)CLEAR
CLEAR WS
>CONTINUE and )CONTINUE HOLD
Signing Off and Saving Active Workspace in CONTINUE
These commands are similar to the )OFF and )OFF HOLD commands described later in this. chapter, except that the
active workspace is saved in workspace CONTINUE instead of being deleted. This workspace is automatically
loaded the next time the user logs on. The active workspace is also automatically saved in workspace CONTINUE
if the phone is accidentally disconnected of if a )SAVE CONTINUE command is given.
The )CONTINUE command saves the user's active workspace in a workspace named CONTINUE, and ends the termina I session. Its form is simply
)CONTINUE
A successful )CONTINUE command wi' I produce a save report (time and date saved) and the UTS log-off
messages. If not enough room remains in the user's account to save the workspace, the system prints an error
130
Commands
message. If this happens, the userwHI have to delete some workspaces or other files before any APL workspaces
may be saved.
. ••'
The )CONTINUE HOLD command saves the user's active workspace in a workspace named CONTINUE and retums
control to the CP-V Terminal Executive Language (TEL). The form of this command is
)CONTINUE HOLD
Note: If ai user's workspace is passworded, the password is retained in the saved fi Ie. In this case, CONTINUE is
not auto mati ca IIy loaded the next ti me the user logs on.
Caution: If an account already contains a passworded CONTINUE workspace, any subsequent CONTINUEwili fail
unti I the passworded version is deleted. Sealed workspc1ces cannot be saved with CON TIN UE.
A successfv I save resu Its in a save report and in CP-V printing a prompt character. (This is the same as the I prompt
character shown in CP-V documentation; it's just that the APL typeball prints a instead of a I.) The user is then
free to enter any other CP-V commands at the TEL level. If the save is unsuccessfu I (because not enough fi Ie space
is left in the user's account), an error message wi II be printed and the user wi II have to delete some saved workspaces
or other fi les before saving any APL workspaces.
0
0
If either form of the )CONTINUE command is given during function definition mode, the currently open function
is closed by APL. When the CONTINUE workspace is loaded later, APL automatically reopens the function and
prompts the user to continue function definition.
The CONTINUE workspace can be used almost like any other named workspace. It can be saved, copied, loaded,
etc. However, it should only be used for temporarily saving a workspace since any previous CONTINUE workspace
will be wiped out by a new CONTINUE workspace save.
Examples
) CONTINUE
CONTINUE
SAVED
10:57 JUN 30,'72
CPU = .0193 eON= :06 INT
14 eHG
=0
)CONTINUE HOLD
CONTINUE
SAVED 10:56 JUN 30,'72
o
}COPV
1
1
Saves active workspace in CONTINUE and
ends terminal session after printing save report and CP-V log-off messages.
Saves active workspace in CONTINUE and
returns control to TEL after printing save
report. TEL prompts for commands with
the character.
0
Copying Information from Saved Workspace to Active Workspace
The copy command enables the user to copy information from a saved workspace to the active workspace. The information can consist of one, several, or all of the functions, global variables, and groups in the saved workspace.
This command may take any of the following forms:
)COpy
)COpy
)COPY
)COPY
)COPY
)COPY
)COPY
)COPY
wsname
wsname objname
wsname. account
wsname. account objname
wsname .. password
wsname •• password objname
wsname. account. password
wsname. account. password objname
where
wsname
is the name of the saved workspace.
objname
is a variable name, function name, or group name. More than one object can also be specified,
with blanks u~d as separators between the objects.
Commands
131
account
is the user account under which the workspace was saved. This option is used to access a workspace
in another account; it is not necessary when accessing a workspace in the current user's account.
password
is a user-assigned password. If a password was used when the workspace was saved, that password
must be used to access the workspace.
I'
)COPY
cannot be used to access a sealed workspace.
Note that if a workspace is saved with a password, that password must be included in the copy command. Also, if
a workspace is being copied from another user's account, the account must be specified in the copy command.
When all of a saved workspace is copied, only functions, global variables, and groups are copied. If copied functions had sidetracks (see Appendix A), stop vectors, or trace vectors set, then these settings also apply to the active
workspace. All referents of a copied group are themselves copied into the ac1"ive workspace. For instance, suppose
group G1 is copied, where G1 contains A, B, and G2 with G2 being another group containing X, Y, and Z. Then
the following are copied into active workspace: G1, G2, A, B, X, Y, and Z. The digits, line width, origin, random seed, and state indicator are not copied.
A copy attempt may fail if there is not enough room in the active workspace or if there are too many new symbols.
After issuing the appropriate error message, APL restores the original active workspace (as it existed prior to the
copy command). An infrequent error message of this type is "TOO BIG TO LOAD". This happens when copying
from a different account in which two conditions are met. First, the workspace being copied from is large (so large
that it cannot even be loaded by the current user). Second, the referenced account was allocated more computer
memory than is avai lable to the current user's account (memory allocations are specifi ed by the insta Ilation manager).
This difficulty can be circumvented with the cooperation of the owner of the larger account. He can copy portions
of the large workspace, forming one or more smaller workspaces. After this cooperative activity, the current user
can copy required objects out of those smaller workspaces.
Note: Due to extensive input/output processing, a copy command may take a long time to complete. This is particularly true if either the active or copied workspace is relatively large.
If a copy command is issued during function definition mode,~he currently open function is temporarily closed.
When the copy is completed, the function is automatically reopened. The copy may have replaced the cu rrent
function. If the copy command names functions that are pendant in the active workspace, they are not replaced.
Suspended functions may be replaced and may cause an SI DAMAGE error message tobe issued. Use of the )PCOPY
command precludes this possibility.
The )PCOPY command, the protected copy command, functions the same as the )COPY command except that an object is not copied if active workspace already contains an object with the same name.
A group of objects can be copied even though the group definiHon is not. This happens if the group name matches
a current pendant function or if the name matches any object in the case of )PCOPY. Alternatively, a group
definition may be copied but some of its objects not copied.
Examples
HENRY
)COPY HENRY.ACCT33.SECRET
SAVED 10:56 JUN 30.'72
HENRY
)COPY HENRY
SAVED
}
10:56 JUN 30.'72
1
HENRY
) COpy HENRY COS MAT
SAVED 10:56 JUN 30.'72
HENRI
)COPr HENRY • • SECRET
SAVED 10:56 JUN 30. '72
•
132
•
Commands
•
Copies all of a saved workspace named HENRY, which
was saved with the password SECRET in another user's
account (account ACCT33); and produces a save report giving the time and date HEN RY was saved.
Copies an entire saved workspace named HENRY from
the user's own account ane! produces a save report
giving the time and date HENRY was saved.
)
Copies a function named COS and a group named
MA T from a saved workspace named HE NRY in the
user's own account; and produces a save report giving
the time and date HENRY was saved.
)
Copies all of a saved workspace named HENRY, which
was saved with the password SECRET in the current
user's account; and produces a save report giving the
time and date HENRY was saved .
)DIGITS
Specifying Number of Significant Digits
The digits command allows the user to set the number of significant digits in noninteger numerical output to some
number between 1 and 16 inclusive. Without this command the APL system will display a maximum of 10 significant
noninteger digits. Only displayed output is affected by this command; internal calculations are not affected. The
command has two forms
)DIGITS
)DIGITS n
where n indicates the number of significant noninteger digits to output and can be any number from 1 through 16.
The first command form, )DIGITS, simply causes the APL system to print the current setting for singificant digits.
The second command form, )DIGITS n, changes the significant digits to be output and causes the APL system to print
the previous setting for singificant digits. It should be noted that internal precision of the computer provides a maximum of 16 digits for some simple operations, 15 or less for more complex operations. if )DIGITS 16 is used, at least
the last digit is subject to error; for this reason 16 is not a recommended setting.
Examples
)DIGITS
}
User requests significant digits be displayed, -and APL responds with
current setting.
)DIGITS 15
WAS 10
}
User sets significant digits to 15, and APL responds with previous
setting.
4+9
0.444444444444444
}
User requests calculation, and APL responds, showing 15 significant
digits.
}
}
User sets significant digits to 5, and APL responds with previous
setting.
IS
10
)DIGITS 5
WAS 15
~
/
)4+9
0.44444
User requests calculation, and APL responds showing 5 significant
digits.
The number of significant digits to be output can also be changed with the DIGITS function described in Chapter 7,
"Defined Functions".
)DROP
Droppi ng
0
Saved Workspace
This command allows the user to remove a saved workspace from his account. It has two forms - one for removing unprotected workspaces and another for removing workspaces protected with a password. These twa command forms are
)DROP wsname
)DROP wsname •• password
where
wsname
password
is the workspace name to be dropped.
is the password that was saved along with the workspace.
If the workspace is not found or if a proper password is not provided, APL returns the message WS NOT FOUND. If
the workspace is deleted, APL returns a message identifying the workspace and the time it was last saved.
Examples
)DROP PAYROLL •• SAVINGS
PAYROLL SAVED 10: 37 JAN 30.' 75
)DROP DANEEN
WS NOT FOUND
}
Removes workspace PAYROLL, saved with the password
SAVINGS, from the user's account.
Attempts unsuccessfully_ to drop workspace named
DANEEN. Either the workspace does not exist or a
needed password has not been provided.
)DROP may not be used to delete files other than APL workspaces. If an attempt is made to delete an existing file
which is not an APL workspace, BAD FILE REF is reported.
}
Commands
133
Removing Objects From Active Workspace
)ERASE
The erase command a IIows the user to delete one or more named objects - functions, globa I variables, groups - from
the active workspace. This command has the form
ERASE objname
where objname is the name of the object - function, variable, or group - to be erased. Note that it is the object
that is erased; its name remains in the symbol table. More than one object name can also be specified in the erase
command, with blanks used as separators between the names. Including the names of global variables and functions
in an erase command causes the actual variables and functions to be erased. If a group is named in the erase command, that group definition is erased along with any functions or variables named in the group; however, if it also
names other groups, they are dispersed (group definitions are deleted, but not their referents). For example, suppose Gl is a group containing variable names A and B plus group name G2. Further suppose that G2 contains variable names X and Y. Then erasing G 1 deletes G 1, A, B, and G2; but variables X and Yare retained. Pendant
functions cannot be erased. During function definition, if the function being defined is erased, its current definition
is abandoned (equivalent to closing the function and then erasing it).
Examples
)ERASE MATHFUNCTIONS
Erases a group named MATHFUNCTIONS and the functions and variables it names. It disperses any group
named within the group MATHFUNCTIONS.
)ERASE PAYROUTINE GROSS INS
Note:
}
Erases a function named PAYROUTINE and two variables named GROSS and INS.
)ERASE will not remove local variables.
)FNS
Listing Function Names
This command allows the user to list alphabetically the names of functions in the active workspace.
are acceptable:
Three forms
)FNS
)FNS string
)F N S stri ng 1 stri ng2
The first form displays all function names. The second form displays all function names that match or exceed the
"string lIt in an alphabeti c ordering. The th ird form displays all function names that match or exceed "string 1" and
are also less than or match "string2". Alphabetic ordering is illustrated in the examples below. Note particu larly
the first )FNS command since it indicates where each name character Iies in a Iphabetic order.
Examples
F
FF
F
)FNS
Ff). FE:. FF
)FNS FF
FX FXY FO Fi
)FNS F FF
FA n. FF FF
)FNS FFF FX
FA
FX
FXY FO
Fi
S
FXY FO
Fi
S
S
FX
)FNS FXY FXY
FXY
F
FA
t
)FNS
Ff).
A S4
FE.
FF
FX
Where "string" is any sequence of characters not including a blank or carriage retum. Ifa string includes more
than 80 c;;haracters, those past the 80th are ignored. Strings are used for range demarcation.
134
Commands
)GROUP
Defining a Group
This command allows the user to reference a group of names - variables, functions, other groups, or just
names - collectively. Group definitions can be used in erase and copy commands to facilitate erasing and copying
a group of related objects. The command to define a group is
)GROUP grpname list
where
grpname
is the name of the group. A group name follows the same formation rules as a variable or function
name, except that a group name cannot be the same as a function or global variable in the workspace.
list
is a list of the names that make up the group.
Names can be added to an already existing group by merely repeating the group name in any of the command forms
)GROUP grpname grpname list
)GROUP grpname list grpname
)GROUP grpname list grpname list
A group can be dispersed with the command form
)GROU P grpname
This form disperses the group; that is, removes the name references previously associated with grpname. The names
and their references are not themselves erased - only the group identity is lost. An erase command could have been
used to remove the group, but the erase command removes the group and deletes the group referents (the actual functions or variables) from active workspace.
Examples
)GROUP PROBl COS TAN A B
}
Defines a group named PROB1, consisting of the variable and function names COS, TAN, A, and B.
)GROUP PROBl PROBl D ST
}
Adds the variables D and ST to the already existing
group named PROB1.
)GROUP PROBl
}
Deletes the group named PROB1 from the active workspace. The referents of PROBl are not deleted.
Note that the last example disassociates the function and variable names from the group, but does nqt delete actual
functions and variables from the'active workspace. The )GRPS command can be used to verify that the group named
PROB1 ha!s been deleted, and the )FNS and )VARS command can be used to verify that the named functions and
variables.still remain in the active workspace.
)GRPS
)FNS
COS TAN
)VARS
A
B
D
ST
Also see the )GRP and )GRPS commands below, which list the members of a group and the names of groups in active
workspace respectively.
Commands
135
)GRP
Listing the Members of a Group
This command allows the user to list object names making up a group. It has the form
)GRP name
where name is the group name. The APL system responds by printing the names of the objects in the named group.
Examples
)GROU'P G1 ABC
)GRP G1
A
A
X
X
G1
G2
X
)GRPS
B
C
)GROUP G1 G1 D
)GRP G1
C
D
B
)GROUP G1 X Y Z G1 G2
)GRP G1
D
G2
A
B
C
Z
Y
)GROUP G2 X A F1
)GRP G2
F1
A
)GRPS
G2
) GROUP G1
)GRPS
)GRP G1
)GRP G2
F1
A
Listing Group Names
This command allows the user to list alphabetically the names of groups in the active workspace. Three forms are
acceptable:
)GRPS
)GRPS string
)GRPS string 1 string2
The first form displays all group names. The second form displays all group names that match or exceed the "string"t
in alphabetic ordering. The th ird form displays all group names that match or exceed "string 1" and are also less than
or match "string2". Alphabetic ordering is illustrated in the examples below. Note particularly the first )GRPS
command since it indicates where each name character lies in alphabetic order.
Examples
G
GG
G
)GRPS
GfJ.
)GRPS
GH GHI
)GRPS
GA GfJ.
)GRPS
GtJ.
Gli GG
GG
GO G1
G GG
G(l, GG
GGG GH
GH
GHI GO
G1
H
GHI GO
G1
H
H
GH
)GRPS GHI GHI
GHI
G
Gf!
t
)GRPS A H8
GfJ. Gli GG
GH
Where "string" is any sequence of characters not including a blank or carriage return. If a string includes more
than 80 characters, those past the 80th are ignored. Strings are used for range demarcation.
136
Commands
lUI
Listing Names of Saved Workspace
This command allows the user to Iist the names of workspaces saved in his own account or another user's account.
If a password was saved with a workspace, the workspace name is listed, but not the password. To list names of the
current user's saved workspace, use the command
)LlB
To list names of saved workspaces in another account, use a command of the form
)LlB account
)LlB will only list workspaces saved by APl release A01 or later. If workspaces are subsequently copied by nonAPl processors such as PCl, they may not be listed by)LlB.
Examples
)L1B
APLQUIZ
APLS1DR
PROB1
PROB2
)
)L1B REI07207
ED1TFILE
FACTOR
PAYROLL
lLOAD
}
Lists names of saved workspaces in the current user's
account.
Lists names of saved workspaces in another account
(account REI07207).
Retrieving a Saved Workspace
This command allows the user to load a replica of a saved workspace into his active workspace. The saved workspace may be retrieved from a user's own account or another account. This command may take any of the following
forms:
)lOAD
)lOAD
)lOAD
)lOAD
wsname
wsname.account
wsname •. password
wsname.account.password
where
wsname
is the name of the saved workspace.
account
is the account under which the workspace was saved. This option is necessary only when accessing
a workspace saved in another account; it is not necessary when accessing a saved workspace in the current
user's account.
is a user-assigned password. If a password was saved with a workspace, that password must a Iso
password
be used to access the workspace.
Note that if a saved workspace is being retrieved from another account, the account must be specified in the load
command. Also if the workspace was saved with a password, that password must be included in the load command.
In response to a successful load, the APl system prints a message giving the time and day that the workspace was
saved. If the workspace is not found or if a proper password has not been used, APl prints the message WS NOT
FOUND.
If a workspace has been saved using the AUTOSTART option (Pages 130-131), execution will start automatically
after the load.
Commands
137
If a workspace was saved during function definition mode, thEe )LOAD command causes APL to automatically reopen
that function and prompt the user to continue function definition or editing. (He may choose to close the function
immediately. )
Examples
HENRY
)LOAD HENRY
SAVED
}
Loads workspace HENRY into active workspace and
prints a save report. Workspace HENRY was previously
saved in the current user's account.
HENRY
)LOAD HENRY •• SECRET
)
SAVED 15:28 JUN 01.'72
Loads workspace HENRY into active workspace and
prints a save report. Workspace HENRY was previously
saved with possword SECRET in the current user's
account.
HARRY
)LOAD HARRY.ACCT33.SECRET
}
SAVED 15:28 JUN 01.'72
Loads workspace HARRY into active workspace and
pri nts a save report. Workspace HARRY was previously
saved with possword SECRET in account ACCT33.
)OBSERVE
15:28 JUL 01.'72
Observing Intermediate Results as APL Interprets a Statement or Traced Function Statements
The )OBSERVE command allows the user to observe intermediate resu Its developed by APL as it interprets a statement.
This could be thought of as a "super-trace" capability. The command format is
)OBSERVE
Following an )OBSERVE command, the succeeding statement is observed along with any traced function lines that
are encountered. Subsequent direct statements are not observed unless the user precedes each of them by a new
)OBSERVE command. Thus, an )OBSERVE command is short-lived - applicable to only one direct statement. By
setting trace-vectors for functions to be encountered during an execution, however, the user can observe arbitrarily
selected statements unti I he issues another direct input line.
While an )OBSERVE command is in effect, Xerox APL displays a series of observations. An observation consists of
displaying: the current line being executed, a marker (error caret) beneath some character in that line, and the
value resulting at that point in execution (empty results, as usual, cause no value to be displayed). The observation marker often marks the leftmost point reached, so far, during APL interpretation of the line; however, when an
ope,rator yields its result, the marker is placed below the operator for clarity. (The only exception is the executeoperator, in which case the "leftmost" ru Ie applies.)
For "observed" lines, observations occur for:
•
•
•
•
Each operator resu It
Each function result
Arguments that have not already been observed on this line
Indexed arguments
Observations are not made for assignments since the assigned value has already been observed prior to the assignment. Observations are also not made for the full variable when it is used as an indexed variable; this eliminates
lengthy displays in cases such as the following sample )OBSERVE command.
A+1000P'GORP'
)OBSERVE
B+A[ 5]
B+A[5]
"
5
B+A[ 5]
G
138
Commands
"
This is the observed line.
}
}
Observation of the argument 5.
Observation of the indexed argument A[5J.
Note in the above sample that A was not displayed. This is fortunate since itsdisplay would produce 1000 characters,
most of which contribute nothing to the observed statement.
The )OBSERVE command has three valuable usages: fo'r debugging, for learning how a calculation is performed, and
for developing better APL functions. Its value in debugging is obvious. Suppose a complicated APLstatement produces a LENGTH ERR. By using the )OBSERVE command and reissuing that statement, the programmer can view development of values leading up to the error and readily see what caused the problem.
Usage of the )OBSERVE command as a learning tool can be a tremendous timesaver. When presented with a new
APL statement or function, the user can spend a great deal of time analyzing how it accomplishes its result. By
observing a sample run, the interpretation path and values can be readily inspected, simplifying analysis greatly.
The reader might apply this process to the following function.
[1]
VPRIMESUPTO N;R;I;J
(Af (O;t (1+ R) ° • I J) V«R+1 L N* 0 • 5)°.
=1) ) / J+l+ 1+1 N-l V
This function produces the prime numbers existing up to the positive integer specified as its argument. To observe
this function in a sample case, the user might proceed as follows:
TtJ.PRIMESUPTO+l
)OBSERVE
PRIMESUPTO 15
Set to trace line 1 of the function.
Request observations.
Call the function.
About 30 observations are made; then the )OBSERVE
command "disappears".
There are at least two ways in which the )OBSERVE command can be used to develop better APL functions. First,
redundant calculations are made obvious and the programmer can then eliminate such redundancies. The following
function is an inefficient version of the PRIMESUPTO function. The reader might try observing the function to discover how apparent such redundancies become under the )OBSERVE command.
[1]
VPRIMESUPTO N
(At (O;t(1+1LN*O.5)0. I (1+1N-l»V«lLN*O.5)0.= (IN-l)))/1+1N-1V
The PRIMESUPTOO function takes considerably more execution time (and produces more observations) than the
PRIMESUPTO function shown previously.
The second way in which )OBSERVE is useful for developing better APL functions is not obvious. It depends upon
the creati'vity and imagination of the user. By viewing the manner in which a calculation is carried out, the creative user may recognize patterns that can be more easily produced by other calculations. In other words, observations can suggest alternate approaches to solving a given problem.
One final;note about the )OBSERVE command should be presented. Suppose the user suspends execution during an
observed run by hitting the break key, for instance. This removes the )OBSERVE command. Subsequent execution
will not be observed unless the user issues a fresh )OBSERVE. As stated earlier, this command is short-lived. At
times its short life can be inconvenient, but considering the voluminous output possible with the )OBSERVE command
this is more often a convenience.
lOFF and lOFF HOLD
Signing Off
These commands provide two ways for the user to sign off the APL system. The )OFF command deletes the active
workspac~ and logs off both A:L and CP-V (producing the CP-V log-off messages). Its form is simply
)OFF
The )OFF HOLD command also deletes the active workspace, but logs the user off APL and returns control to the
Terminal Executive Language (TEL) subsystem. The form of this command is simply
)OFF HOLD
In response to the )OFF HOLD command, the TEL subsystem prints a ° prompt character to signal that it has control. (This is the same as the ! prompt character shown in CP-V documentation; it's just that an APL typeball prints
a instead of a /.) The user is then free to enter any other TE L commands.
0
No.te: IfAPLhas been called from a load module, not directly from TEL, )OFF HOLD returns to the calling load module.
Commands
139
Examples
)OFF
.0095 CON= :01 INT
CPU
4
CHG
Ends APL system communication and returns control to
} TEL.
)OFF HOLD
)OPR and )DPRN
Logs the user and produces the CP-V log-off messages. (See Figure 1 in Chapter 2 for a description of
the log-off messages.)
Communicating With Computer Center Operator
These commands allow the user to communicate with the operator in the computer center. The )OPR command allows
the user to send messages to the operator and request a reply; it has the form
)OPR message
where message is the actual message to the operator; it cannot exceed 120 characters. The APL system responds by
printing the wordSENTand by locking the keyboard until the user depresses the ATTN key. Note that the operator's
console will not include special APL characters, so messages should be limited to ordinary alphanumeric characters.
The )OPRN command is simi lar to the )OPR command except that no reply is expected from the computer operator.
This command has the form
)OPRN message
where message is the same as described above.
then unlocks the keyboard.
The APL system responds to this command with message SENT and
Examples
)OPR
CP-V UP SUNDAY?
Illustrates sending message to operator and
receiving reply.
SENT
YES ,FOR AWHILEo
)OPRN
SENT
)ORIGIN
TRIAL MESSAGE.
1
DON'T REPLY.}
Illustrates sending message to operator, with
no reply expected.
Setting Index Origin
This command allows the user to set or display the origin for indexing on arrays and for operators related to indexing.
There are two origins available - 0 and 1. The operators affected are index of and index generator (I), indexing
([ J), grade up (11), grade down (1'), and random (?). To set the origin to 1 or 0, the command form is
)ORIGIN n
where n is either 0 or 1. This command causes the APL system to reset the index origin and to print a message indicating the previous index origin. If the user does not supply parameter n when issuing this command, the current
index origin will be displayed. Note that the )ORIGIN command affects the active workspace and is saved
along with a workspace. The index origin can also be changed with the ORIGIN function described in Chapter 7, "Defined Functions".
Examples
)ORIGIN
IS
1
WAS 1
WAS
140
) ORIGIN
0
)ORIGIN 1
0
Commands
)PCOPY
Copying Information from Saved Workspace to Active Workspace
This command, the protected copy command, functions the same as the copy command except that an object is not
copied if the active workspace already contains an object with the same name. See the )COPY writeup earlier in
this chapter.
)QLOAD,)QCOPY, and )QPCOPY
Qui et Load and Copy Commands
)QLOAD, )QCOPY, and )QPCOPY are slight variants of )lOAD, )COPY, and )PCOPY. The "Q "stands for quietthe "SAVED" message normally shown at the conclusion of a load or copy is suppressed on a quiet load or copy. No
other message (i. e., error diagnostic) is suppressed by the qui et commands.
Certain APl application programs benefit from the quiet commands - programs that use execute-operations to load or
copy without user intervention. Since the user is unaware that such load or copy commands are executed, he would
be puzz led by "SAVED" messages.
The quiet commands should be inserted in programs only after the application is well checked out. In the event of
an error subsequent to a quiet load or copy, it may be difficult to isolate the problem for lack of knowledge about
the workspace environment.
)SAVE
Saving Active Workspace
This command saves a copy of the active workspace in the current user's account • It does not allow the user to save
the active workspace in another account. This command may take any of the following forms:
)SAVE
)SA V E wsname
)SA VE wsname •• password
)SAVE ;expressi on
)SA VE wsname ; expression
)SAVE wsname •• password ; expression
The first form saves a workspace that a Iready has a name; that is, one that was named with the )WSID command or
that was previously saved with a name and then loaded into the active workspace.
The second form saves a workspace and assigns a name to it (where wsname is the name of the workspace). Like
other APl nal11es, the workspace name can consist of one or a combination of letters (A to Z, or A to?:), numbers,
and l1 or Il, with the restriction that the first character cannot be a number or the combination Tl1 or Sl1. Unlike
other APl names, a workspace name is limited to 11 characters; more characters can be used but the APl system wi II
ignore them. It is strongly recommended that only letters and digits be used in workspace names. The other characters can 'lead to confusion if those names are presented to subsystems of UTS other than APl.
The third form saves a workspace and assigns a name and a password to it (where wsname is as described above). A
word of caution is necessary about using passwords in the save command. If a saved workspace already exists with a
given name and password, specifying the same name with a new password in the save command wi II not change the
password. Instead it results in the error message-BAD FILE REF. The previous passworded workspace must be deleted
before a new version can be saved. To delete the prior workspace, use )DROP with the n':lme and password •
•
A sea led workspace may not be saved. If the current workspace was loaded as a sealed workspace or the )SEAl command has been issued, the workspace can no longer be saved by )SAVE or )CONTINUE. Attempts to do so will result in BAD FILE REF error.
AUTOS TART • The fourth, fifth, and sixth forms are simi lar to the first three except that the expression to the right
of the semicolon is saved with the workspace, and execution of that expression occurs automatically each time the
workspace is loaded. The expression must fit on the same line as the )SAVE command and may be any executable
APl expression. Typically it will be a call to a user-defined function which initiates processing and requests user
interaction. The 'autostart' form of )SAVE may be issued only in direct input mode (not in evaluated input, function definition, or eXt,>:ute made).
When a workspace is successfully saved, the APl system prints a save report giving the name of the workspace and
the time and date of ,the save. This is printed on the line following the save command. The )SAV£ command also
Commands
141
updates the current warkspace identification, i.e., WSID. The name of the saved workspace along with its password
(if any) becomes the WSI D for the active workspace. If the workspace cannat be saved - because it exceeds the
ava'i lable space in the user account - the system prints on error message. In this case the user wi II have to delete
some workspaces or other files from his account before he can save any APL workspaces.
If a save command is issued during function definition mode, the currently open function is temporarily closed. The
saved workspace carries an indication that a function should be reopened on )LOAD. After the save command, APL
reopens the function and prompts the user to continue function definition or editing.
Examples
)SAVE
SAVED
CONTINUE
15:28 JUL 01,'72
}
Saves copy of an active workspace that al ready has a
workspace name (CONTINUE), and produces a save
repart.
KAWA
)SAVE KAWA
SAVED
15:28 JUL 01, '72
}
Saves copy of active workspace with the name KAWA,
and produces a save report.
SANDY
)SAVE SANDY •• PAT
SAVED 15:28 JUL 01,'72
}
Saves copy of active warkspace with name SANDY and
password PAT, and produces a save report.
)SAVE FILEOPS; FIODESCRIBE
,
,
)SEAL
FIODESCRIBE, in this case, may be a functian which
identifies the nature of the workspace and permits the
user to request detailed descriptions of file I/O functions. When FILEOPS is loaded, FIODESCRIBE will
be called automatically.
Saving a 'Sealed' Execute-Only Workspace
This command may take any of the following forms:
)SEAL
)SEAL
)SEAL
)SEAL
wsname
wsname •• password
wsname; expression
wsname •• password; expression
SEAL first lacks all functions in the current workspace and identifies the warkspace as sealed. The workspace is then
saved with the attributes: READ access, NONE, WRITE access, NONE, EXECUTE access, ALL, via APL only. The
saved workspace thus may not be accessed by any processor other than the current official version of APL. Any APL
user may execute the workspace, but may not display user functions or resave the workspace.
A candidate for a seoled workspace should be a thoroughly tested, self-sufficient, application package in APL. The
originator should maintain a backup unsealed version, passworded, to allow for unforeseen error corrections or other
changes.
A sealed workspace is protected from any form of inspection which will divulge the contents of functions in that workspace. Displays of other workspace information, such as names of variables, are also prohibited. Normal operation
can only be resumed after the sealed information is removed by a command such as )CLEAR or )LOAD.
1f the save is not successful, BAD FILE REF, FILE SPACE TOO LOW, or other relevant error messages may be issued.
The active workspace will not be sealed in this case.
)SET
Changing Assignments of Input/Output Streams
The )SET command applies to four input/output streams as follows:
•
INPUT - Source input for APL. Normally assigned to user's console for on-line users; card reader for offline users.
•
OUTPUT - Normal terminal or printer output stream. Normally assigned to user's console for on-line users;
line printer for batch users.
• rn
142
or [2J 'blind input/output streams (Appendix B).
Commands
Syntax of )SET
The' following options are available:
)SET INPUT
UC
logical device
DC/fid
DPfpackidlifid [idopt[idoptJ ••• ]
9T [tapei dl[!fid]
BT[tapeid] [lfid]
MT [tapeidJ[/fid]
UC
logical device
LP
DC/fid
)SET OUTPUT
DP[packid] /fid [;dopt[;dopt] •••]
9T[tapeid] [lfid~
BT[tapeid] [lfid
MT[tapeid][/fid
BCD
BIN
NODRC
DRC
}SET
{~}
1~~OUTl
OUTIN
OUT
UC
logical device
LP
DC/fid
DP[Packid~fid
9T[tapeid] fid]
BT~apeid] rid]
MT[tapeid] [/fid]
[;dopt[;dopt] ..•] [;SIZE =N]
where
UC
is users console.
DC
is disk.
DP
is disk pack.
9T
is 9 track tape, 800 BPI.
BT
is 9 track tape, 1600 BPI.
MT
is 9 track tape, system default density.
If 9T, BT, or MT is not followed by Tapeid and input mode is selected, on I/O error will result •. If output mode is
'selected without Tapeid, a scratch tope is generated.
Logical Devices
are installation-dependent name designations for devices such as the Remote Batch Terminal, cord reader, etc.
Packid
is private pack serial no., of form # serial no.
Tapeid
if not followed by /fid, refers to external seriol number of a free-form tape. In this case the tape is
considered a device.
Tapeid/fid
Tapaid
specifies a labeled tape with SN equal to the designated number.
has the form # seria I no.
CommQnds
143
Serial Numbers
Fid
are 1 to 4 alphanumeric characters.
is the standard CP-V file identification format.
'dopt' includes
COUNT=C
DATA
=C
LINES = N
SPACE = N
VFC
NOVFC
(C
(C
= 1 to
= 1 to
140)
144)
(N = 1 to 32, 767) If LP (N = 1 to 255) If UC
(N = 1 to 255)
• account
~
name [ • account. password
•• password
where
SIZE
=
sets the byte count for reads thraugh
N
rn
or
III .
N = 1 to 32,767.
Default is 512.
COUNT = C
turns on page control and initializes the page count, which will appear at column C at the top
of each page.
DATA
=
C
sets the leftmost column at which output will appear (line printer only).
LINES = N
sets the number of lines per page. If a large value is used, this means no header output.
SPACE = N
sets line spacing if mode is NOVFC.
VFC
sets Vertical Format Control On.
NOVFC
sets Vertical Format Control Off.
BCD
BCD device read-write mode.
BIN
Binary device read-write mode.
NODRC
DRC
Monitor special formatting On.
no special formatting of read-write records.
)SET functions analogously to !SET in TEL (CP-V TS/Reference Manual, 900907). There are, however, some restrictions and differences.
Syntactic Differences between )SET and !SET
144
•
Names and APL symbols are used instead of DCB names.
•
For
and [iJ , IN, INOUT, OUTIN, or OUT must precede the file/device designation.
option.
•
For output operations, the mode is automatically output and SAVE. There is no provision to create temporary files.
•
No explicit file mode options ore permitted.
consecutive.
rn
Commands
Access is always sequential.
It is not an
Output files are
Operation of )SET
The're are operational differences between ISET and )SET. ISET operates only between job steps with the relevant
DeBs closed. )SET may be executed while a DeB is open and active.
If )SET is executed and the relevant DeB is open, the DCB is closed with SAVE prior to executing the chonges in the
DeB. It is then reopened.
The close is executed with a Iremove l option; thus, whenever mognetic tope has been specified ond a new )SET is
issued, the tape reel currently in use wi II be rewound ond a dismount message issued to the operator.
The availability of input/output devices, particularly magnetic tape and private disc volumes, is subject to installation control. APL users who access such devices should be aware of such controls and local conventions on operator reques~s for tape mounts.
Default Device Settings
The following are considered default device settings. Any time an I/O stream is given a device assignment which
differs from its prior assignment, the defaults are reestablishedunlessother options are specified in the )SET command.
DATA = 1
LINES = 32767
SPACE = 1
NOVFC
BCD
NODRC
Meanings of Device Options
Additional information concerning the device options for SET and their use in formatting output is contained in the
CP-V TS/Reference Manual, 900907, particularly Tables 5 and 40.
User Prompts
If either output or input is diverted from the terminal, the prompts normally issued to the user will be omitted. On
2741 equivalent terminals, the user can determine readiness for input by the term.inal lock-unlock status. On teletype and ASCII terminals with full duplex, the echoing of characters indicates input is being accepted.
Break and Error Response
m
and 121. There is no essential change in the handling of errors in ill and 121 input/output.
Errors on
clusion of: )SET within APL permits error action by the user or, if error control is used, in APL functions.
The in-
Errors on INPUT or OUTPUT. If normal input or output has been reassigned from the 'home ' device by )SET and an
, I/O error occurs, control is returned to the home devi ce(s). This is user's console for on·-line users, card reader and
line printer for off-line. If error control is not in effect, an I/O error message is then output. If control is in effect
for I/O errors, no error message is output. The user's error control function should note that input and output have
been restored 'home ' from their )SET assignments.
In order to avoid I/O translation problems, APL will also revert to 'home ' )TERMINAL type if the input or output
terminal type has been individually modified. The CP-V Time-Sharing Reference Manual, Appendix B, includes
tables of CP-V error codes for input/output errors.
Break Re~ponse. If normal input or output has been reassigned from the home device by )SET, it is restored to the
home device by a Break. Translate tables will be restored to 'home ' )TERMINAL type. If the user has taken break
control, the function which manages break control should note that input and output have been restored to the 'home '
device al'1ld terminal.
Commands
145
)SET and VFC
In addition to modifying the DCB to indicate Vertical Format Control, VFC modifies APL output routines to
automatically prefix a vertical format character to each output line. Provision, describ~d in Chapter 9, is added to
APL to permit user control of output spacing with format control characters.
BCD/BIN and NODRC/DRC
These device options affect device read-write formatting conl'rol exercised by CP-V.
Default is BCD;NODRC.
BIN; DRC provides 'transparent' input/output, with no translation or special treatment of characters by CP-V.
rn
SIZE Option for
and 121 Input
The SIZE option allows relief of the restriction on the size of records input via [j] or
derived:
'12/.
Two benefits are thus
•
Large records can be read.
•
In 'transparent' mode via user's console, the SIZE can be reduced as desired to avoid 'waiting for input'
conditions. (In this mode an input record is not processed by CP-V unti I the specified byte count has been
reached. )
)51 and )SIV ! Listing or Controlling the State Indicator
The following commands allow the user to find out what functions have been suspended during execution and where.
They have the forms
)SI
)SIV
The )SI command displays the contents of the APL system state indicator, which is a list of suspended and pendant
functions. For example,
)SI
A[2]
XY[ 5]
B[ 3]
*
*
The most recent suspended function is listed first. An asterisk after an entry indicates d suspended function; no asterisk indicates a function that is pendant. In the above example, function A has been suspended just before line
number 2, and function B just before Iine number 3. Function XY is pendant because it referenced function A at
line number 5. If )SI is issued when an input quad is pending, the input request wi II also be displayed, using the
o character. If )SI is issued when an 'execute' is pending, the execute call wi II be displpyed, using the EO character.
The )SIV command lists the same information as the )SI command except that it also lists the local variable names
appearing in the suspended and pendant functions. For example,
)SIV
A[2]
XY[5 ]
B[ 3J
*
BE
cc
*
PAY
VAL
DD
where BB, CC, and DD are local variables appearing in function A; and PAY and VAL are local variables
appearing in function B. Errors causing suspended functions shou Id be corrected as soon as passible. Suspended functions can be cleared from the state indicator with the branch arrow (->-). (Remember that the
state indicator with its list of suspended and pendant functions and local variables may take up a lot of workspace. Each branch arrow clears the most recent suspended function and all pendant functions associated with
146
Commands
it. This can be repeated until all suspended and pendant functions have been cleared; that is, until the lSI
command returns a blank line. Applied to the above example, this would give
)SI
B[ 3]
*
PAY
VAL
)8I
A more convenient method for clearing the state indicator is to issue an lSI CLEAR command, see below.
For a discussion of the state indicators and suspended and pendant functions, see "State Indicators" and "Function
Execution" in Chapter 7.
Three options are avai lable with an lSI command: CLEAR, OFF, and ON. These may also be used with an )SIV
command, with identical results. The options provide control over the state indicator.
The CLEAR option simply removes every entry in the state indicator. This often frees a substantial amount of workspace and is a valuable tool for recovering from WS FULL errors. The usual syntax is
lSI CLEAR
As with other command syntax, there must be at least one blank between the command and the option. This also
applies to the ON and OFF options described below. Only the first four letters, CLEA, are necessary, but others
may be supplied (as described for system command names).
The ON and OFF options set state indicator control for errors that may occur during subsequent execution of functions in the active workspace. APL normally (the ON setting) suspends the executing function if an error occurs.
This is useful when debugging the workspace since it allows access to local variables for the suspended function.
Suspending the function, however, expends a certain amount of the active workspace, and th is can be a di sadvantage. Use of the command
lSI OFF
sets state indicator control to avoid suspending a function when an error occurs. Note that the OFF setting applies
only to errors. It has no influence over execution breaks or stop vectorsi these may still cause function suspension.
To restore normal state indicator control, the command
)SION
may be issued. This setting also occurs automatically if a )CLEAR command is issued.
The ON or OFF state indicator control is saved when the active workspace is saved and loaded when the workspace
is loaded. Copying does not altei-the control of the active workspace.
lSYMBOLS
Altering Length of Symbol Table
This command allows the user to display or change the current length of the internal symbol table. (The default is
261 possibl,e names.) It has two forms
)SYMBOLS
)SYMBOLS n
The first form of this command, )SYMBOLS, causes the APL system to print the current allocation and the number of
unused entries at present. The second form, )SYMBOLS n, causes APL to change the symbol table allocation and to
print the previous allocation. The n parameter is the number of names the user wants to be allowed to use. If this
number is reasonable, he gets at least the requested allocation, generally a little more; however, n may not
Commands
147
exceed 2001. The )SYMBOLS n command is allowed only when the active workspace is empty. Usually the user
will -issue a )SAVE, )CLEAR, and )SYMBOLS sequence, and then issue a )COPY command - not a )LOAD - to make
use of the new allocation.
Examples
)SYMBOLS
UNUSED OF 261
250
)CLEAR
CLEAR WS
)SYMBOLS 300
WAS 261
)TABS
}
)
Indicates that 250 more names can be entered in a
workspace whose symbol table allows 261 names;
therefore the workspace presently contains 11 names.
Changes the symbol table allocation to 300 or more,
and prints the previous allocation (i. e., 261).
Setting Tabs
This command can be used to display the current tab settings or as part of the procedure in setting new tabs for
input/output. To display the current tab settings, the command is simply
)TABS
to which APL responds with a message giving the current tab settings.
these steps:
To set new tabs, the user must follow
1.
Clear existing tabs, using the CLR portion of the CLR/SET key at the left side of the keyboard.
2.
Set tabs at desired poSitions, using the SET portion of the CLR/SET key.
3.
Type a command of the form
)TABS n
where n indicates the tab settings, and can consist of a scalar (one integer) or q vector (a series of integers)
as follows:
scalar
indicates that tab settings are to be equally spaced or (if zero) that the APL tab feature is to
be turned off. Specifying an integer in the range 3 to 127 indicates that tabs are to be equally
spaced that size (integer) apart. For example, the command )TABS 15 sets tabs at columns 15,
30, 45, 60, etc.
vector
indicates unequally spaced tab settings. The numbers must be in increasing order and must
start at a value of 3 or more. The highest number permitted is 127. For example, the command
)TABS 5 25 35 40 sets tabs at columns 5, 25, 35, and 40. Up to 16 tab settings can be specified in this way.
The APL system responds to this command with a message giving the previous tab settings. If this command
is not specified, the APL system assumes a tab setting of zero by default.
Note that setting tabs is advantageous for speeding output on a standard APL terminal' with true physical tabbing
capability. _The use of the tabs command is discouraged on terminals without physical tabs (such as a teletype) because tab simulation uses computer time without providing any real advantage. Tabs can also be set with the TABS
function described in Chapter 7, "Defined Functions ".
148
Commands
/"-
Examples
)PABS
}
Indicates that current tab settings are at columns 5; 25,
and 37.
)PABS 10
}
Sets tabs at columns 10, 20, 30, 40, etc. The previous
setting was 01' i.e., no tabs were recognized.
)PABS
}
Sets tabs at columns 5, 25, and 37. The previous tab
settings were 10, 20, 30, 40, etc.
IS
5, 25 37
flAS
0
flAS 10
\ )TERMINAL
5 25 37
Specifying Input/Output Device
This command is used to identify to the APl system the input/output device being used. It has the forms
)TERMINAl n
)TERMINAlINPUT n
)TERMINAl OUTPUT n
where n indicates the device to be assumed by the APl system and can be any of the following values:
Indicates 2741 terminal (or equivalent) with APl typeball -this is the standard APl terminal.
2
indicates 2741 terminal (or equivalent) with non-APl typebal I.
3
indicates Teletype Model 33.
4
indicates line printer format output or card reader format input.
13
indicates a typewriter-paired APl/ASCII terminal, such as Tektronix 4013; the user must not falsely declare this setting I
14
indicates a bit-paired APl/ASCII terminal.
This command is not required for users operating on a standard APl terminal or submitting batch runs for card input
and line-printer output (type 1 and type 4, respectively, are assumed by default). New terminal declarations are
acceptable at any time during an APl run, but the user should be aware of the consequences (such as error message
discrepancies and input/output translation problems). See Appendix B for more about this command and the sign-on
protocol on nonstandard terminals. I-beam 28 also results in the integer n; this may be useful for APl programs that
are sensitive to terminal type.
The form )TERMINAlINPUT or )TERMINAl OUTPUT modifies only the specified (input or output) translation table.
This form is useful when normal input or output has been diverted to an alternate device by the )SET command.
Examples
flAS
1
IS
;2
flAS
1
) PERM 2
}
Indicates that a 2741 terminal (or equivalent) with a
non-APl typeball is being used.
)TERM
}
Shows that the non-APl 2741 terminal was most recently declared.
)TERM OUTPUT 4
}
Sets output translation for line printer.
input translation.
Does not change
_
As extended, APl now recognizes three separate parameters for input/output character translation.
/""""".
'Home' terminal type is the sign-on default. It may be changed by the )TERM n command, for example, a
Tektronix 4013 user starts with hame terminal type 3 and will normally issue )TERM 13 to use the APl character set.
Home terminal type is the one returned to on break or input/output error. Input terminal type is changed by either
)TERM INPUT n or )TERM n. Output terminal type is changed by either )TERM OUTPUT n or )TERM n.
Commands
149
I
Use of )TERM with )SET
The combination of )TERM and )SET permits a variety of I/O operations with devices and files. The user should be
warned that some choices, particularly changes to 'home' terminal, can result in inabi lity to carryon further terminal
communication. In general, )TERM OUTPUT 4 should be used for line printer output, but not for filed output which
may be later used for input (such as function displays). Output which will be filedandrereadby the same user should
preferably use home terminal type. If several users with different terminals wi II want to access the fi Ie, a common
type, probably 1,. should be agreed on.
lVARS
Listing Global Variable Names
This command allows the user to list alphabetically the names of global variables in the active workspace.
forms are acceptable:
Three
)VARS
)V ARS string
)VARS string 1 string2
The first form displays all global variable names. The second form displays all global var,iable names that match or
exceed the "string"t in alphabetic ordering. The third form displays all global variable names that match or exceed
"string1" and are also less than or match "string2". Alphabetic ordering is illustrated in the examples below. Note
particularly the first )VARS command since it indicates where each name character lies in alphabetic order.
Exam~les
A
AA
A
)VARS
At.
)VARS
AB ABC
)VARS
All At.
)VARS
A~
Ad AA
AA
AO A1
A AA
Ad AA
AAA AB
AB
ABC AO
A1
B
ABC AO
A1
B
B
AB
)VARS ABC ABC
ABC
A
A~
)WIDTH
)VARS A B3
At. Ad AA
AB
Setting Line Width
In a clear workspace the width of a line of output is set at 120 characters (or 72 characters if a non-2741 type terminal was initially recongized by APL). The )WIDTH command allows the user to change this width or to display the
current width, and has two forms
)WIDTH
)WIDTH n
where n is the number of spaces in a line of output and can be any number ranging from 30 to 254. The first command form, )WIDTH causes the APL system to print the current line width setting. The second command form,
)WIDTH n, causes the APL system to change the line width setting and to print the previous line width setting. This
command is saved along with a workspace. The width of a line of output can also be changed with the WIDTH function described in Chapter 7, "Defined Functions".
i
It shou Id be noted that a width greater than 130 is improper for normal operations on a standard APL terminal. Also
note that if the PLATEN command, at the CP-V leve I, has been used to set a shorter width than dec lared by)WIDTH,
then the PLATEN command overrides WIDTH. In this case lines may be split in the middle of individual values.
t
•
Where "string" is any sequence of characters not including a blank or carriage return. Ha string includes more than
80 characters, those past the 80th are ignored. Strings are used for range demarcation.
150
Commands
Examples
IS
) WIDTH
120
)WIDTH 50
WAS 120
)WSID
}
Displays the current width of a I ine of output (i. e.,
120 spaces).
}
Changes the width of an output I ine to 50 spaces. The
previous line width setting was 120.
Identifying Active Workspace or Changing Its Name
This command allows the user to identify the active workspace or to change its name. To identify the active workspace, use the command
)WSID
and APL wiU return the name and account (if different than the current user account) of the active workspace.
change the name of the active workspace, use the command form
To
)WSID wsname
)WSID wsname •• password
where wsname is the new name of active workspace. The APL system responds with a message showing the previous workspace name. This name can be from 1 to 11 characters. A password may be specified, but a previous password is never displayed.
)WSI D cannot be used to change the name of a sealed workspace.
Examples
~
)WSID
IS
IS
WAS
CONTINUE
)WSID
REI07207 JONES
)WSID SMITH
JONES
}
Lists the name (CONTINUE) of the active workspace.
}
Lists the name (J ON ES) and account (RE 107207) of
active workspace.
}
Changes name of active workspace from JONES to
SMITH.
Commands
151
9. REPORT FORMATTING
Xerox APl provides a formatted output capability by means of a set of fast intrinsic functions. They reside in a
designated "public" workspace (WSFNS), may be copied by any user, and occupy a negligible amount of the user's
workspace since the functions are actually implemented as part of the APl processor. (See Appendix C.)
•
The formatted output function, called .t.FMT, utilizes a set of format control phrases that are applied to a list of APl
expressions. The content of the APl expressions may evaluate to numeric or character scalars, vectors, or matrices.
The format control phrases, called format specifications, are described below.
Format Specifications
liFMT recognizes six data format codes:
A
Alphanumeric specification.
E
Floating-point with exponent (scientific format).
F
Floating-point to fixed decimal position.
Decimal integer.
X
Blank insertion.
I!l TEXT I!l Text insertion.
Format specifications may be in any of the following forms:
[r]
Aw
[r]
Ew.s
[r][q] Fw.d
[r][q] Iw
[r]
[r]
Xw
I!l TEXT I!l
where
is an optional unsigned integer constant indicating the specification is to be repeated r times. When r is
omitted it is taken as 1.
I
152
w
is an integer constant indicating the total fie Id width, or number of print positions occupied by the formatted value (or blanks, for X type).
s
is an integer constant indicating the number of significant digits to be printed in E formats; s must be less
than w-5.
q
is an optional "qualifier" or "affixture" code used to position and affix characters to the results of I and F
output forms. The available codes and their uses are described later in this chapter.
d
is an integer constant indicating the number of digits to the right of the decimal point in F formats;
d must be less than w.
tThis feature was
inv~nted and introduced
Report Formatting
by I.P. Sharp Associates ltd., Toronto, Canada.
•
Form~t Specifications Versus Data Types
~~
Format A may be applied to character data only.
values only.
Formats E, F, and I may be applied to numeric data and logical
Arrays with rank above 2 (matrix) cannot be processed. If a va lue cannot mean ingfully be expressed in the format
and field width specified, the field is filled with asterisks.
Th~ Format Statement [Left Arlument)
A format statement is the left argument of LlFMT, operating on data values in the right argument. The format statement consist~ of a character vector made up of one or more format specifications separated by commas. The left
argument of LlFMT must always be a valid format statement. For example,
t3I5.2EB.2.X12.I3 t APMT •••
The Data List [Rilht Arlument)
The right argument of .6.FMT must be a list of APL variables or expressions, separated by semicolons or a variable
formed by ass,igning such a list to a name. The expressions may represent scalars, vectors, and arrays. For example,
••• LlPMT (VARIABLE1;VARIABLE1+VARIABLE2;'SUMt)
>
If the list contains only one expression, the parentheses may be omitted.
Operation of
~FMT
t>FMT uses the format specifications in its left argument (the format statement) to control printing of its data list
(right argument) in one or mare columns. The syntax is
format stmt t>FMT expr
or
format stmt LlFMT list
The result of executing t>FMT is one or more "lines" of formatted character data. A line may be as long as workspace allows. In printing, long lines are broken up according to the )WIDTH setting. If more than one line is produced (as will be the case.if the data list includes vectors or arrays with more than one row) all lines are of the same
length. The result, then, is a character matrix.
If LlFMT is not used within a larger expression, the amount of temporary workspace required is only the length of one
line. Thus, formatted output may .be used to process output that would overflow available workspace if assigned or
used in its entirety. if lIFMT is used within a larger expression, the result is always a matr:x, even if only one line,
and space for the full matrix is required.
The operation of lIFMT on various right arguments is described below.
Scalar Arguments
/~-~
If the data list consists exclusively of scalars, a single line is created. Forrnatspecifications are used in turn to process elements of the data list in left to right order. Blank insertion and text insertion specifications do not "use up"
elements of the data list, however. A repetition indicator will cause a particular specification to be applied the
designated number of times to successive elements of the data list. If there are fewer format specifications (counting
repetition indicators) than values to be formatted, the list of format specifications is reused as necessary until the
data list is exhausted .
•
Format Specificati ons Versus Data Types/Format Stotement (Left Argument)/Dato List (Right Argument )/Operation of lIFMT
153
Examples: •
'I3.A5.X5' AFMT (100;'A';200;'B')
A
200
B
100
'5F5.2' AFMT (1;10;100:-10;-1)
1.0010.00**********-1.00
This last example illustrates the use of the repetition indicator.
100 and -10 would not fit in the specified format.
Also note the asterisk~ indicating that the values
Vector Arguments
If the data list includes vector and scalar arguments (or vectors only), the number of lines generated equals the length
of the vector with the most elements. Each vector creates a "column" in the resulting character array. The columns
of shorter vectors or scalars are extended by blanks.
Examples:
'El0.4' AFMT 3.1.123
3.100EO
1.230El
1.234EO
5.678E3
1.23 115678
'2IS.A2' AFMT (1 2 3 4;10.4 10.6;'ABCDEF')
10 A
2
11 B
1
3
C
4
D
E
F
In the last example, note the rounding off of values as required for I format specifications, and also note the different column lengths.
Formatting a Vector on One Line
The normal result of IlFMT on vectOr arguments is columnar formatting, but it is often desirable to create row formats
'
for vectors. There are two ways this can be done:
•
Ravel the result of IlFMT. This method is appropriate if the result would contain a single column.
Examples:
,'A2' 6FMT 'DOUBLE SPACE'
D 0 U B L E S P ACE
o
154
Operation of IlFMT
,'IS' 6FMT .14 1.4 14 140 1400
1
14 140 1400
•
•
Reshape the vector as a 1 by N matrix.
as discussed below. )
T
(This method uses a property ofthe operation of lIFMT on matrices,
V+'TRIPLE+SPACE'
'A3' lIFMT (l.pV)pV
RIP L E + SPA
C
E
Matrix Arguments
If the data list includes a matrix argument, each column of the matrix will create a "column" in the formatted output.
Each row of the matrix will create an entry on a "line" of output. Note that a 1 by N matrix creates a row ofa column, and an N by 1 matri x creates the same output form as an N el ement vector.
In essence, lIFMT outputs matrices in the same shape as unformatted output would, but permits control of decimal
placement, column positioning, etc.
Examples:
IOTA .... 3
SptlS
f::.FMT IOTA
'FS.l'
1.0 2.0
3.0 4.0
5.0
6.0
7.0
8.0
9.0 10.0
11.0 12.0 13.0 14.0 15.0
JKL+'JKL'
PI .... 3.14
VECT .... 1 2 3 4
MAT .... 2 2p .1 2.0 30 4
'Al.F6.3,IS.2F6.1' f::.FMT (JKL:PI:VECT:MAT)
J
K
L
3.140
1
2
3
0.1
30.0
2.0
4.0
4
Forms of Output Values
The following rules determine spacing and content of output fields for various format specifications.
•
Right justification. For A, I, and F specifications, the value is right justified in the field and preceded
by blanks where appropriate to fill out the field.
•
E format. The letter E always occupies the fourth space from the right in the field. Three spaces are
reserved for the exponent val ue and exponent sign. If I ess than three spaces are needed, the rightmast space
or spaces are blank. In this format there will be columnar alignment of the decimal points and letter E.
•
~ TEXT ~ format. Characters between the quote-quads are inserted directly into the output line.
There will be as many insertions as there are lines of output. No data list elements are expended by
text insertion.
•
Significance of results. The )DIGITS setting is ignored in tlFMT output; a maximum of 16 significant
positions will be displayed, however. If a format specification requests more than 16 significant digits,
digits beyond the sixteenth and to the left of the decimal point are replaced by underscores. Excess digits
to the right of the decimal point are replaced by blanks.
•
Field width. If field widths are too small to hold formatted values according to the specification, the fields
are fill ed with asterisks.
Forms of Output Values
155
Qualifiers and Affixture Codes
I and F format specifications may be immediately preceded by one or more qualifier or affixture codes.
•
Qualifier codes
•
B
leaves the field blank if the result would otherwise be zero.
C
inserts commas between triads of digits in the integer part of the result.
L
left justifies the value in the result field.
Z
fills unused leading positions in the result with zeros (and commas if C is also used) instead of blanks.
A ffi xture codes
MI!l TEXT I!l
prefixes negative results with the text instead of the negative sign.
NI!l TEXT I!l
postfi xes negati ve resu I ts wi th the text.
PI!]
TEXT I!l
prefixes positive results with the text.
QI!]
TEXT I!l
postfixes positive results with the text.
RI!]
TEXT I!l
presets the field to the text, which is used as many times as necessary to fill the field.
The text will be replaced in parts of the field filled by the result.
Note: If Band R are both specified, R overrides B.
Qualifier and affixture code do not extend field widths. The modified result must fit in the field width specified or
asteri sks wi II be substituted.
Nand Q affixtures, since they postfix the text, shift results to the left by the number of characters to be
postfixed.
Examples:
V+128 0 .25 64 12345.67
'BF10.1,X2,BI8.X2,CI10,X2,LI9' 6FMT (ViViViV)
128.0
128
128
0.3
64.0
12345.7
64
12346
0
64
-12,346
o
128
0
0
-64
12346
'ZF10.2,X2,MI!l**I!lF10.1,X2,PI!l+I!]I8' 6FMT (ViViV)
0000128.00
0000000.00
-000000.25
-000064.00
012345.67
128.0
0.0
**0.3
**64.0
**12345.7
+128
+0
+0
64
12346
'QI!l+++I!lI9.X2.RI!l*I!lI8' bFMT (ViV)
128+++
0+++
0+++
64
12346
156
*****128
*******0
*******0
*****-64
**-12346
Qualifiers and Affixture Codes
Combinations of qualifiers and affixtures may be used together to pravide various output forms as shawn below.
IM~-$~P~$~CF12.21
$12 .• 345.67,
AFMT (12345.67,-9.98)
-$9.98
Use of Result
The principal use of .6FMT is to provide lines af formatted autput to the user's console. However, if .6FMT is used
as part of a larger APL expression, the result of executing .6FMT is a character ma"trix which may be manipulated
and used just as any ather character matri x.
Error Exits
If the right argument includes an array af higher arder than matrix, or the left argument is not a vector, a RAN K
ERR results.
If the left argument is numeri c rather than character data, or contains no format specifications, or contains a format
specification with inconsistent parameters (such as d greater than w, or w = 0), a DOMAIN ERR results.
If there is incorrect syntax in the right argument, a SYNTAX ERR results.
argument, a FORMAT SYNTAX ERR results.
If there is incorrect syntax in the left
If the line length of the result is too big for the remaining workspace, or in the case that .6FMT is included in a
larger expression and the total result exceeds the workspace, WS FULL results.
Other Output Formatting Aids
In addition to .6FMT, the following intrinsic functions may be used to aid in output formatting. These functions are
also kept in WSFNS or may be created as described in Appendix C. The )SET and )TERMINAL commands, described
in Chapter 8, may also be used in the overall process of output report generation.
PAGE is a niladic function with an empty vector result. When executed, if output is to a printing device, the current page will be ejected. If output is to the user's console and UNES has been established by )SET, a standard
header line will also be produced, unless the option DRC was indicated.
NUNES
NUNES is a niladic function with an integer result. If output is to a device, with line count applicable, the result
is the number of lines remaining. If not, the result is zero.
HEADER
HEADER is a monadic function with empty vector result. The right argument must be a text vector length 127 or
less. This function establishes the output header line which will be issued at the start of each page if output is via
a printing device. This intrinsic function uses a CP-V facility which is not cognizant of special APL characters. If
special characters or overstrikes are included .. HEADER wi II not produce correct headings.
VFCHAR
VFCHAR is a monadic function with empty vector result. Right argument must be a single text character. When
VFCHAR Is executed, the character in the right argument becomes the verti cal format control character for the next
print line. After that line is printed, the default blank character is restored as the vertical format control character.
Use of Result/Error Exits
157
The following charocters have meaning as right arguments to YFCHAR:
,,
Inhibit space after printing (not possible on some terminals)
'A'
Space
additional line before printing
'B'
2
'I'
9
2 l' 202
10
21'203
11
2 l' 207
15
lines
'0'
Skip to bottom of page before printing
'1'
Skip to top of page before printing
YFCHAR is effective only when YFC mode is on (see SET command, Chapter 8).
Example:
Line 5 of function FORM is to print a title which is spaced 3 lines below the preceding ou~put line. YFC mode has
been set.
FORM[5]
'PART TWO: COSTS YS PRODUCT'; YFCHAR 'C'
AXl
The translate operator, b.XL, faci litates special character set translations within APL. The form is
R-
A b.XL B
The left argument must be a character vector of length 256. The right argument may be any text entity. The result
has the same shape as the right argument and consists of a translation of the right argument based on the left argument, as follows: The value of a right argument element determines the offset into the I,eft argument. The result
element is the character at that offset in the left argument. Figure B-1, in Appendix B, shows the collating order of
the full EBCDIC and APL character sets.
This feature is designed for sophisticated users, to overcome problems encountered in character set differences between various devices and processors. It allows any character mapping, including mapping! several characters to the
same result character. An example of this use might be to map all 'illegal' characters to some unique character.
Another example is as follows:
L+-1+\256
L[128+\9J+192+\9
L[144+\9]+208+\9
L[161+\8J+225+\8
This value of L, used as left argument of b.XL, wi II convert underscored letters in the, right argument to similar
letters, not underscored, in the result.
158
Use of Re$Ult/Error Exits
10. EXECUTION STOPS
Execution is stopped if any of the following conditions occurs:
1.
Execution is completed (a normal stop).
2.
Execution break occurs (ATTN key is struck), and sidetracking (see Appendix A) does not occur.
3.
User input is required (quad or quote-quad input).
4.
Stop control vector is encountered.
5.
Error is encountered, and sidetracking (see Appendix A) does not occur.
Normal Stop
Execution comes to a normal stop after any action indicated by direct input has been completed. It should
be noted, however, that a direct input prompt does not necessari Iy mean that all pending execution is completed. The user can determine whether any execl.Jtion is pending via the )SI or )SIV commands described in
Chapter 8.
Execution Break
An execution break (that is, the ATTN key) can be issued by the user at any time except during terminal input
(when ATTN becomes an editing signal). There may be a variable delay - sometimes several seconds for a
fully loaded system - until output stops. Sidetracking (see Appendix A) can be used to gain break control within
an APL function; in this case execution does not stop, but is "diverted".
APL's reaction to ATTN also depends on whether the key is struck during execution mode or definition mode. If
ATTN is used during (nonfunction) execution, APL will stop any output and will skip to the next line and indent six
spaces to prompt for new input. If ATTN is used during execution of a defined function, APL prompts the user with
the function name and the line number being executed; the line being executed may have been partially completed.
If ATTN is used during display of a function, APL will exit from function definition mode if a closing del was ineluded in the display command; if the display command did not have a closing del, APL will remain in function defI
inition mode and will prompt with the next line number to be assigned to a statement.
Execution breaks are usually not allowed to interrupt the execution of a system command. However, those that produce lengthy display can be stopped: )FNS, )GRPS, )LIB, )SI, )SIV, and )VARS. ATTN is also used to break out
of the )OPR system command.
Stop for User Input
Execution may be stopped by a pending input request in a line. The normal response to a quad or quote-quad
input request is a line of input. While input is pending, ATTN is not considered an execution break and thus
_ E.xecution Stops
159
does not cause an exit from the input request. If the user's program contains a loop such that he is repeatedly
prompted for input, he may escape as follows:
1.
For quad input, type a branch arrow (-+) followed by a RETURN key.
An example is shown below:
VPITIMES[DJv
V PITIMES
.[1]
[2]
00
-+1
V
PITIMES
0:
1
3.14159'2654
0:
1
3.141592654
0:
o
lSI
PITIMES[1]
0:
)SI
In this example the user has defined a function, PITIMES, that repeatedly requests, input and provides a result. The first )51 command shows that an input request and line 1 of PITIMES are pendant. After the -+,
the input request is no longer repeated. The second )51 command shows that the loop has been broken and
PITIMES is no longer in use.
2.
For quote-quad input, type the following sequence of characters and then strike the RETURN key: 0 backspace U backspace T. This sequence appears at the terminal as fD.
Stop Control Vector
As described in Chapter 7 (under "Stopping Execution"), a stop control vector can be used to specify the exact place
a function suspension is to occur. The user can set a stop control vector by typing the symbols St. followed by the
function name, an assignment arrow, and the line numbers at which function execution is to be suspended. For example, suppose the user wants to suspend execution of function HH at lines 2 and 4; he will, type the expression
SflHH+2 4
APL will then suspend function execution just before each specified line number is reached, print the function name
and line number at which suspension occurred, and skip to the next line and indent six spac~s to prompt for user
input.
HH[2]
HH
'-----carrier is here
The user may then operate as desired, in direct mode, with the function suspended. He can resume or terminate
function execution at any time. Function execution can be resumed by appropriate branching; for example, an
entry of -+3 will resume execution of the suspended function at statement 3. Termination can be accomplished by
a branch to a nonexistent line number (-+O is a convenient choice). The function suspension can a Iso be abandoned
by a suspension clear statement, which is a branch arrow without any Iine number.
160
Stop Control" Vector
.;
A stop control vector can be specified during execution mode, or during function execution as one of the statements
of a defined function. To·discontinue an active stop control vector, assign an empty vector or a nonexistent line
number (sueh as 0) to that stop control vector; for example, S~HH+Owill turn off the stop control for function HH.
Error Stop
As soon as APL detects an error in a statement, execution of that statement is terminated and any partial result is
lost - unless an assignment was completed before the error was detected, in which case the assignment is effective.
'\ Unless side~racking occurs (see Appendix A), APL prints a message indicating the type of error, types the erroneous
statement with a caret below the place the error was detected t , and prompts for user input. The user can then reI enter the statement correctly. ,An example of error detection is shown here:
Xl+4tO
DOMAIN ERR
Xl+4tO
II
If a statement contains more than one error, only the first (rightmost) one detected by APLwili result in an error
report. The next error will not be detected until the user has corrected the first error, as illustrated here:
Xl+(4tO)x(2tO)
DOMAIN ERR
Xl+(4tO)x(2tO)
II
Xl+(4tO)x(2t1)
DOMAIN ERR
Xl+(4tO)x(2t1)
II
If an error is detected in a compound statement or in a statement with multiple specifications, any assignments or
statements to the right of the error will be completed, as illustrated here:
4tC+B xO.B+S
DOMAIN ERR
4tC+B x O.B+S
II
B
5
o
C
During funlction definition some types of errors are detected immediately while other types are not detected until
later when the function is executed. Definition errors, and character errors are detected immediately and must be
corrected os soon as an error report is printed.
VR+B TRI H
AREA+O.5xBxH
DIAGONAL+«H*2)B*2)*0.S
R+AREA.DIAGONAL
[4]
[0.5 TRI CALCULATES AREA AND DIAGONAL OF TRIANGLE
II
DEFN ERR
[0.5] ATRI CALCULATES AREA AND DIAGONAL OF TRIANGLE.
[1]
[2]
[3]
[0.6] V
Line-scan errors are detected immediately and may be corrected immediately by function editing or its correction
may be deFerred. All other errors in a defined function are detected when the function is executed. When APL encounters each error during function execution, it suspends execution and prints an error report containing the following information: the type of error and the function name and offending Iine and statement (with a caret marking
i tSee also the discussion
of error messages for the Execute operator in Chapter 5.
Error Stop
161
the place the error was detected). For example, the following error message is produced because a multiplication
sign lias been omitted after the right parenthesis:
5.TRI 8
SYNTAX ERR
TRI[3] DIAGONAL+«H*2)B*2)*O.5
,.
An error that causes suspended execution can be corrected during the suspension or after termination of execution.
1.
To correct an error during suspended execution, the user can follow normal function editing procedures (see
Chapter 7). For example,
SYNTAX ERR
TRI[3] DIAGONAL+«H*2)B*2)O.5
,.
VTRI[3] DIAGONAL+«H*2)xB*2)*O.5V
After correcting an error, the user can resume execution at the point it was suspended by specifying a
branch to that line number. Thus, the expression -+3 will resume execution at ,line 3 (starting at the
right, as usual for APL).
2.
To correct an error with termination of execution, the user enters a branch arrow to terminate function
execution, edits the function as necessary, and then reexecutes the function. For example,
SYNTAX ERR
TRI[3] DIAGONAL+{{H*2)B*2)*O.5
,.
VTRI[3] DIAGONAL+({H*2)xB*2)*O.5V
5 TRI 8
Each branch arrow removes the most recent suspension from the state indicator list. Thus if severa I suspen, sions have occurred since the last suspension clear, more than one branch arrow (suspension clear) wi II be
required to clear the state indicator. A convenient method for clearing the entire state indicator is to issue
an )SI CLEAR command.
J62
Error Stop
11. GRAPHICS
When the user is on-line with a Tektronix 4013 graphics terminal, and has declared )TERMINAL 13, he may make
use of the graphics capabilities described below. These facilities are implemented in terms of a graphic I/o primitive !land an intrinsic function LlGRF, described later in this chapter. However, most users will find it more convenient to employ the graphic functions defined in a workspace named GRAF described below. These features were
originally developed at University of California Irvine under the direction of Dr. Alfred Bork.
The graphics capability may also be used on a Tektronix 4015, which APL accesses in 4013 mode, or on a 4010. The
4010 does not support the APl character set (see "Teletype Usage", Appendix B).
User Graphic Functions
The following functions are available in workspace GRAF:
DRAW
INT
} Plotting Functions
WHATCOORD
WHATCHAR
} Graphic Input Functions
VS
SCALE
NOSCAlE
CENTER
WHATSCALE
}
S~l;ng
Funo';on'
SIN
COS
EXP
. STRAPIS
} Othe, Funo';on,
WINDOW
}
WHATWINDOW
Window Functions
AXES
BOX
DASH
SET
Auxi I iary Plotting Functions
PUT
ERASE
HOME
Plotting Functions: DRAW, VS, INT
DRAW produces a curve on the screen, working from one-dimensional, two-dimensional, or three-dimensional data,
a.nd determines wh~re th.e curve is to ~ppear. The left argument of DRAW specifies a "window", a rectangular portion of the screen In which the curve IS to appear. The window argument is a four-element vector giving, in inches
the x (horizontal) and y (vertical) window limits. Thus, 2 6 1 5 would specify the 4-inch square window position:d
as shown:
1"
2'....'-ro~_4"
If the left argument of DRAW is a scalar, the current window remains in effect; the value of the scalar is ignored.
Graphics
163
The data to be plotted is given by the right argument of DRAW, which is taken as a collection of one-dimensional,
two~dimensional, or three-dimensional points. For an argument composed of N two-dimensional (2D) points (i.e.,
the argument is 2-by-N or N-by-2), the plotted curve consists of N-1 straight line segments, each joining one
given (x,y) point to the next. For one-dimensional data (i.e., the argument is a vector, or N-by-1, or 1-by-N),
the data is taken as y values and plotted against X = N (which depends on the index origin). Three-dimensional
(3D) data (N-by-3 or 3-by-N) are projected on the two-dimensional (2D) window and platted as (x, y, z) points.
,
After a DRAW, the cursor is returned to the next writable line. DRAW does not erase the, screen, so it can be used
to overplot curves.
The right argument for DRAW is often set up by use of the VS and INT (interval) functions. INT A, B, N produces a
vector of N equally spaced values between A and B. Thus, if
X+INT-6
6
100
X contains 100 values, equally spaced from -6 to 6.
VS is used to "glue together" sets of values to form two-dimensional or three-dimensional groups suitable for use as
DRAW's right argument. Thus
o
DRAW
Y
VS
X
uses VS to form a 2-by-N matrix from the two N-vectors X and Y. For three-dimensional (3D) plotting, the corresponding call is
o
DRAW
Z
VS
Y
VS
X
The following statement produces a curve of the function Y =COS X for O:s; x:s; 6.28 (in radians):
o
DRAW
(COS X)
VS
(X+INT 0.6.28.40)
SCIling Functions: SCALE. NOSCALE. CENTER. WHATSCALE
SCALE, NOSCALE, and CENTER determine the placement of the picture within the winc;Jow; i.e., the limits of
x, y, (and z) values represented by the edges of the window. To set these limits to particular values, use SCALE as
follows:
SCALE xmin, xmax, ymin, ymax
for 2D scaling, or
SCALE xmin, xmax, ymin, ymax, zmin, zmax
for 3D scaling.
In the absence of a fixed scaling specification, "automatic scaling" is in effect: In this mode, each DRAW finds the
minima and maxima of its data along each coordinate, and scales the data to occupy the entire window. NOSCALE
(with no arguments) may be used to restore automatic scaling once an explicit scaling has been set by SCALE.
CENTER (with no arguments) also establishes automatic scaling, but in such a way that the origin is placed at the
center of the window, and the data is scaled to fit the window. Center-scaling is the default scaling rule in effect
before any scaling functions are called.
To find out whatscaling is currently in effect, or what scaling was established by the last DRAW if automatic scaling
is in effect, use WHATSCALE:
S+WHATSCALE
sets S to either a 4-vector or a 6-vector sca Ie:
or
S = xmin,· xmax, ymin, ymax
S = xmin, xmax, ymin, ymax, zmin, zmax
164
User Graphic functions.
Scaling and window data is saved as part of the workspace, so a DRAW command just after a )LOAD will draw the
same curv~ it did just before the workspace was saved.
Window Functio..: WINDOW, WHATWINDOW
The window limits may be set by the left argument of a DRAW command, as seen above, or by a WINDOW command. Thus, either
2 6 1 oS DRAW Y VS X
or
WINDOW 2 6 1 5
will establish the window as shown in the diagram above. Window limits are always set by a four-vector (Ix, ux,
Iy, uy) where the I's and u's are lower and upper limits, respectively, in inches from the lower left corner of the
screen.
Thefunctlon WHATWINDOW returns this four-vector as its value.
Window and scaling data is saved as part of a workspace and restored by )LOAD.
Auxiliary Plotting Functions: AXES, BOX. DASH, SET. PUT. ERASE. HOME
AXES. Draws axes according to the current scaling and window conventions, outputs the end-values, and returns
the cursor to the next writable line.
BC?X. D~aws a box displaying the current window limits and returns tf-e cursor to the next writable line.
DASH. Causes the next curve plotted with DRAW to be dashed. Applies only to the next curve.
SET x, y or SET x, y, z. Places the cursor at the given point in the window. The original cursor position is remembered; it may be subsequently restored by a set with an empty right argument, e.g., SET ".
(x, y) PUT value or (x, y, z) PUT value. Places the cursor at the specified point in the window, then outputs "value",
whether it is character or numeric. Thus,
0.1
3.14
PUT
'CURVE A'
will put the words CURVE A on the screen starting at the point x=O.l, y=3.14.
writable line.
PUT returns the cursor to the next
ERASE. Erases the screen and automatically puts the cursor at its "home" position near the upper left corner of
the screen.
HOME. :Places the cursor at its "home" position near the upper left corner of the screen.
Graphic Input Funetio..: [ilnput. WHATCHAR. WHATCOORD
The graphics input facility allows the user to locate a position on a screen and to communicate the coordinates of
that position to his program. The expression A + [l causes the 4013 to display the "crosshair cursor", a pair of linesone horizontal, one vertical. The user can then move these lines, via two knobs on the terminal, to locate any
point on the screen. When he then types a character, the crosshairs disappear and the coordinates of the intersection of th~ crosshairs become the result oHL In the above expression, A would be set to the value of the coordinates. The result is a two-element numeric vector. The first element is the X, and the second element the Y
coordinate of the intersection, relative to current scaling. After the input, the alphanumeric cursor returns to the
next line.
User GraphIc functIons
165
The input character and the coordinates are saved interna Ily and may be accessed by the functions WHATC HAR,
which gives the character as a result, and WHATCOORD, which gives the coordinates as a result.
If scaling is in effect (which is normally the case) and a crosshair intersection is selected that is not in the currently
defined WINDOW, the crosshairs are turned back on and the user must retry, selecting some point inside the window,
or "break" to escape graphic input mode.
If scaling is not in effect (see "unscaled graphic I/o later in this chapter) coordinates are returned in raster units
and current window and scale parameters are ignored.
Other Functions: SIN, COS, EXP, STRAPIS
For the user's convenience, the GRAF workspace also contains the following functions:
SIN X
equivalent to loX
COSX
equivalent to 20X
EXP X
equivalent to *X
STRAPIS is a function to allow changing the response of APL graphics software to accommodate different "strapping"
options for particular 4013 terminals. APL graphics assumes that the user's 4013 is set to deliver 7 characters in
response to graphics input requests. Some terminals are set to deliver 5 or 6 characters. In this case, if the user
executes a function such as BOX, the terminal will not respond until one or two characters are input. If this occurs,
STRAPIS 6
or
STRAPIS 5
can be used so that APL will only try to read 6 or 5 characters.
Note: If STRAPIS 5 or 6 is used when the actual strapping is for 7 characters, functions such as WHATCOORD will
provide incorrect results. The STRAPIS function should be used with caution.
Direct Control of Graphic I/O
The more sophisticated user may wish to exercise more control over the graphics I/o facility than is possible with
the functions described above. He may do so by making direct use of the graphic I/o symbol!:! and the intrinsic
function lIGRF, as described below.
D Output
The expression [j .... A (where A is not a scalar) performs the same function as 0 DRAW A; that is, it takes A as an
ordered set of points which it scales according to the current scaling rU.le, and plots in the window. If A is a scalar,
!l .... A sends one ASCII character to the terminal; in this case, A is the integer value of the character.
Caution: Scalar output should only be attempted with thorough knowledge of the terminal operating characteristics.
146.
Direct Control of Graphic
I/o
The folloy.'ing table shows the legal possibilities for the shape of A, with the resulting interpretations:
pA
Meaning
(empty)
A is scalar: send as ASCII character
N
or
IN
or
M1
data is 10; plot X =IN, Y =A
}
2N
data is 20; plot X =A [1;]. Y =A [2;]
M2
data is 20; plot X =A[; 1J. Y =A[; 2J
3N
data is 3D; plot X =A [l;J • Y =A [2;J • Z =A [3;]
M3
data is 3D; plot X =A[; 1], Y =A [;2], Z =A [;3]
0
or
OK
}
or
KO
where N
;<:
data is empty; plot nothing
1, M ~ 4, and K~ O.
The data is processed as follows:
•
1I
Data is scaled according to the current rule:
•
automatic scaling (NOSCALE)
•
centered automatic scaling (CENTER)
•
Three-dimensional (3D) data is reduced to two-dimensional (20) data by planar projection.
•
Data that falls outside the window (possible only under the fixed scaling rule) is suppressed; where the data
crosses the window boundary. the curve is extended to the boundary by linear interpolation. If the "reentrance" mode is on (via 10 lIGRF 2). curve plotting resumes at the point where the data reenters the window;
if the "reentrance" mode is off (via 10 lIGRF 1). curve plotting stops when the first out-of-range point is
encountered.
•
If a preceding DASH command has been given, the curve is broken up into short pieces, one per point;
otherwise, it is drawn cantinuously. DASH applies only to the plotting of this one curve;
•
. The resulting picture is drawn on the screen in the position specified by the current window parameters.
•
. After drawing the curve, the cursor is restored to its original position at the beginning of the next APL input line.
GRF Intrinsic
lIGRF is a dyadic intrinsic function used to control graphic I/O. It is declared in the GRAF workspace as follows:
lIGRF--14 T 3
Direct Control of Graphic I/O
167 .
The name for this function could be any name assigned to 14 i' 3, but is assumed here to be LlGRF. The form of the
function is
f LlGRF P
The left argument, f, is an integer specifying which action is to be performed: 0 ~ f ~ 11. The right, p, consists of
any parameters the selected action may require; p is often empty, in which case any type of empty vector will do,
such as II or 10. LlGRF returns a result: it is usually the empty integer vector 10, but (11 LlGRF k) returns a numeric
vector of length 2, 4, or 6 (see Table 6 below), or a character' scalar.
Table 6 shows all of the actions that LlGRF can perform, together with the corresponding user functions where the
latter have been provided.
Table 6. AGRF Calls
Correspond i ng
Function Call
GRF Call
o AGRF
Turns off IJ input scaling
1
o LlGRF 2
Turns on Dinput scaling (default)
1 LlGRF 3
Sets terminal device type = 4013
2 LlGRF ' ,
WINDOW' ,
2 LlGRF
WINDOW x l 'X 2'
X I ,X 2'YI'Y2
Sets default window (default)
Yl' Y2
Sets up given window params
3 l1GRF ' ,
SCALE' ,
Sets 'transparent' !loutput scaling and full-screen
window
3 LlGRF XI'~'YI'Y2
SCALE XI'~'YI'Y2
Sets x and y limits for fixed 2D scaling
3 l1GRF
X 1'X2' Yl' Y2' Zl' Z2
SCALE
Xl' Xu Yl' Y2' Zl' z2
Sets
X,
y, and
Z
limits for fixed 3D scaling
4 LlGRF ' ,
SET' ,
Restores cursor loc saved by SET x, •••
4 LlGRF x,y
SET x,y
Saves cursor loc; moves it to' (x, y)
4 LlGRF x, y, Z
SET x, y, Z
Saves cursor loc; moves it to (x, y, z)
5 LlGRF"
AXES
Draws axes according to current scaling
6 LlGRF 1
NOSCALE
Sets noncentered automatic scaling
6 LlGRF 2
CENTER
Sets centered automatic scaling (default)
6 LlGRF 3
7 flGRF' ,
Fixes current scaling
DASH
8 l1GRF ' ,
Specifies next curve to be dashed
Erases screen and homes cursar
8 LlGRF 1
ERASE
Erases screen (cursor homes automatically)
8 lIGRF 2
HOME
Homes cursor
BOX
Draws box according to current window
9
~GRF
' ,
10 l1GRF 1
168 .
Action Taken
Direct Control of Graphic I/O
Turns off curve reentrance mode
Table 6. lIGRF Calls (cont.)
Correspond i ng
Function Call
GRF Call
10 l'lGRF 2
Action Taken
Turns on reentrance mode (default)
11 lIGRF 1
WHATSCALE
Returns scaling params as result; result is 4-vector
(Xl' x 2' Yt' Y2) or 6-vector (Xl' x 2' Yl' Y2' Zl' Z2)
11 l'lGRF 2
WHATWINDOW
Returns the current window params (in inches) as
a 4-vector (x I' x 2, YI' Y2)
11 l'lGRF 3
WHATCOORDS
Returns the most recent Dl input coordinates as a
2-vector (x, y)
11 llGRF 4
WHATCHAR
Returns the most recent K:! input character as a
scalar
11 llGRF 5,6,07
STRAPIS
Sets program to read 5, 6, or 7 characters on
graphic input requests. Used to accommodate
different "strappings" at the 4013. Default is 7.
Unsealed Graphic I/O
Ordinarily, the x, Y (and possibly z) coordinates of the points given as arguments of SET and DRAW are interpreted
in conjunction with current scaling and window parameters: Scaling determines where in the window a given point
will lie, and the window parameters locate the window on the screen. If desired, however, one may ci"cumvent
these actions and deal with the screen as a "directly addressable" entity; in this mode no scaling or windowing is
done (the "window" is the entire screen), and point locations are specified by X and Y coordinates in raster-point
units. The ranges of such coordinates are
Os
X
s 1023,
Os Y ~ 789.
Unsealed Output
Output scaling may be killed by
SCALE
I
I
This command establishes the "transparent scaling" (i .e., no scaling) rule, and sets the window to full-screen. Thereafter, point data supplied as right arguments of DRAW or SET commands should have coordinates in the ranges indicated above. Three-dimensional points will be projected on the xy plane, as usual; for 3D data, the x and y ranges
are as given above, and the z-range is the same as the x range.
Ordinary output scaling may be resumed via
NOSCALE
or
CENTER
or
SCALE x ,x , .•.
A smaller window may be reestabl ished by
or
'.
the default window may be restored by
WINDOW
I
I
Unsealed Graphic
Vo
1.69
Unsealed Input
Input scaling is turned off by
o lIGRF 1
This command does not alter the existing scaling and window parameters, but it does eliminate dependence on them
by !J input. While in this mode, a character struck anywhere on the screen will be accepted, and its raster-point
coordinates (in the ranges given above) wi" be those returned by WHA TeOORD.
To resume ordinary input scaling (using the existing scaling and window information), input
o lIGRF 2
1~·
u..c:c.led Graphic
I/o .
12. WORKSPACE MANAGEMENT FUNCTIONS
Xerox APL provides a set of intrinsic functions, tlCR, tlWM, and tlTE to aid in user workspace management and
display. The functions may be copied from workspace WSFNS or created as described in Appendix C.
Namelists and Linelists
The introduction of two concepts is useful to allow abbreviated descriptions of arguments and results associated with
the following intrinsic functions. Namelists and linelists are particular forms of character arrays, useful for storing
text data with minimal waste for blank padding.
A name list is any text vector or matrix for which each row consists of one or more valid APL names separated
by blanks, embedded carriage returns, or embedded line feed characters.
When namelists are created by the intrinsic functions, they will always be vectors. Individual names will be separated by embedded line feed characters. The purpose of interspersing line feeds is to avoid the arbitrary splitting
of names in terminal displays of namelists. For this reason, it is advisable for users to create namelists while using
the smallest width setting which will be encountered during their use.
Namelists which are character matrixes may be used as arguments of functions which call for name lists. In this case,
each row of the matrix must satisfy the rules for a vector namelist. Matrix namelists have been allowed to satisfy
circumstances in which users find it advantageous to build rectangular arrays of names.
A linelist is a text vector consisting of character strings separated by embedded carriage returns. In use, the first
'line' must consist of appropriate text for a user function header, and all subsequent 'lines' must consist of text which
would be valid function lines. This includes line length limitations.
Line Feed and Carriage Return
The line feed character is hexadecimal 15 (or decimal, 21). Carriage return is hexadecimal OD (or decimal, 13).
On terminal output, either character generates the line feed-carriage return combination of physical action.
When APL input lines with open quotes are extended, the line separator used internally by APL is the line feed character. The carriage return was selected as the separator for linelists to distinguish this separator from the line feed
character which occurs in open quote line extensions.
Error Reporting for Namelists and Linelists
If a function requires a namelist or linelist as an argument, the argument will first be checked for rank of 1 or 2 and
character data type. DOMAIN ERR will be reported if these checks fail. Namel ists are checked for the presence
of forms bther than valid APL names. If this test fails, DOMAIN ERR is reported.
Linelistsmay generate any of the errors which would be encountered in regular input of the individual 'lines' including LENGTH ERR for lines of excessive length.
Canonical Representation
The tlCR intrinsic function is used for conversion of user functions to text form, for program-controlled function definition, and to lock existing functions. The intrinsic is created by tlCR+ 14T5.
Function to Text
R+1
tlCRA
If A is npt a text
vec~r
•
•
representing a valid name in APL, DOMAIN ERR is reported •
Workspace Management Functions
\71
If A contains a name which does not represent a user-defined function in the dynamic environment, DEFN ERR is
reported. This may occur, for example, if the name represents a function at global level but is currently shadowed
by a local use as a variable. Functions which will use t.CR should avoid the use of common names for dummy or local variables.
If no error is indicated..R is a lin~list, that is, a text vector consisting of lines of the defined function with embedded carriage returns as ~parators. The text vector does not include opening or closing dels or line numbers (it is not
the display form). If A is the name of a locked function, R is the empty text vector. The form of R is the internal
APL character representation, in which valid overstrikes are mapped as single characters. This fact is noted for users
of non-APL keyboards. Mnemonics are not created internally, so indexing by visual position will be misleading.
Note that the separator for function lines is the carriage return (hexadecimal OD), which can be distinguished in
editing operations from line feed •.
.
Text to Function
R+2
6CR
...
LL
If LL is not alinelist, DOMAIN ERR results.
If any 'line' of LL exceeds the maximum length for APL input lines, LENGTH ERR is reported. If the linelist does
not contain at least one line in addition to the function header line, DOMAIN ERR is reported. DEFN ERR is reported if the 'header' line is not in the proper format for a function definition or if the function name has an active
referent which is not a user function or is a locked user function.
DEFN ERR also occurs if the body of the linelist includes constructs including the colon character, not in a quote
string, other than valid line labels.
Errors which would give BAD CHAR or LINESCAN ERR in normal input are accepted and detected later as SYNTAX
ERR during function execution.
If no errors occur, a user function, with the name specified by A, is created. If the new function name is currently
a local symbol, the function will exist as a local entity.
R is a text vector indicating the name of the function created.
Locking Functions
R+3
t.CR
NL
NL must be a namel ist. For each name in NL, if the current referent is a function, it is locked. If not, the name
is included in R.
R is a namelist consisting of any names in NL which were not current function names. If no such names were in NL,
R is empty.
Workspace Management
The workspace management function, t.WM+14T6, is a dyadic intrinsic function providing a variety of operations described below.
Expunge, Local (Active)
R+l
I1WM
NL
NL must be a namelist. The active referents of names found in NL are erased. R is a namelist of any names for
which referents were found but not erased (e.g., pendant functions). Note that a current active referent may be
(and often is) the global referent •
172
.
Workspace Management
Expunge, Global
. R+2
lJ.WM
Same as 1 lJ.WM
NL
NL except that only global referents of names are erased.
list Workspace Named Items
R.... 3
lJ.WM
The value of I must be an integer from 1 to 6. R is a namelist. The entities named depend on I.
Category listed
Labels.
2
Active variables.
3
Active functions. _
4
Groups.
5
Global variables.
6
Global functions.
List Elements of a Group
R.... 4
lJ.WM
A
A must be a text vector containing one name. If A is not the name of a group, DOMAIN ERR is reported.
R is a namelist with names of the elements grouped by A.
List Workspace Parameters
R....5
lJ.WM
The value of I must be an integer from 1 to 8. R depends on the value of I.
1
Jt
WSID as text vector.
2
State indicator as text vector with embedded line feeds.
3
Origin as integer.
4
Width as integer.
5
Digits as integer.
6
Tabs as integer scalar or vector.
7
Symbol table size.
8
Number of symbols still available.
Worksapce Management
173
Identify Local Use of Names
R+-6
r::,WM
NL
The namelist, NL, is scanned for current use of the names. R is a numeric vector. Values are as indicated.
o
No current referent.
Logical variable.
2
Character variab Ie.
3
Integer variab Ie.
4
Real variable.
5
Index sequence. (This is an integer vector with equally spaced elements. It is functionally an integer
variable; but is compressed in storage.)
6
List (used by r::,FMT, r::, TE).
7
Label.
8
User-defined function, niladic, no resu It.
9
User-defined function, niladic, with result.
10
User-defined function, monadic, no result.
11
User-defined function, monadic, with resu It.
12
User-defined function, dyadic, no result.
13
User-defined function, dyadic, with result.
14
Intrinsic function, dyadic.
15
Intrinsic function, monadic.
16
Intrinsic function, niladic.
17
Group.
Note: Intrinsic functions are analogous to locked user functions in that they cannot be displayed.
Identify Global Use of Names
R+-7
r::,WM
NL
Similar to 6 r::,WM except that global use of names is indicated.
List Storage Requirements for Named Active Items
R.... 8
r::,WM
NL
NL is a namelist. R is a numeric vector. NL is scanned for active referents of names. If there is no active referent
for a given name, that element of R will be O. Each element of R is the number of bytes of workspace occupied by
the active referent.
174
Workspace Management
List Storage Requirements for Named Global Items
R+9
/lWM
NL
NL is a namelist. R is a numeric vector. NL is scanned for global referents of names. If there is no global referent,
that element of R will be O. If a name is a group, only the group overhead is listed (to get space requirement for the
members df a group, use 9 t::. WM 4 t::. WM G, where G is the group name). Each element of R is the number of
bytes of workspace occupied by the global referent of the corresponding name.
Note: Storage requirements cited by use of 8 /lWM or 9 t,WM do not include the storage required by long names.
Such names may be shared by local and global referents and are thus not unambiguously accountable.
Text Editing
The text editing function, t,TE-+-14T7, provides five capabilities, described below, to facilitate the examination and
modification of text variables in APL.
APL has suffered a limitation, in handling text, in that most primitive functions work on single characters and that
extensive text variables must be managed as rectangular arrays. This poses problems in wasted space and, much
worse, a very awkward form for modification. In a rectangular array, an edit operation cannot alter the length of
any row without altering the lengths of all rows by the same amount.
The use of embedded carriage returns in text vectors is a solution a lIowing better packing of text variables and making
text substitutions of unequal length a more straightforward operation. HE faci litates use of such text vectors.
Text Index Function
R-+-l
/lTE
L
L is a 'list' with two elements.
L -+- (TViDV)
TV may be any text vector.
DV is a text scalar or vector of 'delimiters'. Typically, delimiters will be blanks, carriage returns, line feeds, commas, or combinations thereof. Any character may be used as a delimiter.
R is an n .by 2 mumeric matrix. Each row contains the index and length of a string of non-del imi.ter characters in TV.
The values of column 1 of R are ORIGIN dependent. R is null if TV is a null text vector or includes only delimiter
character;s.
Example:
TV is a namelist, NL. DV is DV+' " LF, where LF is the line feed character and the quotes enclose a blank.
R-+-l
/lTE (NL;DV) provides the indices and lengths of the names in NL.
DOMAIN ERR is reported if L is not a two-element list, with text elements. LENGTH ERR is reported if DV is an
empty text vector. RANK ERR is reported if TV is a text scalar.
Substring, Search
R-+-2
/lTE
L
L must be a list with 2, 3, or 4 elements
R+(TViSS)
TV may be any text vector.
..
Text Editing
175
SS may be any text scalar or vector not longer than TV •
. l + (TVjSSjFCOl)
FCOl may be any integer scalar value such that FCOl + (number of elements in SS) -1 i$ less than or equal to the
highest index value of TV. FCOl may also be null. FCOl indicates the first column in TV at which search is to
start or
l + (TVjSSjFCOlj lCOl)
lCOl may be any integer scalar value less than or equal to the highest index value of TV and greater than or equal
to FCOl-l + (number of elements in SS). lCOl is the last column of TV involved in the search.
R is a numeric vector with the beginning indices of occurrences of SS in TV, starting at position FCOl and ending at
lCOL. If there are no occurrences, R is empty. 'Occurrences' may not overlapj that is, successive values in Rare
a Iways separated by the length of SS.
Example:
TV is a namelist, Nl, whose length is 100. SS is SS+'BOB'.
R+2
liTE (NljSS) provides the starting indices of all occurrences of 'BOB' in NL.'
R+2 liTE (NljSSj30) provides the starting indices of all occurrences of 'BOB' in Nl from Nl[30J to the end
of NL.
R+2 liTE (NljSSjj30) provides the starting indices of all occurrences of 'BOB' lying within the subset of Nl
from the beginning through Nl[30].
R.... 2 liTE (NljSSj30;60) provides the starting indices of all occurrences of 'BOB' lying within the subset of
Nl from Nl[30] through Nl[60].
DOMAIN ERR is reported if l is not a 2, 3, or 4 element list with TV, a text vector and iSS text scalar or vector, or
FCOl and lCOl not integer values.
lENGTH ERR is reported if the length of SS is greater than the length of TV, or FCOl and lCOl are not scalars.
INDEX ERR is reported if the length of SS is greater than the length of TV with FCOl or lCOl specified, or FCOl
and lCOl specify indices outside the range of TV.
RANK ERR is reported if TV is a scalar.
Since R is a vector of indices, it is ORIGIN dependent. FCOl and lCOl are index positions of TV and, therefore,
are ORIG IN dependent.
Substring Search and Replacement
R+3
liTE
l
l must be a list of 3, 4, or 5 elements.
l+(TVjSSjRS)
TV may be a text scalar or vector.
SS may be a text scalar or vector not longer than TV.
176
Text Editing
RS may be any text scalar or vector not longer than 255 elements, including the empty vector.
R is'a text vector formed by replaced .occurrences of SS, in TV, by RS. Replacement is on a non-overlap basis.
or
l ... (TV;SS;RS;FCOl)
FCOl may be any integer scalar value such that'FCOl + (number of elements in SS) -1 is less than or equal to the
highest index value of TV. FCOl may also be null.
or
l ... (TV;SS;RS;FCOl;lCOl)
lCOl mdy be any integer scalar value less than or equal to the highest index value of TV and greater than or equal
to FCOl-1 + (number of elements in SS).
Example~
Nl is a namelist with the blanks and embedded carriage returns. Several names may print on one line. BlAN K
has been assigned the blank character, and CR the carriage return.
VNl .... 3
aTE (NliBlANK;CR)
VNl has all blanks replaced by CR, and prints one name per line.
VNl+3
aTE (Nl;BLANK;CR;20)
VNl has all blanks from Nl[20] to the end of Nl replaced by CR.
VNl ... 3
aTE (Nl;BLANK;CR;20;30)
VNl has all blanks from Nl[20] through Nl[30] replaced by CR.
VNl .... 3
aTE (Nl;BLANK;CR;;30)
VNl has all blanks fro~ the beginning of Nl through Nl[30] replaced by CR.
VNl + 3
t. TE (Nl;BLANK;NUll)
VNl has all the blanks in Nl removed. (NUll is the empty vector.)
DOMAIN ERR is reported if l is not a 3, 4, or 5 element list with TV, SS, and BS text elements, or FCOl and
lCOl not integer vdlues, or the length of RS is greater than 255.
lENGTH .ERR is reported if the length of SS is greater than the length of TV, or FCOl and lCOl are not scalars.
INDEX ERR is reported if the length of SS is greater than the length of TV with FCOl or lCOl specified, or FCOl
and lCOl specify indices outside the range of TV.
Substring Replacement (Without Search)
l is a list with 4 elements.
l + (TV;RS;FCOl;lCOl)
TV must be a non-empty text vector.
Text Editing
117
RS must be a text vector or sca lar. It may be empty.
FCOl must be an integer scalar representing a valid index of TV.
lCOl must be an integer scalar representing a valid index of TV. lCOl must be greater than or equal to FCOl.
R is formed by replacing that portion of TV bounded by FCOl and lCOl by the string RS. If RS is empty, this constitutes deletion of a specified subset of TV.
FCOl and lCOl are index positions of TV, thus ORIGIN dependent.
DOMAIN ERR is reported if l is not a 4-element list, if TV is not a non-empty text vector, if RS is not a text vector
or a scalar, or if FCOl and lCOl are not integer scalars.
INDEX ERR is reported if FCOl and lCOl are not value indices of TV, with current ORIGIN setting, or if lCOl is
less than FCOl.
Example:
ORIGIN is 1
TV+- 'THE PRICE OF PRODUCT-NAME SHOULD BE'
RS+ 'WHEATIES'
R+4 liTE (TViRS;14;25)
R
THE PRICE OF WHEATIES SHOULD BE
String Comparison
R+5
L'lTE
l
l must be a list with two elements:
l+ (A; B)
A and B must be text vectors of length 1 to 255 characters or text scalars. (Text scalars are treated as one-element
vectors. )
R is a two-element numeric vector describing the comparison of A and B. Comparison is based on the collating
sequence of Figure B-1, Appendix B, which is the EBCDIC collating sequence as modified to support the full APl
character set.
The first element of R indicates which element of l should be first in left to right sorted order.
o means the
text vectors are identical.
1 means A should sort first.
2 mea ns B shou Id sort fi rst •
The second element of R indicates the lowest index position i at which A[i] and B[i] differ.
If A and B are identical, the second element of R is -1. Thus R is 0 -1.
If B is longer than A but each A[i] = B[i], that is B differs from A only by being longer, then A is considered first in
sorting order and R is 1 -1.
If A is longer than B, but each BDJ = AU] then R is 2 -1.
DOMAIN ERR is reported if l is not a two-element list or if A or B is not a text vector or scalar.
lENGTH ERR is reported if A or B has a length of less than one or more than 255.
178
Text Editing
APPENDIX A. ERROR MESSAGES'
Table A-I is an alphabetic listing of possible APL error messages. The first column contains the message and the
second col umn contai ns explanatory detai Is and recovery procedures where appropriate. The effects of error detection on APL processing are described in more detail in Chapter 10; see also "Sidetracking on Errors and Breaks" following Table A-l.
Table A-I.
Error Messages
Message
Description
name NOT COPIED
The item named has the ;ame 'lame as a pendant function
in active workspace.
name NOT ERASED
The item named in an )ERAS::: command was rot erased
because it was a pF!nclant fun,::;ion.
name NOT FOUN D
The item named in 0 )eOPY comrncmd was not found (the
item may have been a local variable).
ABORTED BY BRK OR CTRL-Y
An enqueue request has been aborted by user (pertains to
shared APL indexed fi las).
BAD CHAR
,~
BAD COMMAND
BAD FILE REF
bad input character was detected. This is usually the
,esult of a "tran,mission error or the input of an illegal
Nerstri' - ln ti.e case of nonstandard I/O del;ces, the
)'iessage em als·) indicate the input of a charoer-·cr which
"iJleg i" fo' ,hat dEvice.
'\,1 improper command conshuct was detected.
, bad rf';ferend' to an existing file name was made during
)SAV[ commond. This could occur, for example, if the
Vlorkspoce name specified in the }SAVE referenced some
existing workspnce that wos protected by a password. The
)SAVE should be r<;specified using (1 different workspace
n:tme. This mesE>oge wi II a Iso result on iCON nNUE if a
passworded CDNTINUE workspace already exists.
':l
COMPo ALREADY HELD
/In attempt wm node [0 enqueue a record already enqueued
in a shared APL indexed fj Ie.
COMPo NOT HELD
/\11 error was dd,scted all attempting to dequeue an unheld
record in a shared APL indexed file.
DAMAGED WS, ERROR TYPE: *n*
\!v'orkspace damGge has been detected in executing )LOAD,
)SAVE, or )COPY. In any case, the filed version of the
damaged worbpace exists. The error type is a number
indicating the type of damage Co tected. This message,
and the name and account of the damaged workspace,
should be reported to y,::'Jf time-sharing service. The information may be used by Xerox to correct an error in the
APL processor. If the error occurred during a LOAD or
SA V E, a CO PY of the damaged workspace may allow retrieving the global dola and functions.
-~
DEFN ERR
This message is output for any sort of error in function definition, such as a misplaced del symbol (v), improper syntax of a function header as a result of header editing, or
an attempt to edit a pendant function.
Appendix A
179
Table A-l. Error Messages (cant.)
Message
180
Description
DMS ERR
An error was detected during a DMS operation in a
system supporting interface between APL and EDMS
data bases.
DOMAIN ERR
The indicated argument is of the wrong type or out of the
proper range for this specified operator or for the other
argument. Examples are character data input for a numeric operation, or numbers input for a logical operation
which do not reduce to 0 or 1. See the domain tables in
Chapter 5 for examples of acceptable types of argument
data for each APL operator.
ENQ FULL
The CP-V Enqueue stack is full (pertains to shared APL
indexed fi les).
ENQ UNAUTHORIZED
User is not authorized for Enqueue operations on APL
shared fj les.
FILE ACCESS ERR
This file I/O error often means a password is missing or is
inaccurate.
FILE DAMAGE
This file I/o error indicates some damage, but not necessari Iy to every record or component in the fi Ie. Recovery
is often possible by copying undamaged material to a new
file, replacing damaged items.
FILE IN USE
The file named in a )SAVE command is currently in use,
i.
another user may be simultaneously executing a load
of that file. Since this situation is a momentary timing
conflict, the user should retry the command after a short
wait. This type of timing conflict may also occur when
exercising file I/O.
FILE INDEX ERR
This file I/O error may mean that an index (record identifier, sometimes called a key) is incorrect, or an attempt
has been made to read beyond the limits of a file.
FILE I/O ERR xxxx
This is a general file I/O error message. The "XXXX" stands
for a hexadecimal error or abnormal condition, with the
first pair of digits indicating a code and the second pair
a subcode. A code 00 indicates that APL has detected an
error (see Appendix B, File Input/Output). Other codes
indicate errors detected by the monitor and correspond to
I/O error codes shown in monitor reference manuals, for
example the CP-V Reference fv\anual, 900907.
FILE NAME ERR
This file
properly
file that
crea te a
Appendix A
e.,
I/o error may mean that a file identifier is imformatted, an attempt has been made to use a
doesn't exist, or an attempt has been made to
fj Ie tha t a Iready ex ists.
Table A-l. Error Messages {cont .}
I
Message
Description
FILE SPACE TOO LOW
Either the user's or the system's file granule limit is surpassed. This can occur when workspaces are being saved
or during file I/o operations. Recovery is usually possible;
the user drops unneeded files from his account and retries
the aborted step.
FIL E TBL FULL
This file I/o error means ,that the maximum permissible
number of files have been "tied" (designated).
FILE HE ERR
This file I/o error may mean either that the file has not
yet been tied (designated to an input or output stream), or
that the file being tied has already been tied, or that an
attempt has been made to write into a file owned by another user.
FORMAT SYNTAX ERR
A syntax error was detected in the left argument of a L'lFMT
expression. See Chapter 9 for an explanation of correct
L'lFMT syntax.
I/O ERR
This message indicates that an irrecoverable system I/o
error occurred and an error exit has been made from the
APL processor. A system I/o error should be reported to
the user's field representative along with the conditions
under which it occurred (see also SYS ERR).
I/o
I/o was being used, this message indicates that
the requested blind write could not be executed for some
reason. The user may retry the Vo or otherwise continue
operation.
ERR xxxx
If blind
This general Vo error includes hexadecimal error or abnormal condition "xxxx". The first pair of digits indicates
a code and the second pair a subcode. These correspond
to I/o error codes shown in the Xerox CP-V reference
manuals.
INDEX ERR
The index sLlbscript specified in an expression is out of the
range of the particular array to which it is applied. For
example, if A is a four-element vector, the expression
A[6J would generate an INDEX ERR since the requested
sixth element does not exist.
LENGTH ERR
The length(s} of the indicates argument(s} are not conformable or are incorrect for the operator used. For example,
the expression 9 7 8 + 53 results in a LENGTH ERR because
the two vectors do not have the same number of elements.
LIN ESCAN ERR
An obvious error in form (leading right bracket, misplaced
colon, line ending with an operator, etc.) was detected
in the scan of a line input for execution or function definition. No part of the I ine is executed. On direct input, the user is prompted with the partial line for correction unless the device is nonstandard, in which case he
must retype the entire line. In function definition mode,
the incorrect line is entered as part of the function and
may then be replaced or edited.
Appendix A
181
Table A-l. Error Messages (cont.)
182
Message
Description
NO RESULT
A user-defined function which generated no result was
used in a syntax which requires a result.
NOT APL FILE
This file I/o error means that a component read failed
because it did not have the structure required by APL.
NOT ENQ SYSTEM
An attempt was made to use shared file enqueue feature,
which is not supported by the local installation.
NOT GROUPED
The group name specified in a )GROUP or )GRP command
already references an item which is not a group. A different group name must be used.
NOT SAVED, THISWS IS name
If "name" = CLEAR WS, either there is nothing to save
or the SAVE command did not specify a name for the saved
workspace. Otherwise, the save command named an existing saved workspace when the active workspace name is
different. Change the name or drop the saved workspace.
OPEN QUOTE
The Execute operator has been used on an argument that
has an odd number of quotes before· the end of line (or
first embedded carriage return).
PRIVATE PACK UNAVAIL, CALL OPR.
This file I/o error usually means that the user has referenced a private disk pack that has not yet been mounted
by the computer operator. A message should be sent to
the operator to mount the correct disk pack.
RANK ERR
The rank of the indicated argument is incompatible with
the operator or with that of the other argument.
REQ. WOULD CREATE DEADLOCK
An enqueue request has been made, pertaining to APL
shared files, which, if honored, would create a deadlock stopping further activity of two or more users.
SEALED WS
Attempt was made to save or display functions of a sealed
workspace.
51 DAMAGE
A suspended function has been erased or replaced, and the
state indicator has been modified to delete all calls to it
from its active list. This may occur in function definition,
or upon execution of an )ERASE ora )COPY command.
51 DAMAGE WILL RESULT: TYPE'GO'TOCLOSE
This warning message is output in function definition when
the header of an existing active function is changed. It
indicates that references to this function in the state indicator list wi II be damaged if the header change is implemented. In order to avoid 51 damage, the user may restore
the header to the old form or change the function name in
the header before closing the function. If he wishes to
close the function and accept the 51 damage, he may do
so by typing GO in reply to the warning message.
SING. MATRIX
The right argument of a matrix divide operation (Iil) is a
singular matrix, i.e., it has no inverse.
Appendix A
Table A-l. Error Messages (cont.)
Message
Descri ption
SYM TBL FULL
The internal symbol table is full. This may occur during
execution, in function definition, or because of a )GROU P
command. If the user wishes to extend the symbol table at
this point, he must )SAVE the workspace, issue a )CLEAR
command, use the )SYMBOLS command to request an extended allocation, and then issue a )COPY, not a )LOAD,
to restore the workspace. Fu rther information on the use
of the )SYMBOLS command may be found in Chapter 8.
SYNTAX ERR
Improper syntax was detected in the executed line. Examples of improper syntax are unba lanced parenthesis, two
variables not separated by an operatar or by a function,
or an attempt to assign a value to a label.
SYS ERR
An irrecoverable system error of indeterminate origin has
occurred and an error exit has been made from the APL processor. If APL is reaccessed, it starts again witha clear
workspace and should operate correctly unless the conditions which led to the SYS ERR reoccur. Error should be
reported to field representatives with accompanying data.
TOO BIG
A )COPY command accessed more material than would fit
in the current workspace; no items were copied.
TOO BIG TO LOAD
The workspace specified in a )LOAD command was saved
by a user wi th larger memory a I location than the present
user, and there is insufficient space for the workspace to
be loaded (i n some cases it cannot even be copi ed). See
also the description of the )COPY command, Chapter 8.
TOO MANY SYMBOLS
The symbol table would have overflowed if the requested
)CO PY command were performed; no items were copied.
**TRAP**
Similar to SYS ERR except error was detected via machine
trap rather than by the APL system. See description of
SYS ERR, above.
TRUNCATED INPUT
The input line was too long.
UNDEFINED
The indicated symbol has not been assigned a value.
WRONG TERMiN AL
The user has attempted to perform graphics input, graphics
output, or graphics service (.6.GRF) with a terminal type
not appropriate to graphic I/O. Terminal type 13 should
be used for Tektronix 4013 or 4015. Terminal type 3
should be used for Tektronix 4010.
WS FULL
The active workspace is full. This may occur during execution, in function definition, or because of a )GROUP .
command. Depending on his particular situation, the user
may choose to )ERASE unneeded objects from the workspace, clear the state indicator, or )CLEAR the entire
workspace in order to free up space.
WS NOT FOUND
The workspace file specified in a )LOAD or a )COPY
command was not found.
Appendix A
183
Sidetracking on Errors and Breaks
In some APL applications, the programmer would like to bypass APL's standard error and break procedure. He may,
for instance, wish to substitute his own messages or institute corrective actions. Computer-assisted learning programs and commercial business aids are applications where this may be desired. Users of such applications may have
little knowledge of APL, and messages such as DOMAIN ERR or WS FULL frustrate rather than help.
Xerox APL has been enhanced to allow the programmer to overcome this problem. This enhancement is called "sidetracking"; also the term "error control" is sometimes used (with an understanding that break control is included).
Suppose a DOMAIN ERR has been detected by APL. Under the enhancement, Xerox APL starts looking back through
the state indicator searching for active functions for which the programmer has designated sidetracking. If a sidetracking function wants control over DOMAIN ERR, then APL sidetracks (branches) to the line in the function specified for DOMAIN ERR. If no active function wants such control, then APL issues the standard diagnostic message.
Sidetracking is both flexible and dynamic. Different errors can be sidetracked to distinct lines of a function. Certain
sidetracking functions may control some errors while other sidetracking functions control others. Sidetracking functions can also compete for control of the same error. In this case, the most recently invoked function gets control,
and its competing predecessors never become aware that the error occurred. Sidetrack specificati ons can be changed
at will. They can be turned on and off, the error selection can be altered, and the sidetrack branches can be
changed; the application program itself can modify sidetracking specifications throughout its execution. This capability permits a simple or comprehensive treatment at the programmer's discretion.
Table A-2 shows errors that are subject to sidetracking.
Errors not listed in the table include:
SYS ERR, **TRAP**, *BAD WS*, and (irrecoverable) I/O ERR.
Since recovery from these errors is impossible for an applications program, APL retains exclusive control.
discussion following Table A-2 for details concerning certain unique errors.
See the
Associated with each item in Table A-2 is an error number. Error numbers are informally grouped by common classifications: statement execution errors, input-translation errors, command errors, file input/output errors, etc. Gaps
are provided in the error number sequence to accommodate future diagnostics. It should be pointed out that in the
case of input/output errors two conditions must exist. One, the error must be recoverable. Two, APL must acknowledge the error - if a file I/o subsystem uses the file primitive 141'2, APL will acknowledge file I/o errors. If
file primitive141'l is used, however, the error data is passed on to the file I/o subsystem (a~ a scalar integer), and
APL wi II neither display a standard diagnostic nor attempt a sidetrack.
The items in Table A-2 contain four cases in which APL gives up control somewhat grudgingly:
SI DAMAGE
name NOT COPIED
name NOT FOUND
name NOT ERASED
These cases, in which command processing or function definition is in effect, must reach an orderly conclusion to
avoid workspace damage. Therefore, APL unilaterally displays the messages and proceeds to conclusion. (Nevertheless, sidetracking is still possible, and an application program might issue explanatory messages after the APL
messages, as one alte~native.) As APL proceeds in these four cases, a series of such messages could be displayed
(but this would be unusual). APL permits sidetracking only with regard to the latest error known at the conclusion
of this kind of processing. Using the execute-operator, for example, suppose a )COPY commGlnd occurs while sidetracking is in effect. Suppose also that some object, X, is missing - X NOT FOUND is displayed; furthermore,
suppose that the data found will not fit in the active workspace. Then the )COPY command concludes without copying anything and would ordinarily issue a TOO BIG message. Sidetracking would then apply to this example to the
TOO BIG error and, the NOT FOUND error would be "forgotten".
Note in the ,foregoing example that copying was attempted by means of an execute-operation. This was a necessity.
A function can obtain sidetracking only while it is actively in execution. Thus command and function definition
errors can be sidetracked only when the function (or some function invoked by the sidetracking function) actually
executes a command or function definition. Evaluated-input might seem to provide another way in which a function could, indirectly, invoke command or function definition activity. However, for the reason given below,
evaluated input is not considered capable of being sidetracked (except while that input has itself invoked a sidetracking function).
184
Appendix A
Table A-2. Items Subject to Sidetracking
Error Number
,
Standard Error Message or Break
Error Number
Standard Error Message or Break
1
WS FULL
46
TOO BIG
2
SYNTAX ERR
47
TOO MANY SYMBOLS
3
UNDEFINED
48
name NOT COPIED
4
DOMAIN ERR
49
name NOT FOUND
5
RANK ERR
50
name NOT ERASED
6
LENGTH ERR
51
NOT GROUPED
7
INDEX ERR
55
COMP; NOT HELD
8
NO RESULT
56
COMPo ALREADY HELD
9
SYM TBL FULL
59
ABORTED BY BRK OR CTRL-Y
15
SING. MATRIX
61
REQ. WOULD CREATE DEADLOCK
16
FORMAT SYNTAX ERR
62
ENQ FULL
20
BAD CHAR
64
ENQ UNAUTHORIZED
21
LINE SCAN ERR
65
NOT ENQ SYSTEM
22
TRUNCATED INPUT
70
FILE SPACE TOO LOW
23
OPEN QUOTE
71
FILE I/O ERR xxxx
30
I/O ERR xxxx
72
FILE DAMAGE
31
W~ONG
73
FILE NAME ERR
35
DEFN ERR
74
NOT APL FILE
36
SI DAMAGE
75
FILE TBL FULL
40
BAD COMMAND
76
FILE ACCESS ERR
41
NOT SAVED, THIS WS IS name
77
FILE TIE ERR
42
FILE IN USE
78
PRIVATE PACK UNAVAIL, CALL OPR.
43
BAD FILE REF
79
FILE INDEX ERR
44
WS NOT FOUND
99
DMS ERR
45
TOO BIG TO LOAD
TERMINAL
100
Break
Appendix A
185
In Xerox APL, the execute-operator makes it possible to execute via quote-quad input anything that could be
entered via evaluated-input. Quote-quad input has an advantage from the standpoint of error recovery. The input text can be assigned to a variable before it is executed. Thus, a sidetrack function can analyze this text to
determine correct recovery action. Evaluated-input is not susceptible to this analysis; it is immediately interpreted
by APL.
Setting Sidetracks
A sidetrack setting resembles setting a stop vector. The similarity is so strong that it must be noted that they are
totally independent of one another. The syntax for setting sidetracking in a function is
S6name
+
table
where:
name
is the name of the function and
table
is the 2-column matrix in which the first column contains line numbers and the second contains error
numbers.
The function must be defined when this syntax is executed; it could be a statement in the function.
be set even when a function is locked.
Sidetracks can
In effect, the sidetrack table becomes part of the function's definition and is copied or loaded if the function is
copied or loaded. Function editing has no influence on the sidetrack setting. Since the s,idetrack table contains
line numbers, the following precaution should be observed. If editing a sidetracking function alters the position
of a line specified by the sidetrack table, a correct setting must be reissued. This is necessary to ensure that the
proper line will be branched to if the sidetrack does take place.
Erasing a sidetracking function erases its sidetrack setting. A sidetrack setting can also be removed by being replaced with an empty matrix, as in the following example.
S6FUN+0
2pO
Note: Assigning an empty vector removes the stop vector, but not a sidetrack setting.
- - - affect sidetracking.
Only matrix assignments
When a (nonempty) table is as~igned for sidetracking, it consists of one or more rows. Each row contains a pair of
integers - a line number and an error number. The line number designates which line of the function is to be sidetracked to (branched to) if the indicated error occurs. The following sample sidetrack setting specifies a branch
to line number 9 in case of a DOMAIN ERR (error 4 in Table A-2).
S6 FUN+l
2p9
'+
A new sidetrack setting for a function entirely replaces any previous setting.
remove FUN's control over DOMAIN ERR.
S{' FUN+2
2p9
3
9
Thus, the following example would
2
In this example, FUN sidetracks to line 9 for UNDEFINED or SYNTAX ERR. This illustrates that a sidetrack table
can contain duplicate line numbers; however, it is useless to duplicate an error number in the same table. Only
the first such number would be effective.
In the above example, FUN sidetracks on only two of the possible errors. If other errors occur, APL handles them
in the standard manner unless some other function has specified sidetracking for those errors.
A special error number, 0, exists for sidetracking on all items in Table A-2 except the break (number 100).
the following example, FUN sidetracks:
•
to line 8, if a break is detected
•
to line 7, if WS FULL occurs
•
to line 9, for any other error subject to control.
S6 FUN+3
2p8
100
7
1
9
0
'Error n~mber 0 should always be the last number in the table, anything after it would be ignored.
186
Appe"ncI i x A
In
Breaks are sidetracked only if the sidetrack explicitly includes error number 100.
The following example shows a compact way of setting several different error numbers to the same line:
Suppose ERRLAB is the label of the desired line and sidetracking is set within the function FCN containing ERRLAB.
St.FCN+ERRLAB, [1.5J2 3 5 8 21
sets the indicated error no sidetracks to ERRLAB (see "Lamination").
The above examples illustrate how to set sidetracks. This does not imply that the function (FUN) immediately
receives control if an error occurs. If FUN is not actively in execution, its sidetracking is disregarded. Even if
FUN is being executed, it may still not be given control. The error may have occurred in evaluated-input, or
FUN may have called another function which has a competing sidetrack.
The Dynamics of Sidetracking
A step-by-step outline revea Is significant aspects of sidetracking dynamics. Assume a controllable error or break
has occur!red and APL is ready to check for sidetracking.
Step 1:
APL designates and saves the current error number, replacing any previously recorded error number. For
the moment, it initializes the error location to be line zero and an empty function name. APL points to
the top (latest) entry in the state indicator.
Step 2: The state entry is examined. If it is a pendant function, APL proceeds to Step 3. If it is an executeoperation state, APL points to the next entry and repeats Step 2. Otherwise, sidetracking is not applicable;
so APL issues the standard diagnostic.
Step 3: (Pendant function state.) The error location is tested. If still initialized (see Step 1), the line number
and name of the pendant function are recorded. The funcl'ion's definition is tested for sidetrack setting. If
it features some sidetracking, APL proceeds to Step 4. Otherwise, APL points to the next state indicator
entry and repeats Step 2, attempting to find a function with a sidetrack setting.
Step 4: (Sidetrack setting present.) The sidetrack table is tested sequentially versus the recorded error number. If
a match is found or the table has a zero error number, APL proceeds to Step 5. Otherwise, APL points
to the next state entry and repeats Step 2, attempting to find a function interested in the current error.
Step 5: (Sidetrack acknowledged.) APL removes from the state indicator any entries it bypassed in reaching Step 5.
This puts the sidetracking function at the top of the state indicator. APL then branches to the specified
line number (which mayor may not actually exist in the function).
Considerations After Gaining a Sidetracks
Once APL performs a sidetrack, it has no further interest in handling the break or error. Responsibility falls to the
application programmer, depenc\ing on the line number dictated and statements supplied :or the sidetracking function. Caution is advised.
If a mistake occurs in statements entered via a sidetrack, a new error may confuse the intended recovery procedure.
It is possible for that statement to generate the error being considered, leading to the same sidetrack, the same
mistake, and so on indefinitely. WS FULL can be particularly troublesome. In some cases, the statement reached
by the sidetrack will itself cause another WS FULL. There is no general solutio, to this potential problem, but it is
a rare difficulty for two reasons. First, intermediate results may be discarded after any error, freeing up sufficient
workspace for recovery. Second, more workspace may become available if state indicator entries are removed in
reaching the sidetrack (see Step 5 above).
The application programmer should also be cognizant of the monitor's role in handling breaks. If the monitor detects four consecutive breaks between two terminal input requests, it abandons APL processing and enters the TEL
subsystem. Thus it is recommended that when sidetracking on breaks, some inpL't from the user should be requested.
This clears the monitor's break count before the threshold is reached.
Appendix A
187
Aids for Sidetrack Users
Thr'ee niladic intrinsic functions have been added toAPLwhichareofparticularinterest aftera sidetrack has occurred:
ERRN+16TO
ERRF+16Tl
ERRX+16T2
ERRN produces a 2-element integer vector; the first element is the latest error number recorded and the second is
the line number for the error location (see Step 3 above). ERRF produces a text vector containing the name of the
function for the error location (it might not be the same as the sidetracking function). Initial values are zero for
error number and line number, and the function name is an empty vector. These are re-initialized by a )LOAD or
)CLEAR command.
ERRX produces a 4-character text vector containing the latest I/O "error" information available to APL. These
characters are hexadecima I digits. They represent input-output error (or abnormal) codes and subcodes as shown
in monitor reference manuals or, in the case of file I/O, APL file I/o error subcodes. The latter case is distinguished by two zero characters in the "code" field (i. e., the first two of the four charact,rs).
Note: APL sometimes expects error or abnormal I/O codes.
necessarily indicate erroneous processing.
188
Appendix A
Thus, the value reported when using ERRX does not
APPENDIX B. NONSTANDARD INPUT/OUTPUT
Standard and Nonstandard Devices
As defined in Chapter 3, standard APL input/output refers to the use of the APL typeball with the IBM 2741, or a
functionally equivalent terminal such as the DATEL 20-31; the DURA 1021 and 1051; the NOVAR 5-50; and the
. TST 707. Without attempting a truly comprehensive I/O capacity, APL nevertheless accommodates certain other
devices. These include Tektronix 4013, Teletype Model 33, non-APL equipped 2741 terminals for on-line processing, and card reader format input or line printer format output for batch processing.
Blind I/O and File
I/o are also discussed
in this appendix since they are considered to be modes of nonstandard I/O.
'Using Nonstandard Input/Output
Nonstandard input/output provides the user with a set of substitute characters and mnemonics as replacements for
APL characters which are either illegal or missing on his particular input or output device. In some cases the sub~titution is one-~o-one (APL ex is input or output as @ on nonstandard devices), but most substitutions for APL symbols
Involve mnemonics of one, two, or three characters preceded by a dollar sign key. Standard APL operators and their
substitute character mappings for each nonstandard device are listed in Table B-3 at the end of this Appendix.
Terminal Declaration
The character mapping to be used for a particular I/O device is determined by the user's terminal declaration. This
declaraction is made by means of the ;ystem command )TERMINAL n where n can have the following values:
1 - 2741 (or equivalent) with APL typeball.
2 - 2741 (or equivalent) with non-APL typeball.
3 - Teletype Model 33 (or equivalent).
4 - Line printer format output and card reader format input.
13 - Tektronix 4013 or other typewriter-paired APL/ASCII terminal.
14 - APL/ASCII bit-paired mapping terminals.
Type 1 is the standard terminal. In on-line runs the APL processor assumes a default terminal declaration of Type 1
if no declaration is made by the user. Type 2 typically features both uppercase and lowercase letters, although
special-purpose typeballs are also available. These can be used, but translation correspondences are the responsibility of the user. Type 3 indicates Teletype Model 33, but this declaration may be used for compatible terminals,
such as Teletype Models 35 and 37 (restricted usage). Type 4 is primarily applicable to batch jobs and is the default
declaration in CP-V batch runs. Type 13 is strictly applicable to the graphics terminal, Tektronix 4013, and must
not be declared for any other device.
If the input/output device is nonstandard, the user should make the proper terminal declaration immediately after
calling APL. He may then proceed with normal APL processing, using substitute characters and mnemonics as re. quired fpr his particular device.
Changing Terminal Declaration
The importance of making the correct terminal declaration should be evident to the user. In addition to character
mapping differences among the various devices, certain operational idiosyncracies exist for each device, as will be
discussed later. A false terminal declaration will very likely result in output discrepancies. However, new terminal
declarations are acceptable at any time during an APL run as long as the user can tolerate the consequences. One
example of these consequences is error message discrepancies. A diagnostic message {e. g., LENGTH ERR)will usually
display correctly, but the offending APL statement may appear badly garbled - in fact, some characters may even
be omitted. For the sophisticated user, however, there may be legitimate applications in which a false terminal
declaration can be useful. The following discussion of translation processes is intended to aid this type of user.
Appendix B
189
Input/Output Translation
It is vital that the user correctly identify his terminal to the CP-V communications handler at log-on time. All input
and output, whether standard or nonstandard, is ultimately constrained by the communications handler and the
input/output equipment. The initial translation on input and the final translation on output are always made byCP-V
according to the code set corresponding to the type of terminal indicated at log-on time. In the case of 2741 or
equivalent terminals, this translation is complicated by the fact that two fundamental code sets are avai lable for
these terminals - Selectric® and EBCD. In addition there are APL and non-APL versions for both of these code sets.
Un less decei ved, the communi cations hand ler reconci les the di fferent code sets; otherwi se the confusi on between
EBCD and Selectric codes can be a considerable problem. Whatever the device, this level of translation wi II occur
regardless of the terminal declaration applied by APL. Thus APL exercises only second-level control in the translation process.
The actual effect of the APL terminal declaration is to cause translation tables called Input/Output Mapping
Tables to be brought into memory. The particular set of tables is determined by the )TERMINAL command. Each
character input from the communications handler is then translated according to the resident Input Mapping Table.
Certain one-character translations are made at this point -converting an@ to APL internal ex for Type 2, 3, and 4
tables for example.
Illegal characters and certain key characters will be detected by APL for any terminal declaration. The backspace
key character indicates that overstrikes follow, and the $ key character indicates that mnemonic equivalents to
APL characters may follow. Once an overstrike has been accumulated, it is compared to a table of valid overstrikes.
This either results in the proper translation to internal APL form or the detection of an illegal overstrike character.
When a $ is detected as a single input character, the next three characters are acquired if available. These are
compared to a table of three-character mnemonics. If no match is found, the rightmost test character is ignored
and the remainder is compared to a table of two-character mnemonics. Again if no match is found, only the character following the $ is used for comparison to a table of one-character mnemonics. If a match occurs in any of the
above comparisons, the proper translation to internal form takes place. If no match is found, the $ itself is translated to internal APL form. Thus, if a sequence of characters following a $ looks like a mnemonic, it is translated
accordingly.
The overstrike and mnemonic tables reside permanently wi'thin the APL processor and are unaffected by the terminal
declaration. This means that the Teletype user could actually input overstrikes, assuming he ,could simulate the
backspace and "strange" characters. This flexibility is not possible for output, however. The Output Mapping
Table determines the resulting display regardless of the manner of input.
Output processing is similar to input processing.
occur:
For each internal character, one of four possible translations will
•
Conversion to a Single EBCDIC character.
•
Conversion to an overstrike triplet (character-backspace-character) given in the overstrike table.
•
Conversion to a mnemonic form given in the mnemonic table.
•
No conversion (for instance, when the character is not a known internal APL character).
Final output translation will then be made by the CP-V communications handler, again according to the type of terminal indicated at log-on time.
The following code tables may be of some interest to the user. Figure B-1 illustrates standard EBCDIC codes and
APL codes. Table B-1 shows Xerox line printer graphic codes.
False Terminal Declaration
As noted earlier, false terminal declaration does have potential applications. A batch user, for example, may wish
to create a file for later on-line output. He may declare a Type 1 terminal in this case in order to avoid having
the output fil e c I uttered with mnemon i cs.
®Registered trademark of the IBM Corporation.
190
Appendbc B
XEROX STANDARD a-BIT COMPUTER CODES (EBCDIC)
NOTES:
The characte" ~ \
11 []
are ANSCII
characters that do not appear in any of the
EBCDIC-based character sets, though they
are shown in the EBCDIC toble.
The characters,t
1-, appear
in the 63- and
89-character EBCDIC sets but not in either
of the ANSell-based sets. However, Xerox
software translates the characters
into ANSell characters as follows:
i I'"
EBCDIC
ANSClI
¢
, (6-0)
(7-12)
1
-
(7-14)
The EBCDfC control codes in columns 0
and I and their binary representotion ore
exactly the some os those in the ANSell
tobie, except for two interchanges: LF/NL
with NAK, ond HT with ENQ.
Choracters enclosed in heavy lines are
included only in the standard 63- and
89-chorocter EBCDIC sets.
These characters ore included only in the
standard 89-choracter EBCDIC set.
APl CODES
Most Significant Digits
Hexadecimal
Binary
a
1
c
t:D
~
'c
.2'
3
5
4
Sf
Index
10
8
7
-
n
!
I
I
2
0010
"
i!J
r
-
3
0011
e
0
I
i
,
EOT
5
0101
HT
6
0110
7
0111
8
1000
L
T
E
NL
lDLE
BS
4
0
w
~
•
0
•
q,
\
9
1001
A
1010
•
B
1011
C
1100
0
1101
E
111'0
F
1
.
c
·
t
u
<
.
(
CR
1111
I
1
·
)
;
-
p
?
F
The CP-V communications handler ignores
codes for the unmarked positions in the
tables.
0
B
K
5
2
c
L
T
3
[
D
M
U
4
~
J
E
N
V
5
E.
!!.
[Q]
F
0
W
6
!..
~
IT!
G
f
X
7
.!!.
g
1.
[2J
H
Q
Y
8
L
R
!
R
Z
9
0
,
,
E.
~
~
"-
10
!
<
D
-M
!I..
•
~
!!
>
F
.
Q.
-
~
J
:
·
·
,
,
E
J
J
V
D
A
A
. .
C
1000 1 1001 1010 1011 1100 1101 1 1110 1111
,
0001
0100
B
A
\
1
4
9
A
..
V>
!
6
0000 0001 0010 0011 1 0100 0101 0110 0111
0000
:!
:~
2
:
I
"
I
EOT is input when ATTN key is used in
input mode.
1
-<
[
I
The CP-V communications kandler Converts
both upper and lowercase letters to APL
(copital) letters on output.
4
1
The <), f-, -!, { , and characters are valid
only for the Tektronix 4013 terminal.
,
~
~
I!l
V
Note: C horocten bounded by heavy Hne, ore
ovenlrike combinetion. In APL.
Figure B-1.
EBCDIC and APL Codes
Appendix B
191
Table 8-1. Xerox Line Printer Graphic Codes
Character
6-8it Code
Blank
0
1
2
3
4
5
6
7
8
9
A
B
C
D
E
F
G
H
000000
11 0000
11 0001
11 0010
11 0011
11 0100
11 0101
11 0110
11 0111
11 1000
11 1001
000001
000010
000011
000100
000101
000110
000111
00 1000
Hex. Code Character
6-Bit Code
I
J
K
L
M
N
40
FO
Fl
F2
F3
F4
F5
F6
F7
F8
F9
Cl
C2
C3
C4
C5
C6
C7
C8
00 1001
01 0001
01 0010
01 0011
01 0100
01 0101
01 0110
010111
01 1000
01 1001
10 0010
100011
100100
10 0101
10 0110
100111
10 1000
10 1001
00 1011
0
P
Q
R
S
T
U
V
W
X
Y
Z
.
Hex. Code Character
C9
Dl
D2
D3
D4
D5
D6
D7
D8
D9
E2
E3
E4
E5
E6
E7
E8
E9
4B
<
(
+
I
&
$
*
)
;
-
/
,
%
>
#
@
I
=
6-Bit Code
Hex. Code
00 1100
00 1101
00 1110
00 1111
01 0000
01 1011
01 1100
01 1101
01 1110
100000
100001
10 1011
10 1100
10 1110
11 1010
11 1011
11 1100
11 1101
11 1110
4C
4D
4E
4F
50
5B
5C
5D
5E
60
61
6B
6C
6E
7A
7B
7C
7D
7E
As an example of the potential mix-ups when a false terminal declaration is made, however, consider the on-line
2741 user who issues the line printer declaration )TERMINAL 4. Suppose he requests display of a function containing the characters shown in the first column of the Table B-2. APL wi II transmit the characters shown on the second
column, since APL thinks it is outputting to a line printer. The CP-V communica.tions handler then transmits data
according to the translation codes for a 2741. The results are shown in the remaining columns based on the type
of 2741 used.
Table B-2.
Examples of Problems with False Terminal Declaration
Character
in Function
Character Sent
to Handler
x
#
t
APL
Result
Non-APL (EBCD)
Non-APL (Selectric)
;£
#
#
%
p
%
%
.$'
$
u
$
$
II
&
n
&
&
I
I
I
ignored
ignored
<
>
<
>
<
>
<
>
ignored
ignored
Teletype Usage
ESCAPE Key Sequences Ind APL
An important consideration for Teletype users is that standard CP-V ESCAPE key sequences wi·JI sti II be effective during
APL runs. These should generally be used with caution, since some of the ESCAPE sequence' capabilities may have
strange effects on APL input. Applications and restrictions for the more useful sequences are described below.
Line Editing
The ESC RUBOUT sequence for erasing the last character input, and the ESC X sequence for erasing the entire input
line are the recommended APL line editing procedures for Teletype users.
192
Appendfx B
~,
For Te!etype terminals with true backspacing capability, the CONTROL L key combination (Form Feed) will be
accepted as an alternate input editing signal. The response will be to generate a line feed and continue1accepting
: line input. CONTROL L (followed by carriage return) is used to delete a function line.
Tab Usage
Since Teletype Model 33 does not perform true tabbing, CP-V provides tab simulation. APL then allows input and
output of TAB characters on the assumption that the user has invoked tab simulation mode. However, APL wi II i
always replace input TAB characters with one or more spaces, depending on whether or not tab settings have been
specified via the )TABS command.
Teletype users should generally avoid the )TABS command, however, because its effect is nullified by CP-V tab
simulation. On output, for example, when )TABS have been specified, APL replaces strings of spaces with actual
TAB characters where appropriate. On detecting the TAB charactersCP-Vwilichange them back to spaces in order
to simulate mechanical tabulation. The net result is slower output than would have resulted if )TABS had not been
used.
[ Operational Differences
I
.
Prompt Character
The Teletype displays a double colon in place of the quad-colon sequence to indicate evaluated input prompt.
Quote-quad prompt is indicated by a single colon •.
Illegal Chara:cter
The uppercase (shift) N is considered to be an illegal input character on Model 33 Teletypes because of the potential confusion for APL users. On some keyboards this key represents an up-arrow (the APL "take" operator), while
on other key~oards it represents a caret (the APL "and" operator). Mnemonics will have to be used to represent
, either of these characters.
Error Marker
Th~
!
ampersand will be output on Teletypes as APL's error marker.
Batch Operation
Intended Usage
The batch mode in Xerox APLis provided for: the operation of progra~s with either extensive output or long execution
times. Its usage is not intended for simulation of on-line operations. The anticipated operation is to load extant
workspaces or copy functions and data from extant workspaces and execute them. Below is an example of a typical
card sequenCie which would follow the Monitor control cards.
Appendix B
193
In this example the workspace MYWORK contains the master function MYREPORTER which drives the APL processing.
Quad input will access data cards as appropriate.
Input/Output Device Assignments
i In CP-V batch processing mode, input (DCB = F:APL) and output (DCB = F:OUT) that would normally go to the user's'
terminal are defaulted to the card reader and line printer, respectively, unless otherwise assigned by a Job Control
card. Xerox APL will then assume a character mapping default of )TERMINAL 4 for card redder input and line printer
output. The )TERMINAL command can be used to modify character mappings if desired.
The F:APL DCB is used for APL source input, and F:OUT is used for output of results and diagnostic messages.
or both of these may be reassigned via the Monitor IASSIGN card prior to entering APL. For example,
: !ASSIGN F:APL, (FILE,APLINPUT), (IN)
Either
j
This card will cause APL input to be read from a user's file. That file should normally start with a )TERM command,
unless the user wishes to use the default terminal type 4, and should end with one of the )OFF or )CONTINUE
commands. If the following card is also used, the output will be routed to the file APLOUT rather than to the line
printer:
!ASSIGN F:OUT, (FILE,APLOUT), (OUT), (SAVE)
See the Xerox/CP-V/BP Reference Manual, 90 1764, for use of the IASSIGN card and batch deck setups.\
Card Input Format
'When )TERMINAL 4 is used, the following wi II be observed:
194
•
When input is via records other than cards (e. g., F:APL assigned to a file), APL automatically inserts a
new-line character following the last actual character read.
•
When input is via cards (or, in IBATCH runs with F:APL not assigned to a file), all input lines consist of
80 columns, including trai ling blanks.
•
Each card or record represents an individual line of APL input; there is no provision for continuation.
Appendix B .
Enar Response
Xerox APL batch operation is necessari Iy success-oriented. APL normally expects any input errors to be corrected
as they are detected, which is not possible in this mode of operation. Therefore, any error wi II terminate the run.
If a run is aborted, however, the processor will attempt to save the user's workspace by simulating the )CONTINUE
HOLD command, if appropriate. Sidetracking (see Appendix A) of errors can be used in batch runs, which wi II continue unti I a non-sidetracked error occurs.
O,l ...tionll DifferenCII
Prompt Character
The line printer displays a double colon in place of the quad-colon prompt character to indicate evaluated input
prompt. Quote-quad input is indicated by a single colon. The card reader is accessed for the actual input data
in both cases, unless otherwise assigned by a Job Control card.
Error Marker
When output is to the line printer, the ampersand is used in place of the caret for APL's error marker.
Tektronix 4013 Usage
The Tektronix 4013 terminal is used in conjunction with the on-line curve plotting faci Ii ties described in Chapter 11.
It employs a keyboard for input and a storing CRT display tube for output. Character I/O may be performed in
either of two modes selectable at the terminal: ASCII or APL.
ASCII MQdI
In ASCII mode, recommended for use in communicating with CP-V outside of APL, the 4013 acts like a Model 33
teletype with a true backspacing capabi lity. The character set and keyboard layout is simi lar to that of the
Model 33. Characters that differ from the APL characters shown on the key tops are indicated on the fronts of the
keys. ASCII mode is established by (1) placing the 'ASCII-APL'/,APL' switch in the 'ASCII-APL' position,
(2) illuminating the TTY LOCK switch, and (3) depressing SHIFT and RESET simultaneously to activate the ASCII
character set. This procedure should be done initially, before logging on, and whenever leaving APL to use other
CP-V faci Ii ties.
1- APL Mode
This mode provides a full APL character set with a keyboard layout similar to a 2741, as indicated by the key tops.
This, therefore, is the mode recommended for use in APL. A ")TERMINAL 13" command identifies the 4013 to the
APL processor. Since this command will ordinarily be issued immediately upon entering APL, with the terminal
still in t\SCII mode, it will be necessary for the user to switch to APL mode after typing ")TERMINAL 13". The
user does this by turning the TTY LOCK switch illumination off. Thereafter, I/o is done with the APL character
set shown on the key tops. In addition, the specification of terminal type 13 permits use of the terminal's graphics
capabi lities via D I/O and the ~GRF intrinsic, as described in Chapter 11.
Appendix B
195
Logging On
The log-on procedure is quite similar to that described for ordinary terminals at the beginning of Chapter 2.
reference to the steps there listed, the procedure is as follows:
1.
2.
With
Preparing the 4013 terminal for use:
a.
As shown - no change.
b.
As shown - no change.
c.
As shown - no change.
d.
Set the terminal to ASCII mode as follows:
(1)
Position the ASCII-APLjAPL switch to ASCII-APL.
(2)
Depress the TTY LOCK key to illuminate that key (each depression of this key reverses the TTY
LOC K state).
(3)
Press the SHIFT and RESET keys simultaneously.
Logging on to CP-V:
a.
As shown, except it is not necessary to type * 8. Once communication has been established, CP-V
initiates the dialog by typing the log-on message.
b.
As shown, except the prompt symbol is ! instead of o.
c.
As shown, except the prompt symbol is ! instead of o.
All input characters are ASCII and are shown on the key fronts, if different from the APL characters on the
key tops.
3.
Calling APL:
As shown. When APL prompts for its first input, type the command
)TERMINAL 13
(using the ASCII right parenthesis located over the 0), then switch to APL-mode by depressing the TTY
LOCK key once to turn off its illumination; Thereafter, all characters indicated on the key ~are included in the APL set.
Un. Editing
Line editing is done with the standard BACKSPACE-ATTN sequences, where the function of the nonexistent ATTN
key is supplied by DC (i.e., the CTRL and D keys depressed simultaneously). A function line may be deleted by
striking DC followed by RETURN. In addition, the standard ESCAPE key sequences will be effective, but should
be used with caution.
lf6
AppendIx B
The APL graphics software defaults to expect the terminal to transmit seven characters in "gin-mode". If a terminal
is strapped for five or six characters, users of APL graphics must invoke the STRAPIS function for proper response
(see Chapter 11). Unless conflicts with other operations preclude seven-character strapping, it is recommended
that the 4013 terminal be set in this mode.
The 4013 is available with interfaces to operate at several data transmission (baud), rates. The slowest rate,
110 baud, is compatible with Model 33 Teletype. If higher baud rates are used, different phone numbers are required. <;:heck with local installation management on transmission rate capabilities and corresponding phone line.
(Note that the higher baud rates, such as 300, are preferred for graphics work.)
NOD-APL 2741 Terminals
Appli:ationl
For normal users, the addition of the standard APL typeball to the 2741 terminal is highly recommended. Nonstandard IYo imposes a considerable overhead on the user because of the additional input and output characters
required for any operation. Furthermore, there are only certain applications in which nonstandard I/O capability
would be useful on the 2741. For example, standard APL might be used to generate output intended to be run with
a specialized typeball with dots and lines for plotting, or with a typeball which could output lowercase letters.
The common case, however, involves input and output on the same terminal, and standard I/O use is much more
practical here.
Opel1ltion,1 Considel1ltions '
Functions such as tabbing and backspacing can always be performed on the 2741 terminal regardless of the typeball
used. The 'prompt for quote-quad input - unlocking the keyboard with the carrier at the left margin - is the same
for both APL and non-APL terminals. The BACKSPACE-ATTN sequence for current line editing is also used for both
types. Operational differences are described below.
!llega I Characters
The following characters are considered to be illegal because they are not standard on all non-APL 2741 keyboards.
Mnemonics must be used in place of each.
<
Less than
>
Greater than,
Vertical bar
Exclamation paint
Not sign
]
Right bracket
[
Left bracket
Degree
The cent sign (t) is also considered illegal because it has no reasonable APL interpretation.
Appendix B .
197
Quad Input Prompt
A double colon is displayed in place of the quad-colon prompt character to indicate evaluated input prompt.
Error Marker
The ampersand is output in place of the caret as APl's error marker on nonstandard 2741 terminals.
BlindljD
Blind I/o is a specialized capability which may be of value to the advanced APL user. Essentially, it provides a
means by which characters may be input and output either to a specific device or to a
without undergoing any
sort of translation or validity check by the APL processor. Blind I/o could enable the user to generate special
characters which would otherwise be illegal under APL, for example, and route them to or from a unique device
such as a CRT or a plotter •
file
. . . 81i1111110
APL provides two DCBs - F:Q1 and F:Q2 - to be used for blind I/O, but performs no special set-up on them. It is
assumed that the user will assign F:Q1 or F:Q2 to devices or files, according to his needs, using the )SET command
(Chapter 8).
rn
Within the APl processor, the special input/output characters
and IZI (quad overstruck with 1 and 2) supplement
the quad and quote-quad characters. They are used to access the F:Q 1 and F:Q2 DCBs when blind input or output
is desired.
The default limit on record size for blind input is 512 bytes. This limit can be modified to any value from 1 to
32,767 by the SIZE option of the )SET command. Values higher than 512 may be needed for file input, and very
small values are useful to control input from special devices. Input from
or I2l always creates a text vector
result. If the source data is achi«;llly logrc values, integer values, or double-precision floating point values, then
fi Ie 1/0 operator 25, 26, or 27 may be used to correct the erroneous data type after input.
rn
Blind output may be used to output any data. It should be noted, however, that large owtput records routed to
physical devices with maximum length constraints will be truncated on output. In particular, records output to the
user's console should be limited to 140 bytes, and records output to a line printer to 132 bytes. Note also that
blind output of non-character data to a printing device wi II lead to useless results.
APL bypasses gj! translation sequences and legal ity checks for blind input and output - overstrikes are not even
resolved, for instance. If an end-of-file condition is encountered by a blind-input request, APl returns an empty
integer vector result •
.Blind 110 on a Device '
In the following examples,
I2l
is assigned to the user's console prior to calling APL, as follows:
)SET 121 IN OUT UC
Quad 2 is then used for blind input and for blind output. In the example below, the blil1ld input functions much the
same as a quote-quad input, since the terminal itself is the blind input device.
A+12I
NOW IS THE TIME FOR ALL GOOD MEN.
A
NOW IS THE TIME FOR ALL GOOD MEN.
Consider the next example, however, in which blind input is used to input illegal overstrike characters, which cannot be done with quote-quad input.
•
•
198
Appendix B
C+1'i/I
C
The example$ below illustrate blind output to the terminal. Note that the data to be output was specified as a
literal. When the RETURN key is struck, the data is output to the terminal exactly as it was input.
~'123~567890+xQWER~1UIOP+ASDFGHJKL[JZXCVBNN ••
123~S67890+xQNER~1UIOP+ASDFGHJKL[JZXCVBNN.ol
~'"-<s=~>.vA-.?~cp-++\O*+arL VA.D()c~nu!TI
"-<~.~>.vA-.?~'P-++\o*+arL_vA.D()c~~u!TI;:\
/'
;:\,
i3+'ASDF'
ASDF
The user should note that the CP-V communications handler still performs its normal translation at the level of the
Vo device. Bypassing the APL translation routines can result in the output of characters which are unrecognizable to the handler. For example, the handler maps most overstrikes as bad characters (/ on the 2741) as shown
below.
........
The SET command may also be used to bypass character translation at the CP-V level by using the options BIN and
DRC. These options should be used only by a user with detailed knowledge of the characteristics of the particular
Vo device.
BInd 110 for Files
In the fpllowing examples,
rn is assigned to a test input file which was built using the CP-V EDIT subsystem:
·EDI~
EDl~o HERE
*BUILD BLINDIN
1.000 BLINDIN. RECORD 1.
,
2.000 RECORD 2. ~ES~ BACKSPACING.
3.000 LAST RECO.RD.
I
~.OOO
*END
Record 2 of the fi Ie contains a series of blanks and backspaces such that the total number of characters in the record
is considerQbly more than the example shows. Record 3 contains an "Illegal" overstrike character.
After APL is called:
)SET
I
mIN DC/BLIND IN
In the next example, blind input is used to input the fi Ie records to the processor.
blind VO to access the nonexistent fourth record results in empty integer vector.
Note that an attempt to use
A+1lJ
B+1lJ
C+1lJ
0D+1lJ
Appendix B
199
A, B, C, and D now contain the data from the file records, as shown below. Note that ~he length of B reflects the
blanks and backspace characters that were a part of the file record. C contains the illegal overstrike character
just as it was originally entered.
pA
18
A
BLINDIN. RECORD 1.
pB
57
B
RECORD 2. TEST BACKSPACING.
pC
15
C
LAST RECO_Bp.
pD
o
When blind output to a file is used, records are output as text data - scalar, vector, or array - without any sort of
header data such as the record keys output by CP-V EDIT when it bui Ids afi Ie.
File Input/Output
The Xerox APL processor provides a set of intrinsic operators for fi Ie I/O. Norma IIy, each installation provides its users with a fi Ie I/O system made up of locked functions using these operators. These systems may
vary with the installation and are documented at the installation level. The fi Ie I/O operators used in such
systems are described below. Direct use of these operators by programmers who have no prior I/o programming experience is discouraged. A workspace, FlLEIO, containing a set of user file I/O functions is distributed to each
Xerox APL installation. This workspace includes a user function, DESCRIBE, which descrIbes the contents of the
workspace.
Creating the Set of File I/O Operators
The file I/O operators are a set of 29 "operators" defined by one of three dyadic functions.
created with the forms
These functions are
fname ... 14 1'1
fname ... 14 T 2
fname ... 14 T 4
where "fname" is the function name (fname will be used in all succeeding format examples in this section to indicate
that a function name is to be supplied). The first two forms produce identical processing ih successful usage. They
differ on Iy in the method of hand ling errors. The first type transmits error data (in the form of a sca lar integer) back
to the statement using that type of fname. The second type is used to have APL acknowledge an error; this permits
sidetracking on file I/o errors or else APL will display one of the file I/o error messages (see Appendix A). The
second type is preferred. The first type has been retained primarily to avoid incompatibilities in workspaces that
used that type in the past.
For operators 141'1 and 14i'2, the files built and accessed by APLare CP-V keyed files .. Usually, they are built
and accessed with a particular key system common to Xerox EDIT, BASIC, and APl.
An alternate form of file can be accessed if the file I/o operator is the third form. These files are built using the
CP-V random file capability, and are referred to as APL indexed files. A file I/o package using the 141'4, form
of operator can access either keyed or indexed files and the indexed files have been designed to appear essentially
the sal'ne as the keyed files to the end user. The indexed file capability has been added principally to increase file
access efficiency and to allow for shared access to files, for large data bases.
200
AppendIx B
,~
Appendix D contoins information concerning the creation of APL indexed file~, the design of indexing structures,
and trade-offs between indexed end keyed files. New APL indexed files cannot be created directly within APL.
Check with your installation for availcbility of, ond initiction of, indexed files.
The following usage allows executing sequences of these operations in order in a single line (each use of this form
yields an empty vector as a result unless otherwise specified):
A fname B
where
A
is the I/O operator number (ranging from 1 to 29).
B
is the argument applicable to the I/O operation.
Structure of APL Files
Xerox APL uses two forms of C P-V fi Ie structure, keyed fi les and random fi les. The random file use by APL simulates
keyed access, with certain restrictions and certain odditionol capabilities.
Keyed files normally use a numeric key system, which is essentially that used by Xerox EDIT.
for accessing text keys of up to 31 characters in length.
Provision is also mode
Files created by or accessed by APL can be considered in three cotegories:
•
APL component files. A component consists of two physico I records, on ID record and a data record. Numeric keys are used. The key of a data record is alwoys one plus the key of its ID record. Each data
record consists of one APL variable, including the information required to indicate its shape and type. No
records which are not parts of 'components' may be included.
APL indexed files are always component files.
Component files relieve the user of concern for housekeeping items such as record size, and carry information concerning when and by whom each component was created or most recently changed. The cost is
in the extra file storage and I/O accesses for the ID record of each component. APL indexed files reduce
I/O accesses but not space required for ID information.
•
APL non-component files. These files are similar to component files in that data records are APL variables
and' numeric keys are used. ID records are omitted. The user must maintain information concerning maximum record size, and no information is maintained concerning the source or time of creation of individual
records.
Non-component files reduce I/o occess by half compared with component files, and eliminate file space
requirements for ID records. They should be preferred for use when file structure will be fairly simple ane!
detailed ID information on individual records is not valuable.
•
Non-APL files. Provision is made to access any keyed or sequential file created outside APL. Such files
may be accessed sequentially, or by key. If keyed access is used, two forms are permitted. Numeric keys
are appropriate for accessing numeric keyed files created by EDIT, BASIC, or FORTRAN. For these files,
the key as seen by the originating user is multiplied by 1000 to form the real key.
Example:
EDIT record 1. 25 has a real key of 1250. APL file functions accessing such record~ should apply this conversion factor. Text keys are required to access some files created by processors such as COBOL.
If APL is used to create non-APL files, two modes are allowed: numeric keys or text keys. Numeric keys
shou Id be used if the fi les are to be accessed by EDIT, BASIC, or FORT RAN. In this case, the mu Itiple
of 1000 should be applied to the key value as noted above. Numeric keys are 3-byte keys. If text keys
of more than 3 bytes are to be used in creating a new file, the maximum key length must be specified.
Appendix B
201
Opening and Creating Files
Following are the forms for the set of operators required to establish parameters prior to opening a DCB to a file and
to carry out the open CAL:
•
Establishing "file number":
1 fname B
where B is a positive integer specifying the file number to be used for subsequent file operations. Up to
eight file numbers may be in use (OPEN) at any time.
•
Establishing fi Ie name:
2 fname B
where B is a character vector specifying the file name for the currently set file number. A file name may
contain up to 11 characters. If B is not a character vector, DOMAIN ERR is reported. If B is more than
11 characters, LENGTH ERR is reported.
•
Establ ishing or resetting account:
3 fname B
where B is either zero or a character vector specifying the account for the currently set fi Ie number. An
account can contain up to eight characters. Using a zero for the B argument resets the assignment to the
user's account.
•
Establishing or resetting password:
4 fname B
where B is either zero or a character vector specifying the password for the currently set fi Ie number, consisting of up to eight characters. Using the number zero for the B argument resets the password control to
indicate no password. In the above cases, if B is neither an integer of value 0 or a text vector of letters
and digits, DOMAIN ERR is reported. If the length exceeds eight characters, LENGTH ERR is reported.
•
Establishing fi Ie identifi cation as a single primi tive:
21 fname B
where B is a character vector up to 40 characters in length specifying fi Ie ID for the currently set fi Ie number in the same formats permitted for system commands such as )LOAD. The permitted forms are:
name
account name
name:key
account name:key
name. account
name. account. password
name .. password
•
Assigning serial numbers for private pack utilization (check with local installation for availability of
private pack use) or setting maximum key length:
20 fname B
where B is a text vector of up to 12 characters, the numeric value 0, or a positive integer from 3 to 31.
Other forms give a rank, length, or domain error. Zero resets the pack control authorization, and shou Id
be issued, after a private pack has been opened, before opening public files. Numeric values of 3 to 31
set maximum key length (applicable only to new output files).
202
Append ix B
If B is a character vector, it is used to set the serial number field of the user's DCB for private pack use.
If B is zero, it resets serial number control. The form 20 fname B applies to the currently set file number.
•
Opening DCB in indicated mode:
5 fname B
where B is an integer specifying the mode of DCB for the currently set file number, as follows:
indicotes IN.
2
indicates OUT.
4
indicates INOUT.
8
indicates OUTIN.
17
indicates INABN, which means OPEN in IN mode but take error exit if file is found. It is used
to verify that a fi Ie to be opened for OUT or OUTIN does not replace an existing fi Ie.
20
indicates INOUT, shared, and applies to APL indexed files only.
Unless otherwise indicated, files are created as private files, with read and write access by user only •
When opening new files (OUT or OUTIN), they may be declared public for READ access by adding 32
to the argument and for WRITE access by adding 64 to the argument. For example,
•
5 fname 8+32+64
This example opens the specified file as OUTIN, with public access for READ and WRITE. If the value
of B is not consistent with stating a specified I/o mode, DOMAIN ERR is reported. The result of "5 fname B"
is an empty vector unless an error or abnormal return results from the CP-Y M:OPEN call. Error reporting
is covered later in this section.
As an example of file creation, suppose for function F that N contains the file number, NAM contains the
file name, A contains zero (indicating the user's own account), and P contains a password.
5F 8, 5F 17, 4F P, 3F A, 2F NAM, IF N
This example opens a private, passworded file to the user's account, or detects an error if the file already
exists. The fi Ie is open for output and input. Note that several operations are carried out in a single line.
The result of each (except for error conditions) is an empty vector, which is catenated to the argument of
the next operation.
APL indexed files may be opened only in IN or INOUT mode. IN mode is used for input only. INOUT
may be in exc lusive or shared mode. See operators 28 and 29 for control of shared update access.
,Clasing F,les;
•
Closing and saving file for indicated file number:
6 fname B
where B is an integer specifying the file number. The result is an empty vector.
•
Closing and releasing the file for indicated file number:
7 fname B
where the argument B is the same as above. (This form is used to delete files. A file is opened for input,
using 5 fname, and then closed for release.) The result is an empty vector.
APL indexed fi les may not be releosed by using 7 fname B.
Appendix B
203
Mainllining Componant Ranga and Current Componant Valul
Wh~n files are created by APL or acces~ed in other than sequential mode, primitives are required to find the key
range of an existing file, to change the range as the file is appended, and to set keys for access or creation of
specific records. Keys are usually numeric but may be text. It is very inadvisable to mix the forms in a single file
(text keys may of course consist of text numerals, but such keys are not handled as numeric keys). When a file is
opened in OUT or OUTIN mode, values for the 'first component' and 'last component' are initialized to artificial
values which will be updated when the first record is written. These keys will be numeric unless a maximum key
length greater than 3 has been set. APL indexed files do not use true keys but simulate numeric keyed operation
from the user's viewpoint.
•
Returning the value of a designated key for the currently set file number:
8 fname B
where B is 1, 2, or 3, specifying which key the value is to be returned for (the key returned will be that
for the currently open file, if any, of the most recently referenced file number):
indicates that the value of the first key in the fi Ie is to be returned as on integerscalaror text
vector.
•
2
indicates that the value of the current key is to be returned as on integer scalar or text vector.
3
indicates that the value of the highest key is to be returned as an integer scalar or text vector.
Getting highest index number or index to component ratio.
8 fname B
where B is 4 or 5. Used only if APL indexed files are in use.
•'
4
indicates highest permitted index (or real key) value. For keyed files, returns 9,999,998.
5
indicates ratio of index number to component number for a particular indexed file. Returns 0
if not an APL indexed file. M.ay be used to test if current file is indexed •
Setting the value of the current key for the currently set file number:
9 fname B
where B is on integer or text vector specifying the value for the current key. The key valJJe is established
for the next record to be read or written on the most recently referenced "file number". The result is the
empty vector. If B is numeric and not in the range 1 to 9,999,998, DOMAIN ERR is reported. If B is a
text vector and its length is not in the range 3 to 31, LEN GT H ERR is reported •. If the key length is too
great for the current output fi Ie, an error wi II occur when the next record write is attempted.
KIY Values VlrsUS Componlnt Va lUIs
'In order to permit record insertion into existing numerically keyed files in APL, the 'component number' is generally
chosen as a multiple of the real key value used. This is accomplished by the user functions which set and examine
keys. A typical form of such a system is to use a multiple of 1000. As noted earlier, this provides the same kind
of numbers, from the user's viewpoint, as Xerox EDIT, BASIC, or FORTRAN numerically keyed files.
If the APL file is a 'component file', such a system allows component numbers of up to 9999.998 and the insertion
of components down to the .002 level.
Example:
'Component' 1. 106 consists of on ID record with key 1106 and a data record with key 1107.
If the file is a non-component APL file or non-APL file, insertion to the. 001 level is allowed, as in EDIT and BASIC.
Note that FORTRAN will provide keyed access only for records whose true keys are multiples of 1000.
,204
Appendix B
In the case of APl indexed files, the ratio of component number to index (corresponding to true key) is set at the
time the file is created. User functions must use that ratio to relate component to 'key' values. The ratio may be
found using 8 fname 4 as noted earlier. The ratio will generally be much lower than the 1000 used for the keyed
file examples here. Providing that extensive an insert capability causes prohibitive file storage costs for APl indexed fi les.
Writing APL Records
•
Writing a record containing the value of an expression:
10 fname expression
The currently set key value and file number are used. The result is an empty vector unless an error is detected.
Not permitted for APl indexed fi les.
•
Writing a component:
II fname expression
The first record is an identification record containing the time, the user's account, and the size of the
data block associated with that identification record. The currently set key value and DeB number are
used. The remaining record is as would be written by the "10 fname expression" form above, and has a
key value of one greater than that of the identification record. The result is an empty vector unless an
er~or is detected.
As an example, suppose that a function named WRITE exists to write a component, and that the function call has
the form
A WRITE X
where A is the value to be fi led, XII J is the fi Ie number, and XI2J is the component number (there is no checking
for length errors in the function call or for prior existence of the record to be written). The function consists of
the single Hne
II J
Ilfname A, 9fname r 1000xX12J, lfname XII J
which sets the file number, generates the key, and writes the identification and data records.
the DeB has been opened for output.
It is assumed that
A function similar to WRITE but adding to the end of the file might be the function APPEND,
IIJ
Ilfname A, 9fname 1000xHI(8fname 3) : 1000, lfname X
The file number is set to X. The highest key is found, the next multiple of 1000 is created, and the new key is set.
The identification and data records are then written.
Writing Non-APL Records
Data records maybe written that do not retain the APL internal attributes of 'shape' and other internal reference
data. Such records may not be written as 'components' with paired ID records, and may not be written on APl
indexed fi les.
•
22 fname B
where B is any APl expression. The data represented by B is written as a single record in ravel order. If
B is a logic vector the length is rounded up to a multiple of 8 bits, since the smallest I/O unit is one byte
(8 bits). Data is not converted on output but APl header information is excluded. The purpose of this
primitive is to allow writing records and files for use by processors other than APl. The record is written
using the current key setting and file number.
Appendix B
205
Reading APL Records
Reading records in APL requires that the record size be known, in order to permit all~cating space or indicating
WS FULL. If the user has created files with records of known fixed length, the read may be made directly,
specifying length. If records of variable length are used, the data records should be preceded by identification records, or a 'safe' length used for reads.
•
Reading a data record:
12fnameB
where B is an integer specifying the size of the data record in bytes. The data record is read, if space is
available, using current key and file numbers. If the record size is larger than specified or if the read
results in an error or abnormal return, the result is an error (see Error Reportinfj in this section). If the
record is smaller, the operation is completed. In this case, the unused portion of space reserved for the
data is made available for other use.
Not permitted for APL indexed files.
•
Reading an identification record and a data record:
13 fname B
where B is an integer specifying the key value. The identification record is read; and if space is available, the data record is read using size information from the identificCltion record. As an exumple, suppose that function READ is called with A READ X and that it consists of a single line:
rll
A .. 13fname rlOOOxXf2J, lfname Xl1 I
This example sets the DeB number and the key value and then reads the identification and data records
The data block is assigned to dummy variable A.
•
Reading an identification record into a data block:
14 fname B
where B is an integer specifying the key value.
integer vector with fixed format:
The identification record is read in the form of a numeric
word
,
2
,I.
word 2
word 3
~·-~-.u-r,-,-6-'t"1.-9-1O-~-d-i'~-J:l-,-.-,;J-'.-17-,-,-:-~-~-2-'-n-,-"t"1,-,-,,-,-,,-;-,~-"-S-29-30---'J
word 4
jO .11
I
word 5
o ,
,I.
where
year
206
Appendix B
is a binary value; for example, 1970 is represented m X'46'.
day
is the Julian day of the year represented in binary; for example, September 14 is represented
as X'10P.
hour
is the hour of day (0-23).
min
is the minute of hour (0-59).
is the number of two millisecond units since the lost 1/1000 of a minute (0-29).
TMS
account
is the form contained in DCBs, left-justified, blank-filled to the right, even though it is
delivered as two words of on integer vector. The following APL expression may be used to convert
the integer values into a character vector. Assume the ID record has been read into variable X.
R+, 021' (4P256)T X[ If
5]
Re.ding Non-APL Records
I'
•
23 fname B
Reads a non-APL record using currently set key and file number. B is an integer specifying the record size
in bytes. The data is arbitrarily treated as a text vector and an appropriate APL data block is formed. If
the record is larger than indicated by B, an error results. If the record is smaller, unused space is made
avai lable. Separate primitives (25 to 27) may be used to change the data type of the result to logical,
integer, or real numbers.
Not permitted for APL indexed fi les.
Deleting Records or Components
•
Deleting a specified record:
15 fname B
where B is an integer specifying the key value. The current DCB number is used in deleting the record.
The result is an empty vector unless an error is detected.
Not permitted for APL indexed files.
•
Deleting identification and data records:
16 fname B
where B is an integer specifying the key value. This primitive allows construction of functions for the deletion of selected components or ranges of components. The result is an empty vector unless an error
is detected •
. Sequential Access to Existing APL Files
If a file has been created and modified such that there are gaps and inserts in the range of "component" values, it
may be difficult to read the file in a keyed form without excessive errors for missing components or without inadvertently skipping existing records. The following operations cause sequential reads:
•
17 fname B
where B is an integer specifying the size of the record in bytes. Records are read sequentially, using the
current file number. After each read, the current key value is updated and may be accessed. If an
integer of zero is specified, the record is accessed but data is not read, regardless of actual record size.
If the integer specified is greater than zero and the record size is larger than that specified, an error
is reported.
Not permitted for APL indexed files unless B
=
0 (skip record).
Appendix B
207
•
13 fname
a
This is similar to "13 fname B" except that it reads the next identification reco~d and associated data record. If the next record is not an identification record, records are skipped until an identification record
is reached. At end of read, the current key is set to that of the last record read. If no identification record is found, an error is reported.
•
14 fname
a
This is simi lar to "14 fname B" except that it skips forward to next identification record.
is updated. If no identification record is found, an error is reported.
The current key
Sequential Acee. to Nan-APL Files
•
24 friame B
where B is an integer specifying size of record in bytes. Records are read sequEintially, using the current
file number. Operation is analogous to 23 fname B except that the read is sequential rather than keyed.
Not permitted for APL indexed
fj les.
Converting Data Types
Primitives 23 and 24, for reading non-APL records, arbitrarily create text vector results.! The records read may, in
fact, be logic values, character, integer, or real (double-precision floating point) values.
•
Convert character to logical vector.
25 fname B
where B is a character vector. The result is a logic vector consisting of the actual data in B. The length
value is multiplied by 8 and the data type is switched to logic.
If B is an expression rather than a named variable, this operator does not require that a copy of B be
created. This primitive would typically be used in conjunction with a keyed or sequential read of a nonAPL data record.
Example: C .... 25 fname 23 fname 100
If, in this example, the record read consists of 100 bytes, C is an 800-element logic vector.
•
Convert character to integer vector.
26 fname B
where B is a character vector. The length must be a multiple of 4. The result is an integer vector consisting of the actual data in B. The length value is divided by 4 and the data type switched to integer. If B
is an expression, the operator does not require that a copy of B be created.
•
Convert character to real (double-precision floating point) vector.
27 fname B
where B is a character vector. The length must be a multiple of 8. The result is a real-number vector
consisting of the actual data in B. If B is an expression rather than a named variable, the operator does
not require that a copy of B be created.
208
Appendix B
c_..... Acce. to Shared APL Indexed File.
If an APL indexed file is opened in the shared mode, multiple updates are permitted concurrent access. The following
. features a,re provided to permit the user to lock out portions of such a fi Ie for purposes of reading a set of records
without other intervening updates or completing a set of updates without interference. These features use the CP-V
Enqueue-Dequeue facility, and an installation supporting these features must have reserved queue space.
•
Locking out a record or block of records.
28 fname B
B is an index (key) value. Causes the designated record to be enqueued for exclusive use. Operates only
if fi Ie is in shared IN OUT mode. Successive use of 28 fname B can be made to enqueue a contiguous set
of records, but not to enqueue records not in a contiguous block.
•
Releasing a blocked record.
29 fname B
.B is an index value. If a block of records is queued, they must be released in sequence from the ends,
that is, release of a record may not be used to split a contiguous block of held records into two blocks.
If B = 9999999, all records are released.
Error Conpitions Unique to Enqueue-Dequeue Operations
The following error coliditions may be reported on attempting to use Enqueue-Dequeue features.
be sidetracked.)
(These errors may
Message
Code-Subcode Values (CP-V) and Cause
DOMAIN ERR
No code-subcode. Fi Ie is not shared or result would create noncontiguous blocks of held records.
COMPo NOT HELD
3100
Tried to dequeue an unheld record.
COMPo ALREADY HELD
3101
Tried to enqueue a held record.
ABORTED BY BRK OR CTRL-Y
3104
User aborted queue request.
REQ. WOULD CREATE DEADLOCK
5800
Queuing would deadlock access.
ENQ. FULL
5801
CP-V queue stack is full.
ENQ. UN AUTHORIZED
5803
User not authorized for Enqueue.
NOT ENQ. SYSTEM
AEoo
Enqueue-Dequeue not supported.
~ Listing File Names and Numbers
These operations may be used in functions designed to list file components by number, with or without contents of
the records.
•
Fi Ie names in a specified account
18 fname' B
where B is (! text vector specifying a user account. Result is a character matrix. Each row has account in
columns 1 through 10 and a fi Ie name in columns 12 through 24. The matrix is a list of fi les in the specified account. Because of the general file I/o capability in CP-V, these files will not all be the result of
APL fi Ie I/O and the matrix may include other passworded or protected fi les. Non-APl fi les and APL
workspaces that are not passworded or read-protected will not be reported in the result.
/
Appendix B
209
•
Names or numbers of currently open fi les
19fname B
where B is an integer specifying the structure of the result as follows:
indicates a character matrix with names of currently open fi les, one fi Ie per row.
indicates a numeric vector with the currently open file numbers.
2
If B is not 1 or 2, DOMAIN ERR is reported.
Error Reporting
The use of file I/O primitives may lead to a variety of errors, which are reported similarly to errors for other APL
operations. The following common errors are of course included: DOMAIN, LENGTH, RANK, WS FULL, and
SYNTAX. Errors are also reported for inability to open specified files or find specified records, to read or write
records on a DCB that is closed or not open in the appropriate mode, or to use files and DCB in an inconsistent
combination. The error codes returned by the monitor are listed in the Xerox CP-V/BP Reference Manual, 90 1764.
The error code in the APL file I/o subsystem is an integer scalar, related to monitor error codes as follows:
result = (128xcode) + subcode
The subcode and code may be separated for checking by using the encode operator.
is 2561, the expression
v ... 0
For example, if the result
128Tresult
gives the two-element vector where
Vr1J = 20
and
vr2J = 1
Notice that the code is 20 (hexadecimal 14) and the subcode is 1.
fi Ie is currently open to another user or DCB. )
(An attempt is made to open for output when the
If the code value is zero (that is, the result is less than 128), the subcodes are as follows:
o
indicates INABN set and OLD FILE found.
on read of identification record, indicates invalid record format.
2
on read of data record, indicates record is not a valid APL data block.
3
indicates file tie table is full.
4
indicates attempt was made to release file from an account other than the user's.
5
indicates attempt was made to open a fi Ie with a tie number not in the fi Ie tie table.
6
indicates attempt was made to release a file with a number not in the file tie table.
7
indicates attempt was made to close and save a fi Ie with a number not in the fi Ie tie table.
8-9
indicates attempt was made to query or set key values for a file that is not currently open.
10-17,
22-24
indicates attemptedI/O operation on a file not currently open.
number.
20
indicates attempt to delete record when fi Ie not in update mode.
21
indicates bad file ID format.
No new file numbers may be used until an open file is closed.
Error number is same as primitive
In general these operations wi II be used in locked functions and the error report wi lion Iy ilfldicate the type of error
and the line number of the function.
The above form of error reporting applies, only when the 14 f 1 intrinsic function is used; the error code is produced as a scalar integer result to be analyzed solely by the file I/o subsystem using that iintrinsic. (If 14 f2 is
applicable, the subsystem may use sidetracking to process the error - see Appendix A -otherwise APL will handle
210
Appendix B
the error in the standard manner. The latter case relieves the subsystem from any r"sponsibiiity for analyzing errors,
and it can be designed largely as if only successful operation were possible. )
A list of standard file
I/o error
messages with corresponding code-subcode value (hexadecimal) follows:
Message
FILE
I/o
Code-Subcode Values
ERR xxxx
Any values not specified below
FILE NAME ERR
0000, 0015, 0300
FILE DAMAGE
0001, 7500, 7501, 7502, 7503, 7504, 7505, 7506
NOT APL FILE
0002
FILE TBL FULL
0003
FILE ACCESS ERR
0004, 0014, 1400
FILE IN USE
1401
FILE SPACE TOO LOW
5600, 5700
FILE INDEX ERR
0600, ODOO, 4200, 4300
PRIVATE PACK UNAVAIL, CALL OPR.
2001, 2002, 2003, 2004
FILE TIE ERR
0005, 0006, 0007, 0008, 0009, OOOA, OOOB, OOOC, OOOD, OOOE,
OOOF, 0010, 0011, 2EOO, 4400, 5100, 2500, 0016, 0017, 0018
Correspond infl error messafles for Enqueue-Dequeue features are listed in the section on controlling access to shared fi les.
Generation of File I/O Subsystems
A file I/o subsystem is not included as an integral module in the APL processor. File I/o subsystems may be tailored to an installation's needs, within the capabilities of the provided file I/o primitive operators. A sample workspace, FILEIO, is distributed to APL installations.
Table B-3. Translation Equivalences for Nonstandard Devices
2741 APL
2741 non-APL
TTY Model 33
Line PrinterOutput(Card Read hrm Input)
I
1
1
1
2
2
2
2
3
3
3
3
4
4
4
4
5
5
5
5
6
6
6
6
7
7
7
7
8
8
8
8
9
9
9
9
0
0
0
0
+
+
+
+
x
#
#
#
Q
Q
0
0
W
W
W
E
E
E
E
R
R
R
R
T
T
T
T
.
,',
W
Appendix B
211
Table B-3. Translation Equivalences for f'.lonstandard Devices (cont.)
2741 APL
2741 non-APL
TTY Model 33
LinePrinterOutput(Card Read Form Input)
Y
Y
Y
Y
U
U
U
U
I
I
I
I
0
0
0
0
P
P
P
P
,-
-
..-or
A
A
A
A
S
S
S
S
D
D
D
D
F
F
F
F
G
G
G
G
H
H
H
H
J
J
J
J
K
K
K
K
L
L
L
L
r
$(
[
$(
J
$)
J
$)
Z
Z
Z
Z
X
X
X
X
C
C
C
C
V
V
V
V
B
B
B
B
N
N
N
N
M
M
M
M
I
I
I
I
/
/
/
/
$DRS
$DRS
$DRS
-
-
-
<
<
$LT
<
<
$LE
$LE
$LE
=
=
=
=
~
$GE
$GE
$GE
>
$GT
>
>
I
$NE
$NE
$NE
v
$OR
$OR
$OR
"
&
&
&
$-
$-
$-
%
%
%
-.
-
-
212
Appendix B
.
-
$IS
(Negative Sign)
•
(Subtract Operator)
.
Table B-3. Translation Equivalences for Nonstandard Devices (cont.)
2741 APL
2741 non-A PL
TTY Model 33
Line Printer Output (Card Read Form Input)
?
?
?
$RND
w
$W
$W
$W
E
$E
$E
$E
p
$R
$R
$R
$NOT
$NOT
$NOT
t
$TAK
$TAK
$TAK
"
$DRP
$DRP
$DRP
~
$1
$1
$1
0
$0
$0
$0
*
*
*
*
-+
$GO
$GO
$GO
a
lU\
(n l
(CO
r
$MAX
$MAX
$MAX
L
$MIN
$MIN
$MIN
-
$U
$U
$U
'V
"
"
$DEL
tl
$DLT
$DLT
$DLT
0
$SC
$SC
$SC
I
I
I
I
0
$0
$0
$0
(
(
(
(
)
)
)
)
c
$CPL
$CPL
$CPL
:>
$CPR
$CPR
$CPR
n
$CAP
$CAP
$CAP
u
$CUP
$CUP
$CUP
T
$ECD
$ECD
$ECD
.I.
$DCD
$DCD
$DCD
I
$ABS
$ABS
I
i
i
i
i
:
:
:
:
\
$XPD
\
$XPD
SPACE
SPACE
SPACE
SPACE
TAB
TAB
BACKSPACE
BACKSPACE
$BS
$BS
RETURN
RETURN
NL,CR
NL,CR
INDEX
tNDEX
LF
LF (See also Notes at the end of Table B-3)
$
$
$
$
<I>
$REV
$REV
$REV
I
•
-lAB
$TAB
.
(U nderscore)
0
Appendix B
o.
213
Table B-3. Translation Equivalences for Nonstandard Devices (cont.)
2741 APL
2741 non-A PL
TTY Model 33
Line Printer Output {Card Read Form Input)
til
$TPS
$TPS
$TPS
e
$RVI
$RVI
$RVI
,
$LOG
$LOG
$LOG
$GD
$GD
$GD
11
$GU
$GU
$GU
!
$FCT
!
$FCT
I
$IB
$IB
$IB
~
$QQ
$OQ
$QQ
lil
$MDV
$MDV
$MDV
PI
$COM
$COM
$COM
...
$NOR
$NOR
$NOR
fV
$NND
$NND
$NND
¥
$LOK
$LOK
$LOK
T
$RDI
$RDI
$RDI
~
$XPI
$XPI
$XPI
fD
f}
$OUT
$OUT
-A
a
$UA
$UA
B
b
$UB
$UB
-C
-D
c
$UC
$UC.
d
$UD
$UD
-E
e
$UE
$UE
F
f
$UF
$UF
-G
9
$UG
$UG
-H
h
$UH
$UH
-I
-J
i
$UI
$UI
i
$UJ
$UJ
-K
k
$UK
$UK
L
I
$UL
$UL
-M
m
$UM
$UM
-N
n
$UN
$UN
0
-
0
$UO
$UO
-P
p
$UP
$UP
-Q
-R
q
$UQ
$UQ
r
$UR
$UR
5
s
$US
$US
-
T
t
$UT
$UT
-U
u
$UU
$UU
V
v
$UV
$UV
-W
w
$UW
$UW
e
-
-
-
-
-
214
Appendix B
,
•
Table B-3.
Translation Equivalences for Nonstand9rd Devices (cont.)
2741 APL
2741 non-APL
TTY Model 33
Line Printer Output (Card Reader Form Input)
x
x
$UX
$UX
Y
y
$UY
$UY
Z
z
$UZ
$UZ
$UDL
$UDL
$UDL
$TBR
$TBR
$TBR
$QO
$QO
$QO
$Q1
$Q1
$Q1
$Q2
$Q2
$Q2
Notes:
•
For TTY terminal the INDEX character is equivalent to LF only for output; for input the Form-Feed
(Control-L) is equivalent to INDEX. This is most useful when desiring to delete a function line.
•
For the Tektronix 4013, there is no INDEX or ATTN key.
user may substitute Control-D for an ATTN.
•
The Tektronix 4013 features five unique characters: 0,
equivalents for these characters.
•
As normally provided, Xerox APL accepts only [Q],
and ~ and their mnemonic equivalents.
Individual installations may modify their APL processors to allow ~ through [2]; they could also
allow only a subset of these, and it is possible to allow none of the blind-quads.
•
For TTY operation, APL assumes that the terminal has been designated as a Model 33 TTY at TEL
level. Some installations default to other types, such as 7015. CP-V maps the bracket characters
differently in this case and they may then not be used in APL. It is advisable for TTY users to be
sure that they are identified as terminal type 33 at monitor level.
In order to delete a function line, the
f-, -i,
I ,I.
There are no translation
OJ,
Appendix B
215
APPENDIX C. INTRINSIC FUNCTIONS
The intrinsic functions described in Chapter 7 can be created by using the dyadic T-Bar operator. Used dyadically,
this operator creates a special data block that identifies a particular intrinsic function (coded within the APL processor). The data block may be assigned to any name, which then wi II be the name for the intrinsic function. In
the examples below, the names selected are the standard names for the existing intrinsic functions (other names
could be used).
The following intrinsic function assignments already exist in the WSFNS or GRAF (for b.GRF) workspaces (which
accompany the Xerox APL processor when it is delivered to an installation -see the installation manager).
AFMY'·-
111
TO
fIO<-141J
fIOE'<- J I; T2
tJ.GH } i ' l l l 13
fTOI' 1'1 'TIl
ACH'i_IITtJ
AL.JM-. 111 To
tJ,-n;-<-j II 'T',
AXL---jlj Tt:
ADMS. J II ::'9
ONi c;; N··: ~J 'To
}lInTfJ··l:) 11
J.lIc7I'l":'3 4 .. !: T)
'l'AHS·1~
r:l
.'ic'Tl,INK-] ~ T4
:;S1'FUZZ ..-J ~ T~
ngJ,AY·'1-,1'6
1/ c.'A 0;;:8" I ~ f';
V/-,CHAR"-l tJ f8
NRRN+-16 TO
NRRP+-1611
NRRX<-16T2
PACE'+-1613
NLINBS<-161'4
The left argument of the T-bar operator indicates the type of the resulting intrinsic function:
14 for dyadic function,
15 for monadic function, and
16 for ni ladic function.
216
Appendix C
APPENDIX D. DESIGNING AND CREATING APL INDEXED FILES
The following material describes how to design an APL indexed fi Ie for a proposed data base and how to originate
such a file. Indexed files are created using the CP-V random file capability. Their availability is subject to individualinstallation control.
limits and Trade-Offs
Several characteristics of the keyed APL fi led system, of CP-V random fi les, and of sample uses of APL fi les, have
been considered in designing APL indexed files. Some of these characteristics should also be noted in designing
appl ications. For many data bases, keyed access may be better than indexed fi les.
•
Total Secondary Storage Occupancy
Since indexed files are CP-V random files, they require dedication of a fixed block of contiguous secondary storage from the time of creation. When such files are filled, they cannot be dynamically expanded.
Indexed files are thus suitable only for data bases with a reasonably predictable total size, and occupancy
of a reasonable fraction of that space soon after creation.
•
Component Identification and Size
Since indexed files are to look, to the user, like current APL keyed files, each 'component' includes five
words of identity information -size, date, time, and account (2 words). Each APL variable also includes
a minimum of 2 words of 'header' information. In both the keyed and the indexed fi Ie systems there is
considerable overhead associated with sma II records.
Several design decisions for indexed files have been made to minimize the overhead cost of small records.
It is still true, however, that applications using small records are relatively inefficient compared to those
using primarily large records.
•
Record Size vs. Secondary Storage Granularity
The smallest addressable unit in secondary storage is the 'granule' of 512 words (2048 bytes). All reads
and writes start on granule bounds. If records are not aligned on granule bounds, the impact is as follows:
Reads must be buffered in core and the re levant data moved to its target location. Writes must be preceded
by reads so that the new data is merged, in a core buffer, with the old data. The full granule is then
written. It would clearly be advantageous to restrict data records to start on granule bounds. This is impracticable, however, if a file includes many small records. The design of APL indexed files compromises
on the granule bound question. Records which approach or exceed one granule in size are written on granule bounds. Smaller record~ are packed.
•
Scalars and 'Empty' Components
Existing applications of APL files m9ke extensive use of 'empty' components -records with keys but occupied by 'empty' APL variables. These components each require an identification record (5 words) and a
data record (4 words). In the indexed file system, each index entry consists of 8 words. Any APL variable
which requires a 4-word data record in the keyed file system is stored directly in the index in the new
system. Records stored directly in the index include
Empty vectors
Empty matrixes
Scalars
Logic vectors of length 32 or less
Appendix D
217
Text vectors of length 4 or less
Integer vectors of length 1
This approach increases the size of the file index but significantly speeds treatment of empty and 'very
sma II' components.
•
Insertion Capability vs. Index Size
In keyed APL files, the design encouraged the use of key values which were a multiple of 'component'
numbers. The 'standard' described in the reference manual is 1000 to 1 and allows component numbers to
the.002 level. The ratio is actually dependent on user-clefined functions and may be varied by individual
installations and users. For keyed files, there is no particular extra overhead in allowing extended insertion between components. For indexed files, there is the fixed overhead of the, index itself. If M is the
maximum number of records allowed and IG is the number of granules used for the index:
IG = M 764
It is impractical, for indexed fi les, to use a high ratio of component number to index number because of
the fjxed index granule overhead that would be incurred. This is particularly the case if the average record
size is small. A realistic maximum is probably 10 to 1 -assuming that some significant number of insertions
may be made.
File Sma.
The indexed file capability employs standard CP-V random files.
below:
Structural aspects of these files are described
Granule Zero
The first granule (offset zero) has the following fixed structure:
Word 0
TEXT 'APLI'
Word 1
M
Number of index entries.
Word 2
R
Ratio of component number to index number.
Word 3
0
Granule offset to start of index.
Word 4
L
Lowest index number in use.
Word 5
H
Highest index number in use.
Identifies as APL indexed file.
Words 6-11
Spares (set to zero).
Words 12-511
Free segment chain.
Free Segment Chain
The free segment chain is a variable length table, or tables, of unused fi Ie space.
Each entry requires two words as follows:
218
Word 1
Size, in words, of unused block.
Word 2
Offset, in words, from start of fi Ie.
Appendix D
The table starts in granule zero.
If word 2 = 0, this is the last entry in the table.
If word 2
= 0 and
If word 2
< 0,
word 1 is not zero, word 1 is the granule offset to another table of free segments.
entry is currently not in use.
Index Granules
The file ind~x begi~s.a.t a. granule offset specifie? by word 3 of granule O. The index occupies contiguous granules
and all entries are initialized to zero when the fde is created. Each entry consists of eight words.
Case I.
No record with this index number.
Case II.
Word 1
Zero.
Words 2-8
Unused.
Records of APL variables requiring 4 words or less in primary storage.
Case III.
Words 1-4
APL variable, including header.
Words 5-8
Date-Time-Account in same format as for keyed file
ID records.
Records of APL variables requiring more than 4 words in primary storage.
Distinguishing Cases I, II, and III.
Word 1
Physical record size in words.
Word 2
Word offset from start of fi Ie.
Word 3
First word of data block header.
Word 4
Unused.
Words 5-8
Same as for Case II.
For Case I, Word 1 equals O.
For Case II, Word 1 (bits 16-31) equals 4.
For Case III, Word 1 (bits 16-31) greater than 4.
Data Granules
Each data record in the file is a
always start at granule bounds.
the physical size of records may
always rounded up to a multiple
segments' smaller than 6 words.
copy of the core image of an APL variable. Records which are 400 words or longer
Shorter records may start mid-granule but may not cross granule bounds. Note that
exceed the data block size. This is because physical size for larger records is
of 512 words and because small records may be rounded up to avoid leaving 'free
Efficiency Considerations
This addition to APL file I/o has been motivated by specific needs which relate to extensive resource demands, and
require explicit concern for optimization. The file structure has been designed primarily to minimize the number of
disc accesses required to read and write APL file components. A second consideration has been to minimize in-core
data transfers.
Appendix D
219
In particular, the design choice of placing the component ID data in the index rather than with the data block was
dictated by the desire to allow direct moves of the APL data blocks between core and secondary storage. The additional increase of index entry size to allow direct access of 'empty' and scalar variables was dictated by the fact
that existing data bases of potential users contain a high proportion of 'empty' values.
The design goal of minimal disc access has been compromised for records of sizes between 6 and 400 words. These
records may start in mid-granule and require read-merge prior to write. They also require in-core data transfer following reads.
Fixed Overhead
The fixed overhead in granules associated with an APL indexed file is 1 + M .;- 64, where M is the number of index
entries.
Strictly speaking, this is not all overhead.
plete data for empty and scalar values.
The index includes identification data for all occupied entries and com-
Variable Overhead
As a file is modified, particularly by record deletions and replacements of records by larger or smaller versions, the
free segment chain may grow and a number of unusable small segments of granules may Qccumulate. Each 255 entries
in the free segment chain wi II require one granule (after the 249 'free' entries in granule zero). An extensive free
segment chain slows processing associated with writing or deleting records but has no timing impact on reads. If a
file has become badly fragmented, it should be transferred to a new file, copying in index order, to create a clean
version.
Estimating Granule Requirements
An approximate formula for estimating granule requirements for an APL indexed file is:
G
= IG + DG + 2.
IG = M .;- 64 (index granules).
M = number of index values.
DG = (l -:- E) x NR x ARS -:- 512 (data granules).
E = efficiency of packing.
Depends on record sizes.
If record sizes unpredictable, assume E = .75.
NR
= number of non-empty,
ARS
= average
non-scalar records when file is fully occupied, including anticipated inserts.
record size, in words, including data block header.
Procedure for Creating APL Indexed Files
APL indexed files are created by the following procedure:
1.
Execute APL workspace, SETPARS. This workspace requests information on the following parameters:
Number of granules
Number of index entries
Ratio of index number to component number
Offset to first index granule
220
Appendix D
If the inputs are logically consistent, SETPARS creates a file, APLIPARS, which will be used to initialize
the random fi Ie.
2.
Build a job file, similar to APLISAMP, shown below, specifying file name, and number of granules. This
job file may optionally, as shown, specify READ accounts, WRITE accounts, SN (for private packs), and
a password. The file may be created by the TEL BUILD command or by copying and editing APLISAMP,
using EDIT.
This job consists of an ASSIGN card, with extensions, followed by a RUN of APLILMN, which create and
initialize the file. APLILMN was created from APLISI, also shown below.
APLISAMP sample of job to create APl indexed file:
1.
!JOB
2. ! LIMIT (TIME,5), (CORE, 10)
3. '- !PCl
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
DE LETE DC/fid
END
IASSIGN M:BO, (RAN DaM), (OUT), (SAVE),;
(FIlE,fid),;
(READ, 'All'),;
(WRITE,'NONE'),;
(PASS,name),;
(SN, serial number(s)),;
(RESTORE, limit)
.RUN (LMN, APLILMN)
lEaD
I
Notes:
I
I
I
~
Lines 3 to 5 are to delete any prior file with the name of that being created.
I
I
Lines 8 and 9, as shown, are default Read-Write access.
read access and write access.
Up to 16 individual accounts can be specified for
Line 10 is optional, for passworded files.
Line 11 is optional, for private packs. If private packs are used, the !L1MIT card should also include a
MOUNT option specifying the serial numbers to be used.
Standard CP-V error diagnostics will be issued if this job fails to create the specified random file.
'iJ
[lJ
SETPARS
~+'HOW
MANY GRANULES?'
[2]
~ERROR1X\(NG~rNG)v(1~p,NG)v(NG+D)<6
[3J
~+'HOW
[4]
[sJ
[6]
[7]
[8 ]
[9]
MANY INDEX ENTRIES?'
~ERRORlx\(NIE~rNIE)v(l~p,NIE)v(NIE+D)<l
~+'RATIO OF INDEX NO. TO COMPONENT NO. (INTEGER
~ERROR1X\(RIC~rRIC)v(1~p,RIC)v(RIC+D)<1
~+'OFFSET
TO FIRST INDEX GRANULE=?'
~ERROR1X\(IO~rIO)v(1~p,IO)v(IO+D)<1
LIG+IO+NIG+rNIEt64
[10]
~ERROR2x\LIG>NG
[11]
[12]
[13J
[14J
~ERROR3x\NIG>NGt4
[lSJ
[16 ]
[17]
+CATENx\S2~0
[18J
[19]
[20]
[ 21]
RATIO)=?'
-+IOEQl x \IO=l
01+S12;Sl+p12 x IO-l
02+S12 xNIG+IO;S2+(S12 x NG-NIG+1)-Sl
02+0
-+CATEN
IOEQ1:0l+S12 xNIG+l;Sl+S12 x NG-NIG+1
02+S2+0
CATEN:GRANO+(26 F'APLI'),NIE,RIC,IO,NIE,(7PO),Sl,Ol,S2,02,(496pO)NIG,I 0
S F 2,21 F'APLIPARS',l F 1
Appendix D
221
[22]
6 F 1,22 F GRANO,9 F 1
[23]
-..
[24J
ERROR1: 'INPUT PARAM. NOT SINGLE ELEMENT ,NON-INTEGER, OR OUT OF RANGE'
[25]
-+
[26J
[27J
[28J
-..
ERROR2:'INDEX OFFSET TOO HIGH'
ERROR3:'TOO MANY INDEX ENTRIES'
V
*
* APLISI-SOURCE FOR APLILMN,WHICH Wlf,L CREATE AN APL INDEXED FILE
*
ASSEMBLED BY APLIMETA,WHICH CREATES APLIBO
APLILOAD CREATES APLILMN
* SEE SETPARS, AN APL WORKSPACE, WHICH CREATES THE FILE 'APLIPARS'
*
USED BY APLILMN.
* SEE ALSO APLISAMP, WHICH IS AN EXAMPLE OF THE JOB FILE, U:nNG
APLILMN, TO CREATE AN APL INDEXED FILE
*
GRANO
ZEROS
START
WRITEZ
222
Appendix D
SYSTEM
SYSTEM
REF
REF
CSECT
RES
RES
DOl
DATA
CSECT
M:OPEN
11: OPEN
M:READ
M:WRITE
LW,l
LW,2
M:WRITE
AI,2
BDR,l
M:CLOSE
M:EXIT
lI'ND
BPM
SIG7F
M:BO
M:SI
o
514
o
32
0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
1
M:SI,(IN),(FILE,'APLIPARS')
M:BO, (OUT), (SAVE)
M:SI,(BTD,O).(BUF,GRANO).(SIZE,2056).(WAIT)
M:BO,(BLOCK,O),(BTD.0).(BUF,GRANO),(SIZE,2048)
GRANO+512
NUMBER OF INDEX GRANULES
GRANO+513
INDEX OFFSET
M:BO.(BLOCK,*2),(BTD,O).(BUF,ZEROS),(SIZE.2048)
1
WRITEZ
M:BO,(SAVE)
START
APPENDIX E. APL/EDMS INTERFACE
Installations which support the Xerox Extended Data Management System (EDMS) may also support a version of APL
which provides an interface to EDMS data bases. Xerox EDMS is described in the EDMS Users Guide (903037)
and EDMS Reference Manual (9030 12). The EDMS Reference Manual includes a complete description of the AP!/
EDMS Interface.
Table E-l is a summary of the EDMS interface function call formats. These functions are contained in the DMSFNS
workspace, which normally resides in the DMSLlB account. Table E-l is ordered alphabetically by function name.
Table E-l. EDMS Interface Functions
Function Call Format
Action/Result
BERRCODE
Result is contents of CCB ERR-CODE
cell.
BGRPNO
Result is contents of CCB GRP-N 0
cell.
BREFCODE
Result is contents of CCB REF-CODE
cell.
CLOSAREA 'area-name'
Named area is closed.
CLOSEDB
All areas are closed.
CREATE 'area-name[.~ccount][. [password]G cipher-key]]],
Named area is opened in create mode.
CURRGRP 'group-name'
Result is contents of current-of-type
cell for named group.
CURRSET 'set-name'
Result is contents of set table for
named set.
DCDREF encoded -reference-codes
Result is matrix of decoded reference
codes.
DELETANT 'group-name'
t
DELETE 'group-name'
DE LETSE L 'group-name'
'group-name' DE LIN K 'set-name'
DMSABORT 'function-name'
DMSCHKPT
DBM buffers are flushed and lockout
bit is reset.
DMSENP
Dynamic memory is released and
EDMS public library is disassociated.
QMSERCOD
Result is code of most recent APLlevel EDMS error.
tNo explicit result is returned. See EDMS reference manual for a description of the action taken.
Appendix E
223
Table E-l.
EDMS Interface Functions (cont. )
Function Call Format
Action/Result
DMSLOCK 'function-name'
DMSPASS 'password'
Password is placed into CCB
PASSWORD cell.
DMSPKSN 'serial-numbers'
Serial numbers are placed into most
recently referenced DCB.
DMSRECV
DMSRLSE
DMSSUB 'subschema-name[. [account]G password]]'
Named subschema is identified for
subsequent use.
DMSTRACE
Procedural trace is initiated.
ECDREF decoded-reference-codes
Result is vector of encoded reference
codes.
ENDTRACE
Procedural trace is terminated.
FIN DC 'group-name
I
FINDD
FINDDUP 'group-name'
FINDFRST 'group-name'
FINDG 'group-name'
t
FINDLAST 'group-name'
FIN DM 'set-name'
FINDN {'group-name'}
'set-name'
FINDP {'group-name'}
'set-name'
t
FINDS
FINDSI
FINDX 'item-name [{~ } group-name}
FROMODMS
°
'i"tem-name[I~}{group-name}]'
IN
set-name
FRSTREF encoded-reference-code
tNo explici't result is returned.
224
Appendix E
Result is contents of item working
storage.
CCB FRST-REF cell is set to the value
of the argument.
See EDMS reference manual for a description of the a¢tion taken.
Table E-l. EDMS Interface Functions (cont.)
Function Call Format
Acti on/Resu It
GET 'group-name'
HEAD 'set-name'
LAS TREF {~nCoded -reference -code}
Integer scalar
CCB LAST .. REF cell is set to the
value of the argument.
'group-name' LIN K 'set-name'
MODIFY 'group-name'
OPENRET
OPENUPD
OPRETSHD
I
1
,
area-name[. [account]G[password]G cipher-key]]]
OPUPDSHD
REFCODE encode-reference-code
Named area is opened in indicated
mode.
CCB REF-CODE cell is set to the
value of the argument.
'group-name' RELIN K 'set-name'
REMOVE 'group-name'
REMOVSEL 'group-name'
RESETERR integer-scalar-or-vector
Error control for indicated datadependent errors is reset.
integer-sea lar-or-vector SETERR 'function-name'
Error control for indicated datadependent errors is set to
function-name.
STORE 'group-name'
rrOF}" {group-namel]'
.
value TODMS 'Item-nameUIN set-name
Item working storage is set to argument value.
t No explicit result is returned. See EDMS reference manual for a description of the action taken.
Appendix E
225
APPENDIX F. APL SYMBOLS
Table F-l.
Symbol
APL Symbols and Names
Name{s)
Page{s)
Identity
54
or
+
/lddition
54
Signum
56
or
x
Mu Itiplication
56
Specification Arrow
40
[
Left Bracket
21, 68
)
Right Bracket
21, 68
Ravel
75
1-
or
.
Catenation
75
or
Lamination
76
Period
71, 73
-Reduction
68
/
or
J
Compression
84
Dieresis
7
Negative Sign
13
<
Less Than
63
~
Less Than or Equal
63
=
Equal
64
~
Greater Than or Equal
64
>
Greater Than
65
'"
Not Equal
65
"
Or .
66
A
And
66
..
-
"
Negation
i
226
Appendix F
55
or
-
Subtraction
55
Table F-1. APL Symbols and Names (cont.)
Symbol
.
Name{s)
Page{s)
Reciprocal
56
or
-
?
w
Division
57
Random
74
Omega
7
Membership
87
or
€
Execute
87
Dimension
77
p
or
Restructure
78
-
Not
68
t
Take
86
.j.
Drop
86
Index Generator
74
1
or
Index Of
75
Pi Times
61
or
0
Circular Functions
61
Exponential
57
*
or
Exponentiation
58
+
Branch Arrow
96
a
Alpha
7
Ceiling
59
r
or
Maximum
59
Floor
59
l
or
Minimum
59
-
Underscore
7
'iI
Del
101
Delta
7
Small Circle
73
II
.
-
Appendix F
227
Table F-l.
Name(s)
Page (s)
Quote
14
0
Quad
43, 47
(
left Parenthesis
48
)
Right Parenthesis
48, 122
c
left Cap
7
::;,
Right Cap
7
n
Cap
7
u
Cup
7
T
Encode
83
1
Decode
82
Absolute Value
60
Symbol
I
I
60
;
Semi-Colon
21, 47, 93
:
Colon
105
Scan
70
$
<l>
I!i>
e
e
Append i x F
or
Residue
\
228
APl Symbols and Names (cont.)
or
Expansion
85
Dollar Sign
212-215
Reversal
78
or
Rotation
78
Transpose
79
Reversal
78
or
Rotation
78
Natural logarithm
58
or
logarithm
58
~
Grade Down
82
•
Grade Up
82
Table F-l.
Symbol
Name{s}
Page{s}
Factorial
62
or
!
., .
APL Symbols and Names (cont.)
Combination
62
I
I-Beam
92
I!l
Quote-Quad
44
Matrix Inversion
90
If]
or
Matrix Division
90
A
Comment
10
...
Nor
67
*
Nand
67
~
Locked Function
]]9
Reduction
68
-f
,
or
Compressi on
84
Scan
70
or
Expansion
85
Q
Underscored Delta
7, 15
;:
T-Bar
93
!J
Quad-Zero
166
(j]
Quad-One
198
fa
Quad-Two
198
Appendix F
229
INDEX
Note: For each entry in this index, the number of the most significant page is listed first. Any pages thereafter are listed in
numerical sequence.
A
absolute value operator, 60
account, 17
active workspace, 123
adding characters to end of line, 113
addition operator, 54
affixture codes, 156
ampersand, 198
and operator, 66
APL codes, 191
APL exponential notation, 13
APL features, 1
APL operators, 25,52
APL terminal keyboard, 6,7
argument characteristi cs, 52
arguments, 24
arithmetic group (operators), 54
arrays, 19
arrays of two or more dimensions, 46
assigning a value to an array, 23
assignment, 40
assignment statement, 99
asterisk after an entry, 118
ATTN key, 159
autostart, 2
AUTOSTART, 141
auxiliary plotting functions, 165
B
base value or decode operator, 82
batch operation, 193
blind I/o, 198,2
blind I/O for files, 199
blind I/o on a device, 198
blind output., 47
branch statements, 96
breaks, 50
c
canonical representation, 171
card input format, 194
CATCH command, 128
catching assigAmen.ts, 3
catenation, 76
catenation and lamination operator, 75
CENTER function, 164
changing a function header, 114
changing suspended functions, 105
changing terminal declaraTion, 189
character set, 7
circular operator, 61
CLEAR command, 130
CLEAR option, 147
closing fi les, 203
combination operator, 62
command statements, 95
commands, 124
comments, 10
communications commands, 122
composite operators, 68
compound statements, 2, 100
compression operator, 84
constants, 13
CONTINUE command, 6, 130
CONTINUE HOLD command, 6,130
CONTINUE workspace, 123
control keys, 11
converting data types, 208
COPY command, 131
COS function, 166
.6.CR function, 171,120,121
creating the set of fi Ie I/o operators, 200
o
data list (right argument), 153
data transmission rates, 197
default terminal output, 49
defined functions, 101, 12
defined functions, displaying and editing, 108
defined functions, examples, 102
defined functions, syntax, 102
DELAY, 120
deleting a line, 109
deleting characters, 112
deleting records or components, 207
devices, standard and nonstandard, 189
DIGITS, 120
DIGITS command, 45, 133
dimension operator, 77
direct control of graphic I/o, 166
direct input, 42
direct-line prompt, 9
directives, 105
display function, 89
displaying and editing defined functions, 108
displaying user-defined functions, 106
division operator, 57
domain, 52.
double colon, 198
DRAW function, 163
DROP command, 133
drop operator, 86
dummies, 104
dyadic function, 40
dyadic scalar operators, 53
dyadic transposition operation, 80
Index
231
Note: For each entry in this index, the number of the most significant page is listed first. Any pages thereafter are listed in
numerica I sequence.
E
EBCDIC codes, 191
editing a line number, 114
editing user-defined functions, 107
empty arrays, 46
empty vectors, 46
equals operator, 64
ERASE command, 134
ERRN, ERRF, and ERRX, 121
error and break control, 3
error ex its, 157
error marker, 193, 195, 198
error messages, 179
error reporting, 171,210
error response, 195
error stop, 161
errors, 50
ESCAPE key sequences and APl, 192
evaluated input, 43
execute operator, 2,87
execution and definition modes, 9
execution break, 159
execution stops, 159
EXP, 166
expansion operator, 85
exponential notation, 45
exponential operator, 57
exponentiation operator, 58
expression eva luation, 48
expunge, 172, 173
function line appendage, 2
function name, 15
function references, 39
function-line prompt, 10
functions, 12
fuzz, 45
G
general input/output, 42
general ized logarithm (base A) operator, 58
gin-mode, 197
global variables, 17
grade down operator, 82
grade up operator, 92
GRAF workspace, 167
graphic functions, 163
graphic I/O, 166
graphic input functions, 165
graphics capability, 3
greater than operator, 65
greater than or equal to operator, 64
GRF calls, 168
6GRF intrinsic function, 167
GROUP command, 135
group name, 15
GRP command, 136
GRPS command, 136
H
F
factorial operator, 62
false terminal declarafion, 190
false terminal declaration, problem examples, 192
fast formatted output, 1
fi Ie I/o subsystems, 211
fi Ie identifier (FID), 16
file input/output, 200,1
FlO, 121
FlOE, 121
floor and ceiling operators, 59
L'> FM T, 152,216
FMT operation, 153,157
FNS command, 134
format specifications, 152
format statement (left argument), 153
formats for branching, summary, 98
formatted output function (FMT), 152
.
formatting aids, 157
fractional number, 45
function copying, 2
function creation, 89
function definition mode, 88
function editing, 105
function ·editing in evaluated input and execute mode, 3
function execution, 116
232
Index
HEADER function, 157, 120
h igher-order array, 20
home terminal, 149
I-beam functions, 92
identity operator, 54
illegal character, 193
i lIega I characters, 197
index generator operator, 74
index of operator, 74
indexed assignment, 41
indexing, 19
indexing an indexed argument, 24
indexing of arrays, 21
inner product operator, 71
input scaling, 170
·i nput / output, 42
input/output device assignments, 194
input/output devices, 42
input/output translation, 190
inquiry commands, 122
inserting a line, 110
i nserti ng characters, 112
INT (interval) function, 163
Note: For each entry in this index, the number of the most significant page is listed first. Any pages thereafter are listed in
numerical sequence.
intrinsic functions, 120,216
issuing system commands, 115
items subject to sidetracking, 185
K
key values versus component values, 204
L
labels, 105
lamination, 25,76
left argument, 153
length, 52
less than operator, 63
less than or equal to operator, 63
LIB command, 137
line corrections during input, 8
line deletion, 89
line editing, 192, 196
line insertion, 89
line numbers, 110
line printer graphic codes, 192
line replacement, 89
linelist, 171
listing file names and numbers, 209
LOAD command, 137
local variables, 17, 18
locals, 105
locking function, 119
log on/log off procedures, 4
logging off, 6
logging on, 4, 196
logging on and logging off APL system, example,S
logical operator, 65
M
maintaining component range and current
component value, 204
mathematical notation, 13
matrix, 20
matrix arguments, 155
matrix divide operator, 90
matrix inversion operator, 90
membership operator, 87
minimum and maximum operators, 59
mixed ope.rators, 74
mixed output, 46
modification. function, 90
modifying a line, 11~
monadic function, 40
monadic scalar operators, 53
monadic transposition .operation, 79
multiple assignment, 41
multiplication operator, 56
N
name format, 15
name usage, 15
nomelist, 171
names, 7, 15
nand operator, 67
natural logarithm (base e) operator, 58
negation operator, 55
negative symbol, 13
niladic function, 40
NLINES function, 157,120
non-APL 2741 terminals, 197
nonassignment statement, 99
nonstandard input/output, 189
nor operator, 67
norma I stop, 159
NOSCALE function, 164
not equal to operator, 65
not operator, 68
numeric and character vectors, 46
numeri c constants, 13
o
observation of intermediate results, 3
OBSERVE command, 138
OFF command, 6,139
OFF HOLD command, 6, 139
OFF option, 147
ON option, 147
on-line and batch operation,
opening and creating files, 202
operation without APL characters,
operators, 11,24,25
OPR command, 140
OPRN command, 140
or operator, 66
order of evaluation, 48
ORIGIN, 120
ORIGIN command, 140
outer product operator, 73
output, 44
output scaling, 169
output value forms, 155
overstriking a character, 114
p
PAGE function, 157,120
parentheses, 48
password, 17
passwords, 124
PCOpy command, 141
pendant functi on, 118
pi I·imes operator, 61
plotting functions, 163
precedence of operators, 48
Index
233
Note: For each entry in this index, the number of the most significant page is listed first. Any pages thereafter are listed in
numerical sequence.
primitive functions (see "APL operators ")
prompt character, 193, 195
prompts, 9
o
QCOPY command, 141
QLOAD command, 141
quad input prompt, 198
quad or quote-quad input, 44
quad output, 47
quad prompt, 10
quad zero input, 165
quad zero output, 166
qualifiers, 156
quiet load and copy commands, 2, 141
quitting line editing, 114
quote-quad input, 44
quote-quad prompt, 10
R
rank, 52
rave I operator, 75
reading APL records, 206
reading non-APL records, 207
reciprocal operator, 56
recursive function, 116
reduction operator, 68
referencing a single element, 21
referencing more than one element, 22
replacing a line, 111
replacing characters, 113
report formatting, 152
representation or encode operator, 83
reshape operator, 78
residue operator, 60
reversal operator, 78
right argument, 153
right parenthesis, 122
roll operator, 74
rotation operator, 78
s
SAVE command, 141
saved workspace, 123
scalar arguments, 153
sca lar operators, 53
scalar output, 166
SCALE function, 164
scaling function-;, 164
scan operator, 70
SEAL command, 142
sequential access to existing APL files, 207
sequentia I access to non··APL fi les, 208
SET command, 142
SETFUZZ, 120
SETLINK, 121
shadowing, 18
shape, 52
51 CLEAR command, 119
SI command, 118, 146
SI-damage protection, 2
sidetrack setting, 186
sidetracking considerations, 187
sidetracking dynamics, 187
sidetracking on error and breaks, 184
sidetracking, aids for users, 188
sidetracking, items subject to, 185
significant digits, 45
signum operator, 56
simple assignment, 40
SIN function, 166
SIV command, 119, 146
standard 8-bit computer codes (EBCDIC), 191
standard file I/o error messages, 211
state indicator, 118
statement label, 15
statement labels, 98
statements, 11, 95
stop control vector, 160
stop of user input, 159
stopping a display, 47
stopping execution, 117
STRAPIS, 166
strapping options, 197
subtraction operator, 55
suspended function, 118
suspending execution, 118
SYMBOLS command, 147
syntax considerations, 49
syntax conventions, 52
system commands, 11, 115, 122
system commands, summa ry, 124
T
T-bar functions, 93
tab usage, 193
TABS, 120
TABS command, 148
take operator, 86
~ TE function, 171, 121
Tektronix 4013 graphics terminal, 163
Tektronix 4013 usage, 195
teletype usage, 192
TERMINAL command, 149
terminal declaration, 189
text constants, 14
text editing functions, 175
tracing execution, 116
translation equivalences for nonstandard devices, 211
transparent scaling, 169
transposition operator, 79
types of input, 42
.'
234
Index
Note: For each entry in this index, the number of the most significant page is listed first. Any pages thereafter are listed in
numeriqal sequence.
u
unequally spaced tabs, 2
unsealed graphic I/o, 169
user accounts, 124
user input versus computer output, 8
user-defined functions, 101
y
value of variable versus its name, 48
variable, 15
variables, 11,16
variables local to defined function, 104
VARS command, 150
VCHAR function, 157,120
vector, 20
vector arguments, 154
VS function, 163
w
WHATCHAR function, 165
WHATCOORD function, 165
WHATSCALE function, 164
WHATWINDOW function, 164
WIDTH, 120
WIDTH command, 150
width of line, 44
window functions, 164
/':;.WM function, 171,172,121
wordspace control commands, 122
workspace concept, 123
workspace management functions, 171
workspace name, 15
workspace WSFNS, 120
writing APL records, 205
writing non-APL records, 205
WSID command, 151
x
/':;.XL function, 158, 120
Index
235
XEROX
Reader Comment Form
We would appreciate your comments and suggestions for improving this publication
Publication No.
I
Rev. Letter
I
I
Title
15 the material presented effectively?
How did you use this publication>
D Learning
D
Reference
[J
D
Installing
Maintaining
What is your overall rating of this publication?
D Very Good
[J
Good
D Fair
o
Current Date
D
0
o
Sales
[ ] Fully Covered
Operating
[l Well
Illustrated
D
Well organized
D Clear
What is your occupation?
Very Poor
Poor
Your other comments may be entered here. Please be specific and give page, column, and line number references where
applicable. To report errors, please use the Xerox Software Improvement or Difficulty Report (1188) instead of this form.
I
.
Your name & Return Address
Thank You For Your Interest. (fold & fasten as shown on back. no postage needed if mailed
In
US.A)
PLEASE FOLD AND TAPE NOTE: U. S. Postal Service will not deliver stapled forms
--
.
----------~
First Class
Permit No. 59153
Los Angeles, CA
BUSINESS REPL Y MAIL
No postage stamp necessary if mailed in the United States
Postage will be paid by
Honeywell Information Systems
5250 W. Century Boulevard
Los Angeles, CA 90045
Attn: Programming Publications
Fold
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising