Digital PDFs

AA-H200A-TK

May 1979

333 pages

Original

69MB

Document:	APLSF Language Manual Aug79
Order Number:	AA-H200A-TK
Revision:	0
Pages:	333
Original Filename:	AA-H200A-TK_APLSF_Language_Manual_Aug79.pdf

OCR Text

APLSF

Language Manual
AA-H200A-TK

August 1979
This manual describes the language elements of APL-Basic
and APLSF on both the TOPS-10 and TOPS-20 operating
systems.
This manual supersedes the following: DECSYSTEM-20
APLSF Programmer's Reference Manual DEC-20-LASFAA-D, and DECsystem-10 APLSF Programmer's Reference
Manual DEC-10-LPLSA-A-D.
OPERATING SYSTEM:

TOPS-10 Version 6.03A
TOPS-20 Version 3A

SOFTWARE:

APLSF Version 2
APL-Basic Version 2

Software and manuals should be ordered by title and order number. In the United States, send orders to the nearest
distribution center. Outside the United States, orders should be directed to the nearest DIGITAL Field Sales Office
or representative.
NORTHEAST/MID-ATLANTIC REGION

CENTRAL REGION

WESTERN REGION

Technical Documentation Center
Cotton Road
Nashua, NH 03060
Telephone: (800) 258-1710
New Hampshire residents: (603) 884-6660

Technical Documentation Center
1050 East Remington Road
Schaumburg, Illinois 60195
Telephone: (312) 640-5612

Technical Documentation Center
2525 Augustine Drive
Santa Clara, California 95051
Telephone: (408) 984-0200

digital equipment corporation • marlboro, massachusetts

First Printing, August 1979

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this document.
The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

~ 1979 by Digital Equipment Corporation

The postage-prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DECCOMM
ASSIST-ll

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8

1/82/14

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-ll
TMS-ll
ITPS-10

CONTENTS

Page
PREFACE

CONVENTIONS USED IN THIS MANUAL

xii

ACKNOWLEDGMENT

xiii

CHAPTER

THE APL OPERATING ENVIRONMENT

1-1

1.1

INTRODUCTION

1-1

1.2
1.2.1
1.2.2
1.3
1.4
1.4.1

1-2
1-3
1-5
1-5
1-8

1.4.2
1.4.3
1.4.4
1.5
1.5.1
1.5.2

HARDWARE
APL-Keyboard Terminals
Terminals without the APL Keyboard
THE APL CHARACTER SET
INTERACTING WITH APL
Entering APL Command Level (Starting the
Session
Ending the Session
Returning to System Command Level
Interrupting Execution
KEYBOARD EDITING
Correcting a Line Before Entering
Correcting a Line After Entering

LANGUAGE SYNTAX

2-1

2.1
2.1.1
2.1.2
2.1.2.1
2.1.2.2
2.1.3
2.1.4
2.1.5
2.1.6

INTRODUCTION
Statement Execution Modes
Expression Components
Identifiers
Constants
Spaces and Comments
File Specifications
Statement Types
Evaluation of APL Statements and
Expressions
NUMBER PRECISION
ERROR HANDLING
ARRAY INDEXING AND COMPARISONS
Indexing Arrays
The Index Origin
Comparison Tolerance or Fuzz
TERMINAL I/O OPERATIONS
Evaluated Input Mode-Quad Input (0 or
.BX)
Character Input Mode-Quote-Quad (~ or
.QQ)
Unedited Input Mode-Quad-Del (~ or .QD)
Escaping From Input Mode
Normal .and Quad Output Modes
Mixed Output Mode
Bare Output Mode (Quote-Quad ~ or
Quad-Del ~)

2-1
2-1
2-2
2-2
2-3
2-5
2-6
2-7

2.2
2.3
2.4
2.4.1
2.4.2
2.4.3
2.5
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5
2.5.6
2.5.7

iii

1-8
1-9
1-9
1-10
1-10
1-10
1-11

2-8
2-9
2-10
2-11
2-11
2-15
2-15
2-16
2-17
2-17
2-18
2-19
2-19
2-21
2-22

CONTENTS (CONT . )

Page
CHAPTER

APL FUNCTIONS AND OPERATORS

3-1

3.1
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
3.3.7
3.3.8
3.3.9
3.3.10
3.3.11
3.3.12
3.3.13
3.3.14
3.3.15
3.3.16

INTRODUCTION
PRIMITIVE SCALAR FUNCTIONS
Relational Functions
Logical Functions
I or .AB - The Residue Function
? - The Roll Function
PRIMITIVE MIXED FUNCTIONS
, - The Catenate Function
/ and f - The Compression Function
? - The Deal Function
~ or .DE - The Decode Function
+ or .DA - The Drop Function
T or .EN - The Encode Function
\ and , - The Expansion Function
, or .GD - The Grade Down Function
¢ or .GU - The Grade Up Function
1 or .IO - The Index Generator Function
1 or .IO - The Index Of Function
, - The Laminate Function
E or .EP - The Membership Function
, - The Ravel Function
p or .RO - The Reshape Function
~ or .RV and e or .CR - The Reverse
Function
~ or .RV - The Rotate Function
p or .RO - The Shape Function
t or
- The Take Function
~ or .TR - The Monadic Transpose
Function
~ or .TR - The Dyadic Transpose Function

3-1
3-2
3-5
3-6
3-7
3-9
3-10
3-12
3-15
3-17
3-18
3-20
3-22
3-25
3-27
3-28
3-30
3-31
3-33
3-35
3-36
3-37

3-70
3-70

3.5.3
3.5.4

OPERATORS
f
g - The Inner Product Operator
o
•
f or .SO . f - The Outer Product
Operator
f j - The Reduction Operator
f\ - The Scan Operator

APL SYSTEM COMMUNICATION

4-1

4.1
4.2
4.2.1
4.2.2
4.2.3

INTRODUCTION
SYSTEM VARIABLES
DAI - Storing Account Information
DALPHA - Alphabetic Characters
DALPHAU - Underlined Alphabetics

4-1
4-1
4-2
4-3
4-3

3.3.17
3.3.18
3.3.19
3.3.20
3.3.21

3.5
3.5.1
3.5.2

CHAPTER

3-38
3-41
3-43
3-45
3-46
3-48

3-73
3-75
3-77

CONTENTS (CONT • )

Page
4.2.4
4.2.5
4.2.6
4.2.7
4.2.8
4.2.9
4.2.10
4.2.11
4.2.12

DASCII - ASCII Character Set
DAUS - Saving a Workspace Automatically
DAV - Atomic Vector
OCT - Comparison Tolerance
DCTRL - Control Characters
DERROR - Storing Error Messages
DGAG - Preventing Interruptions
DIO - Index Origin
on
Functions

4-3
4-7
4-8
4-14
4-15
4-16
4-18
4-19
4-20

4.2.15
4.2.16

DPP - Output Precision
DPW - Determining the Width of the
Output Line
DRL - Setting a Random Link
DSF - Setting the Evaluated Input Prompt
DTIMELIMIT - Setting a Time Limit

4-22

4.2.17
4.2.18
4.2.19

4-22
4-23
4-23
4-24

Il!ljlil~1!~1~~liil~lmijIJifl!!ijjj!l~il~~11ID1~I'liliiili~l~i~ji!j;fl!~!~i'00:11!i1j~q~ilMl~m)11!H:i!mijlj!j!jji;1il{Wi!!:':';;
Am@:W~.~·§.~·;:
4.2.22
DTS - Reporting Current Time and Date
4-27
4.2.23
4.2.24
4.2.25
4.3
4.3.1
4.3.3
4.3.4
4.3.5
4.3.7
4.3.8
4.3.9

OTT - Reporting Terminal Type
DUL - Reporting the Job Number
DWA - Reporting the Available Work Area
SYSTEM FUNCTIONS
DBREAK - Sus end
DDL - Delaying the Execution of a
Function
DEX - Erasing a
DFI -

4-31
4-31
4-32

DNC a Name
DNL - Constructing a List of Labels,
Variables, or Functions
DQLD, DQCO, DQPC - Loading and Copying

4-34

4-36

4.3.11
CHAPTER

4-27
4-28
4-28
4-28
4-29

4-35

Input

SYSTEM COMMANDS

5-1

5.1
5.1.1
5.1.2
5.1.3
5.1.3.1
5.1.3.2
5.1.3.3
5.1.3.4
5.1.3.5
5.1.4
5.2
5.2.1
5.2.2

INTRODUCTION
System Command Format
Action and Inquiry Commands
Workspace Characteristics
Workspace Names
The CONTINUE Workspace
Workspace Passwords
Groups
The State Indicator
APL Libraries
BASIC WORKSPACE-CONTROL COMMANDS
)CLEAR - Clearing the Active Workspace
)DROP - Deleting Stored Workspaces or
Files
)LIB - Listing Workspace Names
)LOAD - Retrieving a Workspace

5-1
5-2
5-2
5-3
5-4
5-5
5-6
5-6
5-6
5-7
5-7
5-8

5.2.3
5.2.4

5-9
5-10
5-12

CONTENTS (CONT.)

Page
5.2.5

)PASSWORD - Determining the Workspace
5-13

Password
5.2.6
5.2.7
5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.4
5.4.1
5.4.2
5.4.3
5.4.4
5.4.5
5.4.6
5.4.7
5.4.8
5.4.9
5.4.10
5.5
5.5.1
5.5.2
5.5.3
5.5.4
5.5.5
5.5.6
5.6
5.6.1
5.6.2
5.6.3
5.6.4
5.6.5
5.7
5.7.1
5.7.2

)SAVE - Saving a Copy of the Active
Workspace
)WSID - Identifying the Active Workspace
EXTENDED WORKSPACE-CONTROL COMMANDS
)MAXCORE - Determining the Maximum
Workspace Size
)MINCORE - Determining the Minimum
Workspace Size
)OWNER - Identifying the Owner of a
Workspace
)SEAL - Turning the Workspace Seal On or
Off
)SIZE - Reporting the Workspace Size
)TIME - Reporting the Time Used
)VERSION - Displaying the APL Version
Number
WORKSPACE-CONTENT COMMANDS
)COpy - Copying Objects from a Workspace
)ERASE - Erasing Global Names
)FNS - Displaying a List of Functions
)GROUP - Defining or Dispersing a Group
)GRP - Displaying the Members of a Group
)GRPS - Displaying a List of Groups
)PCOpy - Copying from a Workspace with
Protection
)SI - Displaying the State Indicator
)SIV - Displaying the State Indicator and
Local Variables
)VARS - Displaying a List of Variables
WORKSPACE-ENVIRONMENT COMMANDS
)DIGITS - Determining the Output Precision
)ECHO - Determining Error Line Echoing
)MODE - Determining the Terminal Output
Mode
)ORIGIN - Determining the Index Origin
)TABS - Determining Tab stops on the
Terminal
)WIDTH - Determining the Width of the
Output Line
APL TERMINATION COMMANDS
)C and )CALL - Running a Program and
Returning to APL
)CONTINUE - Saving the Workspace and
Ending the Session
)MON - Returning to Operating System
Command Level
)OFF - Terminating the APL Session
)R and )RUN - Ending the Session and
Running a Program
MISCELLANEOUS COMMANDS
)BLOT - Generating a Mask
)CHARGE - Displaying APL Session
Information

5-13
5-15
5-15
5-16
5-17
5-18
5-18
5-19
5-19
5-20
5-20
5-21
5-22
5-23
5-23
5-24
5-24
5-25
5-25
5-26
5-27
5-27
5-27
5-28
5-29
5-30
5-30
5-31
5-32
5-32
5-33
5-34
5-34
5-35
5-36
5-36
5-36

CONTENTS (CONT.)

Page
CHAPTER

DEFINING AND EXECUTING FUNCTIONS

6-1

6.1
6.2
6.2.1
6.2.2
6.2.2.1
6.2.2.2
6.2.2.3
6.2.3
6.2.4
6.2.5
6.2.5.1
6.2.5.2
6.2.5.3
6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3.8
6.4
6.4.1
6.4.2
6.4.3
6.4.4
6.4.5
6.4.6
6.4.7

INTRODUCTION
DEFINING THE FUNCTION
The Function Header
Symbol Classification
Local Symbols
Global Symbols
Dynamic Localization
Function Input and Output
Comment Lines
Examples of Defined Functions
Niladic Function
Monadic Function
Dyadic Function
EDITING THE FUNCTION
Adding Function Lines
Replacing Function Lines
Inserting Function Lines
Deleting Function Lines
Displaying Function Lines
Editing the Function Header
Character-Editing Procedures
Performing Immediate-Mode Editing
EXECUTING THE FUNCTION
Branching within a Function
Statement Labels
Suspending Function Execution
Examining the State Indicator
The Trace Vector
The Stop Vector
Locking a Function

6-1
6-1
6-2
6-3
6-4
6-4
6-4
6-5
6-6
6-6
6-6
6-6
6-7
6-7
6-8
6-8
6-9
6-9
6-10
6-11
6-11
6-14
6-14
6-14
6-16
6-17
6-18
6-20
6-22
6-22

vii

CONTENTS (CONT.)

Page

APPENDIX A

ERROR MESSAGES

A-I

APPENDIX B

SUMMARY

B-1

APPENDIX C

I-BEAMS

C-1

APPENDIX 0

SPECIFYING TOPS-20 DIRECTORIES

0-1

USING LOGICAL NAMES
Giving the DEFINE Command
Using the Logical Name
USING PROJECT-PROGRAMMER NUMBERS
Using the TRANSL Command
Using the Project-Programmer Number

0-1
0-1
0-2
0-2
0-2
0-3

TERMINAL SESSION

E-1

0.1
0.1.1
0.1.2
0.2
0.2.1
0.2.2
APPENDIX E
INDEX

Index-1

FIGURES
FIGURE

1-1

The APL Keyboard (LA37 Terminal)

1-4

TABLES
'rABLE

1-1
1-2
1-3
2-1
3-1

APL Terminals and Designators
APL Character Set
Editing Characters
Input/Output Functions
Results of Scalar Dyadic Functions

viii

1-3
1-6
1-11
2-16
3-2

CONTENTS (CONT.)

Page
TABLE

Primitive Scalar Functions
The Dyadic Circle Function
Truth Table
Primitive Mixed Functions
Trans ose Definitions

3-9
3-10
3-11
4-1
4-2
4-3
4-4
4-5
5-1
5-2
5-3

Inner Product Descript on
Outer Product Description
Identity Elements
The ASCII Character Set
The Atomic Vector
OCTRL
OTT Terminal Types
ONC Classes
Workspace Name Defaults
)LIB Switches
System Commands and Execute

Pr
ons
The Dyadic Circle Function
Relational and Logical Functions

3-71
3-74
3-75
4-4
4-9
4-15
4-27
4-34
5-5
5-11
5-37

B-3
B-3
B-4
B-7
B-9
B-11

PREFACE
This manual describes version 2 of APL on both the TOPS-10 and TOPS-20
operating systems.
There are two implementations of APL on each system, APL-Basic and APLSF (System Functions). APLSF is a superset of
APL-Basic.
To distinguish APLSF from APL-Basic, we have shaded the
text describing features available only in APLSF.
This document is not an APL tutorial manual. Therefore, if you are
unfamiliar with the APL language, you should read an APL primer before
reading this manual. Also, because you will be using APL in conjunction with either TOPS-10 or TOPS-20, you should have the latest editions of the following documents on hand:
1.

TOPS-20 User's Guide

TOPS-20 Monitor Calls Reference Manual
or

TOPS-10 Operating System Commands Manual

TOPS-10 Monitor Calls Reference Manual

Conventions Used In This Manual

[]

Special square brackets indicating operational
information that can be omitted from a command
string.

{}

Braces indicating a choice.
the enclosed.

Lowercase letters

Lowercase characters in a command string indicating variable information you supply.

UPPERCASE LETTERS

Uppercase characters in a command string indicating fixed (literal) information that you
must enter as shown.

Examples

All examples were produced on an LA37 using
either TOPS-IO or TOPS-20.

Contrasting Colors

Red - Where examples contain both user input
and computer output, the characters you type
are in red; the characters APL prints are in
black.

APL

Refers to both APL-Basic and APLSF.

xii

Choose one from

ACKNOWLEDGMENT

The DECsystem-lO implementation of APL was developed by Richard
Fennell, Frederick Pollack, and William Price under the guidance of
Dr. Alan J. Perl is of the Department of Computer Science at
Carnegie-Mellon University. The APLSF enhancements were made by
Frederick Pollack. The conversion to the DECSYSTEM-20 was done at
Digital Equipment Corporation.

xiii

CHAPTER 1
THE APL OPERATING ENVIRONMENT

1.1

INTRODUCTION

APL (A Programming Language) is a language interpreter that runs under
the control of either of two operating systems, TOPS-IO or TOPS-20.
The TOPS-IO and TOPS-20 operating systems provide the APL user with
standard timesharing features, such as resource allocation, job control, device handling, and usage accounting.
Because APL is a very compact programming language, it is suited for
handling numeric and character array-structured data.
In addition to
its mathematically concise format, APL is also an efficient general
data-processing language.
APL is a 2-segment system. The code segment or shared segment, is
the APL interpreter consisting of code shared among all APL users.
The data segment is the APL user's workspace. Each user has a data
segment, but there is only one copy of the interpreter.

1.1.1

Workspaces

A workspace is a block of storage where all interaction with APL takes
place. Each time you access APL, you are issued a clear workspace in
which to define variables and functions as well as to execute APL
statements. The size of an APL workspace is dynamic and can vary from
2K to l76K 36-bit words on TOPS-IO. On TOPS-20, the figure is expressed in pages of 36-bit words, 4P to 352P. The default workspace size
is 20K on TOPS-IO and 40P on TOPS-20.
If you need to change the size,
refer to the )MAXCORE command, Section 5.3.1.
There are three states your workspace can assume as you proceed
through an APL session:
1.

Clear workspace

Active workspace

Inactive workspace

At the beginning of an APL session, you are given a fresh workspace:
the clear workspace.
It has no open files, no defined variables or
functions; it has a clear (empty) symbol table, and a clear (empty)
state indicator.
System variables are set to their default values.
Once you start typing information into your workspace, it is no longer
clear. The workspace you are currently using is your active workspace.

1-1

THE APL OPERATING ENVIRONMENT

All functions and variables you define during the current APL session
are stored temporarily in this workspace. You can save an active
workspace as a file, in binary format, on a secondary-storage device,
Huch as a disk or magnetic tape. An active workspace becomes an inactive workspace when you save it. You can save several workspaces
in your disk area; however, only one can be active at anyone time.
As a group, inactive workspaces are known as a private library.
When you save a workspace, you are not only saving functions and variables, but also the APL symbol table, state indicator and some system
var~able settings.
When you retrieve an inactive workspace from your
library, it again becomes your active workspace.
A workspace can be named, copied, saved, retrieved, deleted, renamed,
protected, and cleared. These workspace operations are described in
Chapter 5.

1.2

HARDWARE

'rhe APL language consists of a special character set in which Greek
letters and a variety of other special characters represent APL language functions and operators. Examples of such special characters
include t , D, v, and E.
'rOPS-20 and TOPS-10 support a variety of terminals for use with the
APL system. Some terminals provide keyboards with the full APL character set (such as the LA37 in Figure 1-1). However, terminals without the APL keyboard can also be used to access APL. On non-APL
terminals, you can use a special set of keyword mnemonics to represent
APL symbols. See Table 1-2 for both character sets.
You select the APL character set or the mnemonic character set when
you begin an APL session. APL prompts you with:
terlTlinal ••

You respond with one of the terminal designators listed in Table 1-1.

1-2

THE APL OPERATING ENVIRONMENT

Table 1-1
APL Terminals and Designators
Terminal

Designator

IBM Selectric l -type
terminal with APL
typing element, or equivalent

2741

Bit-paired ASCII/APL terminal

BIT

Key-paired ASCII/APL terminal

KEY

DECwriter II model LA36 with
APL option (LA37)

LA36

Tektronix 2 4013

4013

Tektronix 2 4015

4015

Any terminal without
APL character set

TTY [/terminal]

ISelectric is a registered trademark of IBM.
is a registered trademark of Tektronix, Inc.

2 Tektronix

The /terminal switch with the TTY designator can be anyone of the
other terminal designators in Table 1-1, for example TTY/BIT. This
switch is optional.
It takes effect when you use the )OUTPUT command
(Section 7.9).
When you specify LA36, 4013, or 4015, that designator causes character
font-switching sequences to be sent to the terminal when you enter and
leave APL.
This means that you do not have to manually switch character sets by pushing a button on the terminal. Specification of KEY
does not have this effect.

1.2.1

APL-Keyboard Terminals

The keyboard illustrated in Figure 1-1 is a typical APL-keyboard terminal; you can use it in either ASCII or APL mode. When you access
APL, the characters are received and interpreted by the APL system.
Note that letters, numbers, and some of the special characters appear
in the conventional keyboard positions.
In APL mode, the letters print
only in uppercase and are produced only when the keyboard is not shifted.
The full APL character set is described in Table 1-2.

1-3

Figure 1-1

The APL Keyboard (LA37 Terminal)

THE APL OPERATING ENVIRONMENT
1.2.2

Terminals Without the APL Keyboard

If you do not have a terminal with an APL keyboard, you can use a combination of keyword mnemonics, or escape characters, and ASCII characters to interact with the APL interpreter. First, you respond with
TTY when APL prompts for a terminal designator (Section 1.2). Then you
can input any of the keyword or escape-mode equivalents listed in
Table 1-2.
For example, to represent the APL rho symbol (p), either type the
mnemonic .RO or the escape character @R.
To type a character in escape mode, first type the at sign (@) and then enter the desired uppercase character. No delimiting blanks are necessary, and you can mix
the two input modes freely.
APL output can also be displayed in either keyword or escape modes,
but you must select one or the other; they cannot be mixed.
The )MODE
command allows you to select the output mode.
This is where the TTY
/terminal is relevant. See Section 5.5.3.

1.3

THE APL CHARACTER SET

Table 1-2 lists all APL characters available on TOPS-10 and TOPS-20.
The first column lists the APL character set. The second column, TTY
set, lists the keyword mnemonic equivalents. The third column supplies
names commonly associated with APL characters, and the fourth column
lists the escape characters.
The uppercase letters indicate the origin of the mnemonic representation.
The second section of the table lists APL overstruck characters. These
are characters constructed by typing one character, one backspace, then
a second character on top of the first.
For example, to construct the
logarithm symbol (~), type the circle symbol (0), then backspace, then
type the exponentiation symbol (*).
You can also type the exponentiation symbol (*) before the circle symbol (0); the order is not significant.
On non-APL keyboard terminals, overstruck characters are represented by single-strike characters or by keyword mnemonics.
Notice
tha~ dollar appears as both a single-strike and an overstruck character.
On some terminals you can enter dollar as a single-strike character ($), and on other terminals you must enter dollar as an overstruck character (31).

1-5

THE APL OPERATING ENVIRONMENT

Table 1-2
APL Character Set
Single-Strike Characters
APL Set

TTY Set

Name

A-Z
0-9

alphabet
numbers
add
and
assignment
(back-arrow or underline)
concatenate
colon
divide
dollar format
equal to
expand (scan)
exponentiate
greater than
left bracket
left parenthesis
less than
mUltiply
quote string
question (roll and deal)
reduce
right bracket
right parenthesis
semicolon
subtract
take
residue (ABsolute value)
ALpha
quad (BoX)
CEiling (maximum)
drop (Down Arrow)
Dieresis
DEcode
DeL
DiaMond
Down Under
ENcode
EPsilon
FLoor
Greater than or Equal to
GO to (branch)
IOta
Left curly Brace
delta (Lower Del)
Less than or Equal to
Left tacK
circle (Large 0)
Left Union
Not Equal to

*
>
[

[
(
<

]
)

)

(

]

I
a

o
r

o
n
T
E

L
1

{
6..
~

I-

.AB
.AL
.BX
.CE
.DA
.DD
.DE
.DL
.DB
.DU
.EN
.EP
.FL
.GE
.GO
.IO
.LB
.LD
.LE
.LK
.LO
.LU
.NE

1-6

Escape Mode

@K
@Q

@Y
@M
@A
@L
@S
@U
@B
@G
@C
@N
@E
@D

@I
@H

@O
@X

THE APL OPERATING ENVIRONMENT

Table 1-2 (Cont. )
APL Character Set
Single-Strike Characters
APL Set

w
y

}
p
-I

c
0

TTY Set

Name

.NG
.NT
.OM
.OR
.RB
.RO
.RK
.RU
.SO
.US
.UU

Escape Mode

NeGation
Not
OMega
OR
Right curly Brace
RhO
Right tacK
Right Union
jot (Small 0)
UnderScore
Up Union

@T
@W
@R
@Z
@J
@F
@V

Overstruck Characters
(None in Escape Mode)
APL Set

Characters to
Strike Over

TTY Set

I
I

.GD
.GU
.IB
.LG
.NN
.NR
.CB
.CR
.CS
.DQ
.IQ
.OQ
.OU
.PD
.QD
.QQ
.RV
.TR
.XQ
.FM

/:,

1'<

\
e
f
Iil
B

\
o
/

¥
ty1
[!]
<I>

~
.1
'If
R

o
o
o

+
-+

OUT
V
'"

o
o
o
o

d. ... z.

A-Z

/:,

.ZA-.ZZ
.Z@

1-7

Name
dollar (format)
factorial (shriek)
Grade Down
Grade Up
I-Beam (histogram)
LoGarithm
NaNd
NoR
back expansion
(Circle) Rotate
back scan
Divide Quad
Input Quad
Output Quad
OUt
Protected Del
Quad Del
Quote Quad
ReVersal
TRanspose
eXecute
ForMat
Commen t ( lamp)
underscored alphabetics
underscored lower del

THE APL OPERATING ENVIRONMENT

1.4

INTERACTING WITH APL

APL provides easy-to-use commands to allow you to interact with the
operating system. Sections 1.4.1 through 1.4.4 describe some of the
commands available. Chapter 5 discusses APL system commands.

1.4.1

Entering APL Command Level (Starting the Session)

To access APL, first log in to either TOPS-20 or TOPS-IO.
successful log in, type the following on TOPS-20:

After a

@APLSF
On TOPS-IO, type:
.R APLSF
In both cases, APLSF begins the session by asking for your terminal
designator:
terminal ••

If you are unsure of what to respond, type H (for Help).

For example:

terminal •• h
the appropriate response for sour terminal
response
~our terminal
27411
ibm 2741 or similar with apl ball
bit
ascii apl bit pairin~
kehl
ascii apl ke~ pairin~
la36
la36 with apl character set option
4013
tektronix 4013
4015
tektronix 4015
tt~
anhl terminal not havin~ apl font

~ive

TERMINAL ••

After receiving a valid terminal designator, APL responds with a
greeting and identification message.
It then supplies a clear workspace for use during the current APL session, or automatically loads
the special CONTINUE workspace saved from the last APL session, if
such a workspace exists in your disk area.
(See Section 5.6.2 for a
description of the CONTINUE workspace.)
If a clear workspace is supplied, APL displays the message:
CLEAR WS

If the CONTINUE workspace is loaded, APL outputs a standard load
workspace message.
For example:
@aplsf
terminal •• la
APL-20 DECSYSTEM-20 APLSF 2(407)
TTY22) 15:22:57 TUESDAY 26-JUN-79 MASELLA
SAVED
15:22:39 26- JUN -79 5 P

IThe 2741 is supported only on TOPS-ID.

1-8

THE APL OPERATING ENVIRONMENT

APL indents six spaces to s~gnify that it is ready to accept input.
APL outputs at the left margin but automatically indents six spaces
before echoing your input. The first character you type will print in
the seventh column from the left margin. APL thus clearly differentiates between what it prints out and what you type in.

1.4.2

Ending the Session

To log off the system while in APL mode, use one of the following
commands:
)OFF

ends the session and logs you off the system.

)CONTZNUE

ends the session, logs you off the system, and
stores the active workspace under the name
DSK:CONTIN.APL. This workspace, instead of a
clear workspace, will be loaded the next time
you run APL.

Note that APL commands begin with a right parenthesis. These commands, )OFF and )CONTINUE, are described in Sections 5.6.4 and 5.6.2,
along with a description of options available for automatically returning to system command level after ending a session rather than
logging off.
CAUTION
Do not end a work session by disconnecting
the terminal's telephone connection or
the current workspace will be lost.

1.4.3

Returning to System Command Level

To return to system command level during an APL session, type the )MON
command. APL indicates that control has been returned to the operating system by printing:

When you receive the system prompt, you can then perform a variety of
system operations, including sending and receiving messages to or from
other users and the operator, assigning devices to your job, inquiring
about CPU usage, and performing other standard functions.
CAUTION
If you run any other program, the
workspace in memory will be destroyed.
To return to APL with the workspace intact, type CONTINUE. APL responds with APLSF: to indicate that it has again received control.

1-9

THE APL OPERATING ENVIRONMENT

1.4.4

Interrupting Execution

To interrupt APL during an operation, use the attention signal, CTRL/C.
Two CTRL/Cs interrupt function or program execution and return you to
APL mode.
The response may be delayed for a few seconds because of
system buffering.
Typing five CTRL/Cs will return you to system command level. To return
to APL mode and resume APL operations, type one of the following operating system commands:
@REENTER

or
@CONTINUE

1.5

KEYBOARD EDITING

The following sections describe the procedures for entering and correcting APL text on a terminal with an APL keyboard.

1.5.1

Correcting a Line Before Entering

You can type characters in an APL input line in any order.
Regardless
of how you enter the line, APL evaluates it exactly as it appears on
the terminal; the order in which you type characters is not significant.
By using the appropriate space and backspace characters, you can even
type the line backwards. APL interprets the line only when you press
the RETURN key.
(This "random order" feature is not available on TTY
terminals. )
An APL line can contain up to 390 characters. This total includes
spaces and backspaces.
If you type more characters than the limit and
press RETURN, APL ignores the line and sends the error message:
48

INPUT LINE

TOO LONG

For a complete list of APL messages, refer to Appendix A.
NOTE
Backspacing is a method for positioning
the carriage, it does not cause characters to be erased or ignored by APL.
On an APL-keyboard terminal, if you discover an error in a line before
you press the RETURN key, you can backspace to the error and press the
LINEFEED key.
Everything from the LINEFEED to the right is ignored by
APL. You can then complete the line directly below the part in error
by retyping it.
For example:
Ci·· I f;:E:E: I VE:

backspace 4 then line feed

eErVE: I
C

f!;:ECEIVE

1-10

THE APL OPERATING ENVIRONMENT

There are several special characters available with which to make corrections.
Table 1-3 lists these characters and their meaning.
Table 1-3
Editing Characters
Character

Meaning

CTRL/C

Two CTRL/Cs interrupt APL function execution
and expression evaluation. Five CTRL/Cs return you to system command level.

CTRL/U

Deletes the current input line and positions
you in column one of the next line.
It does
not delete past the first LINEFEED it encounters. Echoes as XXX on TTYs and as ~~~
on LAs.

CTRL/O

Suppresses output to the terminal.

CTRL/R

Performs a LINEFEED and displays the corrected line starting at column one.

LINEFEED

In conjunction with backspace, it deletes
input.

DELETE (RUBOUT)

Deletes one character at a time. On an LA,
echoes one r character on TOPS-IO for entire
operation. Echoes one r character for every
character deleted.
The r prints as a \ on
a TTY.

1.5.2

Correcting a Line After Entering

An APL statement entered and processed in immediate mode can be edited
according to the same line-editing rules established for user-defined
functions.
These rules are described in Sections 6.3.7 and 6.3.8.

1-11

CHAPTER 2
LANGUAGE SYNTAX

2.1

INTRODUCTION

This chapter describes the syntax that governs the construction of APL
statements and expressions, including statement components, data types,
and expression evaluation.

2.1.1

Statement Execution Modes

Two execution modes are available in APL:
1.

Immediate mode, in which APL executes statements and expressions as soon as you enter them and press the RETURN key.

Function-execution mode, in which APL executes the statements
contained in a user-defined function (Chapter 6). APL enters
function-execution mode whenever it discovers a user-defined
function in the statement it is currently executing, and
exits from function-execution mode when the last statement in
the function is executed, you suspend the function, or an
error occurs.

The statement syntax is identical in both modes; however, there are a
few special characters that are not generally relevant in immediate
mode, but useful in function-definition mode.
These characters are
described in Chapter 6. Most of the examples in this chapter illustrate immediate-mode execution. Chapter 6 describes functiondefinition mode, in which you prepare and edit functions, and functionexecution mode, in which you actually execute the function.
In immediate mode, APL clearly differentiates between what you type
and what it prints. APL always indents six spaces before accepting
input. After you enter text, press the RETURN key to indicate that
entry is complete. APL processes your input and, if necessary, prints
results beginning at the left margin. After printing output, APL then
performs a carriage return/line feed and indents six spaces. For
example:
A~6

6
9
15

2-1

LANGUAGE SYNTAX

You can have up to 390 characters in a single line.
includes spaces and backspaces.

2.1.2

This count

Expression Components

An APL expression can consist of the following components:
1.

Identifiers
Variables, Section 2.1.2.1
Labels, Section 6.4.2
User-defined Functions, Chapter 6
Groups, Section 5.1.3.4

Constants
Numeric, Section 2.1.2.2
Character, Section 2.1.2.2

Characters
I/O Functions, Section 2.5
Primitive Scalar Functions, Section 3.2
Primitive Mixed Functions, Section 3.3
Extended Functions, Section 3.4
File Functions, Chapter 7
Operators, Section 3.5

System Variables, Section 4.2
System Functions, Section 4.3

2.1.2.1 Identifiers - An identifier can be a variable name, a label
name, or a user-defined function name.
It can consist of any number
of letters and digits; however, the first character must be a letter.
APL defines a letter, in this case, as any character A through Z, 4
through ~, ~ and~.
Only the first 31 characters of the identifier
are significant, and embedded spaces are not allowed. APL truncates
all identifiers to 31 characters; therefore, you cannot create an
identifier longer than 31 characters. For example:
Legal Identifiers

Illegal Identifiers

AX:CC63~8

lA C 75

674
(,)G956 H o

Z(l4 36
F'~742~

(does not begin with a letter)
(contains an embedded space)
(contains invalid character V)

Note that you cannot start an identifier with the characters S~ or
because of a conflict with the trace and stop vectors.
Refer to
Sections 6.4.5 and 6.4.6.

A variable must contain a value before you can reference it. Otherwise, you will receive the message 11 VALUE ERROR from APL. Section
2.1.5 describes how to assign values to variables.
Variable names and their positions have special meaning in functiondefinition mode.
Refer to Chapter 6 for this information.

2-2

LANGUAGE SYNTAX

2.1.2.2 constants - Constants can be either numeric or character data.
A numeric constant is one or more decimal digits with an optional
decimal point. A numeric constant can also be in exponential format;
an integer or decimal quantity followed by E and the power of ten by
which the quantity is to be multiplied. All of the following constants,
for example, are valid representations of the same value.

Wherever possible, APL prints numbers without decimal points and
exponents.
712 712.0 7120 E -1. 7.12 E 2
712 712 712 712

In APL, you represent a negative number by a numeric constant preceded
by a negative sign (-).
This sign is a distinctive symbol (uppercase
2).
It is not the same character as the minus sign (-) which is used
to indicate subtraction. On non-APL terminals, the negative sign is
.NG.
A character constant is one or more alphanumeric and/or special characters (including carriage returns and line feeds) enclosed in single
quotation marks.
For example:
'ABCDEFG'
'GEORGE'
'THIS IS A CONSTANT'

When APL prints a character constant, it omits the enclosing quotation
marks.
If you want APL to output quotation marks, type one extra
single quotation mark next to the one you want to print. For example:
B~'TONY'

'S TENNIS

RAC~UET'

TONY'S TENNIS

RAC~UET

Numeric and character data can be structured in a variety of ways.
APL supports the following types of data:
1.

scalars

vectors

matrices

arrays of three or more dimensions

2-3

LANGUAGE SYNTAX

A scalar is a single numeric or character value with no dimensions.
For example:
32

, ,
(.~

A vector is a I-dimensional array or character string consisting of
any number of values.
Enter a numeric vector as a list of values
separated by at least one space. For example:
H~··l
H

2 :3 4 5

1 2 3 4 5

In this example, H is defined as a vector whose elements are 1, 2, 3,
4, and 5. APL stores the values in the order in which you enter them.
A character vector or literal vector is entered as a string of character constants enclosed in single quotation marks.
Unless you want
the space character as part of the character vector, do not insert
spaces between characters in the vector. Note the following example:
A~'ABCDEFG

HIJKLMHOP'

ABCDEFG

HIJKLMHOP

Because any characters, including carriage returns and line feeds, can
be elements of a character constant, you can also enter several lines
of character data as a I-character vector.
For example:

Ai .. ' THIS

MUL T I PI... r:::

L.. I HE

L.. I Tt:::I:':AL.• '
A

THIS

:[5

MULT I PLr.-::

(.~

1._:[ HE

L I TE:F':('~L.•

Although there are several lines of text, A is still a vector.
Note that a common error occurs when you type a character constant
with an unbalanced number of quotation marks. APL thinks that you are
still defining the constant when you press RETURN to enter the line.
Consequently, APL includes the carriage return/line feed as part of
the constant.
You can spot this error by noticing that APL does not
indent six spaces when you press the RETURN.
Typing a single quotation
mark will usually get you out of this situation.

2-4

LANGUAGE SYNTAX

A matrix is a 2-dimensional array consisting of rows and columns. APL
supports the use of matrices as well as arrays of higher dimensions.
The rho character is used to ~reate and reshape arrays (Sections 3.3.18
and 3.3.15). You enter values corresponding to each element of an
array and also the shape or size of the array. The following examples
show array output.
(To input arrays, refer to Section 3.3.15.)
The following is a numeric matrix with 2 rows and 3 columns.
A

123
456

APL also supports arrays of three dimensions or more. For all practical purposes, there is no intrinsic limit on the number of dimensions
in an APL array. The only restriction is that the size of the array
cannot exceed your workspace size.
If you have unlimited memory available, the maximum number of dimensions allowed is 2*18.
The following is an example of a 3-dimensional character array. Note
that APL inserts a blank line between each plane greater than two.

A~'ABCDEFGHIJKLMNOPGRSTUVWXYZ'

2 3 4fA
ABeD
EFGH
IJKL
MNOP
GRST
UVWX

2.1.3

Spaces and Comments

Spaces are usually not significant in APL. Therefore, you need not
separate functions from constants or variables. This is also true on
non-APL-keyboard terminals. The mnemonics for operators need not be
preceded or followed by a space. The following expressions are equivalent:
35
+

-C

.TR B
35

.TRB
35

2-5

LANGUAGE SYNTAX

Spaces are also not required between a succession of functions or operators.
For example:

However, spaces must be included to separate names of adjacent userdefined functions, constants, and variables.
For example, they are
required when you are entering a series of numeric constants as a
vector.
The spaces included in the following example are necessary:
2 TFU G :3
x:' i·· 3 4 ~.:j

(user-defined function)
(numeric vector)

You can also use comments in APL.
Their use is particularly relevant
in function-definition mode.
Comments must appear on separate lines;
they may not be included on lines containing APL statements.
The first
character in a comment line is the lamp character (A), formed by overstriking the down union character (n) with the jot character (0).
Section 6.2.4 describes comment lines in greater detail and illustrates
their use in a variety of user-defined functions.
On non-APL-keyboard
terminals, use a double quotation mark for the comment character.

2.1.4

File Specifications

The complete form of a file specification is:
dev:filename.ext[directory]<prot>
where
dev:

is a device name, or a logical name you have
defined.
See Appendix D for defining logical
names.

filename

is one to six alphanumeric characters specifying
a particular file in the directory.

.ext or .typ

is one to three alphanumeric characterR identifying the contents of the file.

[directory]

is the project-programmer number of the owner of
the directory.
You can translate a directory
name on TOPS-20 to its corresponding projectprogrammer number by using the TRANSLATE command.
See Appendix D for this information.

<prot>

is a 3-digit octal protection code specifying
who can read and write the file.

2-6

LANGUAGE SYNTAX

You need not give the entire file specification in every case.
defaults are:
Argument

Default

dev:

DSK:

filename

No default; it must be specified

.ext or .typ

Depends on the type of file

[directory]

Your currently connected directory

<prot>

Installation-dependent

2.1.5

The

Statement Types

There are two general types of APL statements:
1.

Branches constructed with +

Assignments constructed with +

Branch statements restart a function and transfer control from one part
of a function to another.
These statements are most relevant in the
context of user-defined functions and are described in Section 6.4.1.
Assignment statements store one or more values into an identifier. The
general form of an assignment statement is illustrated by the following:

where 2+B is an APL expression
+ is the assignment function
A is a variable name
You can have more than one statement on a line by separating each with
a semicolon. Each statement separated must contain a value. For
example:
C~A+B;A~64;B~92

c
156

Assignment statements are, themselves, expressions and can be used in
the construction of other statements. The following example illustrates
a method of assigning values to more than one variable with a single
statement:

2-7

LANGUAGE SYNTAX

Here the value 7 is assigned to C, 11 to B, and 14 to A. The expression is evaluated from right to left according to the rule described in
Section 2.1.5.
In any mode, if you do not include an assignment or branch function in
an expression, APL prints the results on the terminal when the expression is executed. For example:

This type of expression has the effect of an implied print statement
in APL.

2.1.6

Evaluation of APL Statements and Expressions

APL evaluates unparenthesized statements and expressions in strict
right-to-left order, regardless of the particular functions in the
statement. Unlike some languages, which perform multiplication and
division before addition and subtraction, APL has no explicit function
precedence. For example, APL evaluates the expression
3x4+5

as 27, using right-to-left evaluation, rather than 17.
expression is interpreted as

Thus, the

3X(4+~;)

You can control the order in which individual functions are evaluated
by enclosing part of the expression within parentheses. To cause the
expression above to evaluate to 17, enter the following:

<:3X4)+5

APL evaluates this expression as 17 because 5 is added to the quantity
3x4, not simply to 4.

2-8

LANGUAGE SYNTAX

2.2

Number Precision

APL is a double-precision system with internal precision of about 18
decimal digits.
Numbers are represented internally in two ways.
1.

Integers less than 2 to the 35th power (2*35) are stored with
full precision.

Non-integers and integers larger than 2 to the 35th power are
carried out in floating-point format.

APL handles conversion between the two formats automatically.
Although you cannot control the internal
sentation, you do have some control over
The OPP variable, Section 4.2.15, allows
recision of non-inte ers.

Notice how APL outputs the numbers in these arrays:
2 2fL/\O
1. • 70:1. 4 :l.18~~!:)E:38
:L .7014 :1. 1835 JlJ:38

1. 70 141183!~jl:::38
j,. 7014118:3!::jF.~:38

Ai-2 2f 1
A

l. 1
1. :I.
f.~r:2;2]i"L/\O

f.lI

1 • OOOOOOOOOF.~O
1. .OOOOOOOOOE:O

:I..OOOOOOOOOEO
:1. + 70:1.4118:'5!5 E :38

f.~t·'2 21" 1
f.lI[1; :LJt.. 10llc6

1000000

:I.
1.

1
(.H·2 2f1
(-)[2;2]~":l.Ollc-'6

1
1

o • OOOOO:L
('=l[1; 1:H'10llc6
A

1..OOOOOOOOOE6
l.oOOOOOOOOOEO

1 .OOOOOOOOOIE:O
:I. • OOOOOOOOOE .... 6

2-9

LANGUAGE SYNTAX

'rhe range of numbers you can input without receiving an error (15
DOMAIN ERROR) are:
For integers
For non-integers

2*35 to (2*35)-1
.14693679E-38 to 1.70l4ll8E38

Note that Boolean is represented as 36 bits per word:
equal to 36pl.

2.3

(136)=136 is

ERROR HANDLING

When APL encounters an error, it prints three things:

~['he

an error message

the line in which the error occurred

a caret (A) approximately underneath the particular point at
which the error was discovered

following are examples of common error conditions:
Er{<3
AXEr

V('~L.LJJ:::

EJ=;:fl:OR

Axf.<
A

1'" 1 E<+2+3

SYN'TAN

Efl:fl:OJ=;:

1+1 E<+2+3
...\

1. 2+1 2 3 4
1.0

L.F.!:NG'TH

Efl:fl:Ofl:

1. 2 + 1 2 3 4
1\

In the first example, APL printed a value error because the variable
named A had not been assigned a value. The syntax error occurred
because an identifier cannot begin with a number (1B).
The length
error was a result of an unequal number of constants on either side of
t:he pI us sign.
Because APL is a highly interactive system, you can almost always
respond to an error condition simply by correcting the statement in
which the error occurred. This characteristic of the language also
aids the trial-and-error approach to program development.
In functionexecution mode, APL prints an error message, the function name, and
the line number of the statement at which it occurred. APL also suspends execution of the function.
You then have the options of terminating the suspended function, restarting it possibly at another statement, or debugging it before resuming execution. Chapter 6 describes
techniques for developing and executing functions.

2-10

LANGUAGE SYNTAX

2.4

ARRAY INDEXING AND COMPARISONS.

This section introduces the use of array indexing in APL and also the
use of "fuzz" in performing comparisons. Both of these concepts are
helpful in understanding the examples included in subsequent sections
of this chapter.

2.4.1

Indexing Arrays

The concept of using and entering values for arrays has already been
introduced in Section 2.1.2.2. To be able to access, individually,
the values of the elements stored in an array, you must know the positions of the elements within the array. These positions are known as
the indices. The procedure for accessing elements is called indexing.
The first position in an array (index origin) can be either 0 or 1.
You can set the index origin with system variable DIO, Section 4.2.11.
To index an array, specify the array followed by the indices enclosed
in square brackets, and separated with a semicolon. Each index must
be an integer scalar, or an expression that evaluates to an integer.
The number of indices needed to pinpoint an element depends on the
array type.
In general, you must specify as many indices as the number
of dimensions of the array. For a vector, a single index is sufficient
to identify the position of the desired element. A matrix, a 2dimensional array, requires two indices separated by semicolons; a
3-dimensional array requires three indices separated by semicolons;
and so forth.
For example, specifying:
A[lJ

accesses the first element stored in vector A.
vector shown below, then A[3] is 25.
A~"72

If A consists of the

91 25 46 87

(.~[]]

If the array is a matrix, specify two indices:
row and the second one for the column:
:e'f'2 4f' \ 8

1
~5

2
6

:'5
'7

4
8

2-11

the first one for the

LANGUAGE SYNTAX

Specifying the indices in the form of an array enables you to access
more than one element at a time.
For exanple:
44.6 71

A~32

.80 65 97.2

(.~

44~6

71 0.8 65 97.2

A[3 5 6]
'71 65 97.2
M~"2

4, \ 8

M
1
5

....

4
8

M[2;1]
c:·

..J
".) ,. '")
, .... 3]
M[:!. ....

2
6

3
7

The index can also be an expression which is evaluated to generate the
element positions.
It·2 4

22 31 49 56 68 72
V[I+1J
31. 56 68
v~10

Here V and I are both vectors.
The expression V[I] accesses the elements of V referenced by I:
that is, the third, fifth, and sixth
members of vector V.
Character arrays can also be indexed.

For example:

A~IABCDEFGHIJKLMNOPGRSTUVWXYZ

BABY~A[1.0

5 14 14 9 6 5 18 27 :!.2 25 14 27 13 28]

E<AB'y'
·JENNIFEf'; L'fH M.

Note that an element can be duplicated by specifying its position more
than once.
The array being indexed need not be a variable.
It can be
a constant set of values or an expression enclosed in parentheses.
For example:
7 6 5 4 3 2 1[2 4J
.;S 4

-4 16

2-12

LANGUAGE SYNTAX

You can omit a subscript from an index specification, but the semicolon must be included if only one array dimension is specified.
If
you omit the right subscript, all columns are selected from the matrix;
if you omit the left subscript, all rows are selected. For example:
A

3
6

2
5

4
7

AC1;]

1 2

A[;2 3]
2

6
9
1")
.:..

8
11

Note that a semicolon is required to indicate which subscript has been
omitted.
In general, the size of the result when a variable is indexed
is equal to the catenation of the sizes of all the indices.
For example, if Z+X[I1;I2;I3; ••• INJ then (pZ)=(pI1),(pI2),(pI3), ••• (pIN).

V~ ..

t AEfCItEF' t

V[3 5]
CE
AVECTOR INDEXED WITH A VECTOR
nRESULTS IN A VECTOR

V[6 5 4 3 2 1]
1:~EItCB~'

aVECTOR INDEXED WITH A MATRIX
ARESULTS IN A MATRIX
M~2

3'2 5 4 6 5 4

V[M]

AMATRIX INDEXED WITH TWO 2-DIMENSIONAL
nINDICES RESULTS IN A 4-DIMENSIDNAL ARRAY
M~"2 2fl 2 2 1
f.H .. M[M;M]
A

1
2
")

.:..

1
1

1
2

.:..

'')

.:..

2-13

LANGUAGE SYNTAX

f(~

2 2

'")

.:..

41'\6

Mf,2
M

'")

I:!'

4
2

3
1

A'"

•• J

A !;)CAL.A~:
A~.. M[

~:ESULT

1; 1.:]

1
ANUL.L.

A~:~:A'y'

f(.~

(APL outputs a blank line)
At-ELEMENT

VECTORS

B~.. , M[ 1; :I.]
B2 ... M [ , 1 ; :I. ]

:I.
1:'2

:I.
fB

:L
ff.'2

:I.
A 2 .... E L.EME:NT

VECTOr.:

CH·ir: ;2]

c
2 6

rC
2
A(.~

2·.. ·1:'·(·· .. 1.

MAT~:I ~.~

D •.. M[ ; ,2]
l)

~.~

6
1'1)

2 1

You can also use indexing to change values of elements already stored
in an array.
For example:

(.~

1
-4

3
6

c:'
•• 1

(.~

r.: 1. ; ~.~ 3]"'7 8

{.~r:

2; 1

2]~"9

(.:-,

2-14

LANGUAGE SYNTAX

A[1;lJ~12

7
9

12
9

8
6

A[l;l

1J~2

2.4.2

8
6

The Index Origin

In APL, the first position of a value stored in an array is called the
index origin. You have the option of beginning the indices of an array
at either 1 or O. For example, if the index origin is 1, then members
of a vector named A would be numbered A[l], A[2], A[3], and so forth.
If the index origin is 0, elements begin at A[O], A[l], A[2J, and so
forth.
The default index origin in a clear workspace is 1, but you can change
this setting to 0 or reset it to 1 with the DID variable (Section
4.2.11).
The index origin setting is saved when you save your workspace.
Refer to the )SAVE command, Section 5.2.4.
The value of the index origin is often used in conjunction with several
monadic and dyadic functions.
Chapter 3 discusses the index origin in
that context.

2.4.3

Comparison Tolerance or Fuzz

APL handles the problem of performing decimal arithmetic on a binary
machine with a concept known as fuzz.
When two non-integer numbers
are compared, for example, 7.913 and 8.019, they are considered equal
if the difference between them is within a certain range.
This range
is referred to as the comparison tolerance or the fuzz quantity.
There are two types of fuzz:
1.

Absolute fuzz - which is the tolerance used to determine
whether or not a decimal number is close enough to an integer
in value to be considered an integer.

Relative fuzz - which is the tolerance used when comparing
two numbers to determine whether or not they are close enough
to be considered equal.

The absolute fuzz in this version of APL is approximately lE-7.
This
setting cannot be changed. The default relative fuzz is lE-13 in a
clear workspace. You can change the relative fuzz in your active workspace by assigning a new value to the OCT variable, Section 4.2.7.
The relative fuzz setting is saved when you save your active workspace.
The following functions use OCT when making comparisons:
~, ~, AlB, AEB, LA, ALB, rA, ArB.

2-15

LANGUAGE SYNTAX

2.5

TERMINAL I/O OPERATIONS

APL provides you with utilities to ease input and output operations on
a variety of s stem devices. This section describes terminal input
and ou ute

There are several methods of input and output as illustrated by Table
2-1.
Table 2-1
Input/Output Functions
Meaning

Expression

Section

Quad (evaluated) input

2.5.1

Quote-Quad (character) input

2.5.2

Quad-Del (unedited) input

2.5.3

Normal output

2.5.5

A;B;C

Mixed output

2.5.6

O+-A

Quad output

2.5.5

[!J+-A

Bare output (Quote-Quad)

2.5.7

IYl+A

Bare output (Quad-Del)

2.5.7

A+-O

All terminal I/O, except normal and mixed output, use the 0 symbol.
All forms of I/O can be use (:1 in either immediat~mode or function-

··~.~i:~.~~~~i·\'\~i;~i~:~;: .'

;j;;~:~'~~i;~~~t~~~:f~::;:~\r;~~~:t~;:~~~;~:~!~~f~~~~:~~

forms of the quad function.

2-16

LANGUAGE SYNTAX

Evaluated Input Mode-Quad Input (0 or .BX)

2.5.1

The most basic form of quad input is called evaluated input.
In this
mode, the statement you enter at the terminal, in response to the 0
input request, is evaluated and its value is returned as the result of
the 0 input function.
By placing a 0 to the right of a back arrow in
an expression, you signal APL to expect data input from the terminal.
Normally, APL prompts you by printing 0: in the left margin. You can
change the prompt with the OSF system variable (Section 4.2.18). Any
character data input must be enclosed in single quotation marks. Otherwise, it will be considered an APL expression. For example:

0:
5

0:
A

0:
'NO OPERATOR'
MSG
NO OPERATOR

While the system is awaiting your input, you can enter and execute a
system command, evaluate an expression, or define a function.
The
input request remains pending.
If an error is encountered in the
input, APL prints the appropriate message and allows you to reenter
the input.
If you enter a carriage return or spaces and a carriage
return, APL again prints the 0: prompt and waits for input.
The prompt signal (0:) is the default.
variable, Section 4.2.18.

You can change it with the OSF

2.5.2

Character Input Mode-Quote-Quad

or .QQ)

APL has another version of the quad function especially for input of
character data, the quote-quad function (~). An example of quotequad mode is shown below:
x~~

THAT'S AMAZING

x
THAT'S AMAZING

2-17

LANGUAGE SYNTAX

Unlike evaluated input, quote-quad input allows you to enter character
strings without enclosing them in single quotation marks. Note that
APL does not print the 0: prompt in quote-quad mode.
When APL encounters a ~ symbol, it positions the carriage at the left
margin and accepts the data up to the next carriage return as a character variable.
If you enter a single character, APL treats it as a
character scalar; it stores a string of characters as a character vector.
If you enter only a carriage return, APL treats this input as a
vector of length zero; this treatment is significantly different from
the handling of empty input in quad-input mode, in which APL rejects
the input and waits for you to reenter it correctly.
If you enter a
tab, APL converts it into the equivalent number of spaces accomplished
by the tab.
Note that you cannot enter and execute system commands or define function during ~ input.

2.5.3

Unedited Input Mode-Quad-Del

or .QD)

APL has a third version of the quad function, the quad-del function
(~).
The quad-del function allows you to enter special characters,
including backspace, without having APL evaluate them.
The backspace
is treated as' a separate character, and an overstrike symbol is not
created.
APL counts each character you input in quad-del mode.
The length of
the expression includes any spaces and backspaces.
(A tab is treated
as one character.)
The following example illustrates the difference
between quad-del and quote-quad modes in entering overstruck APL charac·ters.
The example uses the transpose function (Q) which takes an
array and transposes its values (Section 3.3.20).
To input this function, type 0, press BACKSPACE, and type \.
The result of the shape
function (p), (Section 3.3.18), prints the number of characters in the
array.

ATHE

BACKSPACE

COUNTED AS

A CHARACTER.

4
AIN

~OUTE-~UADy

THE

BACKSPACE

NOT

COUNTED.

2
AIN

SINGLE

OUOTES y

NOT

fl~A'

2-18

COUNTED

EITHER.

LANGUAGE SYNTAX

The following example shows the particular use of quad-del mode in
accepting input from non-APL-keyboard terminals.
The mnemonics are
not decoded .

• ROB
.ROA
4

.ROB
.ROA
2

.RO'.ROB'
2

As in quote-quad input mode, if you enter only a carriage return or
spaces followed by a carriage return, APL treats this input as a null
vector of length zero.

2.5.4

Escaping From Input Mode

To escape from an input request, you have certain escape options depending on the input mode:
In quad-input mode, type a right arrow
In quote-quad
follows:

(~)

or quad-del

(~)

input mode, type OUT

a backspace U backspace T
or
On non-APL-keyboard terminals, type .OU
Each of these methods causes function execution to be interrupted but
does not cause an exit from the function.
Refer to Chapter 6 for
information on function-execution mode.

2.5.5

Normal and Quad Output Modes

In normal output mode, to display output on the terminal, type an
expression or an identifier without an assignment function (+) or
branch function (~) as the leftmost character.
The result of the
expression prints on the terminal.
For example:
A

64*3

262144

17+A

2-19

LANGUAGE SYNTAX

If the quad symbol appears immediately to the left of an assignment
function (+), the result of the expression to the right of the +
prints on the terminal. This is called quad output. For example:
O~A

Note that using quad output has the same effect as in the previous
example of merely typing the variable name A. Quad output is especially helpful when an APL statement contains mUltiple assignments.
For example:

This statement performs the computation and displays the desired output - the result of the computation 5x4. Thls method is more efficient
than the following:
B~5x4

If the last operation (the leftmost expression) in an expression is an
assignment or branch, then no final output is produced. The following
will not cause output to be printed:

The following will:

When APL outputs an array, and a row cannot fit on a single line, the
remainder of the line prints on the following line, indented six
spaces. For example:

t 50
3 4 J 6 / 8 9 10 1 1 12 13 14 15 16 1 / 18 19
20 21 22 23 24 25 26 27 28 29 30 31 32 33
34 35 36 37 38 39 40 41 42 43 44 45 46 47
48 49 50
~

To provide more room on a line you can alter the page width with the
DPW system variable. Refer to Section 4.2.16 for this information.

2-20

LANGUAGE SYNTAX

2.5.6

Mixed Output Mode

Mixed output mode allows you to print character data and numeric data
on the same line. You request mixed output by entering a series of
values or expressions, separated by semicolons, in the order in which
they are to appear. The output displayed contains no carriage returns
or spaces, except where required by the data.
Although APL evaluates from right to left, it prints items from left
to right.
If you display two expressions separated by a semicolon,
APL will not put a space between them.
You must specify a space if
you want one. For example:

1+1,2+2
:I.+1il'

'y2+2

2 4

In the first part of the next example, APL reports a value error
because no value is assigned to B.
In the second part, B is assigned
the value first.
:I. + x:' y'
:1.:1.

V('~LUI:::

'j) x:'

EHI:;:OI:;:

:I. + x:' j)'

l+ X:'y'

'il x:'
'VY::(~··1

2 :I.

APL will not print a value if the leftmost expression on a line is an
assignment or branch operation. You can get around this by enclosing
the assignment within parentheses. Note the following examples:

THE

'THE VALUE OF A IS 25'
VALUE OF A IS 25
A~5y

'NOTHING WILL

(A~'THIS

THIS l-IJ:I:L..I... PI:;:INT

I ) ; 'WILL
~~EC('~l.!!:;I:::

PRINT BECAUSE OF THE ARROW'
PRINT BECAUSE OF THE PARENTHESES'
OF THI::: 1::·(.~t=;:ENTHE!:;E·::;

Another way of printing the leftmost expression containing an assignment or branch, is to precede the statement with a semicolon:

2-21

LANGUAGE SYNTAX

Although the semicolon is considered a statement separator, each expression in the list must return a value. For example, if F is a userdefined function that does not return an explicit result (regardless
of the number of arguments F requires), the construct 'iFi' returns
an 11 VALUE ERROR.

t::2J

£::~::I

'"l

THEI:::E I

:1. YF~) 2
HI

THI,,:I:::E

THEI:::E

:I.:/. v (.~ I... U E I,,: ,::: ,::: 0 I:;:
:1. y F p 2

2.5.7

Bare Output Mode (Quote-Quad

or Quad-Del

Bare output is a special mode that allows you to request input on the
same line as an output string.
Like quad output mode, if you place a quote-quad or a quad-del to the
left of an assignment function, the expression to the right of the
function prints on the terminal. However, unlike quad output, APL
does not perform a carriage return/line feed at the end of the output.
Note the difference in the following example:
(.~ ~"I~I Y (] ~"

ENTEF;;
II:::ENE

','01..11:;;

'E:: H T Ii:: ,:;:

YOU I::: H (.~ /VI E

N('~ME

(.~

Notice that the value input is preceded by a number of spaces equal to
the length of the ~ output.
If the last character of a character constant to be output is a
comment (lamp) character A, APL suppresses the printing of the A as
well as the usual delimiting carriage return/line feed, thus, leaving
the carriage in mid-line. This feature is useful for entering input
on the same line as the previous output. For example:
YOUR
ROSE

A~M;O~IEHTER

EN'fER

YOUR

NAME

(.)

In immediate mode, bare output is the same as normal output. A bare
output statement such as ~+A must be followed by an input entry at
the terminal.
Thus, in this instance, output is concluded by the
conventional carriage return/line feed.
Bare output is more appropriate in function-execution mode.
Refer to Chapter 6 for more information on functions.

2-22

CHAPTER 3
APL FUNCTIONS AND OPERATORS

3.1

INTRODUCTION

APL provides several characters, known as functions and operators,
that allow you to perform various operations with numeric data and
character data. These functions and operators are grouped as follows
within this chapter:
1.

Primitive Scalar functions - arithmetic, relational, and
logical, Section 3.2

Primitive Mixed functions - for extensive array manipulation,
Section 3.3

Operators - more than one function in the syntax, Section 3.5

Functions are either monadic or dyadic. A monadic function requires
only one argument placed immediately to the right of it. A dyadic
operator requires two arguments, with the function placed between
them.
Depending on the function, arguments can be variables, numbers,
character strings, or expressions.
Functions are also classified as either scalar or mixed. A scalar
function generally takes a single-value argument and returns a singlevalue result. However, scalar functions can also be used with vectors
and arrays where they operate on an element-by-element basis. A mixed
function can take a scalar argument and return a result in the form of
a vector or an array, or take a vector or array argument and return a
scalar result.
Therefore, the result of a mixed function is not as
apparent as a scalar function.
Both scalar and mixed functions can be either monadic or dyadic. With
a scalar monadic function, the shape of the argument determines the
shape of the result. For example, a scalar argument returns a scalar
result; a vector argument returns a vector result, and so forth.
When
using scalar dyadic functions, you must specify arguments that have
the same number of elements and, if arrays, the same dimensions.
Table 3-1 shows the results achieved by specifying certain arguments
to scalar dyadic functions.
An operator is a function that takes another function as its argument.
APL operators are described in Section 3.5.

3-1

APL FUNCTIONS AND OPERATORS

Table 3-1
Results of Scalar Dyadic Functions

3.2

Argument

Function

Argument

Result

scalar

vector

scalar

vector

scalar

matrix

scalar

matrix

PRIMITIVE SCALAR FUNCTIONS

The primitive scalar functions are the arithmetic, relational, and
logical functions.
They are used primarily for basic arithmetic and
logical operations, such as addition, exponentiation, maximum value,
and logical OR. With a few exceptions, primitive scalar functions
1:ake numeric scalar arguments. The relational functions (~,~,<,>,=,~)
can take either character or numeric arguments but only the equal (=)
and the not equal (~) primitives can take both character and numeric
arguments in the same expression. The logical functions (A,V,~,~,~)
must have arguments that are equal to 0 or 1 within a tolerance of
lE-7, the absolute comparison tolerance that APL uses (Section 2.4.3)
Table 3-2 summarizes the primitive scalar functions available in this
version of APL. Most of the functions are straightforward and familiar
arithmetic or logical operations.

3-2

APL FUNCTIONS AND OPERATORS

Table 3-2
Primitive Scalar Functions
Dyadic

Monadic
Function

Meaning

Function

Meaning

X+Y

Add X to Y

-Y

Negative of Y

X-Y

Subtract Y from X

sign of y 1

XxY

Multiply X and Y

Reciprocal of Y

XfY

Divide X by Y

X*Y

X to the Yth power

Magnitude of Y

X!Y

X residue of Y (see
primitive mixed
operators)

Ceiling of Y

xrY

Maximum of X and Y

Floor of Y

xLY

Minimum of X and Y

Natural logarithm of Y

X~Y

Log of Y to the
base X

Factorial of Y

X!Y

Binomial coefficient (number of
combinations of Y
things taken X at
a time)

A random integer of lY

X?Y

X number of random

to the Yth power

integers in the
range 1 through Y
OY

IDefinition:

xoY

Pi times Y

XY is -1 if Y<O
XY is 0 if Y=o
xY is 1 if Y>O

3-3

Trigonometric
functions (Y is in
radians.
See Table
3-3)

APL FUNCTIONS AND OPERATORS

Table 3-3 lists the values 0 through 7 and 0 through -7 that are
needed as the left argument to the circle function (0) in order to
perform trigonometric functions.
The right argument, a scalar or
vector, is expressed in radians.
Table 3-3
The Dyadic Circle Function
Expression

Result

Expression

Result

OOX

(1-X*2)*.5

lOX

sine X

-lOX

arcsin X

20X

cosine X

-20X

arccos X

30X

tangent X

~30X

arctan X

40X

(1+X*2)*.5

-40X

(-1+X*2)*.5

50X

sinh X

-50X

arcsinh X

60X

cosh X

-60X

arccosh X

70X

tanh X

-70X

arc tanh X

The following examples illustrate ways in which primitive scalar
functions can be extended to arrays:
A~3
A

6
2

3r5 6 8 3 2 1 6 4 2

8
:I.

642
AELEMENT-BY-ELEMENT
e~

MULTIPLICATION

x (.~

:;.~ ~:.:j

<;>

4
16

1
4

:1.2

'")

:1.2

2x(.~

:1.6
",',.

2~0 :I. 2 3 4 5 6 7 8
:I. 2 4 8 :1.6 32 64 :1.28 256

<;>

1.6

2~":j

~56*0.~":;

234!~;,~)

3-4

APL FUNCTIONS AND OPERATORS

3.2.1

Relational Functions

In APL, the relational functions (~,~,<,>,=,~) return results; they
are not simply comparison functions.
An expression of the form A~B
yields the result of 1 if true (A is less than or equal to B), and 0
if false.
For example:
9>6

1
4>6

o
1

These functions can take either numeric or character arguments, but
only the equal and not equal functions can have mismatched arguments,
that is, one numeric and one character argument simultaneously. For
example:

When you use relational functions with Boolean arguments (0 and 1),
the relational functions can perform logical operations. For example,
the not equal (~) function performs an exclusive OR operation if its
arguments are Os and Is:

0110
0011~0101

3-5

APL FUNCTIONS AND OPERATORS

3.2.2

Logical Functions

The following table is a truth table that describes the results of
logical operations:
Table 3-4
Truth Table
Arguments

Functions
AND
-

-OR

NAND
-

NOR
-

XAY

XvY

X1<Y

X¥Y

NOT
-

"'X

3-6

APL FUNCTIONS AND OPERATORS

I or .AB - The Residue Function

3.2.3
Format

dyadic
Argument Types
Both arguments can be either scalars or vectors and either
integer or noninteger.
Definition
Obtains the remainder or residue of a number.
The residue is a
unique number whose value is in the range between the value of
the left argument and zero.
It is obtained by adding or subtracting multiples of the left argument from the right argument.
For example, for positive arguments, the remainder is obtained
by dividing right arguments from left arguments.
The result of
a residue operation has the same sign as the sign of the left
argument.
The formal definition of the residue function is as follows:

AlB IS B-AxLB7 A+A=O

If the left and right arguments are equal, the residue is O.
If
the left argument is 0, then the residue is equal to the value of
the right argument.
If the left argument is not 0, then the residue is in the range
of the left argument through 0; it may equal 0 but not equal the
value of the left argument.

3-7

APL FUNCTIONS AND OPERATORS

Examples
~.:j I B

·..·::517
·..·3

717

710

017
7

:t B
I::'

.::.

r.:'
..!

c'
..!

I ")

::.:j I ",:")..

-.J

•• J

IB B

3 3
~~~

2 2

.,'0.

A',.

Related Functions
None

3-8

APL FUNCTIONS AND OPERATORS

? - The Roll Function

3.2.4
Format

monadic
Argument Types
The argument is an array of positive integers.
Definition
Generates an array of independent random integers.
Each element
is in the range 0 or 1 (depending on DIO) to the value of the
corresponding element in the argument.
There may be duplicate
values.
Roll also changes DRL.
See Section 4.2.17.
The term "roll" relates to the analogy between the operation
performed by this function and the rolling of several dice.
Examples
:1.0 :/, ~:5 20
:1.4 B
'i) ~::j :/, () :I.::,:; 20
l) :I. :3 :~~ 2:1.
I!)~)

."),',. 6
I::'
'.. J

;.~ !~j

A', •

(.~~"2

~~ !:.)

31" \ (.)

(.~

::.~

I~'

(.)
'i)(.~

:I.

•..

.::'
"J

:I.
4

:-5
4

,/(

'i)(.~

......

1'0',.

"')

.,'0.
?(.~

:1,

:t.

:-5

:';~

.")
.:..
4

Related Functions
Deal, Section 3.3.3
Deal differs from roll in that deal generates a set of random
numbers in which no number is selected twice.

3-9

APL FUNCTIONS AND OPERATORS

3Q3

PRIMITIVE MIXED FUNCTIONS

Unlike the primitive scalar functions discussed in the previous
sections, the functions presented in the following sections are
considered primitive mixed functions.
Scalar functions usually take
scalar arguments, return scalar results, and are extended to arrays
on an element-by-element basis. Primitive mixed functions, however,
can take vector arguments and return scalar or vector results, or can
take scalar arguments and return vector results.
In expressing primitive mixed functions for arrays of higher rank, you may need to specify the particular coordinate of the array to which the function applies.
The primitive mixed functions provide the capability of extensive
array manipulation.
Table 3-5 lists the primitive mixed functions available in this
version of APL. The operators are also listed.

Table 3-5
Primitive Mixed Functions
Function

Section

X,Y

3.3.1

Meaning
Catenate X to Y along the last dimension of
X

X/Y

3.3.2

X (logical) compression along the last
dimension of Y

X/[N]Y

3.3.2

X (logical) compression along the Nth
dimension of Y

XfY

3.3.2

X (logical) compression along the first
dimension of Y

X?Y

3.3.3

Deal X integers selected randomly in range
1 through Y without duplication

X.tY

3.3.4

Decode the representation of Y in number
system X

X-I-Y

3.3.5

For X>O, drop first X elements of Y - for
X<O, drop last lx elements of Y

XTY

3.3.6

Encode Y in number system X

X\Y

3.3.7

x (logical) expansion along the last
dimension Y

X\[N]Y

3.3.7

X (logical) expansion along the Nth
dimension of Y

3.3.7

x (logical) expansion along the first
dimension of Y

3.3.8

Generate an index vector such that X[wy]
is in descending order

3-10

APL FUNCTIONS AND OPERATORS

Table 3-5 (Cont.)
Primitive Mixed Functions
Function

Section

Meaning

X!Y

3.3.9

Generate an index vector such that X[!Y]
is in ascending order

3.3.10

Generate the first Y consecutive integers
from current origin

X1Y

3.3.11

Find the first occurrence of Y in vector X

X, [N]Y

3.3.12

Laminate X to Y along the Nth dimension of
X

3.3.13

Determine the membership of X in array Y

3.3.14

Return the ravel of Y (make Y a vector)

<t>Y

3.3.16

Reverse along the last dimension of Y

<t>[N]Y

3.3.16

Reverse along the Nth dimension of Y

3.3.16

Reverse along the first dimension of Y

3.3.18

Return the shape of X

XpY

3.3.15

Reshape Y to make dimension X

X<t>Y

3.3.16

Rotate by X along the last dimension of X

X<t>[N]Y

3.3.16

Rotate by X along the Nth dimension of Y

XeY

3.3.16

Rotate by X along the first dimension of Y

XtY

3.3.19

For

3.3.20

Transpose the dimensions of Y (for a
matrix, exchange the rows and columns)

3.3.21

Transpose array Y according to X

X~y

X>O~ take first X elements of Y - for
X<o, take last lx elements of Y

3-11

APL FUNCTIONS AND OPERATORS

, - The Catenate Function

3.3.1
Format

dyadic
Argument Types
scalars, vectors, or arrays
Both arguments can be either numeric or character data.
Definition
Chains two scalar or vectors to form a new vector. Catenation
joins constants or variables along an existing dimension. Any
number of items can be catenated. The order in which values are
catenated is the order in which you specify them in the APL
statement. Actually, the value(s) of the argument to the right
of the catenate function is appended to the value(s) of the
argument to the left of the function.
The result of a catenation can be formally expressed as follows:
if pA is 5 and pB is 3, then pR+A,B is 8, R[15] is A and R[5+13]
is B.
You can also catenate literals. APL does not allow you to
catenate numbers to characters and vice versa.
If you attempt
this, you will receive a 15 DOMAIN ERROR.
The catenate function also allows you to join multidimensional
arrays along an existing coordinate as long as they have the same
length over the other dimensions. You include the coordinate
within square brackets along with the right argument of the
catenate specification. For example, A,[1]B. The coordinate is
1 for first dimension (row), 2 for second dimension (column), and
so forth.
You can also catenate constants to an array or matrix.
If you do
not specify the coordinate, APL assumes the highest rank of the
array being catenated, that is, the last dimension. See examples.
When catenating arrays, you must follow two general rules:
1.

Using the expression A,[K]B, if the arrays have equal rank
«ppA)=ppB), then K must be in tppA and pA must equal pB
except in the Kth dimension.
This is illustrated in the
following:
fA
345
365
R~A,[2JB

3 10 5

Here A is equal to R[;14;] and B to R[;4+16;].

3-12

APL FUNCTIONS AND OPERATORS

If the arrays have different rank (ppA)~ppB) then one of the
arguments must be a scalar (1=I(ppA)-ppB), and pB must equal
pA without its Kth coordinate.
This is shown below:

:3 4 .::.,.J
fEe

4 5
f::~ .. (.~ y

£::1. JI-:<

f F::

Here, A is equal to R[13;;] and B to R[4;;].
Examples
The following example catenates two vectors to each other and to
several scalar values:
(.~ ~ .. ~.)

r':<~"l

1::'
~J

D 9

, 1,.:<

B (?
B

t2
B :1.2

:l.Oy(.~,E<,

10 :::j B 9 l

• N (.~ ME' ,

(.~~··2

E'~"2
H

:I.
4

2
::5

~-: y

3ft ") :3 4 ::) 6
:3fl B ') :1. 0 :/. :I. :1.2
II....

3
6
1:'

l
10

:1.:1.

9
:1.2

(.~ y

[t]B

,.,

:/.

J
t>
9
:/,2

,.':.

-4
l

0::'

:to

:1.:1.

,.J

(.:\ y [2]X-:<

J
6

:I.
-4

A',.

I::'
,.J

,.,

:I.
4

.....:.

".7

0::'

-.!

".7
:1.0

:1.:1.

9
:1.2

(.~ Y [:1.]/

:3
6
""/
(.~ y /

1
-4

...)
A',.

~:.:j

3
6

l
/

3-13

APL FUNCTIONS AND OPERATORS

>~ ·t·· ::.~

3rB ?

Y~"2

:::~fO

:3 <;> 4

1 2

~< !I [:I,::I'r'

'7
4

:J.

::~

-4

"'I

\,'

-4

n
......

y 'y'

0
:3

:J.

-4

....:.

Related Functions
Laminate, Section 3.3.12
Ravel, Section 3.3.14

3-14

APL FUNCTIONS AND OPERATORS

/ and f - The Compression Function

3.3.2
Format

dyadic
Argument Types
The right argument can be a scalar or any array. The left
argument must be the scalar argument 0 or 1, or a Boolean vector
(a vector containing only Os and Is).
Definition
Builds a new vector or array from an old one by specifying the
elements to be deleted and the elements to be preserved.
For
example:
A~5

B~1

n.1 11 13
101 0

5 7 11

Elements in A whose positions correspond to the positions of
nonzero elements of B are preserved; elements corresponding to
zeros in B are dropped.
If B contains only Is, all elements of
A are preserved; if B contains only Os, the result is an empty
vector.
The lengths of both arguments, for example A and B, must generally
be the same. However, if A is of length 1, it will automatically
be extended to the length of Bi if B is of length 1, it will be
extended to the length of A. Thus:
A~5
B~l

7 9 11 13
1 0 1 0

B/5
~

9 11 13

l/A
J

O/A

(APL outputs a blank line)
The expression a/A produces an empty vector because all elements
of A are dropped.
You can also compress arrays by specifying, within square brackets,
the coordinate to be compressed.
(The coordinate is dependent
upon the index origin, Section 4.2.11.)
For a matrix, compression along the first coordinate can cause certain rows to be
omittedi compression along the second coordinate can cause columns
to be dropped. The result in all cases is a matrix.

3-15

APL FUNCTIONS AND OPERATORS

If you omit the coordinate in square brackets, APL compresses the
highest-ranking coordinate of the array. By specifying the
special compression symbol f (.CS) without including a coordinate,
APL compresses the first coordinate.
Examples
(.)i··3

4r \ 1:2

(.)

::.~

r.:'
,.1

(.)

:3
?

:1.0

:1.:1.

:1.2

10:1./[1](.)
23-4

:1.0

:1.:1.

1 () :I. () / I:: 2 ] (.~
3

...}

::.:j

:1.1
f(O/(.~)

~< ~ :::.~

3.1-' \ (~)

1
-4

::~

!:.:;

(.)

c:.

,.1

~~
(.)

:1.

()

:I.

1/:<

:I. 0/;<
3

Related Functions
Expansion, Section 3.3.7

3-16

APL FUNCTIONS AND OPERATORS

3.3.3

? -

The Deal Function

Format
dyadic
Argument Types
Both arguments must be positive scalars or single-element vectors.
Definition
Generates a vector of integers randomly selected from the right
argument vector without selecting any number more than once.
The length of the vector produced by the operation is specified
by the left argument. You can set the seed of the pseudorandom-number generator with the ORL system variable, Section
4.2.17. Every time you use the deal function, ?, you change ORL.
Examples
515
13524
511.0E7
6595053 6514970 5824656 4389382 7540976
511.0 E 7
2010075 9444312 5995397 3627744 3545552
511.0E7
5923563 4257710 6323814 5360300 2709926

Related Functions
Roll, Section 3.2.3
Unlike the roll function, deal is like dealing a number of cards
from a deck with no two cards alike.
Roll is like rolling
several dice independently.
Roll may generate duplicates but
deal will not.

3-17

APL FUNCTIONS AND OPERATORS

3.3.4

or .DE - The Decode Function

Format
dyadic
Argument Types
scalars, vectors, or arrays
Definition
Reduces a representation in a number system to a value.
It is
the converse of the encode function (T); equivalent examples of
the two functions as they operate on a quantity expressed in
yards, feet, and inches, are shown below:
1760 3 12y63
123
1760 3

12~1

2 3

The expressions ATB and ALB differ only in the value included in
B; A expresses the number base in both cases.
The number of elements in both arguments, for example A and B,
must generally be the same; the first element in A expresses the
base in which the first element in B is decoded, and so on.
However, if A is a scalar or a single-element array, it is
extended so that its length is the same as that of B.
For
example, the following expression has the effect of producing the
base 10 value of the base 8 number 3777 (octal to decimal
conversion) .
8~3

7 7 7

2047

You can also specify the decode function with multidimensional
arrays.
The expression ALB is equal to W+.XB where W is the
weighting vector given by the expression W[pA]
1 and W[(-N)+pA]
is equal to A[C-N)+1pA]xW[(-N)+1+pA]. The value of A[1] is
irrelevant.
The arrays you specify as arguments must conform to the following
rules using A and B as arguments:
1.

A or B is a scalar.

The results of -1tpA and 1tpB are equal.

3-18

APL FUNCTIONS AND OPERATORS

Examples
ACOHVEf':TS

1 :·5 1 2

.1.

:-5

Yr.o~;;.

2 FT.

-4

:I:NCHE~:;

IHCHE~:;

3 2 4

:L56
AIS

2.5

2 + ~.:.i ..l.l.> .....?

A ZERO OF

THE

POLYNOMIAL

6X*2-7X-20

····:;.~O

ABASE-10 EaUIVALEHT
5.1.4 3 4

BASE-5

NUMBER

Related Functions
Encode, Section 3.3.6
Inner Product, Section 3.4.1
The decode function can be viewed as a form of the inner product
operator. The following example illustrates two equivalent
operations:
(.~ i·· :1. ? i~; ()
I-:<~··l

:1. 2

{l.A. X,<
1

·:r

\.) .... 1

3-19

APL FUNCTIONS AND OPERATORS

+ or .DA - The Drop Function

383.5
Format

dyadic
Argument Types
The right argument must be an array.
In most cases, the left
argument must be a scalar; it can be a vector if the right
argument is a multidimensional array.
Definition
Builds a new vector or array by dropping a specified number of
elements from an existing array. For example:
O~V~l5

1 234 5
O~x~2~v

345

The expression drops the first two elements of V and forms a new
vector with the remaining elements.
If the value of the scalar
is greater than the number of elements in V, then the result is
the null vector.
The drop function handles negative scalar values by dropping the
elements from the end of the array instead of from the beginning.
For example:

123

You can also specify multidimensional arrays with the drop function.
In this case, the left argument must be a vector containing one element for each dimension of the array.
In the
expression, S+V, the value of S[lJ indicates the number of
elements to be dropped along the first coordinate of V, and so
on.

3-20

APL FUNCTIONS AND OPERATORS

Examples
~.) J-' \ :I. ~:)

[f~ .. (.~ ~"::5

:I.

6
1:1.

"1
12

:1. :~

:I. ~:)

.... j,

!::j

<;>

:to

1.4

1. ~)

:1.

~:.)

3.J.-(.~

3-J.·(.~

Related Functions
Take, Section 3.3.19

3-21

APL FUNCTIONS AND OPERATORS

3.3.6

T or .EN -

The Encode Function

Format
dyadic
Argument Types
The right argument identifies the scalar or array to be translated.
The left argument is a vector that represents the number
base in which the value is to be expressed.
The vector contains
one element for each column ~epresentation.
Definition
Represents a scalar or an array in any number system. For
example, to encode the decimal value 7 in four columns of binary
representation, the following expression can be specified:

o :J.

:1.

You can also specify mixed bases for the number to be represented.
The encode function can express some number of inches in miles,
yards, feet, and inches; or some number of milliseconds in days,
hours, minutes, seconds, and milliseconds.
The following examples
illustrate these two situations:
nMILESy

-4

~)46

FEET~

INCHES

~:.'j

RDAYS~

~:J

YARDS~

o 1760 3 12y273125
HOURS y

MINUTES,

SECONDS y MILLISECONDS

o 24 60 60 :J.000y719732523
!.:.:; !::j

:.~ ::.~

!!,) ::.~ ::~

In the expression ATB, A can be considered as the representation
rule to be applied by B. Each element of the vector A is defined
in terms of the element immediately to its left. Thus, in
encoding a number as miles, yards, feet, and inches, the following elements are specified from right to left:
1.

12 inches in 1 foot

3 feet in 1 yard

1760 yards in 1 mile

In the previous example, a miles specification is not defined in
terms of another quantity, so 0 is printed in the miles column.

3-22

APL FUNCTIONS AND OPERATORS

The following examples of base 3 conversions demonstrate the
specification of different numbers of columns in the rule vector
and illustrate the way in which negative numbers are encoded:

2 2

:/. () :I.

Another useful application of encode is to return the integer and
fractional portions of a number:

:1, '1"::<

()

You can also specify the encode function with multidimensional
arrays.
The shape of the result of the expression R+ATB is
always (pA), pB.
Examples

::.~

")
<A'"

:'~

:3
..

x:<~ ~:5

,,0..

[] ~ .. ,:;: ~ .. (.~ 'I"

1
1

x':'

o
o
o

")
A',.

f (.~

06!:'i
10]

429
6<»2

3-23

APL FUNCTIONS AND OPERATORS

10 to tOTe
t~

-4
6

~,~~

I::'
,.J

::.~

'"'
.'\'.~

0 1 t
:1.

()

,.)

",'

'")
/1>'"

2T13

0 1
,.)
,.)
2 2 2T····13
",:..
h"
:1.

:1.

Related Functions
Decode, Section 3.3.4

3-24

APL FUNCTIONS AND OPERATORS

3.3.7

\ and \ - The Expansion Function

Format
dyadic
Argument Types
The right argument can be any array.
The left argument must be a
scalar value 0 or 1 or a Boolean vector, a vector containing only
Os and Is.
If the right argument is a character vector, spaces
are used instead of Os. The number of Is in the Boolean vector
must generally be the same as the number of values in the array
included as the right argument.
Definition
Builds a new vector or array by expanding the elements of another
vector into a new format specified by the function.
For example:
~~~··l

v~··l

'") :3

b :I.

() :I.

V\('~

1 () 2 () :3
V\ I ('~I""I... I
(.~

F'"

I...

The function expands the elements of A into the format specified
by V.
The values of A are inserted in positions corresponding to
the occurrences of Is in V.
For numeric values, zeros are
inserted in positions corresponding to Os in the Boolean vector.
If the right argument is a character string, as in the second
example above, spaces are used instead of zeros.
A scalar Boolean value as the right argument is extended as in
the following example:
:I.

::5 ()

()

1. \:::j

~.:j

You can also expand multidimensional arrays along a particular
coordinate.
(The coordinate is dependent upon the index origin,
Section 4.2.11.)
You include the coordinate within square
brackets. The syntax is the same as the compression function,
Section 3.3.2.
If you omit the coordinate, APL expands along the
last coordinate of the array.
To specify expansion along the
first coordinate, use the special symbol \, or type .CB.

3-25

APL FUNCTIONS AND OPERATORS

Examples
[Jt·(.~~··

:L
4

c:'
.J

(;)
()

:J.

0
-4

2
0

:'5
0

I::'

(;)

,.}

()

:t.
-4

0
0

.......

~:5

()

2 31-' \6

:1. \t:::I. ::t(.~

:I. \t::2::t(.~

:1.

3
6
O\\()

() 0 ()
t::I f· (.~ ~ .. ()

()

(APL outputs a blank line)

* TH:r.

~:;:t: ~:;('~N

F.:)<P('~N~; 1: ON
F.:N(.~MPLE"J( "/(

V~:I.

:I.

fr.THI~:;

:t:~:;

('~N

I::: ).( P ~~ N

~:;:t:

C) N

E::)<('~MP

1... 1:::

1<"/(

1 () :I.

:I.

:I. \~<

TH:t:~:;:t: ~:;('~N

E ~.( P (.~ N S :t: 0 N
E:-(('~MI::·I ... E"/( "/(

Related Functions
Compression, Section 3.3.2

3-26

APL FUNCTIONS AND OPERATORS

t or .GD - The Grade Down Function

3.3.8
Format

monadic
Argument Types
The argument can be a vector or a matrix.
Definition
Creates an index to sort a vector or matrix in descending order.
The t function creates a permutation vector that APL can use to
sort the original vector.
Duplicate values are ordered by their
relative positions in the original vector. You can also reorder
character arrays with t. The grade down function does not use
fuzz in performing comparisons.
The symbol t is formed by overstriking the del (V) with the
residue (I).
Examples
(.~~ .. 2

<? ?

4 :-5 :I. () :-5

[] ~.. E' ~ .. t (.~
62:·54~:5"/:I.

ArE']

10 <"I "/ 4 :-5 ;3 2
(.~

I:: t (.~ ~ . I M (.~ N U (.~ L.. I ::I

Related Functions
Grade Up, Section 3.3.9

3-27

APL FUNCTIONS AND OPERATORS

3.3.9

or .GU - The Grade Up Function

Format
monadic
Argument Types
The argument can be a vector or a matrix.
Definition
Creates an index to sort a vector or matrix in ascending order.
If two or more elements of a vector or matrix have the same
value, the order of the elements is determined by their relative
positions in the original array.
(Fuzz is not used in comparing
the elements.)
The ~ symbol is formed by overstriking the delta
residue (I).

(~)

with the

Grade up does not actually sort the vector.
It creates a permutation vector of the index numbers of the elements. This vector
is then used to sort the original vector.
If the array to be sorted is a matrix, the simplest operations
cause each row of the matrix to be treated as a string. The
result of the grade up operation is a vector whose length is
equal to the number of rows in the matrix.
You can cause a matrix to be sorted by rows; and by subscripting
the function, you can also sort on the basis of columns. For
matrices, the expression ~M is equal to ~[2JM.
Examples
A.--2 9 7 4 3 10 3
[li--X-:' ~--,t.A

1 574 326
~~ [1:<:1

2 3 3 4 7 9 :1.0

S TE:Vr:::
S(-'M
ST~'N

f(.":'

~:;

,-)

,t.A
.:..

:1.
A[,t.A;]

~:;~Ho1

ST~~N
~:;TEVE:

3-28

APL FUNCTIONS AND OPERATORS
Ec

A'~

1
9
0

5
7

0
0
0

f E(

:3 J

I!!'

,t.Ec

:3 1
F,( I:: .*,1\( ;

::I

:'5

:I.

()

'"
"

2
2

()

0
0

Related Functions
Grade Down, section 3.3.8

3-29

APL FUNCTIONS AND OPERATORS

3.3.10

or .10 - The Index Generator Function

Format
monadic
Argument Types
The argument can be a nonnegative integer scalar or a I-element
array.
Definition
Generates a number of consecutive integers equal to the value
specified as the argument, starting from the value of the index
origin, Section 2.4.2.
The expression IN generates a vector containing N components.
If
the index origin is set to 1, these components have values 1
through N.
If the index origin is set to 0, then the resulting
vector has values 0 through N-l.
The index origin default is 1 in a clear workspace, but this
setting can be changed with the )ORIGIN command (Section 5.5.4)
or the OIO variable (Section 4.2.11).
Examples
n1.··(.~1.··

i-4

:I. 2 :·5 4
.1-'(.:\

-4
nPO'A,lEI!;:S

2"/( i :I. ;;.~

2 4 8 :1.6 32 64 128 256 5:1.2 :1.024 2048 4096
nOFTEH
f l !:.:;O

USED

WITH

RHO

!:50
l r::-:

:1.

2 3 -4
nGEHERATES

A HULL

VECTOR

(APL outputs a blank line)

fiO

Related Functions
Index of Section 3.3.11.
Reshape and Shape, Sections 3.3.15 and 3.3.18

3-30

APL FUNCTIONS AND OPERATORS

3.3.11

or .10 - The Index Of Function

Format
dyadic
Argument Types
The left argument must be a vector.
any scalar or array.

The right argument can be

Definition
Returns the index in the left argument of the first occurrence of
the value in the right argument.
The result of a dyadic iota
operation always has the same shape as the right argument.
That
is, the result returns an index for each of the values in the
right argument.
If the value is not located in the vector specified as the left
argument, APL reports a value equal to the number of values in
the vector plus 1, «( pA )+1) •
The right argument need not be a single-element array; it may
have many elements and many dimensions. The right argument can
also contain literal characters.
The result of a dyadic iota expression, for example X+B1A, always
has the same shape as the right argument, formally pX is the same
as pA.
If A is a matrix, the correspondence between A and X can
be expressed as X[I;J] is the smallest K such that A[I;J] is
equal to B [K] •
Examples
I,'
4 9 6 B
(.~

6
E< \ (.~

\ r IX"~
[] . . ).: \ r /

>:~··E'

~ (.~ ~

~.:

9
X~[E' \

E'~··()
~~f·:·5

r /E']
,.)
:·5 4
:I.
,.! :-5
2f"b 1::'
~.

I::'

6 7 B

,.)

()

,.J

<"}

)-( ~ .• 1:< \ (.~

F.'

o 1 234 5 6 7 B 9

3-31

APL FUNCTIONS AND OPERATORS

5
2

6
3
0

<"}
v

l
4

:LO

:-5
'ABCDEFGH', 'HEADED'

B:5:L4~.'j4
Ii' ~ .. ~5 4
(.~~"2

2 3 "7 B
21" \ 4

I' \ {.~

l
4

'A'=2

'AAA'

IS LEGAL.

Related Functions
Index Generator, Section 3.3.10

3-32

WITH CHAR AND NUMERIC ARBS

APL FUNCTIONS AND OPERATORS

, - The Laminate Function

3.3.12
Format

dyadic
Argument Types
Both arguments can be scalars, vectors, or arrays.
Definition
Joins scalars, vectors, or arrays along a new dimension. The
syntax is the same as the catenate function, Section 3.3.1.
However, the coordinate specification ([J) is usually a fraction
to indicate a position between existing coordinates in which the
new coordinate is to be placed.
(The coordinate is dependent
upon the index origin, Section 4.2.11.)
If two arguments in a laminate operation do not have the same
dimensions, then at least one of them must be a scalar value.
Examples
('H<C

X)EF

2 3
ACREATES A NEW DIMENSION BEFORE
ATHE FIRST ONEPADDS A ROW

ACREATES A NEW DIMENSION AFTER
ATHE FIRST ONE;ADDS A COLUMN
[] ~" D ~ .. 3

:::,~

U v 1A) >; 'y' ~,~ I

~~~"3

21" I ('~I':<CDF.::F I

I:;;E"~~ y

1::. 2];()

f F;:
~; ~ .. ~~ y [

1. • ? J X:I

f'I:;:
I~:~ .. (.:)y

[2.3][1

r F;:
'X

....1

"......

3-33

APL FUNCTIONS AND OPERATORS
.f" I~:

232
[] ~ .. F;: ~.. I :.{ I

I:: 1. • ~; :1 (.~

c:o

rf::

322
I

L:?

~:.:;J(.~

Related Functions
Catenate Function, Section 3.3.1
Ravel Function, Section 3.3.14

3-34

APL FUNCTIONS AND OPERATORS

3.3.13

€

or .EP - The Membership Function

Format
dyadic
Argument Types
Both arguments can be arrays of any dimension; the left argument
contains the elements by which membership in the right argument
is determined.
The arrays need not have the same rank.
Definition
Determines whether or not particular elements of one array occur
as elements of another array.
The result is a Boolean array
whose shape is the same as that of the left argument.
The result consists of only Os and lSi a 1 indicates that the
corresponding element in the left array is present in the right
array, 0 indicates that it is not present.
Examples
U~A~'ABCDEFG'e

'HEADED'

100 1 100
Aj'ABCDEFG'
ADE

The compression function I, is helpful here in identifying the
particular characters that are members of the vector.
A~2

3,7 8 2 4 6 9

Ae\6

001
110

o 0
o 0

3 4e '34'
34e\0

'A'=2

'AAA'

IS LEGAL.

€

000

Related Functions
Index of, Section 3.3.11

3-35

WITH CHAR AND NUMERIC ARGS

APL FUNCTIONS AND OPERATORS

3.3.14

, - The Ravel Function

Format
monadic
Argument Types
The argument can be any scalar or array.
Definition
Produces a vector from any scalar or array. The vector produced
has the same length as the original array. The elements of the
array are preserved in the resulting vector in row order.
If the
argument is a scalar, then the ravel function produces a vector
containing one element.
Examples
(.~

'")

A'~

~:.:j

r (.~

2 3
(] 'i" x:< ~" ~ (.~

1 ::? 3 4 5 6
fE<

t,
[]~"(.~~"2

I::'

,,}

13
1'7
21

41" \ (1'0

1.0

3
'7
1:1.

4
0
:1.2

:1.4
1.0

1.:::j
1.9

:1.6
20

'.)'0)
JI!..Ik.

2~~

~ (~)

1 2 :3 4

I::'
...!

f , (.~

'7 B (y :1.0 1.1. 12 13 :1.4 1.5 16 :1.'7 :1.8 1.9 20 2:1. 22 23 24

24
234

Note the difference in the shape of a scalar and the shape of a
scalar to which the ravel function has been applied
f4

(APL outputs a blank line)
1

Related Functions
Catenate, Section 3.3.1
Laminate, Section 3.3.12

3-36

APL FUNCTIONS AND OPERATORS

3.3.15

or .RO - The Reshape Function

Format
dyadic
Argument Types
The left argument can be a scalar or a vector. The right argument can be a numeric constant, or a literal character, or the
name of an existing array. A literal array can be constructed
by including a character string as the right argument and enclosing the string within single quotation marks.
Definition
Constructs an array or reshapes an existing one. The left argument specifies the shape of the array; the right argument specifies the values to be assigned to each element of the array. The
shape of the array describes both the number of dimensions of the
array and the number of elements in each dimension. The values
are placed in the array in row order; that is, the first value is
placed in row 1 column 1; the second value is placed in row 1
column 2; the third value is placed in row 1 column 3, and so on.
If the left argument is a single value, a I-dimensional array is
created.
The array being reshaped need not have the same number of values
as the array from which the values are taken.
If the right
argument has too many values, the excess values are ignored from
the right.
If there are too few arguments, the values are duplicated from the right.
Any number of array elements can be specified in a reshape
operation as long as the number is not negative or fractional and
does not generate a vector or array too large for your workspace.
Examples
3,5
9,'ABC'
ABCABCABC
X~8
Y~2

9 7 4
2,x

2 S,A
4
3
2
1
3 4

A~l

~
~

3 4
1
~

3,A
1 2 3

3-37

APL FUNCTIONS AND OPERATORS

[] E·· (.~ i·· 2

:I.
3

2r \4

2
-4

The following expressions each generate a null vector:
ASHAPE
:L

WITH

A SCALAR

(.:l~ ..

r(.~

(APL outputs a blank line)

Of I I

(APL outputs a blank line)

OrO

(APL outputs a blank line)
(APL outputs a blank line)

[]~ (.~~

.. 3 0 ::.:; 4

r(.~

f (.~

3 ()

~.:;

Related Functions
Shape, Section 3.3.18

3-38

APL FUNCTIONS AND OPERATORS

3.3.16

or .RV and e or .CR - The Reverse Function

Format
monadic
Argument Types
The argument can be a vector or array.
Definition
Reverses a vector or the elements of one coordinate (last
dimension) of an array.
It changes the order of the elements,
not their dimension.
To specify the coordinate to be reversed, include it in square
brackets.
(The coordinate is dependent upon the index origin,
Section 4.2.11.)
The default is the highest coordinate (last
dimension) of the array. The special character e (.CR) reverses
the first coordinate of ~he array.
The reverse is formed by overstriking the circle 0 with the
residue function I. The e character is formed by overstriking
the circle (0) with the minus (-).
Examples
4r, B

[]~""(.~~""2

1.
~:":j

::~

2
b

4
B

(J) I:: :1" ::I ~~
~:;

4
B

:"5
"7

I::"

"7
:3

(j)[2]~~

2
b

:I.
~:5

a(.~

'1"'

'")
AO••

"7
:"5

n
4

The following example reverses a matrix in both dimensions
simultaneously:
[] ~"" ~"~ ~"" 2 :-5 f \ (.)
:"5
~:;
6

1.
4

6
:"5

~:)

:t.

~)cI>l::l.]~<

3-39

APL FUNCTIONS AND OPERATORS

Reverse is not the same as transpose:
~x

1
~

4
~

Related Functions
Rotate, Section 3.3.17

3-40

APL FUNCTIONS AND OPERATORS

3.3.17

or .RV - The Rotate Function

Format
dyadic
Argument Types
The left argument can be a scalar or a vector.
ment can be any array.

The right argu-

If a vector is being rotated, the left argument must be a scalar
or a l-element vector.
If a multidimensional array is being
rotated, the left argument must be a scalar, a single-element
vector, or a vector whose elements correspond to dimensions of
the array being rotated, with the dimension being rotated omitted
from the vector.
The rotate function is formed by overstriking the circle
the residue function \.

with

Definition
Rotates an array by a specified number of places. A positive
rotation causes a left shift; a negative rotation causes a right
shift.
You rotate a multidimensional array by specifying the coordinate
along which rotation is to take place.
(The coordinate is dependent upon the index origin, Section 4.2.11.)
The default is
the highest coordinate of the array.
To specify the first coordinate, use the special symbol e (.CR)
which is formed by overstriking the circle 0 with a minus Examples
](J> \ ~.:;

~.'j

:1. 2 3
.... 34> \ ~5

:34~:.'i12
x~3

4f'ABCDEFGHIJKL'

('~f.ICX:'

E:F'(::"H

1: ...I I( I...

(.:-'BCD
FGHF.::
I( L:J:'oJ

1 1 2

J(j) I:: 1. :I >~

O~A~3

5r'ABCDEFGHIJKLMND'

EFKD
:r. ..JCH
(.:-, f,IG I...

ABCI)E
FGHI'o.J
I( LMND

3-41

APL FUNCTIONS AND OPERATORS

:1.

····1

2 2

2(;.)(.~

FLMNO
K E<CI)E
AGH:t:J
AE<CJ:lE
H:t: ....IFC;
OKI... MN

Related Functions
Reverse, Section 3.3.16

3-42

APL FUNCTIONS AND OPERATORS

3.3.18

p or

.RO - The Shape Function

Format
monadic
Argument Types
The argument can be scalar, vector, or array.
Definition
Returns the shape of the argument, that is, it returns the length
of a vector or the dimensions of an array. For example, if the
argument B is a character vector consisting of 'ABCDEF', then the
following expression returns the number of characters in the
array:
B~'ABCDEF'

ABCDEF

If the argument is a matrix, rho returns the number of rows and
columns it has. For example:
A~5

6rl10

fA
5 6

If the argument is a scalar and not a vector or array, then the
rho of that scalar is a null vector, a vector of length zero.
APL outputs a blank line in response to the shape operation with
a scalar.
Two shape functions (pp) return the number of dimensions (rank) of the arguments as follows:
Argument

ppK

scalar
I-dimensional array
2-dimensional array
3-dimensional array
and so on.

1
2
3

This effect is the result of the fact that pK is a vector containing one element for each dimension of K, so its p (ppK) is
a I-element vector consisting of the number of dimensions of K.

3-43

APL FUNCTIONS AND OPERATORS

Examples
A

:/,
?

"...

B
-4

I::'

I.)

..!

<"I

!:)
:/,

..,
I

4
:1.0
I.)
"j

A,.

I::'
.,J

:I.
'?
3
9

h':.

4
:/.0

f (.)
1::'

b
f' f (.)

2
K~ ..

f I(

(APL outputs a blank line)

Related Functions
Reshape, Section 3.3.15

3-44

APL FUNCTIONS AND OPERATORS

3.3.19

The Take Function

Format
dyadic
Argument Types
The left argument can be a scalar. However, if the right argument is a multidimensional array, the left argument must be a
vector containing one element for each dimension of the array.
The right argument can be any array.
Definition
Builds a new vector or array by taking a specified number of
elements from an existing array.
If the value of the scalar is
greater than the number of elements in the vector, the resulting
vector is extended so that its length is the value of the scalar.
Zeros extend numeric vectors, and spaces extend character vectors.
In the expression R+S+V, if S is positive, then R consists of
the first S elements of V.
If S is negative, then R contains the
last IS elements of V.
If IS is greater than the number of
elements in V, then zeros or blanks are inserted in R before the
values of V.
Examples
21',3
1.

:::.~

4·1', 3
1 2 :3 0
:I. !::jt I ('~Pl... SF I , n·.,.·!:.'.i

5 0 0 0 0 0 0 0

API...SF

.... 6·t:I.2 24 3!:'=; 4B

() 0 12 24 :3!:.) 4B
·..·!:.=;·1' \ 3
00:1. 2 :3
!::j1' \ 3

1 2 :3 () ()
.... 20-1- I Tt:::ST I

Related Functions
Drop, Section 3.3.5

3-45

APL FUNCTIONS AND OPERATORS

3*3.20

or .TR - The Monadic Transpose Function

Format
monadic
Argument Types
The argument can be a matrix or higher-dimensional array.
Definition
Transposes the dimensions of an array. For a matrix, it exchanges
rows and columns.
If you use a vector as the argument, it will
have no effect. For example:
(.~~

.../ 2 3 -4 !5

/.'Q(.:}"

J. 2 :-3 -4

!' =;

To form the

symbol, overstrike the circle

Examples
..

[]~ (.~ ~

:I.
-4

:/.
2
3

-4

.. 2 3r \6

3
b

~::;

[]~ .. C I. .. ~(.~

1:,'

,.J

b
f~'~

14.'..

[] ~ •• 1:< ~ •• 2
")

:/.

,'.

I:!'

,.J

::.~

I::'

(.)

:/.

1.::'

A',.

3
?
3

"7
3
"'1

...

3 4r \ B
'!oJ

B
4

n
-4

3-46

with the slash \.

APL FUNCTIONS AND OPERATORS

lI:!F.<

::5

..!

I::'
,.!

::.~

\~:.

")
~:

"?
:-3

-4
B
-4

B
-4
B

"',,

"'J

fll:!F.<

Related Functions
Dyadic Transpose, Section 3.3.21

3-47

APL FUNCTIONS AND OPERATORS

3.3.21

or .TR - The Dyadic Transpose Function

Format
dyadic
Argument Types
The left argument must be a vector containing one element for
each of the dimensions of the array to be transposed.
The right
argument can be an array.
The shape of the vector expresses the
rank of the right argument.
For example, in the expression V~A,
the rank of the right argument can be expressed as:
pV which
must be equal to ppA.
Thus, V must have two elements if A is a
matrix, three if A is a 3-dimensional array, and so on.
If the rank of the array is 3, then valid values for the leftargument vector can be 1 1 1, 1 2 1, 1 3 2, 3 1 2, but not 1 3 1
(2 is missing) .
Definition
Permutes the coordinates of an array.
The following table lists
transpositions for a variety of arrays:
Table 3-6
Transpose Definitions
,---

Expression
R+1~V

R+1
R+2
R+1
R+1
R+1
R+2
R+3
R+1
R+1
R+2
R+1

2~ M
1~M
1~M
3~A

2
3
3
1
1
2
1
1

2~A
1~A
2~A
2~A
1~A

1~A
1~A

Shape of R

pV
pM
( pM) [2
L/pM

Definition

R+V
p+M
1J

pA
(pA)[1
(pA)[3
(pA)[2

3 2J
1 2J
3 1J
(L/(pA)[1 2J),(pA)[3J
(L/(pA)[1 3J),(pA)[2J
(L/(pA)[2 3J),(pA)[1J
L/pA

3-48

R[I;JJ+M[J;IJ
R[IJ+M[I;IJ
R+A
R[I;J;KJ+A[I;K;JJ
R[I;J;KJ+A[J;K;IJ
R[I;J;KJ+A[K;I;JJ
R[I;JJ+A[I;I;JJ
R[I;JJ+A[I;J;IJ
R[I;JJ+A[J;I;IJ
R[IJ+A[I;I;IJ

APL FUNCTIONS AND OPERATORS

Examples
3r \6

[I ~ .. (.~ ~ .. 2

:I.
4

:-5
6

~:;

nDYADIC

SOMETIMES

SAME

MONADIC

~(.~

~~~"2

:'~f' 6

(.~

:I.
-4

~:.:;

6
(.~~··2

3 4f"' \ (.)

(.~

:I.

",,',.

:-5

~:.)

:1.

::.~

~:5

:1.

")
,:..
,f)

:.~

I::'
,.J

:I.

,.~'.

-4

~::;

:1.

:I. ~(.~

:I.

:1.

I::'

t::·

::.~

,.J

,.,

,.}

Related Functions
Monadic Transpose, Section 3.3.20

3-49

APL FUNCTIONS AND OPERATORS

3-50

APL FUNCTIONS AND OPERATORS

Related Functions
Matrix Divide Section 3.4.2. The monadic expression ffiX is equal
to the dyadic IffiX, where I is an identity matrix whose order can
be described as ltpX.
If the argument of the matrix inverse is
a scalar, the expression ffix is equal to +X.

3-51

APL FUNCTIONS AND OPERATORS

ffi or .DQ - The Matrix Divide Function (Quad-Divide)

3.4.2
Format

dyadic
Argument Types
Both arguments can be scalars, vectors, or matrices.
Definition
Performs more complicated matrix operations than the inversions
described in section 3.4.1. In the expression XffiY, X and Y must
conform to the following:
1.

Y must have a rank of 2 or less.

If the dimensions of Yare M by N, then M~N.

X must have a rank of 2 or less and (1tpY)=1tpX

This implies that matrices X and Y have the same number of rows,
and the columns of Yare linearly independent.
If Z+XffiY, then
ppZ is the same as ppX and +\((Y+.xZ)-X)*2 is minimized (least
squares solution).
The matrix divide treats scalar arguments as matrices containing
one row and one column. The expression XffiY is equal to scalar
division XfY, except that the operation offio produces an error
condition.
If the arguments are vectors, they are treated as
matrices with a single column.
If I is an identity matrix of the
same dimension as X, then ffiX is equal to IffiX.
Examples
The following example illustrates the use of the matrix division
function in solving these linear equations:
3A+B=9
2A-B=1
In the expression XffiY, Y is a matrix whose values are the coefficients of the equations, and X is a vector containing the
values 9 and 1.
~<·~··9

:1.

Yi··2

21-'3 1 2 .... l.

::-q~p.

The result is a vector in which the first element is the value of

A in the linear equations, and the second is the value of B.

3-52

APL FUNCTIONS AND OPERATORS

The following examples illustrate the use of the matrix divide,
including a least squares solution:
[JH~~·· (2

2
~;

:l.r2

~:.:j)

y:l.

1
:I.
!(~··10

f ).~ ~. I~' rn A

10 19
..

[]~ (.~~

1
2

:I.

.. (~5 :l.r \ ~::;) 1':I.

:I.

B~2.001
[] f·)·~ ~.. I-:< (.":t

2.998 4.002 4.997 6.0:1.

1.001"7 0.9965
E< •.. (.~+. x N
O~·NHJA

-2.000000000 E -:I. -:l..OOOOOOOOO E -1
2.923875822 E -20
1.000000000 E -:I.
2.000000000 E -l
8.000000000 E-:I.
5.000000000 E -:I.
2.000000000 E -l
-1.000000000 E -l -4.000000000 E -:I.
N+.X A

1.000000000 EO
-1.301042607 E -18

5.42:1.0:1.0862 E-20
1.000000000EO

Related Functions
Matrix Inverse, Section 3.4.1

3-53

APL FUNCTIONS AND OPERATORS

3.4.3

.EP or .DE - The Execute Function or Unquote Function

Format
monadic
Argument Types
The argument can be a scalar or a vector.
If the scalar is
numeric, the value of EA is equal to A.
If the scalar or vector
is a literal, APL evaluates it exactly as quad input from the
terminal would be evaluated.
Definition
Executes a character string as an APL statement. The scalar or
vector included as the right argument of the function is evaluated as the character string to be executed by APL.
The E and
~ can be used interchangeably to indicate the execute function.
APL treats carriage return/line feeds in the argument as statement separators, just as they would be if they were input from
the terminal, so multiple lines are allowed.
The result of the
expression R+EA is the value of the last statement evaluated in
A.
If the last statement has no value, R is a null vector.
Errors encountered in the character string processed by the
execute function are handled exactly as if they occurred in
statements entered from the terminal.
If an error is encountered
while evaluating the execute string, an error message is output,
and the segment of the execute string currently being evaluated
is displayed. No further evaluation of the string is performed.
The EA returns a null array whose shape is 0 E, where E is a
number indicating the error that was encountered. Appendix A
contains a complete description of all APL error conditions.
The execute function is also known as the unquote function,
because it strips quotes from the value entered as its argument.
Other uses of this function include:
1.

Function definition (character-editing commands are not
permitted)

Conversion of vectors of characters
constants into numeric values

Passing an unevaluated APL name to a function.
can be evaluated with 6.inside the function.)

3-54

represent~ng

numeric
(The argument

APL FUNCTIONS AND OPERATORS

Examples
The following examples illustrate the use of E in function
definition, system command execution, and APL statement evaluation:

Z~"!':<+3

.. x ~.~

::,~ ~ ~.~
I~.I

X:<~"4

NOT

DEFINED

:I. 1 v (.~ L U IE:: 1::: I:;: I:;: 0 F;:
F
.A.

C~"i: A

NOW DEFINED

49
C~"!i' )FN~:~'

3+2
6'

:0
E

1:1.

V('~I...UE

E F;: I:;: 0 F,:

1:::
.''\

3+2v
4'
:LO

E SYNTAX ERROR

3+2,

o 7

f E::

n ALL
:1.:1.

E
V (.~ I... I..II~:

VARIABLES

ARE NOW

ERASED

I::: 1:,: I:.: 0 1:,:

I:::
1\

) \A,!:; I x:'
I..IJ('~S

CI...E('~I~:

TH I sw~:;

w!:;

3-55

APL FUNCTIONS AND OPERATORS

o,;,-H

[lJ
[2J

HARD TO BELIEVE'
THISWS'
[3]
'WHEN LOADED, EXECUTION RESUMES AFTER EXECUTE
AUTOM(.~T:1: CALL 'T' ,

[4]

'THIS

Z~~')SAVE

'i)

THIS IS HARD TO BELIEVE
WHEN LOADED, EXECUTION RESUMES AFTER EXECUTE
('~UT()M('~T:[ CALL',
) L.O('~X:' TH I St'J~;
WHEN LOADED y EXECUTION RESUMES AFTER EXECUTE
(:~ U T () M(.~ TIC (.) I... L. 'y'
ATHE NEXT EXPRESSION DbES NOT PRINT A VALUE
<: ' (.) {.. ::) ,
ATHE

NEXT ONE DOES

[]~ .. t

' A~ .. ~:.) ,

E« .. i:

' ,

/-,E<

()

The last example illustrates that the execute function always
returns a value. Because, in this case, there is no value expressed in the character string, the value of the operation is
simply a null vector. Similarly, if the character string contains a branch (+), the execute function does not transfer
control but returns the null vector.
Note that you can use )ECHO (OFF),Section 5.5.2, to suppress
the error message from E.

Related Functions
Extended Execute, Section 3.4.4

3-56

APL FUNCTIONS AND OPERATORS

3.4.4

or .XQ - The Extended Execute Function

Format
monadic
Argument Types
The argument can be a scalar or a vector.
Definition
Processes system commands and supports the entry of mUltiple
lines. ' The execute symbol ~ is formed by overstriking the
decode or unquote character i with the. jot character 0 .
The ~ function is very similar to the € or i functions.
However,
there are two major differences.
If an error is encountered in
the character string being executed, ~ does not return a null
vector indicating the type of error.
Instead, ~ generates an
error message for the line on which the actual execute occurred.
The second major difference is that if the ~ character string
contains a branch (+), control passes to the specified function
line.
Examples
V'F

(.~

I:I~··:l.(.~

[1.]

~:; "y" N T (.~ ~o(

1::: I:;: I:;: <:) I:;:

.....

2 ~:) I::: ~.~ I::: CUT EEl:;: I:;: 0 I:;:
F [: t ]

X~~·· .t.(.~

.....
) ~;:r

F[:I.]

/(
f,1

:1.:1.

v (.~ I... U I:::

E I:;: I:;: D I:;:

XiI

.....

:L:I. v (.~ I... U J::: E: I:;: I:;: C) I:;:
F [: :1. ::I
:f:1 ~ •.•f. (.~
.....

3-57

APL FUNCTIONS AND OP'ERATORS

In the last example, a value is required in the execute string,
but none is included. APL generates an error message and
suspends function execution.

Related Functions
Execute or Unquote, Section 3.4.3

3-58

APL FUNCTIONS AND OPERATORS

$ - The Dollar Format Function

3.4.5
Format

dyadic
Argument Types
The right argument can be one or more scalars, vectors, or
multidimensional arrays containing numeric or character fields
to be formatted.
The left argument is a character vector containing one or more format fields describing the type of formatting to be performed on the specified fields.
The left argument
is enclosed in single quotation marks.
Table 3-7 summarizes the syntax of the format fields.
Table 3-7
Format Fields
Format

Meaning

'MAW'

Character data - cannot be used for numeric values

'MEW.d'

Floating-point numeric data with exponent

'MQFW.d'

Fixed-point numeric data

'MQIW'

Integer numeric data with automatic rounding

'MXW'

Blanks inserted in edited line

'M~text~'

Literal text inserted in edited line

where

is an optional repetition factor (number of
values to which the format is to be applied).

is the width of the field.

is the number of decimal positions.

is any number of qualifiers (see Table 3-8).

The lamp character (A), formed by overstriking the down union
(n) with the jot (0), can be used instead of the quote-quad (~).
On non-APL-keyboard terminals, .QQ replaces ~ and" replaces A.

3-59

APL FUNCTIONS AND OPERATORS

Table 3-8
Qualifiers
Meaning

Qualifier
B
C
L
Z

M[!]text[!]
N[!]text[!]
P[!]text[!]
Q[!]text[!]
R[!]text[!]

Blank field if value is 0
Insert commas
Left justify
Fill with zeros
Insert text left of
negative result
Insert text right of
negative result
Insert text left of
nonnegative result
Insert text right of
nonnegative result
Insert text in background

If more than one format field is included in the left argument,
the fields must be separated by commas.
Successive fields apply
to successive vectors or arrays represented by the right argument
of the function.
If you include a repetition factor in one of
the format fields, this factor indicates the number of vectors to
which that format is to be applied.
Definition
The result of a format operation is one or more lines of edited
text.
Each resulting line consists of one edited row of each
array in the right argument, where each vector (V) is treated as
an array of dimensions (pV) by 1. The total number of lines
produced by a format is equal to the longest column in the array
contained in the right argument.
The columns of values with
shorter columns are extended with blanks.
As many as 18 significant digits can be specified in a format
statement. A format field that requests more than 18 significant
digits will cause digit positions to the right of the decimal
point to be filled with blanks, and digit positions to the left
of the decimal point to be filled with underscores. A minus sign
is output on non-APL-keyboard terminals.
A format field that does not specify sufficient room for all
significant digits plus any inserted characters causes the entire
field to be filled with stars on APL terminals and asterisks on
TTYs.
If a format expression produces a very large matrix that is not
assigned explicitly to a variable name, APL saves storage in the
workspace by displaying each line of the matrix as it is formatted and not saving the results.
As in other languages that support format specification similar
to this APL function, parentheses can be used to repeat groups of
fields.
They can be nested to three levels.

3-60

APL FUNCTIONS AND OPERATORS

Examples
'I4 1$(\5;10+\6)
11
12
13
14
15
16
'Z F 4.1 1 $1 2 3

1
2
3

4
5

01.0
02.0
03.0
A~'F4.2~3(12~E8+1),All

AIS EGUAL TO
A~'F4.2~I2,E8.1,I2~E8+1~I2~E8.1,All

115 1$3 -7 4.7 4.2

5
4
3

115 1$(3;-7;4.7;4.2)
-7
5
4
O~A~'F6.21$(3;6;-7.4.3)

3.00

6.00 -7.00

4.30
-7;4.3)

O~A~'F6!2IS(3;6

3.00

6.00
-7.00

4.30

2 18
S~2E25

'F30.2ISs
2000000o0o00000000 ________ •
'F3.2IS50u
A~2

3,(619999)+100

'I4,~I~,F6.2,x3~E10.21$A

351 51.19
701 29.36
'Al'$'AB'

8.9 EO
9.0 E l

A
B

PENCILSPAPER
7,'PENS
.05 .01
AMNT~20 50 2589

T~4

TOTAL

COST~.19

TCOST~AMNTxCOST

'7Al,~I~,I6,F8.2,F12.2IS(T;AMNT;COST;TCOSTy+/TCOST)

PENS
I
PENCILSI
PAPER
I
TOTAL
I

20
50
2589

0.19
0.05
0.01

3.80
2.50
25.89
32.19

3-61

APL FUNCTIONS AND OPERATORS

-25 -0.4 .8 0 100

X~-23456.78
1 I~'Ft().

1. 1 $~'~

.... 2~~4!:)6 • 8
.... 2 !:; • 0
.... 0.4

0.8

too.o
1

CE.!

$~'~

-"2:3,4!57

:lOO
1 ~?F9

• :l 1 $>~

.... 02:3456. B
'-'OOOO~,~~:; • ()

-0000()().4
O()()()()OO.8
OOO()OOO.O
OO()O:L 00.0
1

L.t 9 1 $~'~

S 'y'NT('!I)'~

EHI:i:DFi:

11...19 1 ~i)'~
,A,

11...:1:9 1 ~i~'~

.... 2~~4!:57
()

:I.
()
J()()
M r.J ........ ,~, F t 1. + 2
.. -.... 2::~4!:)6. lB
........ 2!::; • 00
........ 0.40
1

~I; ),~

O.BO
0.00
:1.00.00

3-62

APL FUNCTIONS AND OPERATORS

I f;:C!+r.JF'C!+fP: 11 I $~'~
+++++ .... 2~~4~:57
++++++++'-25
++++++++++0
++++++++++1
++++++++++0
++++++++:I.()()
'M~-$C!P~.C!BF:I.:I.+21$X
-"$2:34~,:i6 + 78

·"$2:7i.00
.... ~;(). 40
~;O + 80

Nfl fjC:t:20

~p~

.... 23 ¥ 4~:,:i7

o
:I.

o
1()()
'RCI*~P~$C1CF:I.:I.+21$IX

)'($2:~~4~:j6. 70
**'/(**~;2~:').O()

**'/('Jt.'Jt.*~t>O.40

'/('/1.'/('/(lA:lA:!t>O.BO
'/(fr.'/('/('/('/($O.O()

'/( '/( )'( '/(. :1, 00 + 00
I

/:':I~I

70
.... 2 !:,:j • 0 0
.... O.4()

'-::~34~:,:i6.

O.BO

NON/:::

:l.oo.O()
'MCI(~

N~)CI

aCl CI Fl0.2 1$X

(2~54!::j6 • '70)
(2~5.()(»

(O.4(»
O.BO
0.00
l()O.OO

INC! DBC! GCI CRCI
2:'54~::i6. 70

X)X\'

2~:5 + O()

DX\'

O. SO

C/:·:

:I. O() + O()

Cf::

MCI~

BF:l.4.21$X

o .4() X)B

Related Functions
None

3-63

APL FUNCTIONS AND OPERATORS

3.4.6

T or .FM -

The Monadic Format Function

Format
monadic
Argument Types
The argument can be a scalar or an array of any shape and either
numeric or character data.
Definition
Converts numeric arrays to character arrays. When applied to a
character scalar or array, the result of the format R+TA is an
array identical to A.
If A is numeric, then the character array
represented by R will be identical to A as it appears when displayed by APL. However, the blank characters displayed along
with the values of A will actually be a part of the new array R.
The format of a scalar number is always a vector.
Examples
The following example illustrates the difference between the
shapes of a displayed numeric array and a formatted character
array:
A~2

4Pl8

B~.A

3
7

pA
~

4
B

2 1?
B[ ;3x \ 4J

1234

5678

Related Funct~ons
Dyadic Format, Section 3.4.7
System variables OPP Section 4.2.15
OPW Section 4.2.16

3-64

APL FUNCTIONS AND OPERATORS

3.4.7

• or

~FM

- The Dyadic Format Function

Format
dyadic
Argument Types
The right argument must be a numeric array.
The left argument
can be a scalar, a pair of numbers, or a vector whose length is
no more than twice the number of columns in the numerical array.
The left argument controls the format of the result.
Two numbers
are usually supplied as the left argument.
The first number
specifies the width of the numeric field, and the second sets the
precision of that field.
Definition
Provides output control exceeding that available with the monadic
format.
It offers a number of formatting options but does not
provide the comprehensive formatting capability available with
the dollar format function ($).
Dyadic format provides a powerful tool for formatting tables,
headings, and labels.
Precision is expressed differently for
decimal values and in scaled exponential forms of output.
The
form is determined by the sign of the precision argument. For
decimal output, precision is a positive number, expressed as the
number of digits to the right of the decimal point. For scaled
output, precision is negative and is the number of digits in the
multiplier.
If the width of the specification is zero or omitted from the
expression, APL provides a default width such that at least one
space is inserted between pairs of numbers.
If only one number
is provided as the left argument, the number is assumed to represent the precision of the result, not its width.
In general, the width must be large enough to accommodate the
number field.
However, APL does not require that space be inserted between columns.
You can specify width and precision arguments for each column of
the array to be formatted or even for each element of the array.
A format operation can also be specified for a multidimensional
array and applied to the last two coordinates.

3-65

APL FUNCTIONS AND OPERATORS

Examples

31.16
-15.578

2 3

3. x

O~Y~12

0.000
8.000

31.160
-15.578
rY
2 36

2. X

A~9

-1.070
-235.610

•

0.00
8.00
O~R~6 O.x
31
0
-1

31.16
-15.58

-235.61

2 18

3.1 E 1
-1.6 E 1

8.0 E O

3E1

-2 E 1

8EO
nCOLUMN
rD~8

-lEO
-2 E 2
FORMATTING

0 0 -2 8 0 .x
0
-1

2 25
nFORMATTING

5
7

6
8

A MULTIDIMENSIONAL

2 2p\8

O~A~2

1.00 2.00
3.00 4.00
5.00 6.00
7.00 8.00
B

3.1 E 1
-1.6 E l
B~3

o
8.0 E O
3r1

-1.I E O
-2.4 E 2

0 0 1 0 I 1 I I

3-66

ARRAY

APL FUNCTIONS AND OPERATORS

ATABLE FORMATTING
I:;: 0 W S ~ .. ~:.:i

"7 f ' (.~ I"· L.

CDI... ~:;~ .. ,

USERS

FOF;:M~ .. ~.'j

(

FORTRANCOBOL.
PROGS

BASIC

SYSTS'

3f(.~

'¥[lJROWS)¥CDL.S¥[lJ70. FORM
U~:;EI:;:~:;

PRDG~:;

!:;Y~:;TS

:I.
4

~~
~:'j

3
6

."7

B
;·5
6

4
"7

('~F:·L

F (J F;: T ,:;: (.~ H

COlo:' 0 I...
C

X:<('~!:i I

PL.:L

I::'

...:

,.J

:1.

Related Functions
Monadic Format, Section 3.4.6

3-67

PL.1

APL FUNCTIONS AND OPERATORS

3.4.8

or .EN - The Quote Function

Format
monadic
Argument Types
The argument can be a scalar or an array with either numeric or
character data.
If numeric, APL converts it to a character
string.
Definition
Converts numeric values to character strings and also provides
aid in preparing text to be processed by the execute function.
If the argument is already a character string, APL determines
whether or not the string represents an identifier (for example,
a variable name or function name).
If the character string is
not an identifier, then APL returns a null vector.
If the
argument if a variable, APL returns the value of the variable.
If the argument is a function, APL returns the lines of the
function definition, separated by pairs of carriage return/line
feed characters.
Examples
In the following example, array A is converted to a 20-character
vector (spaces output by APL are included in the size) in which
the character representations of 1 through 6 are members, but
the corresponding numeric values are not.
A~2

3f16

B~TA

'123456'sB
1 1 1 1 1 1
(\6)~B

0 0 0 0 0 0

3-68

APL FUNCTIONS AND OPERATORS

3-69

APL FUNCTIONS AND OPERATORS

3.5

OPERATORS

An operator differs from a function in that an operator takes a
function as its argument. The following operators are available in
APL:
1.

Inner Product

Section 3.5.1

Outer Product

Section 3.5.2

Reduction

Section 3.5.3

Scan

Section 3.5.4

3.5.1

f . g - The Inner Product Operator

Format
dyadic
Argument Types
Both arguments can be vectors, matrices, arrays, or higherdimensional arrays.
If either argument is a scalar or a
I-element vector, it is extended so that its dimensions match
the dimensions of the other argument.
Both f and g can be any dyadic scalar function as long as both
are of the same type, that is, both arithmetic, both logical,
and so on.
Definition
Obtains the common algebraic matrix product, and also extends
this capability to other arithmetic operations and other array
dimensions.
You can also specify an inner product in which an operation other
than multiplication is performed.
It is possible to locate
values containing specific characters by this method or to search
for a row of one array in which all the elements are equal to
those in a column of another array.
The two arguments, say A and B, must conform to certain rules to
be used in an inner product operation. The two arguments conform if any of the following is true:
1.

A or B is a scalar.

Results of -1tpA and -1tpB are equal.

Either -1tpA or -1tpB equals 1.

If the third characteristic is the case, then the corresponding
argument is extended so that the arguments have equal lengths
along the specified coordinate. The basic test for conformability

3-70

APL FUNCTIONS AND OPERATORS

is whether or not the length of the last dimension of the left
argument matches the length of the first dimension of the right
argument.
The dimensions of the result can then be considered
all dimensions of A except the last, catenated to all dimensions
of B except the first.
In Table 3-9, the letters have the following meaning:
f

is a primitive function.

is an argument.

is the result.

C,D,E,F

are the respective shapes of the
arguments.

I,J

are indices.

Note that when one or both of the arguments are scalar the shape
of the arguments need not conform to any rules.
Table 3-9
Inner Product Description
Result

Shape

Definition of
Z+Af·gB

Z+f/AgB

scalar

Z+f/AgB

scalar

Z+f/AgB

scalar

Z[I]+f/AgB[ ;I]

scalar

Z[I]+f/A[I; ]gB

Z[I]+f/AgB[ ;I]

scalar

Z[I]+f/A[I; ]gB

Z[I;J]+f/A[I;]gB[;J]

3-71

C
F

APL FUNCTIONS AND OPERATORS

Examples

ni·· (.~ ~ .. 2 3 r \ \~i
123
4

::.)

[f~ .. Bi·· \

123
(.) ·f· • X E<

14 32
(\;3)+.x\3

14
2 6+ • .~(.":j

012
14

(.) ·t· • x !Q (.~

32
77

D~X~4

3r'OHETWOSIXTEN'

OHE:
TWO
S I ~.{
TEN

4 3

rV
3
:·{A. ==:V

001 0

Related Operators
Outer Product, Section 3.5.2

3-72

APL FUNCTIONS AND OPERATORS

3.5.2

f or .SO • f - The Outer Product Operator

Format
dyadic
Argument Types
Both arguments can be any array.
acter, not the circle.

The

symbol is the jot char-

The f is any dyadic scalar function.
The period (.) is the
connector between the jot and the function.
Definition
Specifies an operation to be performed by every element of one
array on every element of another array. For example, in the
expression R+A.fB, R is any array that results from applying f to
every pair of elements of A and B. The shape of R is the dimensions of A catenated to the dimensions of B, or (pA),pB.
Unlike
inner product, outer product performs only one operation.
Table 3-10 describes the results of using a variety of arrays.
The letters have the following meaning:
f

is a primitive function.

is an argument.

C,D,E,F

are the respective shapes of the
arguments.

I,J,K,L

are indices.

is the result.

3-73

APL FUNCTIONS AND OPERATORS

Table 3-10
Outer Product Description
Shape

Definition of

Result

Z+Ao .gB

Z+AgB

scalar

Z[I]+AgB[I]

scalar

Z[I]+A[I]gB

scalar

Z[I;J]+A[I]gB[J]

Z[I;J]+AgB[I;J]

scalar

Z[I;J]+A[I;J]gB

Z[I;J;K]+A[I]gB[J;K]

scalar

D E F

Z[I;J;K]+A[I;J]gB[K]

Z[I;J;K;L]+A[I;J]gB[K;L]

Examples
.1.
'")

,,'..

4
6

2 J" x2 :";} 4
I::'
..J
:~
4
B 10
6
:I. ~:j
'»
12
2 3 2 2

(.~~""l

C D E
F

c:'
':. ..1

(\3)".::::(.~

:I.

() () () ()

o :J. () :I.

() () :I. () () ()

... / ( \ J ) ,! • :::: (.)
nTHERE

ARE

ONES y

TWOS y

Related Operators
Inner Product, section 3.5.1

3-74

AND

:J.

THREE

C D E F

APL FUNCTIONS AND OPERATORS

3.5.3

ff - The Reduction Operator

Format
monadic
Argument Types
The argument is a scalar, a vector or one coordinate of an array.
The f can be any scalar dyadic function.
Definition
Specifies that an operation is to be used to combine the elements
of a vector or elements along a specified dimension of an array.
The result of reducing any vector is a scalar value.
The result of reducing an array has a rank that is one less than
the rank of the original array. Thus, the reduction of a matrix
yields a vector.
To specify a coordinate, include it within
square brackets.
(The coordinate is dependent upon the index
origin, Section 4.2.11.)
The default is the highest coordinate.
The special symbol to specify the first coordinate is f (.CS).
If the argument is an empty vector, then the result of a reduction is the identity element of the operator, if one exists.
Table 3-11 lists the identity elements for scalar dyadic functions.
Table 3-11
Identity Elements
Dyadic Operator

Symbol

Plus
Minus
Times
Divide
Power
Residue
Maximum
Minimum
Logarithm
Combination
Circle
And
Or
Nand
Nor
Less
Not Greater
Equal to
Not Less
Greater
Not Equal

1
1
1

*
I

Identity Element

L
e

-1.70l4ll835E38
1.70l4ll835E38
none

none

&
v

1'<

none
none

:s;.

1
1

:?;

>
;t

3-75

o
o

APL FUNCTIONS AND OPERATORS

Examples
n~··>:~·· l 6
I::'

1. 2 3 4

,.J

t· ./~<

x /' ~<
?20

r /;-:

6
I.. /~<

1
.~.

//5 .,',.I

20
'1·/1

6 /

···/1

._,
.I

2
A ~:;AME

(.~ ~:;

l .... 1.) ...../

1"/"/

?
x/

1.
6

:-5

")
A_

+/[2J(.~

10 :1.4
+/[:I.](.~

6 8 4 6

Related Operators
Scan, Section 3.5.4

3-76

APL FUNCTIONS AND OPERATORS

3.5.4

f\ - The Scan Operator

Format
monadic
Argument Types
The argument can be a scalar, a vector, or one coordinate of an
array.
The f is any scalar dyadic function.
Definition
Returns partial results in calculating the reduction of an array.
The shape of the result of a scan is the same as the shape of the
original vector.
The first element of the result is always identical to the first element of the original vector.
The last
element is equal to a reduction of the entire original vector.
For example:
+\3 4 5
3 7 12

If the argument is a null vector, then the result of the scan is
a null vector.
You can also specify a scan for one particular coordinate of a
multidimensional array.
You specify the coordinate to be scanned
by including a bracketed number with the function.
The syntax is
the same as that of the reduction function.
If you omit the
coordinate within brackets, APL scans the last coordinate of the
array.
You can specify a scan on the first coordinate by using
the symbol \ (.CB), which is formed by overstriking the scan
(backslash) with the minus sign.
If the dyadic function specified with scan is associative (for
example, + or x) APL performs the scan in a way that is different
from the conventional scan, in order to increase efficiency by
reducing the number of operations.
The definition of R+f\A is
equal to R[I]=f/ItA as follows:

R[l]=A[l]
R[I]=R[I-l]fA[I]FOR IE1+pA
This definition requires fewer operations than the traditional
scan.
The result of an associative operation of this kind may
differ slightly from the nonassociative approach and should be
used carefully if the results require a high degree of precision.

3-77

APL FUNCTIONS AND OPERATORS

Examples
-l E 6 l E -16

A~lE6
(.~

1000000 -1000000 1.000000000 E -16
+\(.~

1000000 0 1.000000000 E -16
+/(.~

:~:~

4 B

:I.

r',

v '\. ::.:~

2 2

\..-\0
1

()

x\ t /

"'}

6 24 :1. 20 720

....:.

~:)

() -4 ()

\~ [~

8
[lo!-- (.~I~" 2

3r 1. {)

::.~

,.J

-4

I::'
d

.1;
f·'\ (.~

:1.

-4

:1. ~:5

~- \

I:: :I. J (.~I
:-5

,.,

~.::.

I::'

('\

\. I:: 2::r (.~

6
:t. I::'
d

:-5
9

:I.

-4

,.,

+\;(.)

...::.

~';)

I::'

'''J

... J

Related Operators
Reduction, Section 3.5.3

3-78

CHAPTER 4
APL SYSTEM COMMUNICATION

4.1

INTRODUCTION

There are a variety of ways in which you can communicate with the APL
system to change parameters, determine hardware or operational characteristics, and modify processing methods.
The APL system commands
in Chapter 5 facilitate many of these system operations. The elements in Chapter 4 that aid system communication are:
system variables - They are similar to ordinary variables but are
distinguished by special names that begin with a quad character,
for example, ~;iilli1.
system functions - They allow you to interact with APL by specifying distin uished names beginning with a quad character, for
example,
Section 4.2 describes system variables and Section 4.3 describes
system functions.

4.2

SYSTEM VARIABLES

APL system variables allow you to perform such operations as the
following:
1.

Set the index origin and relative fuzz

Change the output precision and line width

Specify an operation to be performed when the workspace is
activated

Save the active workspace automatically after editing

The syntax of APL system variables is similar to ordinary variables in
that you can use both types of variables in any language expression or
function.
APL system variables have distinguished names; they begin
with a quad character (0).
They differ from ordinary variables
because of their special significance to the system.
APL system variables cannot be used as names for user-defined functions. Also, you cannot copy, erase, or collect them in a group.

4-1

APL SYSTEM COMMUNICATION

The 25 system variables described in this chapter serve as an interface between APL and the operating system you are using.
The workspace and the APL processor can each use values specified by the other
as appropriate to the particular operation being performed. The value
of a system variable being used in a workspace can sometimes be different from the value last specified by the user of the workspace.
System variables fall into two categories:
1.

System variables to which you can assign a value.
These
variables retain the value until you override it with another
value or clear the workspace. You can save the value with
the workspace, and you can also localize them in a function
definition. These system variables do have default values.
The following system variables are in this category:

DAUS
OCT
DERRGR
DGAG
DIG

Section 4.2.5
Section 4.2.7
section 4.2.9
Section 4.2.10
Section 4.2.11

DPW
DRL
DSF
DTIMELIMIT

Section
Section
Section
Section

System variables that have values you cannot change.
If you
assign a value to this type of variable, you will not recelve
an error; however, the assignment will have no effect. The
following system variables are in this category:

DAI
DALPHA
DALPHAU
DASCII
DAV
DCTRL
DLC
DNUM
DTIMEGUT
DTS
OTT
DUL
DWA

4.2.1

4.2.16
4.2.17
4.2.lB
4.2.19

Section
Section
Section
Section
Section
Section
Section
Section
Section
section
Section
Section
Section

4.2.1
4.2.2
4.2.3
4.2.4
4.2.6
4.2.B
4.2.12
4.2.14
4.2.20
4.2.22
4.2.23
4.2.24
4.2.25

DAI - Storing Account Information

The DAI (account information) system variable stores the following
account information during a work session:
1.

User identification (for the project-programmer number
[PROJ,PROG] this is PROG+PROJx2*lB)

Computer time (CPU time) used during the current APL session

4-2

APL SYSTEM COMMUNICATION

Connect time used during the current APL session

Keying time (time during which the keyboard is unlocked) used
during the current APL session

All times are expressed in milliseconds.
For example:
OAl

1048708 1235 440967 382458

4.2.2

DALPHA - Alphabetic Characters

The DALPHA system variable is a subset of the DAV system variable,
Section 4.2.6. The value contained in DALPHA is a vector of the 27
alphabetic characters 6 and A through Z.
For example:
OALPHA
oABCDEFGHlJKLMNOPQRSTUVWXYZ

4.2.3

DALPHAU - Underlined Alphabetics

The DALPHAU system variable is a subset of the DAV system variable,
Section 4.2.6. The value contained in DALPHAU is a vector of the 27
underlined characters & and 4 through ~.
For example:
DALPHAU
~a!£PtE9~!JrbM~QE~~§!YYW~X~

OAVtOALPHAU

481 482 483 484 485 486 487 488 489 490 491 492 493 494 495
496 497 498 499 500 501 502 503 504 505 506 507

4.2.4

DASCII - ASCII Character Set

The DASCII system variable contains 128 ASCII characters. This distinguished variable is designed primarily for use with ASCII files,
as an easy way to output arbitrary ASCII codes to those files while
using the APL character set. The first 32 characters of DASCII are
the control characters in DCTRL, Section 4.2.8. The rest are pure
ASCII, not translatable by APL.

DASCII is a subset of DAV. The indices into DAV that contain DASCII
are DAV[257] through DAV[288] and DAV[381] through DAV[476].
DASCII is intended for use with output functions, especially output to
the terminal.
It accepts a list of numbers that it translates into
ASCII codes for transmission.
It does not go through the usual translation from APL 9-bit to ASCII.

4-3

APL SYSTEM COMMUNICATION

When you write to an ASCII sequential file (Section 7.5.1) using
OASCII, you can output the full range of ASCII characters. The
following example writes seven ASCII characters to an ASCII sequential
file while in APL mode. The APL equivalents of these characters print
during output. Once back at operating system command level, you can
access the ASCII characters.
For example:
[J(.~SS

THIS/~~S I

1.2
< :::: >yt····l .....
neLS

)MON
MON 1: TOI:;::

(~TY

THI~:; (. AA~:;

:IJ:%&*@,.' ....
@

fr?

Table 4-1 contains the decimal indices and octal values of OASCII.
Table 4-1
The ASCII Character Set
OASCII (OIO+1)
Index

ASCII Char

Octal Value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DCl
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB

000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027
030
031
032

4-4

APL SYSTEM COMMUNICATION

Table 4-1 (Cont.)
The ASCII Character Set
DASCII (DIO+1)
Index

ASCII Char

Octal Value

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

ESC
FS
GS
RS
US
space
!

033
034
035
036
037
040
041
042
043
044
045
046
047
050
051
052
053
054
055
056
057
060
061
062
063
064
065
066
067
070
071
072
073
074
075
076
077
100
101
102
103
104
105
106
107
110

"
#
$
%
&

' (apostrophe)
(
)

0
1
2
3
4
5
6
7
8
9
:
;
<

=
>

?
@

A
B
C

E
F
G
H

III

J
K

112
113
114
115
116
117
120

L
M
N
0

4-5

APL SYSTEM COMMUNICATION

Table 4-1 (Cant. )
The ASCII Character Set
OASCII COIO+1)
Index

ASCII Char

Octal Value

82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

Q
R

121
122
123
124
125
126
127
130
131
132
133
134
135
136
137
140
141
142
143
144
145
146
147
150
151
152
153
154
155
156
157
160
161
162
163
164
165
166
167
170
171
172
173
174
175
176
177

III

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

S
T
U
V
W
X

Y
Z
[

\
J

(uparrow)
(underscore)
'(grave)
a
b
c
d
e
f
g
h
i
A

j
k

1
m
n
a
P
q

r
s
t
u
v
w
x
Y

z
{
I
I

}

DEL

[]ASCI I[ 124 J through [127J print differently on other terminals such as
on a VTOS or VTS2.

4-6

APL SYSTEM COMMUNICATION

4.2.5

DAUB - Saving a Workspace Automatically

The DAUB (automatic save) system variable activates a special feature
that allows you to save the currently active workspace automatically
at periodic intervals. Workspace backup is often critical when you
are performing an extensive amount of function editing and debugging
or typing a large table of values. Normally, you would stop editing
and issue the appropriate APL commands (Chapter 5) to save the workspace on disk to ensure that a system crash does not destroy the current workspace.
If DAUB is set to 1, APL automatically saves the
workspace on disk every time a function is closed or a quad-input
request is sent to the terminal.
This ensures that you will probably
have to reenter only a small amount of input in the event of a system
crash.
The default value for DAUB in a clear workspace is installation dependent and can be changed by the System Manager. APL saves the value
of DAUB with the workspace, and you can localize it in the same manner
as DIG and several other variables.
When saving a workspace, DAUB creates a disk file and assigns a name
to it in the format:
XNNWWW.TMP:
where

is A, if the job number divided by 100 equals

is B, if the job number divided by 100 equals 1, and so on.
NN

is the job number modulo 100.

WWW

is the first three characters of the current workspace name.

TMP

is extension or filetype.

For example, if the job number is 79 and the workspace name is TESTS,
then the temporary filename will be A79TEB.TMP.
If the job number is
179, the temporary file will be B79TEB.TMP.
If the system crashes and is reloaded, you can verify that a temporary
disk file exists for the workspace by issuing a )LIB command. For
example:

DSK:
A79TES.TMP

After APL displays the sign-on message, you can load the backup file
as the active workspace by issuing a )LOAD command (Section 5.2.4).
)LOAD A79TES.TMP
SAVED

9:49:59

2-JUL-79 5 P

4-7

APL SYSTEM COMMUNICATION

APL prints the )LOAD message. The name of the active workspace is now
the name that the workspace had before the backup was performed, not
the name of the temporary file.
) ""I!!~ I D

TESTS

r:4~204]

After completing the editing of a function or entering data you should
explicitly save the active workspace and delete the temporary backup
on disk.
APL deletes a .TMP file that it has written when anyone of the following conditions occurs:
1.

A )SAVE has been completed successfully.

An )OFF,

) CONTINUE ,

)CALL, or )RUN command is executed.

APL intends to write a new .TMP file with a different name.
For example:
[I(.)US~"

W('~S

:J.

) W~!; I D (.~f.<C
WS

CI...E('~I~:

''lF

2 ~.'j x '? 1 3

[ :J. ]

(.:1 ~ ..

I: 2 :1

:(~< ~ .. (.~ ..:.. 6 B

[3]

''1

AHERE
)LJ:I~<

API... WRITES
'Ic.TMP

THE

.TMP

THE

NEW

FILE

:(I~:;K:

(.~:r.BAX~<C. TMP

) lA, !!; I 1:0 :-: 'T' :;:~
I.AJA~:>

(4f.·C

[4,204]

\';Jf::'

[3]

I~'

[4]

'V
AHERE
)LIX-~

API... WRITES
'It..TMP

.TMP

FILE

X)S K t
(.)18~':'r'~'~. TMP

4.2.6

OAV - Atomic Vector

The OAV (atomic vector) system variable contains a vector of every
character in APL. Table 4-2 lists the characters with their positions
in the vector. Note that the positions are based on an index origin
of 1.
In Table 4-2 characters that are normally non-printable are
output as 0, a squish quad.

4-8

APL SYSTEM COMMUNICATION

Table 4-2
The Atomic Vector DAV (DIO+1)

DAV[ ]

Symbol

TTY Set

Name

1 through 16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41 through 46
47
48
49
50
51
52

.SQ

<I>
~
I

.RV
.TR
.IB
.QQ
.LG
.NN
.NR

squish quad
factorial
reversal
transpose
I-Beam
quote quad
logarithm
Nand
Nor
Comment (lamp)
grade up
grade down
circle (rotate)
back scan
back expansion
squish quad
protected del
quad del
input quad
output quad
divide quad (domino)
format (dollar)
fix
execute
format
squish quad
dieresis
less than
less than or equal
greater than or equal
greater than
question (roll, deal)
omega
epsilon
rho
take
drop (down arrow)
iota
alpha
ceiling
floor
left parenthesis
right parenthesis
left square bracket
right square bracket
right union
left union
up union
underscore
squish quad
left arrow (assignment)
right arrow (branch)
quad (box)
not equal
equal
down union
decode

54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70 through 72
73
74
75
76
77
78
79

!!I
e
tf4I.

,
R

e
f
\

0
~

ffi
ffi
ffi

m
.t
'f

0
<
::;

.GU
.GD
.CR
.CS
.CB
.SQ
.PD
.QD
.IQ
.OQ
.DQ
$

.FI
.XQ
.FM
.SQ
.DD
<

;;:::

.LE
.GE

?
w
E

p
t

.OM
.EP
.RO
A

.DA
.IO
.AL
.CE
.FL

(
)

[

[
]

CI.

]
c
;:)

.RU
.LU
.UU
.US
.SQ

+
~

D
;z!

n
.i

.GO
.BX
.NE
.DU
.DE

4-9

APL SYSTEM COMMUNICATION

Table 4-2 (Cont.)
The Atomic Vector OAV (OIO+l)

[]A V[ J

Symbol

80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

(none)
(none)
(none)

102

(none)

103
104
105
106
107
108
109
110
111
112
113

(none)
(none)
(none)
(none)
(none)
0

0
(none)
(none)

114
115

(none)

TTY Set

.OR
.NT

...

.LO
.AB

,
0

.SO
.EN
.DL
(backspace)
(line feed)
(double line
feed)
(carriage
return)
(null)
(space)
(escape)
(formfeed)
(tab)
.SQ

116
117
118
119
120
121
122
123
124 through 256
257
258
259
260
261

(none)
(none)
0
OCTRL[lJ
OCTRL[2J
OCTRL[3J
DCTRL[4J
OCTRL[sJ

.NG
.SQ
(at @)
(left
bracket)
.LK
(right
bracket)
(uparrow)
(left arrow)
.DM
.LB
.RK
.RB
(tilde)
(delete)
.SQ
.BXCTRL[lJ
.BXCTRL[2J
.BXCTRL[3J
.BXCTRL[4J
.BXCTRL[5J

262
263

DCTRL[6J
DCTRL[7J

.BXCTRL[6J
. BXCTRL[ 7J

I-

(none)
(none)
()

{
-l

}

4-10

Name
and
or
not
reduce
expand
exponentiate (star)
mUltiply
divide
add
subtract
circle (large 0)
residue (absolute)
semicolon
comma
jot (small 0)
encode
del
colon
quote
for internal use
for internal use
for internal use
for internal use
for internal use
for internal use
for internal use
for internal use
for internal use
squish quad
period
negation
squish quad
for internal use
for internal use
left tack
for internal use
for internal use
for internal use
diamond
left curly brace
right tack
right curly brace
for internal use
for internal use
squish quad
null (NUL)
start of heading (SOH)
start of text (STX)
end of text (ETX)
end of transmission
(EOT)
enquiry (ENQ)
acknowledge (ACK)

APL SYSTEM COMMUNICATION

Table 4-2 (Cont.)
The Atomic Vector DAV CDIO+l)
DAV[ ]

Symbol

TTY Set

Name

264
265
266

DCTRL[S]
DCTRL[9]
DCTRL[10]

.BXCTRL[8]
.BXCTRL[9]
.BXCTRL[lO]

267
268
269
270
271
272
273
274
275
276
277
278

DCTRL[ll]
DCTRL[12]
DCTRL[13]
DCTRL[14]
DCTRL[15]
DCTRL[16]
DCTRL[17]
DCTRL[lS]
DCTRL[19]
DCTRL[20]
DCTRL[21]
DCTRL[22]

.BXCTRL[ll]
.BXCTRL[12]
.BXCTRL[13]
.BXCTRL[14]
.BXCTRL[15]
.BXCTRL[16]
.BXCTRL[17]
.BXCTRL[18]
.BXCTRL[19]
.BXCTRL[20]
.BXCTRL[2l]
.BXCTRL[22]

279
280

DCTRL[23]
DCTRL[24]

.BXCTRL[23]
.BXCTRL[24]

DCTRL[25]
DCTRL[26]
DCTRL[27]
DCTRL[2S]
DCTRL[29]
DCTRL[30]
DCTRL[31]
DCTRL[32]

.BXCTRL[25]
.BXCTRL[26]
.BXCTRL[27]
.BXCTRL[28]
.BXCTRL[29]
.BXCTRL[30]
.BXCTRL[3l]
.BXCTRL[32]
.SQ
0
1
2
3
4
5
6
7
8
9
.SQ
.LD

bell (BEL)
backspace (BS)
horizonal tabulation
(HT)
line feed (LF)
vertical tab (VT)
form feed (FF)
carriage return (CR)
shift out (SO)
shift in ( SI)
data link escape (DLE)
device control 1 (DCl)
device control 2 (DC2)
device control 3 (DC3)
device control 4 (DC4)
negative acknowledge
(NAK)
synchronous idle (SYN)
end of transmission
block (ETB)
cancel (CAN)
end of medium (EM)
substitute (SUB)
escape (ESC)
file separator (FS)
group separator (GS)
record separator (RS)
unit separator (US)
squish quad
zero
one
two
three
four
five
six
seven
eight
nine
squish quad
delta

281
282
283
284
285
286
287
288
289 through 304
305
306
307
308
309
310
311
312
313
314
315 through 352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369

0
0
1
2
3
4
5
6
7

S
9

0
f:,.

B
C
D
E
F
G
H
I

C
D
E
F

G
H
I
J
K

L
M

N
0
P

K
L
M
N

4-11

APL SYSTEM COMMUNICATION

Table 4-2 (Cont.)
The Atomic Vector DAV (DIO+l)

[JA V[ J

Symbol

TTY Set

Name

370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426

Q
R
S
T

S
T

W
X
Y
Z

U
V
W
X

DASCII[ 33 J
DASCII[ 34J
DASCII[3SJ
DASCII[ 36 J
DASCII[37J
DASCII[38J
DASCII[39J
DASCII[40J
DASCII[41J
DASCII[42J
DASCII[43J
DASCII[44J
DASCII[4SJ
DASCII[46J
DASCII[47J
DASCII[48J
DASCII[49J
DASCII[SOJ
DASCII[SlJ
DASCII[S2J
DASCII[S3J
DASCII[S4J
DASCII[SSJ
DASCII[S6J
DASCII[S7J
DASCII[S8J
DASCII[S9J
DASCII[60J
DASCII[61J
DASCII[62J
DASCII[63J
DASCII[64J
DASCII[6SJ
DASCII[66J
DASCII[67J
DASCII[ 6 8 J
DASCII[69J
DASCII[70J
DASCII[71J
DASCII[72J
DASCII[73J
DASCII[74J
OASCII[7sJ
OASCII[76J
OASCII[77J
DASCII[78J

.SQ
.BXASCII[33J
.BXASCII[34J
.BXASCII[35J
.BXASCII[36J
.BXASCII[37J
.BXASCII[38J
.BXASCII[39J
.BXASCII[40J
.BXASCII[4lJ
.BXASCII[42J
.BXASCII[43J
.BXASCII[44J
.BXASCII[45J
.BXASCII[46J
.BXASCII[47J
.BXASCII[48J
.BXASCII[49J
.BXASCII[50J
.BXASCII[5lJ
.BXASCII[52J
.BXASCII[53J
.BXASCII[54J
.BXASCII[55J
.BXASCII[56J
.BXASCII[57J
.BXASCII[58J
.BXASCII[59J
.BXASCII[60J
.BXASCII[6lJ
.BXASCII[62J
.BXASCII[63J
.BXASCII[64J
.BXASCII[65J
.BXASCII[66J
.BXASCII[67J
.BXASCII[68J
.BXASCII[69J
.BXASCII[70J
.BXASCII[7lJ
.BXASCII[72J
.BXASCII[73J
.BXASCII[74J
.BXASCII[75J
.BXASCII[76J
.BXASCII[77J
.BXASCII[78J

4-12

squish quad
space
exclamation point (1)
double quote (")
number sign (#)
dollar sign ($)
percent (%)
ampersand (&)
apostrophe (')
left parenthesis «)
right parenthesis(»
asterisk (*)
plus (+)
comma (,)
hyphen (-)
period (.)
slash (I)
zero (0)
one (1)
two (2)
three (3)
four (4)
five (5)
six (6)
seven (7)
eight (8)
nine (9)
colon (:)
semicolon (;)
less than «)
equal (:::)
greater than (»
question mark (?)
at sign (@)
A
B
C

o
E

F
G
H
I

J
K

L
M

APL SYSTEM COMMUNICATION

Table 4-2 (Cont.)
The Atomic vector DAV (DIO+l)

DAV[ J

Symbol

TTY Set

427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442

DASCII[79J
DASCII[80J
DASCII[81J
DASCII[82J
DASCII[83J
DASCII[84J
DASCII[8SJ
DASCII[86J
DASCII[87J
DASCII[88J
DASCII[89J
DASCII[90J
DASCII[91J
DASCII[92J
DASCII[93J
DASCII[94J

.BXASCII[79J
.BXASCII[80J
.BXASCII[81J
.BXASCII[82J
.BKASCII[83J
.BXASCII[84J
.BXASCII[85J
.BXASCII[86J
.BXASCII[87J
.BXASCII[88J
.BXASCII[89J
.BXASCII[90J
.BXASCII[91J
.BXASCII[92J
.BXASCII[93J
.BXASCII[94J

443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477 through 480
481
482
483
484
485

DASCII[9SJ
DASCII[96J
DASCII[97J
DASCII[98J
DASCII[99J
DASCII[100J
DASCII[101J
DASCII[102J
DASCII[103J
DASCII[104J
DASCII[10SJ
DASCII[lo6J
DASCII[107J
DASCII[10SJ
DASCII[109J
DASCII[110J
DASCII[lllJ
DASCII[112J
DASCII[113J
DASCII[114J
DASCII[llSJ
DASCII[116J
DASCII[117J
DASCII[llSJ
DASCII[119J
DASCII[120J
DASCII[121J
DASCII[122J
DASCII[123J
DASCII[124J
DASCII[12SJ
DASCII[126J
DASCII[127J
DASCII[12SJ

.BXASCII[95J
.BXASCII[96J
.BXASCII[97J
.BXASCII[98J
.BXASCII[99J
.BXASCII[lOOJ
.BXASCII[lOlJ
.BXASCII[102J
.BXASCII[103J
.BXASCII[104J
.BXASCII[105J
.BXASCII[106J
.BXASCII[107J
.BXASCII[108J
.BXASCII[109J
.BXASCII[llOJ
.BXASCII[lllJ
.BXASCII[112J
.BXASCII[113J
.BXASCII[114J
.BXASCII[115J
.BXASCII[116J
.BXASCII[117J
.BXASCII[118J
.BXASCII[ll9J
.BXASCII[120J
.BXASCII[121J
.BXASCII[122J
.BXASCII[123J
.BXASCII[124J
.BXASCII[125J
.BXASCII[126J
.BXASCII[127J
.BXASCII[128J
.SQ
.Z@
.ZA
.ZB
.ZC
.ZD

0
tl

d
l2.
Q

4-13

Name
N
0

P
Q
R

S
T
U
v

X
Y
Z
left square bracket ([)
backslash (\)
right square bracket
( J)
up arrow (A)
underscore (-)
grave ( ... )
a
b
c
d
e
f
g
h
i
j

k
1
m
n
0

P
q
r
s
t
u
v
w

x
Y

z
left brace ( { )
vertical bar ( : )
right brace ( } )
tilde ("')
delete (DEL)
squish quad
underscored delta
underscored A
underscored B
underscored C
underscored D

APL SYSTEM COMMUNICATION

Table 4-2 (Cont.)
The Atomic Vector OAV (OIO+l)
O.A V[ ]

Symbol

TTY SET

Name

486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508 through 512

g
E.

.ZE
.ZF
.ZG
.ZH
.ZI
.ZJ
.ZK
.ZL
.ZM
.ZN
.ZO
.ZP
.ZQ
.ZR
.ZS
.ZT
.ZU
.ZV
. ZW
.ZX
.ZY
.ZZ
.SQ

underscored E
underscored F
underscored G
underscored H
underscored I
underscored J
underscored K
underscored L
underscored M
underscored N
underscored 0
underscored P
underscored Q
underscored R
underscored S
underscored T
underscored U
underscored V
underscored W
underscored X
underscored Y
underscored Z
squish quad

f1.
I
~

Ii
I..
1:1.

11
Q

P.
Q

B.
§.

T.
If.
f
Ii

K.
I
Z.
0

Subsets of OAV are:
OALPHA.
OALPHAU.
OASCII.
OCTRL.
ONUM.

4.2.7

Section
Section
Section
Section
Section

4.2.2
4.2.3
4.2.4
4.2.8
4.2.14

OCT - Comparison Tolerance

The OCT (comparison tolerance) system variable sets the degree of
tolerance or relative fuzz (not absolute fuzz) to be applied in performing comparisons. The meaningful range of OCT values is 0 through
1E-S.
The default value is lE-13.
You can specify OCT in conjunction with the following functions:

L
>
~

;:::
<
;t

Ceiling
Floor
Greater than
Less than or equal to
Equal to
Greater than or equal to
Less than
Not equal to

4-14

APL SYSTEM COMMUNICATION

The OCT value is saved when you save the active workspace.
description of fuzz in Section 2.4.3.

See the

For example:
[leT

1 • 1 :'~6B64040t:::"":L :.~

4.2.8

DCTRL - Control Characters

The DCTRL system variable is a subset of DAV (Section 4.2.6).
contains a vector of the 32 characters listed in Table 4-3.

Table 4-3

DCTRL (DIO+1)
Index
1
2
3
4
5
6
7
8
9

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Character Name

Octal Value

NUL (Null)
SOH (Start of Heading)
STX(Start of Text)
ETX(End of Text)
EOT(End of Transmission)
ENQ(Enquiry)
ACK(Acknowledge)
BEL (Bell)
BS(Backspace)
HT(Horiz. Tabulation)
LF(Line Feed)
VT(Vert. Tabulation)
FF(Form Feed)
CR(Carriage Return)
SO(Shift Out)
SI(Shift In)
DLE(Data Line Escape)
DC1(Device Control 1)
DC2(Device Control 2)
DC3(Device Control 3)
DC4(Device Control 4)
NAK(Negative Acknowledge)
SYN(Synchronous Idle)
ETB(End of Transmission Block)
CAN (Cancel)
EM(End of Medium)
SUB (Substitute)
ESC (Escape)
FS(File Separator)
GS(Group Separator)
RS (Record Separator)
US(Unit Separator)

000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027
030
031
032
033
034
035
036
037

Note that for any formatting-control character the internal code that
appears in DCTRL is not the same as the internal code used by APLSF
for that formatting-control character.

4-15

APL SYSTEM COMMUNICATION

For example:
AINDEX ORIGIN
(]AV, IJCTI:;:I... r: l4::1

AWHILE

THE

i~(.~

TAKING

Cfi:I... F

FIRST

HALF

I~~

[]P,V, 11"

102

4.2.9

DERROR - Storing Error Messages

The DERROR system variable contains text that identifies what error
occurred and where it occurred. APL sets DERROR during immediate mode
and function-definition mode as well as function-execution mode.
DERROR contains one error at a time.
When a new error occurs, the new
message overwrites the old one.
You can, however, localize DERROR
within a function to save error information within the environment of
a particular function.
You can also set DERROR to contain your own
message.
In this way, you can clear DERROR by assigning a null string
to it, DERROR".
The text that APL sets contains a character vector of variable-length
lines, each delimited by a carriage return/line feed.
The text has
the following format:
nn error message
funcname [n] line containing the error caret pointing to symbol
in error
where
nn error message is the number and text of the message.
funcname is the name of the function in which the error
occurred.
[n] is the line number where the error occurred.
For example:
VABC;OTRAP;OERROR
[1]

(]TRAP~'~

[2J

:l.A~··~5

[3]

LABtOBREAK

'CHECK

I:: 4::1

'I:;:ESUME

L.:t: NE

[~)]

LAB'

('~T

ERROR

MESSAGE'

0;;'
('~x·:'c

CHECK

?
(.~ F.< C

ERROR MESSAGE
ClEI:;:I:;:OI:;:
S Y N T (.~ ::.( E I:;: I::: (;) I:;:

I:: 2 ::I

:I.

(.~ ~ ~)

,...

4-16

APL SYSTEM COMMUNICATION

) ~:; I
AX-:(C[~'~]

'I<

nAT THIS POINT,

CAN CONTINUE EXECUTION

..~[]I_C+ 1
~:ESUME:

~~T
L. I NI::~ 4
nFUNCTION HAS FINISHED EXECUTION
nNEXT IS AN IMMEDIATE MODE ERROR
c+(.~

:1.1

V('~I_UE

[-!:Fi:I:·:OFi:

c+(.~

nCHECK

GLOBAL VALUE

OF DERROR

[I1~~ I:;: Fi; 0 I~:

1:1.

V('~LUI!!:

E:I:;:I:i:DI:i:

C+(.~

) ~:; :t:

The three lines of text in DERROR are exactly the same three lines APL
displays on the terminal.

DERROR can contain up to 384 characters. If the line containing the
error is too long to fit in DERROR, APL truncates the line and prints
the significant portion containing the error.
The last character will
contain -1 fDA V.
Note that if an error occurs during an
tains six lines of text.
For example:

execute, then DERROR con-

.t. 'WW'

.f.

V('~J...UE

Efl:fl:Ofl:

WW
/\

2~j

EHECUTE

e:F': F.: 0 fl:

.f. I WW I
/\

[]Efl:fl:Ofl:

11 .t.

VALUE

Efl:Fi:or~:

WW
/\
I")e::'

,O;J

EHECUTE

Efl:fl:OFi:

.t. IWW "
/\

For more information on DERROR, refer to Section 6.5.

4-17

APL SYSTEM COMMUNICATION

DGAG - Preventing Interruptions

4.2.10
~~he

DGAG system variable allows you to prevent certain messages from
appearing on your terminal.
On both the TOPS-10 and TOPS-20 operating
systems, users have the ability to send each other messages.
On
TOPS-10, a user can send a message with the SEND command; on TOPS-20,
a user can send a message by LINKing to you with the TALK command.
You set DGAG to either 1 or 0.
The default is installation-dependent.
On TOPS-10, DGAG+1 means "TTY NO GAG" - Accept Messages
DGAG+O means "TTY GAG" - Refuse Messages
On TOPS-20, DGAG+1 means "RECEIVE LINKS" - Accept Messages
DGAG+O means "REFUSE LINKS" - Refuse Messages
On TOPS-10, if you return to monitor level, the DGAG setting will not
inhibit messages.
On TOPS-20, the DGAG setting remains in effect at
monitor level.
For example:
ATOPS····20

:l
)MDH
MOHITOI:;: :

fr:'i

t(·:~ Y'lrl

I NAI... 1.•• A36
TERMINAl... SPEED 300
,:;:EC[ I V[ I... I NI'::~:;
F~FFUSE I!:)DV I CE
RECEIVE SYSTEM-MESSAGES
TFr:;:r-1:r: NAI... NO "'C
TEI:~M

(~cont
.~~ I::' l... ~:; F

:I.
nc-:·{'~G~

)MON
MOH I '1'01:;: :

'!:,e l"lrl
T E r;: t1 :r: N I~ I... I... A ::3 (.

(~\l

TERMINAl... SPEED 300
I:;:[FU~:;E

I... I NI\:~:;

,:;:EFUSE

AD'vIICE

r:~ E C F I I) E

~:) y~:; T [ M.... r'i E n n I~) GE·.. · C

H TOP~:; .... :I. 0

o
) COHT

""01... ['

15:46:24 ll- JUL -79 2 BLKS
TTY44) 15:46:24 Il-JUL-79
COHNECTED
0:01:07 CPU TIME
2 STATEMEHTS 0 OPERATIONS
KIl...O-CO~~-SECS

0:00:00

EXIT

4-18

APL SYSTEM COMMUNICATION

-r TTY
RZ363A KL 11026/1042 15:46:35 TTY44 s~stem 1026/1042
Connected to Node KL1026(26) Line 1 44
Job 61
User MASELLAYS~
[27,2617]
[tSI-(C:
KL1026 S~stem disk DSKC
Er~ Ie:
TOPS-10 Benchmark STR with 7.00 monitor
DSKB:
KL1026 S~stem disk DSKB
NOLC NOTADS NOFORM ECHO CRLF WIDTH:72 GAG NODISPLA
F II... I... : :1. NOTA
·RU APLSF[611v5172]
tf:~ T'm :i. na:l. ~ ~I...I~I
APL-10 DECSYSTEM-10 APLSF 2(412)
TTY44) 15:47:08 WEDNESDAY l1-JUL-79 MASELLAyS.
~:;('~\)ED
1 ~:.=;: 46: 24 11 .... ,JUI... .... 79 2 (
'
[] c; (.~ E.

[27,,2617]

()
[lGi:~G~ ..

:I.

)COHT HOI...D
15:47:33 :l.1- JU I...-79 2 BI...KS
TTY44) :1.5:47:34 :l.1-JUI...-79
C [) N N I::: C T I::: D

() : 00 : 2~:.)

CI::'U

T I MI:::

0:00:00

2 STATEMENTS 1 OPERATIONS
I( :t: 1...0 .... COI:;:I::: .... ~:;EC~:;

<»

EXIT
-1 TTY
RZ363A KL 1:1.026/:1.042 15:47:42 TTY44 s~stem 1026/1042
Connected to Node KL1026(26) Line. 44
Job 61
User MASELLAYS~
[27,,2617]
DSKC:
KL1026 S~stem disk DSKC
ERIC:
TOPS-10 Benchmark STR with 7.00 monitor
DSKB:
KL1026 S~stem disk DSKB
NOLC NOTABS NOFORM ECHO CRLF WIDTH:72 NOGAG NODISPLA
FILl...: 1 NOTAPE TYPE"'C

You can localize DGAG in a user-defined function.
DGAG cannot be
saved with your workspace, however, its setting remains unchanged
during a )LGAD or a )CLEAR operation.

4.2.11

DIG - Index Origin

The DIG (index origin) system variable changes the setting of the
index origin.
This setting determines whether the values of a vector
or array are indexed beginning with position 0 or 1. The default is

1.
The index origin is important in array operations and in conjunction
with roll and deal (Sections 3.2.4 and 3.3.3). The value is saved
when the active workspace is saved and is only meaningful if it is 0
or 1. This system variable is equivalent to the )GRIGIN command,
Section 5.5.4.
DIG is used with the following operations:
lA, ?A,

A?B, A[], AlB.
4-19

APL SYSTEM COMMUNICATION

For example:
[]:rO~"l

1 2 3

I] ~ .. ~~~ .. 2

4f\(.)

3
1

.:..

+/[2]A

10 14

+/[:J.]A

6 f:I 4 6
+/[()](.~

f:I

:r NX:IE~'~

F::I~:I:i:O~:

+/[()](.~

[]:r ()~ .. ()

012
+/[2]1~

f:I

l: NDEN

E::~:J=;:OFi:

+/[2]A
+/ I:: 1 ](.~

10 14

+/ I:: ():1 (.~

6 B 4 6

4.2.12

OLe - Reporting on Executing Functions

The OLe (line counter) system variable is used to obtain a partial
report on functions that are currently being executed.. It is stored
as a vector of the line numbers contained in the state indicator,
arranged in order of the most recently suspended function first.
The
default value for OLe is o.
The OLe system variable is particularly useful in branch statements
(Section 6.4.1). You can specify that execution is to resume
immediately following the line number at which function execution was
most recently suspended with OLe.
For example:
~)HEI""

[lJ

.. ~ 1.

[2::1

18 ATTENTION SIGNALED
1:1 ..d

NE~W[

(]LC

4-20

APL SYSTEM COMMUNICATION

4.2.14

DNUM - Digits

The DNUM system variable is a subset of the DAV system variable
(Section 4.2.6).
DNUM contains a vector of the ten digits, 0, 1, 2,
3, 4, 5, 6, 7, 8, 9.
For example:
I]NUM

o12:34!::i 6 ?09
[](.~v t []NUM

:305 :306 :30? :300 309 310 311 312 :313 :314

4-21

APL SYSTEM COMMUNICATION

4.2.15

OPP - Output Precision

The OPP (print precision) system variable determines the precision of
non integer output by allowing you to set the number of significant
digits to be displayed.
Legal values for OPP are integers 1 through
18. The default is 10.
The OPP system variable does not affect the
precision of internal calculations or the display of numeric constants.
For example:
opp

123456789.123456789
123456789~1
OPP~5

123456789.123456789

DPP~15

123456789.123456789
123456789.123457

APL rounds off a number if it contains more digits that the setting.
The precision you specify is saved when the active workspace is saved.
OPP is equivalent to the )DIGITS command (Section 5.5.1).

4.2.16

OPW - Determining the Width of the Output Line

The OPW (page width) system variable sets the maximum number of
characters that can appear on a terminal output line, before a
carriage return/line feed is performed.
Legal values for OPW are
integers 30 through 390.
The default is 120.
OPW has no effect on
the display of messages or the length of input lines.
For example:
OPW~30
O~A~ITHIS

THIS

A TEST

IS A TEST OF THE
TH VARIABLE.

PAGE

THE

PAGE

WIDTH

VARIABLE. I

WID

The width is saved along with the active workspace.
to the )WIDTH command (Section 5.5.6).

4-22

OPW is equivalent

APL SYSTEM COMMUNICATION

4.2.17 ORL - Setting a Random Link

The ORL (random link) system variable sets the seed of the pseudorandom-number generator in APL. This generator is used with the roll
and. deal functions (Sections 3.2.4 and 3.3.3). The range of meaningful values you can specify is -1+2*1 through -1+2*35. The default
value is o.
Every time you specify either a roll or deal operation, you change the
value of the random link.
For example:
ORL

5?5
1 3 5 2 4
ORL

30388006192
5?5
1 4 532
ORL

9311234783

The value of ORL is saved when you save the active workspace.

OSF - Setting the Evaluated Input Prompt

4.2.18

The OSF (signal for evaluated input) system variable changes the
standard signal message used as the prompt in accepting evaluated
input. You can use any printing character(s) as the prompt for
evaluated output. The default is:

carriage return/line feed 6 spaces

For example:
A~3+0+5

0:
13

0:
IINPUT'
B
INPUT
OSF~IWHAT

IS YOUR

NAME?

c~O

WHAT

IS YOUR NAME?

ISARAHI

c
SARAH

Note that you must enclose the character input within single quotation
marks in evaluated input.

4-23

APL SYSTEM COMMUNICATION

4.2.19

DTIMELIMIT - Setting a Time Limit

The DTIMELIMIT system variable sets a limit to the amount of time you
have to respond to a quote-quad input request (~) or a quad-del input
request (~).
The range of meaningful values you can specify is -1 to
262143 milliseconds.
Example:

n T I /Vi E I... I MIT ~" ~:,:j () () ()
(:~~"

YOU

HAVE

FIVE

SECONDS

FIVE

SECONDS

FIVE

,::1

YOU

HAVE
(.~'l" I~I

'r'O!.!

11.

H('~VE
V('~I...UE

EF;:I:;:O~:

COH1)~:i

ARAH

OUT

TIME

(.~

YOU

HAVE

FIVE

If you exceed the time limit, APL accepts only the data you typed
before you ran out of time. Any input accepted ends with a carriage
return/line feed.
Note that by specifying a negative argument (-1) to DTIMELIMIT. you
can set APL to accept type-ahead input. This feature can be useful
if you are accepting input from a pseudo-terminal (PTY).
To find out whether you or another user ran out of time, use the
DTIMEOUT system variable (Section 4.2.20).

4.2,.20

DTIMEOUT - Reporting on Time Limit

The DTIMEOUT system variable reports whether a user ran out of time
during a quote-quad input request (~) or a quad-del input request
(~) with a DTIMELIMIT set.
DTIMEOUT is set to either 1 or 0: a 1
means that the user ran out of time, a 0 means the user did not run
out of time.

4-24

APL SYSTEM COMMUNICATION

For example:
[IT:I: MEI... :t: MIT ~ .. ~::.iOOO
~~f'I~1

YOU

HAVE

FIVE

SECONDS

[IT :1: ME OUT

o
ADID

NOT

RUN

OUT

TIME

(.~~"I~

YOU

HAVm:

1.:1.

V('~I...UI~:

FIVE
EI:;:I:;:OI:;:

~;;ECOND~:;

[IT:1: JI.~EOUT

:1.

The value of OTIMEOUT remains constant until you type one of the
following:
1.

Quote-quad input from the terminal

Quad-del input from the terminal

Input from a pseudo-terminal (PTY).

4-25

(~).

APL SYSTEM COMMUNICATION

4-26

APL SYSTEM COMMUNICATION

4.2.22

OTS - Reporting Current Time and Date

The OTS (time stamp) system variable obtains the current time and date
and stores it as a 7-element vector in base 10 format.
This vector is
known as a timestamp and contains the following elements:
current year, month, day, hour, minute, second, millisecond
For example:
OTS

1979 7 2 13 44 47 70

4.2.23

OTT - Reporting Terminal Type

The OTT (terminal type) system variable contains a value that relates
to the type of terminal being used for the current APL session. When
you run APL, you specify the terminal type in response to
TERMINAL ••

APL stores this information according to the following table:
Table 4-4
OTT Terminal Types
Value

Meaning

TTy-type terminal
TTYCOM terminal
LA36 or Tektronix 4013, 4015
APL keyboard- or typewriter-paired
ASCII/APL terminal
APL bit-paired ASCII/APL
APL ONTEL
Reserved
2741 Selectric-Type

1
2
3
4
5

6-9
10

For example:
OTT

4-27

APL SYSTEM COMMUNICATION

4.2.24

OUL - Reporting the Job Number

The OUL (user load) system variable contains the system job number
associated with the current APL session. The value is stored in base
10 format.
For example:
OUL

4.2.25 OWA - Reporting the Available Work Area
The OWA (work area) system variable contains the amount of available
storage space in the active workspace.
This value allows you to
determine the maximum amount to which your workspace can increase.
The size is given in bytes, not words. APL obtains the value by
subtracting the current data-segment size from the maximum datasegment size.
For example:
OWA

73232

4.3

SYSTEM FUNCTIONS

The system functions described in the following sections allow you to
perform such operations:
1.

Expressing the canonical representation of a function and
storing the function definition as data

Expunging a named object

Constructing a name list of labels, variables, or functions
and returning the classification of a named object

Delaying execution of a function for a specified period of
time

System functions are an integral part of the APL language and can be
used freely in all APL function definitions. The names of the 13
system functions described in this section all begin with a quad (0)
character and are reserved words. Like system variables, system
functions cannot be copied, erased, or collected in a group.

4-28

APL SYSTEM COMMUNICATION

You access a system function by simply stating its name with
arguments, as you would access a primitive or user-defined function.
The system functions described in this chapter are:

OEX
OFI

Section
Section

ONL
OQCO
OQLD

Section
Section
Section
Section

4.3.1

4.3.8
4.3.9
4.3.9
4.3.9

OBREAK - Suspending Execution

Format

OBREAK arg
where
arg is any APL object.
The OBREAK system function suspends execution of the function in which
it is contained and returns you to immediate mode.

OBREAK is a monadic system function.

It takes any APL object as an
argument and prints that argument before breaking to the terminal.

For example:
.;;}FUI·~C

[1]

'FII:':~:;T

I... I 1-11::: '

[2J
I: ~~]

OBREAK

'BREAK

'RESUME

LI1-IE

[4]
FUNC

F·;[F':!:)T
X~F':F.::~~ 1<

I...IHE
('~T

L:t: HE

) ~::. :t:

FUNC[:;?]

"/(

··~nLC+ 1

F':I:::j:;UME

('~T

I... :t: NE

:·5

To return to function execution after a break, you can either go to a
specific line number (~3) or use the system variable OLC.
Specifying
OLC would return you to the line where the OBREAK executes. To resume
at the line after the breakpoint, specify OLC+l.
Note that OBREAK is illegal from immediate mode and

execute.

For more information on the use of OBREAK, refer to Section 6.5.

4-29

APL SYSTEM COMMUNICATION

4-30

APL SYSTEM COMMUNICATION

4.3.3

DDL - Delaying the Execution of a Function

Format

DDL arg
where
arg is the number of seconds you want to delay execution. The
argument must be a scalar or vector with a single numerical value
(1~ppARG) or APL returns a 9 RANK ERROR or a 15 DOMAIN ERROR.
There is no limit to the value of the argument.
Although DDL specifies the desired duration of the delay of the
function, the actual delay can be somewhat different. Other demands
on the APL system at the time that the DDL is issued can affect the
accuracy of the delay.
In addition, you can use a single attention
signal, CTRL/C, at any time to abort the delay and cause an interrupt
in the function in which the DDL appears.
For example:
DEL~DDL

DEL

DEL is a scalar value equal to the actual delay incurred as a result
of the 2-second DDL specification.
The DDL function uses a negligible amount of computer time; you can
issue it freely in situations where tests are required at periodic
intervals to determine whether or not an event has occurred as
expected.
This is helpful in simplifying interuser and interprogram communication of various kinds. Another way to wait specifically for input is
to use DTIMELIMIT, Section 4.2.19.

4.3.4

DEX - Erasing a Named Object

Format

DEX arg
where
arg is a function name enclosed in single quotation marks or a
variable name whose value is a matrix of function names.
Therefore, the argument can have a rank of 2 or less
(2~ppARG).
The DEX (expunge) system function erases a variable or function name
so that you can reuse it without confusion.
DEX operates on global or
dominant local variables. You cannot erase a named object that refers
to a label, a group, a suspended or pendent function, or a system
variable.

4-31

APL SYSTEM COMMUNICATION

When you erase a name (or names) DEX returns a 1 or a 0 depending upon
whether the name was successfully erased. A 1 signifies that the name
was erased; a 0 signifies that the name cannot be erased. You also receive a 0 if the name is not a legal APL variable name.
APL returns a 9 RANK ERROR if the argument has a rank higher than 2,
and returns a 15 DOMAIN ERROR is the argument is not a character string.
For example:
)FNS
GROW

ABCD

A~3

TEST

4f'ABCDTESTGROW'

ABCD
TEST
GROW
OEX A

111
)FNS

(APL outputs at blank lines)

4.3.5

OFI - Converting Characters to Numerics

Format

OFI arg
where
arg is a character scalar, vector, or one-element array.
The OFI system function takes a character argument and converts it
into a numeric, placing zeros in each position that does not corres,pond to a valid number. Note that a minus sign preceding a number is
not part of the number but is rather an operation to be performed on
the number. However, in the expression -5, the negative sign is a
valid part of the number in APL.
For example:
VZ~AVERAGE

[lJ
[2J
[3J

Z~~

[4]

~.5

A LIST

~;D~'ENTER

Z~(OVI

Z)/OFI

Z~(+/Z)~fZ

AVERAGE
A LIST OF NUMBERS
A 0 +2 -.5 6 • •

In the previous example,

OVI is 1 1 0 1 1 1 1 0
OFI is 1 3.5 0 0 2 -.5 6 0

4-32

NUMBERS'

APL SYSTEM COMMUNICATION

4-33

APL SYSTEM COMMUNICATION

4.3.7

ONe - Returning a Name Classification

Format

ONe arg
where
arg is a character matrix of names or a vector or scalar consisting of one name. The rank of the argument is 2~ppARG.
The ONe (name classification) system function returns the classification of a name or group of names.
If the argument is a matrix,
ONe returns the class of the name represented by each row in the
matrix.
If the argument is a vector or scalar, ONe returns the class
of a single name.
ONe returns a numeric value representing each name
class. Table 4-5 lists these values.
Table 4-5

ONe Classes
Value

Meaning

Name available for any use

Label name

Variable name

Function name

Not available for use as a name

A value of 4 implies that the argument is not a valid name or that it
is currently in use as a group name (Section 5.4.4).
For example:
[INC

I ('~VEH I

4-34

APL SYSTEM COMMUNICATION

4.3.8

ONL - Constructing a List of Labels, Variables, or Functions

Format

[a]ONL n
where
a

is a scalar or vector of alphabetic characters. The letters
must be supplied in alphabetic order. This parameter is
optional.
(Do not type the square brackets.)

is one or more integer scalars or a vector from the following list:
Values

Meaning

Labels
Variables
Functions

The ONL (name list) system function can be either monadic or dyadic
depending on whether you supply the left argument.
In both forms, the
function constructs a list of named objects residing in the active
workspace.
The "n" parameter identifies the type of named objects to
be included in the list.
For example:
>:~

.. []HI...

:1.

causes the names of all labels and variables in the workspace to be
included in the name list X in alphabetic order. Each row of the
matrix will contain the name of one label or variable.
The number of
columns is determined by the length of the longest name.
ONL fills
the shorter names with blanks to the length of the longest name.
The dyadic form of ONL allows you to restrict the name list to names
beginning with specified characters by including an "a", left argument, in the expression.
For example:
HLIST~'ABCDEF'

[]NL

NL:t:!:;T
(,:,Vf~: f;: ('~G E

c: (.~ I":
FUNC

causes a name list to be constructed of function names whose initial
letters are A through Pi the list is arranged in alphabetic order.
The ONL system function is useful for a variety of purposes.
these are described below:

Some of

1.
You can
so use
t to analyze interactions between variables and functions.
(Remember to remove the blanks on the right, if any exist.)

4-35

APL SYSTEM COMMUNICATION

In conjunction with OEX (Section 4.3.4), the ONL function can
cause all of the named objects in a certain category to be
erased dynamically.
It also helps the design of a function
that can be used to clear a workspace of all but a preselected
collection of named objects.

In its dyadic form, DNL can guide you in choosing names while
developing or interacting with a workspace.

The following example illustrates the construction of a matrix containing the names of variables in the active workspace that begin with
the letter V.
I-II... I S T to. I v 'ON L

I-ILIST
V~~F;:l

VAI:;:2
VAF;:203
vj!~fi:99

VBMA:-(

4.3.9

DQLD, OQCO, OQPC - Loading and Copying a Workspace

Format

OQLD arg
OQCO arg
DQPC arg
where
arg in each case is a character vector (enclosed in single
quotation marks) representing the workspace name, an optional
password and an optional list.
The password is the password associated with the owner of the
workspace.
The password is necessary only if you are not
privileged to access the particular workspace.
(Do not type the
square brackets.)
The list is an optional parameter used to identify specific
objects to be copied.
If you omit this parameter, all functions,
variables, and groups in the workspace are copied.
(Do not type
the square brackets.)
The DQLD, DQCO, and OQPC system functions perform the same operations
as the )LOAD, )COPY, and )PCOPY commands described in Chapter 5.
OQLD
loads a workspace, OQCO copies a workspace, and OQPC copies a workspace with certain protection considerations.
Unlike the system commands, the system functions do not return messages
to verify a successful load or copy. The system functions, however,
return the messages OBJECTS NOT FOUND and NOT COPIED: when applicable.
These are not inhibited.

4-36

APL SYSTEM COMMUNICATION

Also, APL does not output a blank line to indicate that no value was
returned. Therefore, you can ~se one of these system functions alone
or as a function line without blank lines a
on your terminal.

The OQPC system function does not cause APL to return the names of
objects that were not copied.
If an error occurs during the execution of any of these three system
functions, APL prints an error message. Therefore, you can trap
errors as usual with the use of the execute function (Section 3.4.3).
For example:

SAVED

) I...D(:~r;. T
13:53:13 11-JUI...-79 5 P

:I.
) CI... E('~I';:
CLF.~Ar:

ws
[]C~l...r.:o

T I

) tAJ !:i l: X)

<()()7>

[4~2()4]

1
) CI...E('~I';:
CLI:::('~I:;:

W!:;

SAVEr;.

) c C) I'" Y T (.~ 1·:<
13:53:13 11- JU I...-79 6 P
~~

X:<

2
C'

1:1.

V (.~ I... U m:

E~ I';: I::: 0 I';:

f'
A

) CLE(')F;:
CL..F.::('~fl:

[]GCO

'T'

1
")

.:.

) CI...E('~I';:
CJ...I:::('~I:;:

ws
[IC~CD

(.~

X':< I

1
2
1:L

V('H .. UI:::

1:~r:fi;(Jfi:

4-37

APL SYSTEM COMMUNICATION

)CLEAR
CLEAR

WS
)COPY

TAD

SAVED
13:53:13 11- JUL -79
D
OBJECTS NOT FOUND:
A

VALUE
B

ERROR

)CLEAR
CLEAR

oaco IT A DI
OBJECTS NOT FOUND:
)CLEAR
CLEAR

WS
A~20

)PCOPY

SAVED
13:53:13 11- JUL -79
NOT COPIED:
A
A

3
)CLEAR
CLEAR

WS
A~20

OGPC
NOT

ITI

COPIED:
A

3
CLEAR

)CLEAR
WS
Z~DQCO

OBJECTS

o
CLEAR

NOT

A DI

FOUND:

)CLEAR
WS
Z~DQPC

OBJECTS NOT

A DI

FOUND:

4-38

APL SYSTEM COMMUNICATION

4-39

APL SYSTEM COMMUNICATION

4.3.11

DVI - Validating Input

Format
DVI arg
where
arg is a character vector, scalar, or I-element array.
The DVI (validating input) system function is used in conjunction with
the DFI system function (Section 4.3.5). While DFI converts a character vector into a numeric vector, DVI returns a Boolean vector that
contains a 1 in each position corresponding to a valid number that can
be converted with DFI.
It returns a 0 for nonvalid numbers.
For example:

OVI

1 1 0 1 0 1 0 1
OFI
1~5

3 0 -5 0 1+000000000 E 15
(OVI

A)/OFI

0-3

1+5 3 -5 1.000000000 E 15

-3

4-40

CHAPTER 5
SYSTEM COMMANDS

5.1

INTRODUCTION

APL provides a wide variety of system commands to communicate with the
APL system and to control the operating environment in which the APL
session is conducted.
System commands allow you to examine or change
the state of the system. For example, they allow you to:
1.

Clear, save, or name the active workspace

Load or copy a workspace from a secondary storage device

List workspace, variable, function, and group names

Determine memory and workspace size, time and system
resources used, and version and device information

Display the status of functions and local variables in the
workspace

Set the index origin, the maximum number of significant
digits, and the output line width

System commands are not considered a part of the APL language itself,
but can be viewed as an interface between you and the language interpreter.
System commands implemented for use with the APL file system
are described in Chapter 7. Appendix B provides a summary of the
format of all system commands in alphabetic order.
This chapter is structured in the following way.
Section 5.1 provides
an overview of the format for system commands, the two ways of using
system commands (action and inquiry), characteristics of workspaces,
and APL libraries that allow you to share programs with other APL
users.
Sections 5.2 through 5.7 describe the system commands themselves by category:
Section

Commands

5.2

Basic Workspace-Control

5.3

Extended Workspace-Control

5.4

Workspace-Content

5.5

Workspace-Environment

5.6

APL Termination

5.7

Miscellaneous
5-1

SYSTEM COMMANDS

Section 5.8 discusses the special function of the execute function (€)
in relation to system commands.

5.1.1

System Command Format

Unlike other APL statements, system commands begin with a right parenthesis, as shown in the following format:
) command-name [parameter-list]
You can abbreviate the command-name to its shortest unique form, which
usually requires no more than four characters.
Some system commands
require one or more parameters or arguments in the command string.
If
you include required or optional parameters, you must separate the
individual elements of the command string with at least one space.
(Do not type the square brackets.)
The following examples illustrate the format of several system
commands:
)I':CG1TS

WAS

10
)D1G1

C'
,J

)[OIGIT

) SAVE

M'y'WOF;: K

14:38:11 ll- JUL -79 1

PGS
)COPY WS40-SESAME ABC

SAVED

VAR6

14:36:45 11- JUL -79 6 P

The first three examples invoke the same system command, )DIGITS,
since the first four letters of each of the command names are the
same; note that extending a command name beyond its unique form (four
letters) has no effect.
In the fourth example, MYWORK serves as an
additional argument to the )SAVE system command.
The fifth example
illustrates the inclusion of a series of parameters in the )COPY command.
Only WS40 is a required argument; the password and name list
are optional (see Section 5.4.1).

5 .. 1.2

Action and Inquiry Commands

You can use APL system commands for two distinct purposes:
To obtain information - inquiry commands
To change the state of a workspace or operating environment action commands
Action commands cause some change in the state of the APL system.
Inquiry commands report on the state of the system but do not change
this state in any way.

5-2

SYSTEM COMMANDS

The )MON command is an example of an action command.
To return to
operating system command level, specify the following:
)MON
MOH:t:TOFl: :

The )SI command, on the other hand, operates as an inquiry command.
It reports the status of APL program execution.
For example:
)SI
F"Fn:MI~:f:;[2]

1t.

You can use many system commands as both action and inquiry commands.
The distinction between action and inquiry is made by the inclusion of
optional parameters.
The )ORIGIN command is an example of a command
you can use in both ways.
The )ORIGIN command can either (1) change
the index origin setting associated with an array specification
(action) or (2) return the current setting of the index origin
(inquiry) .
The first example below shows the use of )ORIGIN as an action command;
this command sets the index origin to 0 and also reports that the previous setting was 1.
The second example shows the use of )ORIGIN as
an inquiry command; this command reports that the current setting of
the index origin is o.
)DR:t:G:t:H
W('~f:;

:1.

5.1.3

Workspace Characteristics

The APL system uses a buffer in your memory area to store functions,
variables, and values, information on the status of functions, group
descriptions, and any temporary results obtained while executing APL
statements. When available in memory, this buffer area is known as
the active workspace.
You can enter system commands that cause this active workspace to be
saved on a secondary-storage device; subsequently, you can load the
saved workspace into the buffer area to function as the active workspace once again.
The term "workspace" is used to refer to either the
active workspace or a version of an active workspace now saved in
secondary storage.

5-3

SYSTEM COMMANDS

Many of the system commands described in this chapter aid in changing
the status of a workspace. For instance, you can clear, save, load,
name, lock, and delete a workspace. You can also copy functions,
variables, and other elements from a saved workspace into an active
workspace and di·splay their names. Workspace size, owner, and password information can be reported. As an APL user, you have extensive
control over the activity and characteristics of the workspace in
your system.

5.1.3.1 Workspace Names - Each APL workspace defined in your disk
area has a unique name associated with it.
In the command formats
presented in this chapter, this name is represented by the parameter
"wsname".
The workspace name has five distinct parts:
1.

Device name

Filename

Extension or type

Protection code

Directory

Your directory

5.1.3.2 The CONTINUE Workspace - When you terminate an APL session
with the )CONTINUE command (see Section 5.6.2) APL saves your workspace on disk and names it CONTIN.APL.
The CONTINUE workspace is an
image of the active workspace as it existed at the time of termination.
It has the workspace name:
DSK:CONTIN.APL<std prot>[directory]
where
<std prot> is an installation-dependent standard protection code
[directory] is your directory
APL recognizes CONTIN as a special workspace.
If a CONTINUE workspace
exists in your disk area, APL loads it as your active workspace when
you begin the APL session.
This means that when you run APL instead
of having a clear workspace, you will automatically have the workspace
you saved with )CONTINUE.
The CONTINUE workspace replaces any existing one on disk.
You can also backup your workspace periodically by setting the DAUB
system variable to 1.
Refer to Section 4.2.5 for more information on

DAUS.

5-5

SYSTEM COMMANDS

When you )CALL something, your active workspace is in CONTIN.APL and
will start up at the line 1 plus the )CALL line.

5.1.3.3 Workspace Passwords - In addition to the unique name, each
APL workspace can also have a password associated with it. A password
begins with a hyphen and can have up to eight more characters. The
default is a hyphen (-). This is considered a null password. For
example:
-SESAME

Workspace passwords provide additional workspace protection.
If you
want to use a password-protected workspace, you must specify the
password associated with that workspace before APL allows you to
retrieve it from secondary storage.

5.1.3.4 Groups - Various functions and variables in a workspace can
sometimes be easier to work with when they are treated as elements in
a single logical collection. This approach is aided by the "group"
concept in APL, which allows you to treat functions and variables as
logical entities. Several system commands are available that allow
you to define a new group, list the members of a group, add members to
or delete members from an existing group, erase or "undefine" a group.
See Sections 5.4.4 through 5.4.6.

5.1.3.5 The State Indicator - Every APL workspace contains a status
vector known as the state indicator. This indicator stores information on the execution of functions within the workspace. You can
obtain a report on the status of APL functions by issuing an )SI or
)SIV system command (Sections 5.4.8 and 5.4.9). These commands list
the contents of the state indicator, which identifies suspended and
pendent functions.
A suspended function is one that has stopped
executing for some reason. A pendent function is one that contains a
call to a function that has not completed. The pendent function is
waiting for the called function to return.
If the state indicator is "empty", no functions are currently suspended
or pendent. The use of the state indicator in debugging and executing
functions is described in Section 5.4.8.

5-6

SYSTEM COMMANDS

5.1.4

APL Libraries

A special library facility is available through the APL system that
allows you to make your programs available to all APL users. You can
save programs in workspaces on a library device and subsequently allow
other users to retrieve them. All workspaces you store on a library
device must be assigned a library~device name as the device name portion of the workspace name. A library-device name consists of the
characters LIB, followed (without intervening blanks) by an integer in
the range 1 through 999, followed by a colon.
Some examples of possible library-device names follow:

LI B 44S:
L 1B 001:

The third example, LIB001:, is equal to both LIB1: and LIB01:.
Workspaces specified with a library device do not have file extensions
or file types associated with them.
CAUTION

LIB: activates a special password system, so if the library workspaces are
removed to another area, you might need
to rename them.

5.2

BASIC WORKSPACE-CONTROL COMMANDS

This section describes the basic workspace-control commands. These
commands allow you to manipulate APL workspaces in a variety of ways.
You can:
1.

Clear or name the active workspace

Delete workspaces when no longer needed

List the names of workspaces in your area or in a library

Specify, change, or return a password for a workspace

Save the active workspace on a secondary storage device and
retrieve it when required

5-7

SYSTEM COMMANDS

5.2.1

)CLEAR - Clearing the Active Workspace

Command

)CLEAR
Example
) CL..E('~F;:
Cl..E('~i:;:

ll.,l!;;

'rhe )CLEAR system command closes all open files and clears the active
workspace by replacing it with a special workspace known as the clear
workspace.
)CLEAR resets all the workspace constants to their defaults.
APL also gives you a clear workspace when you begin a work session unless you have the CONTINUE workspace (CONTIN.APL) in your disk area.
'rhe clear workspace contains the default values for all workspace
related system functions:

Contains no functions, groups, or variables.

Has an index origin of 1 (DIO).

Has an output line length determined by the operating system
width specification.
You can change the output width with
DPW. See Section 4.2.16.

Displays numbers with 10 significant digits.
This output
precision can be changed with DPP.
See Section 4.2.15.

Has a clear symbol table and state indicator.

Has the name CLEAR WS
Cannot be saved without being given a name with either )WSID,
or )SAVE.

Has the null password hyphen (-).

Requests quad input with the message 0: followed by a
carriage return/line feed and six blanks.
(DSF)

APL uses a symbol table to record function, variable, and group names
and constants.
The size of this symbol table expands as new names are
specified and is limited only by the size of the workspace.

5-8

SYSTEM COMMANDS

)DROP - Deleting Stored Workspaces or Files

5.2.2
Command

)DROP wsname [switch-list]
Examples
) x:ot:;: C) P

9:15:30

:J: NT. f.< 2 ()
6- JUL -79

X) S I( :

T E ~i; T • (.~ Xi< I
TEST
TE~i;T •

x':<20

TEST • M('~C

) l:1~:DP

TE~:; T •

'/(

:COI:;:()PF'ED:
TE!,iT. (:~B:I:
TE~i;T

TE~;

r • 1:'<20

TEST + M('~C

9:16:14

6- JUL -79

The )DROP system command is an action command that deletes stored
workspaces or files.
)DROP can delete any system file for which you
have the necessary protection privileges. You can erase one, several,
or all of the files on a directory device.
To delete a single workspace or file, specify the. name as the parameter. As described in
the )LIB command, Section 5.2.3, you can use an asterisk as a wildcard
designator.
If you use the asterisk, APL lists the deleted files.
In
both cases, APL displays the time and date of the )DROP request.
You can also include a switch-list in the )DROP command string. These
switches are the same as the ones listed in Table 5-2.
If you include
a switch, )DROP displays the information applicable to the file just
prior to its deletion. For example:
) X:O~:DI::'

W~i;9

/1;'<

X)I:;:OPI::'ED:

F II...E
w~i;9

9::1.7:23

l.·:<I...I{!ii
:I.
:I.

6- JU I...-79

The example above displays the number of blocks freed by deleting the
workspace named WS9.
On TOPS-20, the file is deleted but not expunged.

5-9

SYSTEM COMMANDS

)LIB - Listing Workspace Names

5.2.3

Command
)LIB [wsname][switch-list]

Examples
) L. I 1·:<
DSI( :
(~LI::'H~~

CH(-'j!;;
G I::: 0 j!;; G I:::

PF'; I ME::
) S('WE

WS40

14:56:23 I1- JU L.-79 1

PGS

) L. I I-:'
X:I~:; K

AI... PH(.~
CH(.~j!;:

Gt::':OFl:GE
PI~:lMF.::
W~-)4()

) '::i('~VE

w'::i40. V(')F':

14:57:32 I1- JUL -79 1
)I...1l:<

PGS

w'::;40.*

WS4()
w540. V('~I:;:

) I... I 1..:<

"It.."/(

{IS I( :
(~L..f!"H('~

CHAI:;:
GE-:OI~:GE

L.OG 1 N. CMII

L. () GIN • E::)< E
F:'r~: 1 ME:

WS40
~'S4(). VAj!;:

)1...18

FILE:

I...OG1N.CMD

I-:<'-.1{5

:o~:; K :

I... C>G:I: N. CMII

1
1

The )LIB system command is an inquiry command that displays a list of
workspaces in your disk area.
)LIB assumes that any file in your disk
area with the extension or file type .APL, contains a workspace.
You can use the )LIB command to list the names of all or selected
files on any directory device.
These files need not be APL workspaces.

5-10

SYSTEM COMMANDS

If you specify the wsname, you can specify the filename or file type
to be displayed. You can identify a particular file or use the
"wildcard" character, the asterisk, to substitute for the filename
and/or extension or type. The asterisk matches any name. For example,
this command lists the names of all files that have WS40 as their
filename:

This command lists the names of all files on device DSKH:.
) I... :r x·:<

X:I!::·I<

lui: '/I. • 'J(

The optional switch-list parameter is used to obtain information about
files on directory devices. A description of all switches supported
with the )LIB command are listed in Table 5-2. You can specify more
than one switch, but each switch must consist of a slash(/) followed
by one of the letters shown in the table. The information returned is
displayed on the same line as the filename.
Table 5-2
)LIB switches
Meaning

Switch

Access:

Blocks: the number of blocks required for the file
(Divide the number of blocks by four to determine
pages. )

Creation:

Long:

Mode: the mode in which the file was written (disk
only); TOPS-IO only

No header:
line

Protection: the protection code associated with the
file (disk only)

Time:

the date the file was last read (disk only)

The creation date of the file (disk only)

same as typing

IBIPIC

suppresses printing of the display header

the creation time of the file (disk only)

5-11

SYSTEM COMMANDS

)LOAD - Retrieving a Workspace

5.2.4
Command

) LOAD [ magtape-position] wsname [password]
Examples
) L.OAD

WS35

SAVED

15:49:56 l1- JUL -79 2K

SAVED

)LOAD LIB1:APLSF
9:52:57 13- sEP -77 4K
) I... C>('~D

SAVED

) I... 0 (.~ [t

SAVED

1"'1:;; I /VIE

14:52:57 11- JUL -79 51'"
(.~ V E F;;

15:45:03 24-DCT-78 51'"

The )LOAD system command is an action command that retrieves a workspace from a secondary storage device. When you load a workspace, it
becomes your active workspace, replacing the currently active workspace and destroying its contents.
You must specify the name of the
file in order to retrieve it.
However, APL assumes the rest of the
wsname;
that is, i·t assumes .APL as the file type or extension, disk
as the storage device, current user directory and a null password (-).
If a password was submitted when the workspace was saved, you must
specify it, or APL will not retrieve the workspace.
If the workspace is stored on magnetic tape, you can specify the number of tape marks to skip before APL tries to load the workspace.
The
magtape position is an integer corresponding to the number of end-offile marks to skip on the tape.
When you load a workspace the )LOAD system command responds by displaying the word SAVED, followed by the time and date when the workspace was saved, followed by the size of the newly active workspace.
If the newly active workspace contains a suspended function, APL also
prints an asterisk (*).
The OQLD system function, Section 4.3.9, performs the same operation
as the )LOAD command, except without verifying messages.

5-12

SYSTEM COMMANDS

5.2.5

)PASSWORD - Determining the Workspace Password

Command

)PASSWORD [password]
Examples
)PASSWORD -SESAME
WAS

....
) P('~SSWOFo:I:'

····SE~j.(.~ME:

W~~S

) 1::·('~SSWDFi:D ....
.. ··SE:~;(.~ME
) F·(,~S~:;WDFo:X:'

The )PASSWORD system command allows you to either display the current
password associated with a workspace or change the password.
The
password parameter you supply must begin with a hyphen and can contain
up to eight more characters from A-Z, d-~; ~, Q, 0-9; the first character after the hyphen must be alphabetic (A-Z, d-~, ~, Q).
The
default or null password is a hyphen (-).

5.2.6

)SAVE - Saving a Copy of the Active Workspace

Command

)SAVE [magtape-position][wsname][password]
Examples
) \•.I~:; I D
CLE('~I:i:

60 WS

W~:;

) S('~VI:::
HOT SAVED,

) ~'-'s I D

THIS

WORKSPACE

IS CLEAR WS

~\I~:;30

) S('~VE
16:08:40 11- JUL -79
) ~I S

:r: D

PGS

WS30

[4,204]

W ~:; :I. ()

W530 [4,204J
) ~:; ('~VE
:1.6:08:5:1. 1:1.- JUL -79 :I. PGS
WS10 [4,204]
) \1,1 ~:i I x:' W ~:; 3 0
WAS WS10 [4,204]
) S('~VE \.\Is:I. ()
60 WS NOT SAVED, THIS WORKSPACE IS WS30 [4,204]
WAS

) ~I ~::. I

WAS

\.\Is30

~I ~:;

3 ~::;

[4,204J

The )SAVE system command is an action command that saves a copy of the
active workspace on a secondary storage device.
The saved workspace
can be stored as a file on disk, DECtape l , or magnetic tape.

ISome systems do not support DECtapes.
Administrator.

5-13

Check with your System

SYSTEM COMMANDS

The )SAVE system command assumes that you want to save your active
workspace on disk. All three parameters in the command string are
optional.
If you specify a wsname, )SAVE stores the active workspace
under that name.
The default wsname is the name of the currently
active workspace.
In both cases, the file type or extension is .APL.
The protection code is the standard one for your installation. As
shown in the first example, APL will not save a clear workspace.
If
your workspace is clear, you must use )WSID to give it a name before
you can use the )SAVE command.
If you are saving a workspace on magnetic tape, you can also specify
the position at which the save is to start.
The magtape-position
parameter in the command string is an integer representing the number
of end-of-file marks you want to skip before the save begins.
If you
omit this parameter, APL makes no attempt to position the magnetic
tape.
For example:
)SAVE 3 MTA1:ws35
16:26:49 ll-JUL-79 3 BLKS

In the example above, APL skips three tape marks before it starts to
save the workspace.
When you save a workspace, you have the option of saving it under its
current name (check the )WSID) or renaming it.
However, you cannot
save a workspace under a name that already exists in your storage area
unless the )WSID is that name. APL refuses to save the workspace.
If
you specify a new name with the )SAVE command, you not only store your
active workspace under that name but also change the name of the currently active workspace to the new name specified.
NOTE
If your current )WSID is the same as a
workspace you have already saved and you
save it under this name, APL overwrites
the old file with the new one.
The )SAVE system command also provides the option of specifying a
password for your workspace.
The default is a null password (-).
Subsequently, you must know the password of the workspace to retrieve
it from storage.
If you interrupt a function execution by typing two CTRL/Cs and then
save your workspace, the function is suspended in your storage area.
Therefore, when you load this works
the function does not continue automaticall .

The )SAVE command responds by displaying the time, date, and amount of
space required to store the workspace.
If you have not included the
wsname, APL also displays the current name.

5-14

SYSTEM COMMANDS

)WSID - Identifying the Active Workspace

5.2.7
Command

)WSID [wsname][password]
Examples
)WSID D5K:MYWORK.APL
CLEAR WS
)WSID
MYWORK [4~204J
)WSID MTA11
WAS MYWORK [4v204J
)WSID
MTA1:MYWORK [4v204J
)WSID[4,311J
WAS MTA1:MYWORK [4~204J
)WSID

WAS

MYWORK

[4v311J

The )WSID system command can be used as either an action command or
inquiry command. As an action command, )WSID allows you to change the
name and password of the active workspace. As an inquiry command,
)WSID returns the name of the active workspace. When you use )WSID as
an action command, you must specify the wsname parameter. However,
you need not specify the entire name. APL uses the defaults listed in
Table 5-1. with )WSID you can also specify a password parameter. This
causes the password associated with the active workspace to be changed
to the specified password. The )PASSWORD system command (Section 5.2.5)
allows you to change only the password.
As shown in the examples above, the )WSID system command returns a
workspace name when used either as an action command or as an inquiry
command. When )WSID returns a workspace name it always returns the
workspace filename.
Those additional parts that are the same as the
defaults are not displayed. The password is never displayed with
)WSID.

5.3

EXTENDED WORKSPACE-CONTROL COMMANDS

This section describes a variety of system commands that extend the
basic workspace-manipulation functions detailed in Section 5.2. These
commands can be used to:
1.

Determine the maximum and minimum size of the active workspace

Report workspace owner and version information

5-15

SYSTEM COMMANDS

Turn the workspace lock on and off to control access by other
users

Report how long the active workspace has been in use

Determine how large the active workspace would be on a
secondary storage device

5.3.1

)MAXCORE - Determining the Maximum Workspace Size

Command

)MAXCORE [{ K-of-memOr y }]
P-of-memory
Examples
nTOP!:;····lO
) M(.~>(CC)I:;:E

2()1</
IAI(.~S

1 "?6 (
'
) M(.~>~CC)F;:E

~::jO

2()1(

n TOP !:;·..·20
) M (.~ ~o( C c) F;: E

4()P /

3~::;2P

) M(.~~-(CDI:;:E
I.... (:~!:;

4()1::·

The )MAXCORE system command can be used as either an action command or
an inquiry command. As an action command, )MAXCORE changes the current setting for the maximum workspace size to the amount you specify
and displays the previous setting. As an inquiry command, )MAXCORE
should be typed without a parameter; it returns the current maximum
workspace size and the system memory limit for the data segment.
The standard APL default is 20K words for the data segment on TOPS-10
and 40P words on TOPS-20. The maximum value for K-of-memory is either
l76K words or the system memory limit, whichever is smaller. The
maximum value for P-of-memory is 352P words. Note that you do not
type P or K in the command string.

5-16

SYSTEM COMMANDS

5.3.2

)MINCORE - Determining the Minimum Workspace Size

Command

)MINCORE [{K-of-memor y }]
P-of-memory
Examples
n TOPS -l0
)MIHCORE

OK
)MIHCORE
WAS

n TOPS -20
)MIHCORE
OP
WAS

)MIHCORE
OP

The )MINCORE system command can be used as either an action command or
an inquiry command. As an action command, )MINCORE changes the current setting for the minimum workspace size to the amount you specify
and displays the previous setting. As an inquiry command, )MINCORE
should be typed without a parameter; it returns the current minimum
workspace size.
The standard APL default on both operating systems
is o. Note that you do not type P or K in the command string.
NOTE
APL does not allow you to specify a
minimum workspace size that is larger
than the setting of )MAXCORE.
The )MINCORE system command is very useful in dealing with very large
arrays or with operations requiring large amounts of intermediate
storage that cause the workspace to expand and contract.
)MINCORE
causes APL to retain at least the amount of memory specified and thus
to speed up operations by precluding the frequent acquisition and
release of large blocks of memory.

5-17

SYSTEM COMMANDS

5.3.3

)OWNER - Identifying the Owner of a Workspace

Command

) OWNER
Example
) O~\JNEI:;:
CREATED ON

12-~UL-79

[4~204]

TTY22

The )OWNER system command is an inquiry command that displays information about the creation of the currently active workspace.
)OWNER
returns the date on which the workspace was created, the directory of
the creator of the workspace, and the terminal number of the device
at which it was created.

)SEAL - Turning the Workspace Seal On or Off

5.3.4
Command

Examples
) ~:; I::: (.:or I...

OFF
) '::i E(':or I•.•
lA)A~::·

OFF

The )SEAL system command is both an action command and an inquiry
command. When you use it as an action command, you can turn the workspace seal (lock) on or off.
The default setting is OFF. When the
workspace seal is on, only the user who turned the seal on can copy
objects from the workspace or turn the seal off.
The )SEAL command
has no effect on the )LOAD command.
As an inquiry command,
setting of the seal.

)SEAL without a parameter returns the current

5-18

SYSTEM COMMANDS

5.3.5

)SIZE -

Reporting the Workspace Size

Command
)SIZE

Examples

35P

ATOPS-20
)SIZE
1 PGS

ATOPS-l0
)SIZE
2 BLKS

The )SIZE system command is an inquiry command that displays information on the size of the active workspace.
)SIZE returns two numbers:
the first is the current size of the data segment, the second is the
amount of disk space that would be required to store this workspace
if it were saved in its present state.

5.3.6

)TIME -

Reporting the Time Used

Command
) TIME

Examples
)CLEAR
CLEAR WS
)TIME
CONNECTED
0:00:04 CPU TIME
0:00:00
)LOAD PRIME
SAVED
14:52:57 11- JUL -79 35 P
)TIME
CONNECTED
0:18:10 CPU TIME
0:00:03

The )TIME system command is an inquiry command that reports the amount
of connect time and CPU time accumulated while the currently active
workspace has been active.
This command is useful in determining the
amount of time expended by programming projects. The time begins to
accumulate when the workspace is created as a clear workspace, and runs
until the session is terminated or the current workspace is saved.
The )COPY command does not affect the time accumulation.

5-19

SYSTEM COMMANDS

)VERSION - Displaying the APL Version Number

5.3.7
Command

) VERSION

Examples
)VERSION

2(412)

The )VERSION system command is an inquiry command that displays the
APL version number with which the currently active workspace was last
saved.
If your workspace is a clear workspace, APL prints the current
version of the interpreter, in the format ver(edit#) where edit is in
octal.

5.4

WORKSPACE-CONTENT COMMANDS

This section describes the system commands that examine and control
workspace elements such as functions, variables, and groups.
The
following operations can be performed:
1.

Copy variables, functions, and groups from a stored workspace, and erase these elements from the active workspace
when desired

Display a list of functions defined in the active workspace

Collect named objects into a group, disperse the group, display the members of the group, and display a list of groups
defined in the active workspace

Display the APL state indicator to report on the execution of
functions in the workspace

Display a list of variables defined in the active workspace

5-20

SYSTEM COMMANDS

)COPY - Copying Objects from a Workspace

5.4.1

Command
)COPY

wsname [password][named-object-list]

Examples

SAVED
SAVED

)CDPY AVER
15:45:03 24- DCT -78 35P
)CDPY AVER B
15:45:03 24-DCT-78 35P
)CDPY AVER C
15:45:03 24-DCT-78 35 P

SAVED
OBJECTS NOT FOUND:

The )COPY system command is an action command that retrieves functions,
variables, and groups from a stored workspace and places them into
your active workspace.
If there is a password associated with the
workspace, you must include it in the command string.
You have the
option of copying all the named objects in a workspace or a subset of
them.
The named-object-list identifies the specific objects to be
copied.
If you omit this parameter, all user-defined functions, variables, and groups are copied.
)COPY does not transfer local values for variables and functions, nor
does it copy the state indicator, the width, origin, and significantdigits setting.
Only global values of user-defined objects are copied,
since a )COPY writes a fresh user symbol table.
That is, if A is a
local variable with a value of 3 and a global value of 15, APL copies
the global value 15. Also, if your active workspace contains objects
with the same name as those in the copied workspace, APL replaces the
global values in your active workspace with the copied ones.
For
example, if B is a variable in the active workspace with a global
value of 10 and a local value of 5, and the workspace being copied
has a variable B with a global value of 20 after the )COPY, the active
workspace will have a variable B with a global value of 20 and a local
value of 5.
Objects that have the same name in both workspaces but
are pendent functions or functions still being defined are not replaced.

When you copy a group, all members of the group are copied along with
their values.
However, if a member of a group is itself a group, APL
copies only the group names and not the values from this level.
If you specify an object ??at is not located in that workspace, APL
returns a message OBJECTS NOT FOUND.
The )COPY command is the same as the OQCO system function except that
OQCO does not display messages to confirm that the copy was successful.
See Section 4.3.9 for OQCO information.

5-21

SYSTEM COMMANDS

5.2.4

)ERASE - Erasing Global Names

Command
name-list

)ERASE

Examples
(.~~··2

3 4

(.~

234
) I:!:Fo~ASE

(.~

:1. 1

V('~LUI:::

E"·:I~:OH

(.~

'71~:~ .. F

[1.]
NOT

) ERASE

ERASED:

[1]

'Ilhe )ERASE system command is an action command that erases global
names from the active workspace by undefining the functions, variables, and groups specified in the name-list parameter. You can
undefine a suspended function but not a function in the process of
being defined.
If you specify a group name, then the group name is
erased from the active workspace along with the members of the group.
If a member of the named group is itself a group, the group name is
erased but the members of the subgroup remain intact. For example:
)FNS

cos
) GI~:I::'

CIHCLE
ARC

T('~N
TFo~ 1: G

cos

SIN

TAN

)GRP CIRCLE
DIAM
HADIUS
) 1:::r.:ASE Tf;:IC;
) Gf;:P TI;; :1: G
INCOHRECT PARAMETEH
) G F,: ,::'

T 1:,: :r G
A

) GFi:P CIf;:CLE
INCORRECT PARAMETER
)GI:;:P CIHCI... E
A

) FN~:;

DI('H-1

The )ERASE command does not distinguish between pendent functions and
other functions.
You should avoid erasing pendent functions because
of problems you could create. APL attempts to alleviate such problems
by displaying the following message after performing the )ERASE
operation:
13 POSSIBLE SI DAMAGE

5-22

SYSTEM COMMANDS

This warns you that remedial action might be required before execution
of the function continues.
(SI refers to the state indicator.)
Note that )ERASE leaves a slot in the symbol table for the erased name
(symbol). Although you erase a symbol, the slot in the symbol table
still exists.
If you reuse a name that was in the symbol table, APL
places it in the same slot where it was before.
If you do a )COPY of
the workspace, APL rebuilds the workspace thus erasing the slot as
well. as the symbol.

5.4.3

)FNS - Displaying a List of Functions

Command

)FNS [letter]
Examples

ALPH
I

)FNS
HILB
)FNS I
INV

INV

LSO

The )FNS system command is an inquiry command that displays an alphabetic list of global names used as user-defined function names
(Chapter 6) in the active workspace.
The optional letter parameter
identifies the letter at which the alphabetic listing is to begin.
If
you omit the letter the entire set of global function names is displayed.

5.4.4

)GROUP - Defining or Dispersing a Group

Command

)GROUP

group-name [group-member-list]

Examples
)GROUP
)GROUP
)GROUP
)GROUP

FINANCIAL INT FUTUAL PRESVAL
FINANCIAL TAX FINANCIAL
FINANCIAL
FINANCIAL X

The )GROUP system command is an action command that places a collection of named objects under one group name and can disperse an existing group.
The objects can be variables, functions, and other group
names.
The )GROUP command is used primarily with the )COPY and
)PCOPY commands. After collecting a set of functions and variables
under one group name, you can specify this name in a )COPY or )PCOPY
command to copy the entire collection at one time.
In the first
example above, the functions and variables named INT, FUTUAL, and
PRESVAL are collected into a group named FINANCIAL.
To add a new member to an existing group, you must list the groupname
as an element in the member list.
This ~s illustrated in the second
example where the variable TAX is added to the group named FINANCIAL.

5-23

SYSTEM COMMANDS

To disperse a group, specify the group name without a group-memberlist.
The group name will no longer be defined but the individual
members of the group still exist under their original names.
The
third example above disperses the group FINANCIAL.
A group name is always global; you cannot localize it.
(.~ .~

For example:

.. :I.

X·:'~··2

[lJ

e')GROUP

[2]

1;:)

CAB'

24 e NOT GROUPED y NAME IN USE
) GI:;:C) UP

(.~

x·:·

)GRP - Displaying the Members of a Group

5.4.5

Command
)GRP

group-name

Examples
)GROUP
") (-:./=;:1""

INT

FINANCIAL

INT

FUTUAL

PRESVAL

F I H('~NC I ('~L

FUTUAL

PRESVAL

The )GRP system command is an inquiry command that displays the members of the group named in the command string. The members are
listed in the order in which they entered the group.

)GRPS - Displaying a List of Groups

5.4.6

Command
) GRPS [letter]

Examples
) E·I:;:P~:;

F:r. N~~NC J: ('~L
) GI:;:PS

:r NVENTOI:;:Y

The )GRPS system command is an inquiry command that displays an alphabetic list of global names you specified as group names in the active
workspace.
The optional letter parameter identifies the letter at
which the list is to begin.
If you omit the letter, the entire set
of group names is displayed.

5-24

SYSTEM COMMANDS

)PCOPY - Copying from a Work.space with Protection

5.4.7

Corrunand
wsname [password][named-object list]

)PCOPY

Examples
t~~"2!::;

I'" I... tJ~>I:;:OW ~ .. 40

)pCOpy MYWORK F Pl...tJSROW PRIMES A
SAVED
10:24:30 12-JtJL-79 35 P
NOT COPIED:
A
pLtJSROW
)PCOPY MYWORK G B F
SAVED
10:24:30 12-JtJL-79 351'"
OBJECTS NOT FOtJND:
G
NOT COPIED:
F

The )PCOPY (protected copy) system corrunand is an action corrunand that
performs in much the same way as the )COPY system corrunand.
However,
)PCOPY protects you from accidentally replacing objects in your active
workspace, that is, )PCOPY does not replace objects in the active
workspace with objects of the same name in the copy workspace.
Instead, APL returns the message NOT COPIED: along with the names of the
objects involved.
When copying groups, the )PCOPY corrunand does not copy any members of
the group that have the same name in the active workspace.
If the
group name itself is the same as a group name in the active workspace,
APL does not copy the group name but does copy any member of the group
that does not have the same name in the active workspace.
Named objects that cannot be found in the copy workspace or cannot be
copied are displayed as shown in the examples.
The )PCOPY system corrunand operates the same as the DQPC system function
except that OQPC does not return messages to verify the success of the
copy.
See Section 4.3.9 for information on OQPC.

)SI - Displaying the State Indicator

5.4.8

Corrunand
)SI

Examples
(.~~

.. []

1"'[2::1
G[3]

)'(

The )SI system corrunand is an inqui~y corrunand that displays the state
indicator of the active workspace.
The state indicator contains the

5-25

SYSTEM COMMANDS

status of the execution of user-defined functions in the workspace.
By analyzing the )SI listing, you can determine such function-status
conditions as the following:
1.

suspended functions (*)

pendent functions

pending quad input requests

A bracketed line number following the function name indicates the line
at which the function stopped executing. An asterisk following the
bracketed line number indicates that the function is currently suspended.
If there is no asterisk, the function is a pendent function
(one awaiting the return of a called function).
Instead of a line number, t~e:.}S'I~~sR~~X?<:iI1S()I1taiI1.()J:lly an asterisk
(*), a quad character (D) ,t~¥;r:i~nU;~~:eci:ifi'e;ii;;:fiun~tri~ri,:;0~~;;~;I;L:Q1rl;;jMii;,ii1.
In this
case, an asterisk indicates that a suspended function has been erased.
A quad character indicates pending quad input. An execute function
indicates an execute operation.
The order in which functions are displayed in the )SI list is significant; the function that was most recently active is listed first.

)SIV - Displaying the State Indicator and Local Variables

5.4.9

Command
)SIV

Examples
) ~:i I v

F[2J

1t.

(.~

(::;[:"5:1

"/(

x:'

The )SIV system command is an inquiry command that acts much the same
as )SI. However, )SIV also displays a list of variable names local to
the halted function including localized system variables.
The )SIV
command displays the status of pendent and suspended functions, pending quad input requests, and operations involving the execute operator.
Unlike )SI, )SIV also displays the current line of any pending execute
string.

5-26

SYSTEN COMMANDS

)VARS - Displaying a List of Variables

5.4.10

Command
) VARS [ letter]

Examples
) ""'AI:;:~:;
I(

:t:

)V('H;:S

The )VARS system command is an inquiry command that displays an alphabetic list of global names used as variable names in the active workspace. The optional letter parameter identifies the letter at which
the listing is to begin.
If you omit the letter, the entire list of
global variable names is displayed. Local variables are not listed.

5.5

WORKSPACE-ENVIRONMENT COMMANDS

This section describes a variety of system commands that allow you to
control the characteristics of the workspace environment. These
commands can be used to:
1.

Specify the maximum number of significant digits to be
displayed

Determine the index origin setting

Determine the terminal output mode, displaying error lines,
setting terminal tab stops

Set or return the width of the output line

)DIGITS - Determining the Output Precision

5.5.1

Command
)DIGITS

[n]

Examples
)D:t:G:t:TS

1.23456789123456789
1. 234~,)t.)789:1.
)IoIG
lA,1 A ~5

~.'.'j

1 ()
1.23456789123456789

1,,2346

5-27

SYSTEM COMMANDS

)DIG
WAS

1.23456789123456789

The )DIGITS system command is both an action command and an inquiry
command. As an action command, )DIGITS allows you to specify the
maximum number of significant digits you want APL to display for
non integer output only. As an inquiry command, )DIGITS displays the
current setting. The parameter n can be from 1 to 18; the default
setting is 10.
APL rounds off a number if it has more digits than the current
setting.
The )DIGITS system command does not affect the precision of internal
calculations or the display of numeric constants. The setting is
preserved when you save the active workspace.
The )DIGITS command performs the same operation as the OPP system
variable (Section 4.2.15).

)ECHO - Determining Error Line Echoing

5.5.2
Command

)ECHO

Examples
ON

)ECHO

5-28

SYSTEM COMMANDS

)ECHO OFF
WAS ON

The )ECHO system command is both an action command and an inquiry
command. As an action command, )ECHO allows you to sel~ct whether or
not to have APL echo statements that contain errors. As an inquiry
command, )ECHO returns the current state of echoing.
The parameter is
either the word ON or the word OFF.
The default is ON.

The echoing status is preserved when the active workspace is saved.

5.5.3

)MODE - Determining the Terminal Output Mode

Command

)MODE

ill

ESCAPE }~
KEYWORDUj

Examples
)MODE
KEYWORD
)MODE ESCAPE
WAS KEYWORD
A_'@A@K@K@Z'
A

)MODE KEYWORD
WAS ESCAPE
A
.AL'.RU
The )MODE system command is both an action command and an inquiry
command.
As an action command, )MODE allows you to select the mode of
output on terminals that do not have an APL character set (see Section
1.3). As an inquiry command, )MODE displays the current setting.
The parameter can be either the word KEYWORD or the word ESCAPE.
Either word can be abbreviated to one letter.
In ESCAPE mode, on
output, @p, @K, @Q, @Y, print as *, " ?,
The default is KEYWORD.
This setting has effect only if you responded to the TERMINAL ..
prompt, at the beginning of the session, with TTY.
A.

The mode setting is preserved when the active workspace is saved.
5-29

SYSTEM COMMANDS

)ORIGIN - Determining the Index Origin

5.5.4

Command
)ORIGIN

[n]

Examples
) () I:;: :t: G :t: N

1
,.!
t I::'
1. .,.).:.. :3 4 I::'

'"'

) DI~::t:G:r:N
w(.~~:;

()

:1.
I::'

0 1

,.,
",':.

\ ,.J

:3 -1

The )ORIGIN system command is both an action command and an inquiry
command. As an action command )ORIGIN allows you to change the
setting of the index origin for array operations and returns the
previous setting.
The parameter "n" can be either 0 or 1. The default setting is 1. As an inquiry command, )ORIGIN displays the
current setting.
The effect of the )ORIGIN command is to renumber the elements of
arrays to begin at 0 or 1, depending on the setting.
This command is
particularly relevant when used with the 1 function.
(Sections 3.3.10
and 3.3.11.)
The index origin setting is saved when the active workspace is saved.
The )ORIGIN system command performs the same operation as the DIO
system variable (Section 4.2.11).

)TABS - Determining Tab Stops on the Terminal

5.5.5

Command
)TABS

[n]

Examples

o
) T('~I-:<S

The )TABS system command is both an action command and an inquiry
command. As an action command, )TABS sets the increment between tab
settings for APL output. As an inquiry command, )TABS returns the
current tab setting.
The integer parameter "n" specifying the tab
increment can be frorn 0 to the page width.
The default setting is o.

5-30

SYSTEM COMMANDS

If you reset the page width with either the DPW system variable
(Section 4.2.16) or the )WIDTH command (Section 5.5.6), the )TABS
setting is reset to the new page width.
For example:

7'2
) T (.~ x·;< ~:;

".7 ()

[] J::. W ~ .. ~5 0

) T('~X-:<S

) W:J: DTH

w(.~ S

4~::j

~:.:j () "It.

) T('~I·;<~;

4 ••C:·J

The asterisk in the above example indicates that )TABS has been reset.
NOTE
The )TABS system command is designed for
use on terminals with physical tab stops.
The tab setting is not saved with the
active workspace.
APL will output a TAB instead of a string of blanks if the next nonblank character to output comes after a tab stop.

)WIDTH - Determining the width of the Output Line

5.5.6

Command

[n]

)WIDTH

Examples
)WIDTH

"I :I. ~)

1 2 3 4 5 6 ".7 8 9 :1.0 :1.1 :1.2 13 14 15
)lJ.1IDTH
W(~S

72"1<
"t 1~)

1 2 3 4 5 6 7 8 9 :1.0 11 :1.2 13
:I. 4

:L ~.:j

) l"'IDTH

The )WIDTH system command is both an action command and an inquiry
command. As an action command, you can set the maximum number of
characters that can appear in an output line and display the previous
setting. As an inquiry command, the )WIDTH command returns the

5-31

SYSTEM COMMANDS

current width of the output line.
The parameter "n" must be an
integer within the range 30 ,through 390. The default is determined
by the system width setting. You can change the system width for
your current job at operating system command level by using:
@TERMINAL WIDTH

!TOPS-20

.SET TTY WIDTH

!TOPS-IO

The )WIDTH system command does not affect the display of messages on
the terminal or the allowable length of input lines. The width setting is preserved when you save the active workspace.
The )WIDTH system command performs the same operation as the DPW
system variable (Section 4.2.16).

5.6

APL TERMINATION COMMANDS

This section describes the various system commands that can terminate
an APL session. You can exit from APL in a variety of ways. You can:
1.

Terminate the session, save the active workspace, and run a
program

Terminate the session and save the active workspace

Return to system command level

Terminate the APL session, optionally returning to system
command level

Terminate a session and run a program

)C and )CALL - Running a Program and Returning to APL

5.6.1

Command
)C [n] file specification'

) CALL [n] file specification

Examples
) c (.~ I... I...

~::

y ~:} ! F [) ,:;: T ,:;: (.~

*yTTYt :::: TTY!
I :::::1.

END
..... "y

i ..

FORTRAN V.5A(62:/.) IKI

~1tlIN.

P,0tGE :/.
O()()O:l.

1:::::1.

OO()02

END

SUBPROGRAMS CALLED

5-32

:1.2····,.JUL··.. ?9

:1.3:00

SYSTEM COMMANDS

SCALARS AND ARRAYS [

"*" NO rXPLICIT DEFINITION - H%" NOT REFERENCED]

:1.

MAINt

r NO ERRORS DETECTED]

* RUN:APLSF/RUNOFFSET:1
T1:: RMIN AL +

l.. A

APL-20 DECSYSTEM-20 APLSF 2(412)
TTY22) 13:01:33 THURSDAY 12-JUL-79 MASELLA
CL.E~('~R

W~:;

The )C and )CALL system commands perform the same operation as )R and
)RUN except that )C and )CALL also save your active workspace as
CONTIN.APL. They also write an APL .TMP file (nnnAPL.TMP) or .TMPCOR
file so that, if APL is subsequently run with a CCL linkage, the
processor is able to determine the terminal type from the file written
and does not prompt you with TERMINAL ...
The difference between )C and )CALL is the default device searched.
The )C command defaults to SYS:.
The )CALL command defaults to DSK:.

5.6.2

)CONTINUE - Saving the Workspace and Ending the Session

Command

)CONTINUE [HOLD]
Examples
) CONTINUE HOI...['
:1. 2 .... ,.J U I....... "7 9 2 HI... I( ~:;
TTY44)
9:35:54 12- JUL -79
CONNECTED
0:01:49 CPU TIME
STATEMENTS 0 OPERATIONS
KII...O-CORE-SECS 13

9 : :'5 ~:) ! ~::.; 3

0:00:00

EXIT

The )CONTINUE system command is an action command that ends an APL
session after saving the currently active workspace.
) CONTINUE
operates the same was as )OFF (displaying the same statistics) except
that before ending the session )CONTINUE saves the active workspace in
your disk area under the name CONTIN.APL.
The workspace is saved
only if it is indeed active, that is, contains at least one symbol in
the symbol table.
The saved workspace replaces any other disk file
that you previously saved with the name CONTIN.APL.
The next time you begin an APL session, instead of a clear workspace,
you will receive the CONTIN.APL workspace as your active workspace.
The HOLD parameter returns you to operating system command level
after ending the APL session.
)CONTINUE not only prints the same
summary information as the )OFF command, but also displays an initial
line that specifies the time, date, and size of the saved workspace.

5-33

SYSTEM COMMANDS

5.6.3

)MON - Returning to Operating System Command Level

Command

)MON
Examples
n TDP £;····20

)MON
MOl-! I TOI:;::
WCD~·IT I
('~PI

NUl:::

... SF:

ATOPS····lO
)MON
MON I TDI:;::
• F~EENTEF~
(,)1::·1... ~:;F

The )MON system command is an action command that returns control to
operating system command level.
The )MON command does not save the
active workspace as the )CONTINUE HOLD does.
Therefore, if you intend to return to APL and save the workspace, be careful not to destroy
your memory image while at command level. This could occur if you
issue a command that runs a program.
You can return to APL by typing the operating system command CONTINUE
or REENTER. For more information on returning to APL, refer to
Section 1.4.4.

5.6.4

)OFF - Terminating the APL Session

Command

)OFF [ HOLD]
Examples
)DFF

TTY22) 1 ~:5 t 40! 22 12···· ,JUL····"79
CONNECTED
0:00:34 CPU TIME
0:00:0:1.
5 STATEMENTS 6 OPERATIONS
KILLED JOB 16y USER MASELLA, ACCOUNT APL, TTY 22,
AT 12-JUL-"79 1S:40:22,
USED 0:0:1 IN 0:0:42
) OFF

1--101... x:'

1 ~:5 : 41 : 1 B 12···· ..JUI·······"79
CONNECTED
0:00:19 CPU TIME
o STATEMENTS 0 OPERATIONS
TTY:::.~2)

o:oo:()O

EXIT
@

The )OFF system command is an action command that terminates your APL
session.
If you specify the HOLD parameter, APL terminates your
5-34

SYSTEM COMMANDS

session and returns you to operating system command level. Without
the HOLD, APL not only terminates your session but also logs you off
the system.
The )OFF commands outputs several lines of information before terminating the session. The lines contain the following:
1.

Your terminal identification

Current time

Current date

Length of time connected to APL

Amount of computer CPU time used

6 • . Number of statements
7.

Number of operations executed

Kilo-core-seconds-used (TOPS-IO only)

The )OFF command destroys the currently active workspace.

5.6.5

)R and )RUN - Ending the Session and Running a Program

Command
)R

[n] file specification

)RUN [n] file specification
Examples
) I:;: U H

D ~,; I( ! T I:,: ~,; T

EXIT
(r?
) I:;:

F 0 ,:;: T ,:;: (.)

The )R and )RUN system commands perform essentially the same function
as )OFF HOLD.
They terminate the current APL session and return you
to the operating system, but unlike )OFF HOLD, they also run the
program you specify as the filespec in the command string. The file
you specify must contain a program ready to run, that is, a program
with a file extension or file type of .EXE. The optional parameter
"n" is an integer value that is added to the starting address of the
file to be run; this facility is useful when starting from alternate
entry points (for example, CCL entry points are equal to 1).
The )R and )RUN commands do not save the currently active workspace
nor the reentry point to APL before ending the APL session.
If the
program you identify cannot run for some reason, you will be at
operating system command level.

5-35

SYSTEM COMMANDS

The difference between the )R command and the )RUN command is the
default device that is searched. The)R command default device is
S.YS:. The )RUN command default device is DSK:.

5.7

MISCELLANEOUS COMMANDS

This section describes the additional system commands that perform such
tasks as the following:
1.

Generating a mask to protect confidential data

Displaying a record of activity during the current APL
session

)BLOT - Generating a Mask

5.7.1

Command
)BLOT

[n]

Examples
) X·:<I .•. DT

:::SO

G~O~~OOW~DUM~EHM~affiaB~R~8~NaBMI

The )BLOT system command is an action command that generates a mask in
a random pattern to conceal confidential input such as passwords.
The
optional parameter "n" specifies the length of the mask.
If you omit
the parameter, the default length is 25 characters.

)CHARGE - Displaying APL Session Information

5.7.2
Command

) CHARGE
Examples
) CH(')I';:GE

TTY22) 15:43:39 12- JUL -79
CONNECTED
0:00:35 CPU TIME
o STATEMENTS 0 OPERATIONS

0:00:00

The )CHARGE system command is an inquiry command that displays a
record of activity during the current APL session.
Information to be
displayed includes the statistics as the )OFF and )CONT commands
display:
1.

connect time

CPU time

number of API. statements

5-36

SYSTEM COMMANDS

number of operations executed

kilo-core seconds (TOPS-lO only)

5-37

SYSTEM COMMANDS

5-38

CHAPTER 6
DEFINING AND EXECUTING FUNCTIONS

6.1

INTRODUCTION

APL language statements operate in any of three modes:
Immediate mode (or execution mode):
in this desk-calculator
mode, APL statements and expressions are executed immediately
after you terminate the line.
Function-definition mode:
in this mode, you name, develop, edit,
and save functions for use at a future time.
Function-execution mode:
in this mode, you execute the function
you created in function-definition mode.
The language syntax is the same in all modes.
However, in functiondefinition mode there are a variety of special APL characters available and a number of practical considerations you need to take into
account when you construct a function.
This chapter discusses:
1.

Function definitions, headers, and variables

Editing procedures

Branching and the use of labels, trace vectors, stop vectors,
and the state indicator

Use of locked and suspended functions

6.2

DEFINING THE FUNCTION

APL provides a comprehensive facility for defining, changing, and
calling user-defined functions that supplement the large set of
primitive functions discussed in Chapter 3.
Once you write or define
a function, you can save it and recall it with the ease of a primitive
function.
You construct a user-defined function in two parts, a function header
and a function body.
For the function header, you define the name of
the function and the syntax of the function call.
The function body
consists of a series of statements and expressions that define the
actions to be performed by the function when it is executed.

6-1

DEFINING AND EXECUTING FUNCTIONS

To enter function-definition mode, type a del character (~) followed
by the function header and a carriage return/line feed.
This signals
the APL processor not to execute subsequent lines as you enter them,
as it would in immediate mode. However, system commands are executed
immediately.
In function-definition mode, APL prompts you for successive lines of the function body by displaying successive bracketed
line numbers for every line. All the lines you enter are treated as
function lines until you type another del (~).
The second del returns
you to immediate mode. Functions can have up to 1000 lines.
The format of a function is shown in the following:
~

function header

[1 J
[2 J

[3J
[4J
[5 J
[6 J
[7 J
[8J

function body

There are no restrictions on the type of statements you can include in
a function definition. You can include system commands in a function
but you must precede them with the execute function.
If you do not,
APL executes them immediately.
See Section 5.8.
You can define and execute functions in quad input mode. The input
request remains pending until you leave function-definition mode.
You delete a function from your workspace with the system function DEX
(Section 4.3.4).

6.2.1

The Function Header

The function header contains the name of the function and the syntax
of the function call. You type the function header on the same line
as the del (~) that signals function-definition mode. There are six
types of functions that you can define depending on the number of
arguments the function header takes and whether or not the function
returns an explicit result. Table 6-1 displays the formats of the six
function types.
Table 6-1
Function Headers
Type

Explicit Result

Type

No Explicit Result

niladic

variable +name

niladic

name

monadic

variable +name arg

monadic

name arg

dyadic

'1/

variable +arg2 name argl

dyadic

arg2 name

arg~

The arg, argl, and arg2 in the function header are dummy arguments.
They look like variable names but they have no values assigned to
them. A dummy argument is a placeholder for an actual argument

6-2

DEFINING AND EXECUTING FUNCTIONS

(value) you supply when you call the function.
The number of dummy
arguments in the function header determines the calling syntax of the
function (niladic, monadic, dyadic).
You must include the same dummy
arguments in the function definition as in the function header.
The variable in the function-header syntax (Table 6-1) is also another
dummy argument. However, the presence of this variable in the function header determines whether or not the function returns an explicit
result.
This variable temporarily stores the results of the function
execution. You assign the function name to the variable in the function header.
If a function returns an explicit result, you can use
this function in subsequent computations by including its name in an
expression just as you would an APL function.
A function that does
not return an explicit result (no variable assigned in the function
header), may also return a result when you execute it. However, you
cannot use this function result for further work as a value within
another function.
Functions that return explicit results can be included as part of any
expression. Functions that do not return explicit results must be
either the only statement on the line or the last statement in a
multi-statement line (last statement on the left).
The following function header returns an explicit result:

In this function header, A is the variable (dummy argument) that
designates this function to be one that returns an explicit result.
The result of the execution is stored temporarily in A. The variable
names Band C are dummy arguments, and FROG is the function name.
When you call a function containing dummy arguments, you must supply
the values for APL to use during execution. You include the values in
the calling syntax of the function name. For example, if the function
header has two dummy arguments:
NAME B

you must supply values for A and B.
25

NAME

When APL executes the function, the values 25 and 42 are used in the
calculations wherever you placed A and B in the function definition.
You can also include local symbols in a function header.
Local names
must be unique from dummy names in the same function definition.
See
Section 6.2.2.1.

6.2.2

Symbol Classification

An APL workspace contains an area that is known as the symbol table.
This area is empty in a clear workspace. Every time you create a
variable name, function name, or group name (Section 5.4.4), this name
is written, and referred to as a symbol, in the symbol table.
(Dummy
arguments are not recorded in the symbol table). Any values you

6-3

DEFINING AND EXECUTING FUNCTIONS

assign to these symbols are also stored in the symbol table.
save an active workspace, APL also saves the symbol table.

When you

Symbols are classified as being either local or global symbols depending on how their values are treated before and after function
execution.
The following subsections describe the characteristics of
local and global symbols.

6.2.2.1 Local Symbols - A local symbol has significance only during
the execution of a particular function.
To specify a symbol as being
a local symbol, include that symbol in the function header and then
assign it a value within the function definition.
Separate local
symbols from the function name with semicolons. All local symbols are
placed to the right of the function name.
For example:

In this function header, I, LOC and G are local variables.
Local
variables have no significance in determining whether a function is
niladic, monadic, or dyadic.
Dummy variables do.
See Section 6.2.1.
During execution of a function, the local value is always dominant.
For example, if a local variable has the same name in two separate
functions, the execution of one function does not affect the value of
the local variable in the other function.
You initialize local variables when you call the function, and any local values are lost upon
exiting from the function.
Using a local variable before you have
assigned it a value results in an 11 VALUE ERROR.
Note that there is
no need to include local variables in the function call.
Function-line labels (Section 6.4.2) are treated as local variables
and are also initialized when you call the function; however, they
cannot be assigned a value.
System variables (Section 4.2) can also be localized within a function
definition.

6.2.2.2 Global Symbols - A global symbol has the same significance
(value) throughout the scope of its workspace, whether or not it is
inside or outside a function.
You can change a global symbol, erase
it, or expunge it throughout that scope.
However, you can have only
one global definition at a time for a symbolic name.
Because naming conventions for functions and variables are the same,
you cannot have a global function and a global variable with the same
name.
You can, however, have a local and a global with the same name.
In this case, certain rules apply for determining which value takes
precedence, global or local.
See Section 6.2.2.3 for this explanation.

6.2.2.3 Dynamic Localization - The phrase "dynamic localization"
refers to the precedence of local symbols over global symbols with the
same name.
During function execution, the value of a local variable
supersedes the value of a global variable with the same name.
Also,
depending on the particular function being executed, a local variable
can supersede another local variable of the same name.

6-4

DEFINING AND EXECUTING FUNCTIONS

For example, if you have a global variable A and you execute a function containing a local variable, A, APL uses the value of the local
variable A during function execution. Once APL exits from the function, A retains its global value.
If two functions have a local.variable with the same name, APL uses
the value from the function in which it is currently executing. For
example, the local variable B has a value of 10 in FUNG1 and a value
of 25 in FUNG2. While executing FUNG1, APL uses 10; while executing
FUNG2,'APL uses 25. Upon APL's return to FUNG1, B resumes the value
of 10. Finally, upon APL's exit from FUNG1, B has no value.

6.2.3

Function Input and Output

You can input and output data and the results of function execution by
using the standard APL input/output functions described in Chapter 2.
All the quad symbols (0) can be used in both immediate and functiondefinition mode.
These are:
1.

Quad (0) or evaluated input, Section 2.5.1

Quote-quad

Quad-del

Normal output, expressed by simply typing a variable name,
Section 2.5.4

Mixed output, expressed by typing values separated by
semicolons, Section 2.5.6

Quad output (0), Section 2.5.5

Bare or character output

(~)

or character input, Section 2.5.2

or unedited input, section 2.5.3

~),

Section 2.5.7

File input and output are discussed in Chapter 7. The other varieties
of input and output are described in detail in Section 2.5.
One aspect of APL I/O, escaping from an input request within an
infinite loop, is particularly relevant to a discussion of function
execution.
In this case, you may not be able to escape by typing the
attention signal, two CTRL/Cs. You can escape by typing several
right-arrows (+). Also, you can escape from either quote-quad or
quad-del input mode by typing the following:

o backspace U backspace T (or .OU from a non-APL terminal)
Either form of escape has the same effect as function suspension
(Section 6.4.3); it causes function execution to be interrupted but
does not result in an exit from the function.

6-5

DEFINING AND EXECUTING FUNCTIONS

6~2.4

Comment Lines

You can include comment lines anywhere in the APL function.
They are
particularly useful in annotating statements in the definition.
Comments must appear on separate lines and cannot be included on lines
containing APL statements. The first character in a comment line must
be a lamp character (~), formed by overstriking the down union (n) and
the jot (0). APL treats the text following this symbol as a comment;
and the text can consist of any combination of valid APL characters.
Note that a comment cannot extend across line boundaries.
When you display a function definition, APL begins a comment line one
character position to the left of the rest of the text. Actually, the
lamp character (~), itself, prints one position to the left. An example of this is shown in Section 6.2.5.3.

6.2.5

Examples of Defined Functions

This section contains three different examples of defined functions.

6~2.5.l
Niladic Function - The following niladic function does not
return an explicit result. Note the value of VECTOR, as a global
variable outside the definition of AVG and as a local variable inside
AVG.

QAVG;VECTOR
M~IENTER
THE VECTOR TO BE AVERAGED!
ITHE RESULT IS ';(+/VECTOR)0'yVECTOR~EM

[lJ
[2J
[3J

~
VECTOR~'ABCD'

ENTER
THE

AVG
THE

VECTOR

RESULT IS
VECTOR

AVERAGED:

3 4 5 6 7

ABeD

6.2.5.2 Monadic Function - The following monadic function returns an
explicit result:
~ANS~AVERAGE

[lJ
[2J

VEC

ANS~(+/VEC)0'yVEC

AVERAGE

3 5 4 6 7

100XAVERAGE

3 5 4 6 7

500

6-6

DEFINING AND EXECUTING FUNCTIONS

6.2.5.3 Dyadic Function - The following dyadic function included
below does not return an explicit result:
[1]

[2J
[3J
[4J

VLETTER IN STRING;T
nRETURNS NUMERIC POSITION WHERE
nAPPEARS IN STRING

CHARACTER

T~(LETTER=STRING)/",STRING

~O,D~T;~5x'O=,T

[5]

INO OCCURENCESI

[6J

v
LETTER~ICI

T~IGLOBALI

LETTER

357

LETTER IN
NO OCCURENCES
T
GLOBAL

6.3

IABCACBCI
ILMNOpl

EDITING THE FUNCTION

You can edit a function definition in a variety of ways. There is no
need to go to a text editor outside of APL. APL has a line editor
that allows you to add, delete, and change definition lines and also
alter the function header. You can even edit individual characters in
a line. See Section 6.3.7 for character-editing procedures.
You must be in function-definition mode to edit a function.
function for editing, type:

To open a

v function name
After an addition, replacement, insertion, deletion, or display
operation, APL displays a line number to allow you to add or enter
additional text.
If you do not want to do this, type a del (V) to
close the function and thus shift from function definition to immediate mode. You can also type a del on an edit line. For example:
VSTAT

[7J

[o5]V

In this example, APL deletes line [5J and then exits from functiondefinition mode. The del can be included on any line except a comment line.
After you return to immediate mode, the lines in the function are
automatically renumbered sequen~ially, beginning at line [lJ.
Therefore, lines you insert with fractional numbers affect the
function only while it is open for editing.

6-7

DEFINING AND EXECUTING FUNCTIONS

6.3.1

Adding Function Lines

You can add lines to the end of a function in a very convenient manner. When you open an existing function, APL assumes that you want
to add new lines and it displays the next available line number.
For
example, the function named STAT can exist in the following form before you edit it to remove errors.
9STANDX~NSUBJ

[lJ

SUMX~+X

[2J

SUMX2~+/(X*2)

STAT

[3J

ACOMPUTE

[4J

MEANX~SUMX+NSUBJS

[5]

MEANX~SUMX+NSUBJ

[6J

MEAN,

VARIANCE,

STANDARD

DEVIATION

You can add lines in response to the bracketed line numbers displayed
as shown below.
~STAT

[6]

AFUNCTION

[7J

STANDX~VARX*O.5

[8J

RETURNS

VALUE

STANDARD

DEVIATION

To terminate the specification of additional lines, enter a del to
transfer from function-definition mode to immediate mode.

6.3.2

Replacing Function Lines

You can replace existing lines in a function definition by entering
function-definition mode, then specifying the affected line number and
the new text of the line.
In the next example, APL displays the line
number [8J indicating that the existing function has seven lines.
The
first line of the function is replaced with the new text.
VSTAT

[8J

[1]

[2]

SUMX~+/X

APL then displays the next line number after the replaced line, in
this case, [2J. At this point, you can either enter new text for line
[2J, or escape from function-definition mode by typing v.
The line number you specify must be a positive number less than 1000.
If the line does not currently exist, it is inserted (see Section
6,.3.3).
You can include a decimal point but you cannot specify more
than three decimal places.

6-8

DEFINING AND EXECUTING FUNCTIONS

6.3.3

Inserting Function Lines

You can insert new lines between existing lines of a function definition by first entering function-definition mode. Then, specify the
new line number followed by the text. For example, to insert a line
between [5J and [6J you can specify any number from [5.001J to
[5.999J.
To insert a line before line [1J, you can use any number
from [0.001J through [0.999J. Note the following example:

[0.6J

VSTAT
rOtSJ
[5.S]

[S.6]

[8J

ASUM ELEMENTS

ARRAY

VARX~(SUMX2+NSUBJ)-MEANX*2

The new lines are inserted between existing lines [oJ and [1J and [5J
and [6J respectively.
In each case, APL prompts with the next line
number after the inserted line.
To derive the line that is next in an
inserted sequence, APL increments the present line number by 1E-D
where D is the number of decimal places in that line number. The next
line after [0.5J is thus [0.6J, the next line after [5.5J is [5.6J,
and the next line after [8.29J would be [8.3J.
Line number [6J is
after [5.9J, and line number [7J, not [6.1J, .is after [6J. You can
enter new text for the line number displayed, override the line number
by specifying another one, or return to immediate mode by typing a v.
After you close the function, APL renumbers the lines to consecutive
integers beginning with [1J.
Line numbers you insert must be positive
numbers up to but not including 1000, with or without a decimal point,
and with no more than three decimal places. The renumbered function
definition now exists in the following form.
V

STANDX~NSUBJ

ASUM

[1]

ELEMENTS

STAT X
OF ARRAY

SUMX~+/X

[2]
[3J

SUMx2~+/(x*2)

[4]

ACOMPUTE MEANy

VARIANCE y

[S]

MEANX~SUMX+NSUBJS

[6J

MEANX~SUMX+NSUBJ

[7]
[8]
[9]

STANDARD DEVIATION

VARX~(SUMX2+NSUBJ)-MEANX*2

AFUNCTION

RETURNS

VALUE

STANDARD DEVIATION OF

STANDX~VARX*O+S

6.3.4

Deleting Function Lines

To delete existing lines in a function-definition mode, you type a
delta (6) and the line number both within square brackets. For
example, to delete line [5J of STAT, type the following:
VSTAT
[10J

[~S]

[5]

6-9

DEFINING AND EXECUTING FUNCTIONS

APL displays the number of the line just deleted to give you the
opportunity to type a new version of the deleted line. You can enter
new text or escape from function-definition mode by typing V. After
you close the function, APL renumbers the lines.

6.3.5

Displaying Function Lines

APL gives you the ability to display an individual line, a part of the
function definition from the specified line to the end, or the entire
function definition.
To display an individual line, type the line number and a quad character (0) within square brackets. For example, to display line [3J
of function STAT, type:
';l~'; T(')T

£: 3t:J::I

SUMx2~+/(x*2)

[3]
[3]

APL prints the number of the line just displayed to give you the
opportunity to specify a new version of the line. You can now perform
any editing operation or escape from function-definition mode by
typing v.
To display the function definition from a particular line number to
the end, you type the quad character first and then the line number
from which lines are to be displayed. For example:
'(?~'; TAT

[7]
[8]

I:: IT7 J

AFUNCTION RETURNS

VALUE

OF STANDARD DEVIATION OF X

STANDX~VARX*O.5

'il

APL displays the number of the next line after the final line of the
function definition, in this case [9J, to give you the opportunity to
add more text.
To display the entire function definition, type the quad character
without a line number. For example:
V'~:;

TPIT I:: [J::I V'

STAT X
ASUM ELEMENTS DF ARRAY
STANDX~NSUBJ

1:1]
1:2]
[3J
[4]

5 U M ~< ~ .. + / ~.:
SUM~-:2~··+/ (N)'(2)
ACOMPUTE MEANy

[5J

VARIANCE y

STANDARD DEVIATION

MEANX~SUMX+NSUBJ

[6J

VARX~(SUMX2+NSUBJ)-MEANX*2

AFUN C T :J: 0 N ";: E T U F;: N !,i

I:: 7 ]
[8]

V (.~ LUliE 0 F

STAHDX~VARX*O.5

Ii?

6-10

!:; T ~) N x;r (.) F;: X:I

X:I Iii: V :I: (.~ T :t: 0 N

DEFINING AND EXECUTING FUNCTIONS

The V characters preceding line [1J and following line [8J indicate
the delimiters of the function and identify its name.
They do not
change the mode as the function prints. APL displays the number of
the next line after the final line of the function to give you the
opportunity to add new text.
If you want to display a line or an entire function and return to
immediate mode after the display, type the closing V on the same line
as the display request.
For example:
~STAT[DJ~

6.3.6

Editing the Function Header

You can edit the name or arguments of a function header by accessing
line number [oJ.
You can display and replace the function header just
like any other line in the function.
However, you cannot delete the
header using the delta character 6.
Also, you must include a valid
function header before leaving function-definition mode.
The following example displays the function header:
9STAT

[9]

[00]
9

[0]

STANDX~NSU~J

STAT X

Notice that the header is displayed without a line number. When you
specify a character position in the header (see Section 6.3.7), APL
types the header with line number [OJ and without the V.
For example:
9STAT

[9]
[0]

[007]
STANDX~NSU~J

STAT X

The caret in the above example indicates the position of the terminal
head.
It does not print on your terminal.
Line-editing positions are
discussed in Section 6.3.7.

6.3.7

Character-Editing Procedures

Besides providing a way to edit a function definition line by line,
APL allows you to edit a function definition character by character.
Character editing is a multiple-step process.
The first step involves
deleting characters no longer needed and inserting blanks in the line

6-11

DEFINING AND EXECUTING FUNCTIONS

to allow additional desired text to be typed.
The second step involves typing in the new text.
Repetition of these steps is often
necessary.
The final appearance of the line should be identical to a
function line just entered from the keyboard.
To modify a line, specify (1) the line number followed by (2) a quad
character (0) followed by (3) the estimated character position at
which editing is to begin.
For example:
VDIESEL

[7J
[lJ

[1010]
A~R*GAMMA-l

APL displays the line, performs a carriage return/line feed, and then
positions the cursor or terminal head at the position you specified.
In the example above, the caret (A) indicates the position specified;
it does not print on the terminal.
If you specify position 0, APL
places you at the end of the line. Once you are in the desired position, you can do any of the following:
1.

Delete a character by typing a slash(/) beneath each
character you want to delete.

Insert a space by typing a digit or letter beneath each
character before which you want to insert a space.
Typing
the digit 1 beneath a character inserts one space before that
character. A 2 inserts two spaces, and so forth.
You can
insert multiples of five spaces by using letters.
Typing an
A inserts five spaces; typing a B inserts ten spaces and so
forth.
If the number of spaces you specify plus the current
line length exceeds the length of the terminal line (the
value of OPW) you will receive a 5 DEFN ERROR error message.

All other characters you type are ignored.
When you press the RETURN key after inserting spaces and deleting
characters, APL displays the line with the inserted spaces and without
the deleted characters.
It then performs a carriage return and
positions you at the first inserted space on the line to be edited.
If you did not insert spaces, APL positions you at the end of the
line.
You can enter new text in the spaces or make further modifications to the existing text.
On APL terminals, you can backspace
to insert new characters and can create illegal overstrikes to aid
in retyping the line.
If you change the line number while you are editing the line, any
edits you make correspond to the new line number.
The original line
remains unchanged.

6-12

DEFINING AND EXECUTING FUNCTIONS

The following example illustrates the use of character-editing in
correcting the line:
T~(LETTR=5TRIHG/\8Py5TRIHG

[1]

There are several errors in this line:
1.

LETTER is misspelled LETTR.

The right parenthesis is missing after STRING.

The "8" should not appear at all.

The "PH should be p.

Because the first error occurs in LETTR, you could edit the line this
way:
V'FU~·~C

[:L[]1 4 :I

[!) ]

T~(LETTR=5TRIHG/\8

(1]

1 I

P~5TRIHG

T~(LETTE~=STRIHG)/\r,STRIHG

[1]

(2]

The cursor or terminal head is now positioned at the space between T
and R.
You can now enter the new characters, spacing over the text
you want to preserve. To do so, type the following:

E in the space between LETT and R

in the space between STRING and /

2.
3.

in the space between

and ,

The new line looks like this:
9 FUHC [:LrJ]V'
[:L]

T~(LETTER=STRIHG)/\f,5TRIHG

When you press the RETURN key, this line replaces the existing function line [1J in your function definition.
You can type a deliberate character error, for example, an illegal
overstrike, after a character-editing display to cancel the revision
of the function line. When APL encounters a character error, it
displays both an error message and the line up to the point at which
the error occurred. However, you cannot escape from character-editing
mode except by completing the line.

6-13

DEFINING AND EXECUTING FUNCTIONS

6.3.8

Performing Immediate-Mode Editing

You can edit lines during immediate mode as well as function-definition
mode.
In immediate mode, line edits affect the last immediate line
entered from the keyboard. Because immediate-mode lines do not have
line numbers, type (1) any arbitrary legal line number (that is a number less than 1000) followed by (2) a quad character (D) followed by
(3) the character position at which editing is to begin. For example:
ACRON~INIT1,INIT2[INIT3

SYNTAX ERROR
ACRON~INIT1,INIT2[INIT3

(1023]
ACRON~INIT1,INIT2[INIT3

11
ACRON~INIT1,INIT2,INIT3

Immediate-mode editing proceeds exactly as in function-definition
mode. However, after you press RETURN to conclude the final edits,
APL executes the line. Note that the DELETE key (RUBOUT), CTRL/U,
and CTRL/R also work in immediate mode.

6.4

EXECUTING THE FUNCTION

The process of defining a function associates the function header
provided by you with the statements you enter as the function body.
When you decide to execute the function, you use the function name as
you would use a primitive APL function.
The information provided in
the function header specifies the number of arguments to be supplied
in the function call and determines whether or not a value will be
returned.
Section 6.2.5 provides examples of defined functions and
their corresponding function calls.
It is also possible to issue function calls from within other functions. You can nest functions to any depth.
The following sections provide information on function execution.
They focus on branching, suspending, tracing, stopping, and locking
functions, using the state indicator, and trapping errors.

6.4.1

Branching Within a Function

APL statements in a function definition normally execute in the order
determined by their line numbers. Execution begins at the first
statement following the function header, terminates after the last
statement in the definition, and executes only once. You can modify
this standard order of execution by including branch statements in the
function definition. A branch statement changes the sequence of execution by transferring control to another line in the function definition.
Branching allows you to execute loops within the body of the
function.

6-14

DEFINING AND EXECUTING FUNCTIONS

There are two types of branch statements: unconditional and conditional.
An unconditional branch statement consists of a branch symbol
(+), followed by the number of the function line or label to which
you want to transfer control. For example:
(5]

This statement causes an unconditional branch from line [5J to line
[1J.
Line [1J is thus the next statement to execute.
The line number you specify after the + can be in the form of a constant, a variable, or an expression.
It must be equivalent to an
integer line number within the current function definition to allow
execution to continue.
If the integer does not reference a line number in the current function, the branch statement closes the function
and returns you to immediate mode or to the caller.
(APL users often
deliberately specify an out-of-range number to stop execution.)
Line
number [OJ, the function header, is not a legitimate reference for a
branch statement.
Therefore, specifying +0 also closes the function
and returns you to immediate mode or to the caller.
If the object of the branch is a nonempty vector, control passes to
the line number referenced by the first element of the vector.
If the
vector is empty, the branch statement is not meaningful and the normal
order of execution continues.
You can include a branch statement in the middle of a multi-statement
line.
However, if the branch executes, the rest of the expression to
the left of it is ignored.
If the branch does not execute, the result
of the statement scanned so far is considered the empty vector.
Therefore, the expression to the left of the branch is executed.
APL also allows you to include conditional branches in a
definition.
A conditional branch executes as the result
a logical expression, not in response to any specific IF
are two popular ways of doing a conditional branch.
The
is:
+

function
of evaluating
logic.
There
first format

line number x logical expression

For example:

APL evaluates the logical expression to the right of the line number
specification (+9).
Logical expressions return either a 1 (true) or a
o (false). Therefore, if I is greater than B, the value of the expression is 9x1 and control passes to line number [9J.
In the expression +(A<B)/13, if the logical expression A<B evaluates to 1,
(1/13), then control passes to line number [13J.
(If the logical
expression evaluates to 0, (0/13) returns a null so control passes to
the next line.)

6-15

DEFINING AND EXECUTING FUNCTIONS

You can include more than one line number in a conditional branch but
each line number must have a corr~sponding logical expression. Only
one expression can evaluate to 1. Both the line numbers and the expressions are separated by commas. For example:

APL transfers control to the line number whose expression evaluates to
1.

Note that you should use labels instead of line numbers in branch
statements because APL renumbers when lines are added or deleted.
Section 6.4.2 for a description of labels.

6.4.2

See

Statement Labels

Because APL automatically renumbers function lines as consecutive
integers when exiting from function-definition mode, problems can
occur when you refer to explicit line numbers in branch statements.
Instead, you can associate a line number with a label and reference
the label, not the line number, as the object of the branch. For
example:
[1SJ

INCR: I-+I+1

[27J -+

INCRxI<IMAX

As shown above, a statement label consists of a distinct identifier,
followed by a colon(:). When you specify the label in the branch
statement, you do not include the colon. The internal value of the
label identifier is the line number with which it is associated.
A label acts like a local variable in that its value is local to the
function in which it appears.
Label values are internally respecified
upon each exit from function-definition mode. You cannot explicitly
define a value for a statement label, and you cannot place a statement
label in the function header.

6-16

DEFINING AND EXECUTING FUNCTIONS

Following are two examples of defined functions that use branching and
statement-labeling techniques. Note that APL prints lines containing
labels or comments one character to the left of the rest of the text.
'7FACTOfi::I: AL [0] '7
'7

1:1]

1:;:t·I:"':~CTOfi: I

Fi:t-l

[2]

..tOX\O::::N

1::3:1
[4 J

Fi:t-Fi: X N

[~j]

... 2

t·~~ .. N·"·1

FACTOFo:IAL

'V Ff.H:' [0] '7

~~t·I::'AC

~NZEROX\N::::O

[1]

[2]

Zt-NXFAC

[3]

ANOTICE

[4J

AARE

[~)J

N-l
THAT

RECURSIVE

DEFINITIONS

PERMITED

.. ~O

[6J

N~·~F.::I:i:r.): ~~.f"1

Ff.~C

!:'j

:1.20

6.4.3

Suspending Function Execution

Function execution can be suspended before normal completion by means
of:
1.

An error report

An attention signal, two CTRL/Cs

The stop control vector

The OBREAK system function

When an error occurs, APL suspends function execution and displays an
error message and the line number where the error occurred. Appendix
A lists possible errors you may encounter. The attention signal, two
CTRL/Cs, is described in Section 1.4.4. The stop vector is described
in Section 6.4.6. The OBREAK system function is discussed in Section
4.3.1.
When function execution is suspended, APL displays the name of the
suspended function and the line number of the statement that would
have been executed next. APL then begins a new line, indents six
spaces, and awaits input in immediate mode. You can perform any
operation at this time, including erasing the suspended function (see
the )ERASE system command, Section 5.4.2).
The suspended function remains active until you terminate it, erase
it, or clear the currently active workspace. You can resume execution
at any time by typing:
-+

line

6-17

DEFINING AND EXECUTING FUNCTIONS

where line identifies the line number at which execution is to be
continued. You can terminate a suspended function by typing:
+0 or just +
When a function is suspended, its local variables remain active. You
can examine these variables and can specify their values by using an
immediate-mode assignment.
[]LC contains the line number of the line where execution was suspended. Therefore, +OLC restarts the suspended function at the
beginning of the line that was interrupted.

6.4.4

Examining the State Indicator

The state indicator is a status vector that resides in your active
workspace. You can examine the state indicator to determine the
status of all active functions by specifying an )SI system command
(Section 5.4.8). The )SI system command lists active functions as in
t:he following example:
) ~:; :r

T[3]
~:; 1:"7]

f/.

F·: [6::1

F[2::1

f/.

The listing displays functions in the order in which they were most
recently active. The example included above indicates that execution
was suspended during execution of statement [3J of function T, which
was called during line [7J of function S, which was called during line
[6J of function R.
(Before this sequence of calls, execution was
suspended during execution of line [2J of function P.)
In the )SI display, an asterisk (*) following the name and line number
indicates a suspended function.
The other functions in the list are
pendent. A pendent function is one which is awaiting return from
another function - possibly a suspended one - which it called. You
can edit a suspended function but not a pendent one. Although you can
erase both suspended and pendent functions, you can cause considerable
confusion by erasing a pendent function and then resuming execution of
a suspended function that was called by that pendent function.
Following is an example of an operation of this kind:

(.~[~5]

f/.

E<[4]
C[~.:i]

11:

) r:::r~:('~SE::

)~:; I

'/(

E'[4]
C[~i]

6-18

DEFINING AND EXECUTING FUNCTIONS

You can resume execution of C at this point but not B.
In the )SI
display, an asterisk without a line number indicates an erased
suspended function.
Whenever you erase a pendent function, APL
displays:
13 POSSIBLE SI DAMAGE

to warn you to consider the status of existing functions before you
resume execution.
From the )SI listing you can also determine when quad-input requests

~~~a~e~~!~~l~!I~!!~~!~I~~~~~~~~~~ing.

An example of both of these special conditions is shown below:
) ~;} I

F[2::1

A[?::I
T~··[]

n:
AiX

IJ
"'"[2::1
(.)[ "7::1

"/(

You can clear the state indicator by terminating the execution of each
suspended function in the list.
There are several ways to accomplish
this:
(~)

You can type a right arrow
asterisk.

for each function marked by an

You can issue the I-beam function 130 to clear the state
indicator completely (Appendix C).

You can clear the state indicator by saving the active
workspace, then clearing and copying it again (see the )COPY
system command, Section 5.4.1).

If the state indicator is clear, APL outputs a blank line in response
to )SI.
You can use the )SIV system command (Section 5.4.9) to obtain a more
extensive display of the state indicator.
In addition to the information accessible to )SI, )SIV returns a list of local and dummy

6-19

DEFINING AND EXECUTING FUNCTIONS

variables for each function displayed. The current line being executed by the execute function is ~lso displayed.
The following is
an example of an )SIV display:
)SIV

5[6J

*
*

F[2J
A[7]

T
T

T[3J
[1]

M B;OIo;m
~Z~A
OBREAK tL£NE 1 OF

[2J

1 M 2
LINE

OF M
)SIV

M[l]

S[lJ

*
*

DID

This indicates that. the variable T, local to function F is currently
dominant, and that the variable T local to function A, as well as the
function named T, are currently inaccessible.

6.4.5

The Trace Vector

You may find it helpful for debugging purposes to obtain an automatic
printout of intermediate results of function execution. As a program
tracing aid, you can output the values computed by one or more function statements each time those statements execute.
To set the trace vector, use the following format:
T6function name+line number(s)
where function name is the name of the function you want to trace and
the line number(s) are the lines you want information on.
You can set the trace vector in either immediate mode or within a
function definition. For each execution of the line numbers you
specify, the trace vector causes the following information to be
displayed in the order shown:
function name
bracketed statement line number
final value returned by each statement on the line

6-20

DEFINING AND EXECUTING FUNCTIONS

An example of a trace operation is shown below:
TOF~4

6 7

F[4]
F[6J
F[7]

32.5 37.9
9
16 1.7

If the statement being traced is a branch statement, then the value
printed is the line number to which control is passed by the branch.
In the example above, line [6J was +9.
To trace all the statements of a function, for example F, you can
supply the following specification:

where N is a number at least as large as the number of statements in
F.
To disable the trace vector, type the following:

T6FUNCTION NAME+l0
For example:

The trace control vector can be set within a function to aid in
selective tracing or setting breakpoints. For example, you may want
to initiate tracing if certain conditions are in effect and disable it
as soon as a specified value has exceeded a defined maximum.
If you edit a function for which you have defined a trace control
vector, you clear the trace vector. Also, when you lock a function,
you automatically clear the trace vector. The trace vector setting is
saved with your workspace.
Note that APL identifiers cannot start with T6 because this is reserved for the trace vector syntax.

6-21

DEFINING AND EXECUTING FUNCTIONS

6.4.6

The Stop Vector

APL allows you to suspend execution of a function at predetermined
points. A stop control vector is available with a syntax similar to
that of the trace vector.
To cause statement execution to stop before
executing a particular line, you can type the following:
S~function

name+line number(s)

where function name is the name of the function you want to suspend
and line number(s) specify where you want to suspend execution.
You
can set the stop vector either in immediate mode or within a function
definition. When you execute the function, the stop vector suspends
execution at the first line number you specify.
It displays the
function name and the line number.
You can resume execution by typing
a branch to the desired line number (+5) or continue by typing +DLC.
The stop vector will then suspend execution at the next line you
specified.
When you edit a function for which you have defined a stop control
vector, you automatically clear the stop vector. Also, when you lock
a function, you automatically clear the stop vector.
The stop vector
setting is saved with your workspace.
Note that APL identifiers cannot start with
served for the stop vector syntax.

6.4.7

because this is re-

Locking a Function

APL allows you to lock a function definition to protect it from
unauthorized use, to maintain security, or to treat a function as a
proprietary program.
To create a locked function, or to lock an
existing function, you open or close the function with a del-tilde
(~) character (protected del) rather than a simple del (V).
The
del-tilde (~) is created by overstriking (V) and (~).
The following example illustrates the locking of a previously unlocked
function definition:
7TRIG

[19J

A locked function cannot be edited in any way; if you try to edit a
locked function, you will receive the error message, 5 DEFN ERROR.
You cannot add, change, delete, or display a function line.
Trace and
stop vectors cannot be defined or changed for the function.
Any trace
or stop settings in effect at the time you lock the function are
automatically cleared.
If an error occurs during execution of a locked function, the function
name and line number at which the error occurred are displayed, but
the contents of the line are not displayed. APL then causes an exit
from all pendent functions that are locked until the function on the

6-22

DEFINING AND EXECUTING FUNCTIONS

top of the SI stack is not locked.
If all functions on the SI stack
are locked, APL clears the SI stack and enters immediate mode.
Note
that you cannot unlock a function once it is locked.
However, you can
delete a locked function by using )ERASE.
CAUTION
If a locked function calls an unlocked
function and the unlocked function
becomes suspended, the environment of
the locked function is available for
examination.

6-23

DEFINING AND EXECUTING FUNCTIONS

6-24

DEFINING AND EXECUTING FUNCTIONS

6-25

DEFINING AND EXECUTING FUNCTIONS

6-26

DEFINING AND EXECUTING FUNCTIONS

6-27

DEFINING AND EXECUTING FUNCTIONS

6-28

CHAPTER 7
THE FILE SYSTEM

7.1

INTRODUCTION
/

The file system is an integral part of the APLSF language itself.
allows you to store data files on a number of system devices.

APL can create and handle a variety of file types. You determine the
size and content of the records and the structure and access properties of the file.
You can write records into a file in either immediate mode or function-execution mode and subsequently retrieve them.
One of the most significant extensions of this implementation of APL
is the inclusion of a powerful data-file capability.
APL allows you to create and store four types of files:
1.

ASCII sequential

Internal sequential

Direct access

Binary access

ASCII sequential files allow you to create and/or read any standard
ASCII file while at APL level. You can read and work with an ASCII
file created by another language, or you can create an ASCII sequential file to be passed to a program in another language such as
FORTRAN or COBOL.
Internal sequential files and direct-access files
can be created and read only by APL functions (or by you in immediate
mode). Binary-access files can be accessed in any format as randomaccess memQry, and can be read and written in almost any language.
The file system has three distinct components:
1.

File functions that allow you to read from a file (ffi) and
write to a file (ffi)

System functions that allow you to assign, deassign, close,
rename, and append files

System commands that create a direct-access file and divert
terminal input and output to other devices

7-1

THE FILE SYSTEM

This chapter focuses on the following:

7.2

Access methods

APL file input and output functions

Basic file system functions

Sequential files

Random-Access files

utility system functions

Synchronizing shared-file access

Handling I/O from non-terminal devices

ACCESS METHODS

The methods that you use to store or retrieve data in a file are
determined by the file's organization. The organization of a file is
fixed at the time you create it, but, depending on the access allowed,
an access method can change each time the file is opened.
In some
cases, you can vary the access during function execution or during
immediate mode. You can use two types of record access: sequential
or random.
Sequential indicates that the records are accessed in a
serial order; random indicates that records can be accessed directly
at any point in the file.
Table 7-1 shows the relationships between file organization and record
access.
Table 7-1
Access Methods
File Organization

Access Method Allowed

ASCII sequential

Sequential only

Internal sequential

Sequential only

Direct access

Sequential and random

Binary access

Sequential and random

The following sections discuss each type of record access.

7.2.1

Sequential Access

All file organizations allow you to access records sequentially.
Sequential record access is employed when you issue a series of
requests for the next record. The record operations are performed
in terms of a predecessor-successor record relationship. For each
successfully accessed record (except the last) there is a succeeding
record somewhere in the file.

7-2

THE FILE SYSTEM

Sequentially organized files (ASCII sequential, internal sequential,
and binary-access sequential) allow only sequential access.
In these
files, each record except the last is physically adjacent to the next
record.
Sequential access to a sequential file means that records are
accessed in the order of their insertion into the file.
A particular
record can be read only after each preceding record has been successfully read.
Similarly, once a record has been read or written, you
must reposition the file to the beginning before preceding records
can be accessed.
When you assign a sequential file with either the lAS switch (ASCII
sequential) or the lIS switch (internal sequential), APL positions the
file pointer at the beginning of the file.
You must then do sequential reads to get to the particular record you want.
If you do a
write operation at the beginning of the file, you overwrite the existing file, not just the existing record.
When you assign a sequential file with either the IAS* switch or the
IIS* switch, APL positions the file pointer at the end of the file.
You can then append records to the end-of-file with a write operation;
a read gets an end-of-file.
Direct-access and binary-access files can be accessed sequentially.
Sequential access to a direct-access or binary-access file means that
records are accessed in ascending order according to record number
(for direct-access) or word number (for binary-access). A sequential
read from one of these files finds the next record by adding I to the
value of the record/word number used in the previous I/O operation.
Binary-access files allow the writing of data based on word position.
Empty words are assigned a value of integer O.
Direct-access files
allow, empty record positions that can be caused by a record deletion
or by your purposely leaving positions empty. APL maintains the
predecessor-successor relationship through its ability to recognize a
record position as either empty or occupied.

7.2.2

Random Access

Random access allows you to control the order of record access.
The
predecessor-successor relationship has no effect on random access.
You identify each record of interest in each operation. This procedure allows you to access records in any order at any point in the
file.
Random access is not permitted on ASCII and internal sequential
files because of the strict physical relationship maintained among
records.
Direct-access and binary-access files do allow random access.
By specifying a record number in a direct-access file or by specifying
a word number in a binary-access file, you can access any record in
the respective file.
You can also alternate the type of access to
these files, sequential or random.
Records in APL random-access files are called components. There is no
restriction that all records in these files be the same length.

7-3

THE FILE SYSTEM

7.3

FILE INPUT/OUTPUT FUNCTIONS

ffi

AND ffi OR .IQ AND .OQ

You can initiate input and output to and from a file either in immediate mode or during function execution. When you perform a read operation, you are requesting input data from the file.
When you perform
a write operation, you are outputting data to the file.
APL provides two quad functions for files, one to perform file input
and one to perform file output: ffi (.IQ) and ffi (.OQ).
These functions
work in much the same way as the basic quad input and output functions
described in Section 2.5. The file input and output characters are
formed by overstriking the quad (D) with either the left arrow (+) or
the right arrow (+).
The syntax of the I/O functions is explained with each file organization.

7.4

BASIC FILE SYSTEM FUNCTIONS

The following sections describe four basic system functions that perform the following file operations:
1.

Assigning a file DASS

Deassigning a file DDAS

Closing a file DCLS

Renaming a file DRENAME

The names of these system functions, like those described in Chapter
4, begin with a quad (D) character and are considered to be distinguished names.
That is, you cannot use them for user-defined function
names, and you cannot copy, erase, or collect them in a group.

7.4.1

DASS - Assigning a File

Format

DASS' [channel] filename [password][;file org][;share][;dump] ,
where
channel is an integer scalar in the range 1 through 12 inclusive.
If you do not specify a channel number, APL assigns you one.
filename identifies the name of the file to be read or written on
the specified channel. The filename has the same format as a
workspace filename.
See Section 5.1.3.1.
password is optional.

The default is (-).

/file org is one of the file organizations listed in Table 7-2.
If you do not specify this switch, the default is IDA.

7-4

THE FILE SYSTEM

/share is a switch that allows you to extend multiple-user characteristics.
It is relevant to direct-access and binary-access
files only (Sections 7.6.2 and 7.6.5).
/dump is a switch used for magnetic tape I/O.
It is relevant
only to binary-access files (Section 7.6.8.1). The single
quotation marks are required.
The DASS system function assigns a file to a specified channel number.
In this way, you can refer to the channel number rather than the
filename specification when performing I/O. You can also use DASS to
return information concerning a file.
By specifying the channel as
the argument, you receive the name of the file currently assigned to
that number plus any other characteristics you may have specified
previously.
For example:
OASS

DIRACC.EXM

2
[4~204]/DA

If the channel you specify is currently unassigned, APL returns a null
vector.
The DASS system function operates in the same manner as any other (APL
function.
DASS returns the value that is the channel number you
assigned. Therefore, you can specify a variable to receive the value
of the channel number.
For example:
CHAN~OASSITEST/ASI

CHAN

Because the range of channels is 1 through 12 inclusive, you cannot
access more than 12 files simultaneously.
If you do not specify a
channel, APL assigns an available channel in the system and returns
this number as the function result.
If you assign a channel number
(for example 12) that has already been assigned to a file, APL closes
the first file and deassigns it from the channel, then assigns the new
file to that channel number.
If a syntax error is encountered in the
DASS function or if there are no available channels, APL returns a
function result of 0, which means your assign failed.
The DASS system function does not cause input or output to be performed.
It establishes a connection between a filename and a specified
channel.

7-5

THE FILE SXSTEM

Table 7-2
File Organization Switches
File org
Switch

Default
File Extension

lAS

.AAS

ASCII sequential

.AAS

ASCII sequential; file is positioned at end of file to allow
appending

.AIS

Internal sequential

.AIS

Internal sequential; file is
positioned at end of file to
allow appending

IDA

.ADA

Direct-access which supports
reading and writing

IDI

.ADA

Direct-access which supports
reading only

IBS

.ABI

Binary-access which supports
reading or writing, but not both;
file can be read by multiple
users, but written by only one
user at a time

.ABI

Binary access; file is positioned at end of file to allow
appending and same user capability as IBS

.ABI

Binary-access which supports
reading and writing; file can be
used by only one user at a time

lIS

IBU

7.4.2

Type of File

DDAS - Deassigning a File

Format

DDAS

channel(s)

where
channel(s) is either a numeric scalar or vector, or a null
vector.
The DDAS system function deassigns the files on one or more channels
in the system.
In general, DDAS reverses the operations performed by
the DASS system function.
It disassociates the channel number(s) with
the file(s).
If the files associated with the channel numbers being
deassigned have not been closed (DCLS), DDAS closes these files
automatically.

7-6

THE FILE SYSTEM

Like the DASS system function, DDAS returns a function result.
cases, this result is a null vector.

In all

For example:
ODAS 1

This example outputs a blank line and deassigns the file associated
with channell. The following example deassigns files from three
channels:
ODAS 2 3 5

You can deassign the files on all channels by specifying a null vector
as the argument (or 112).
For example:
DDAS

ASAME AS
ODAS t12

7.4.3

DCLS - Closing a File

Format

DCLS

channel(s)

where
channel(s) is either a numeric scalar or vector, or a null
vector.
The DCLS system function closes the files on one or more channels in
the system. However, DCLS does not deassign the channel from the
file.
This capability is useful when you want to return to the beginning of a sequential file after performing an operation. After
you close the file, the next read operation reads the first record in
the file; the first write truncates the file.
There is no need to
reassign the file to the channel.

7-7

THE FILE SYSTEM

The following example closes the file associated with channel 2:
OCLS 2

The DCLS system function always returns a null vector as a result.
You can specify more than one file or all files.
For example:
eCLS

2 3

eCLS

ASAME

eCLS

\12

7.4.4

DRENAME - Changing the File Specification

Format
'filespec'

DRENAME

channel

where
filespec is the new file specification. You can specify all or
part of a new file spec. Every element except the name is
optional. The single quotation marks are required.
channel is the number associated with the file.
Specifying elements of the filespec-a new device name, extension or
filetype, protection code, or directory- is optional. The old value
is the default.
The DRENAME system function renames a currently assigned file.
Therefore, before you can use DRENAME, you must assign the file with DASS.
When you execute DRENAME, you also close the file if it is open.
If other users have the file open when you issue a DRENAME, the
DRENAME will fail, but the close will be done in any case. Also, if
other users have the file assigned but not opened (have not performed
a read or write) they cannot use the file until they reassign it under
the new name.
However, you, the user performing the DRENAME, will
automatically have the file reassigned on the same channel under its
new name.

7-8

THE FILE SYSTEM

For example:
OASS'TEST/AS'
10

INEW'

OREHAME

OASS 10
HEW+AAS [4y204J/AS

7.5

SEQUENTIAL FILES

APL supports three types of sequential files:
ASCII sequential internal sequential, and binary-access sequential files (/BS and /BS*).
The first type, ASCII sequential, is a standard operating system ASCII
sequential file that can be read or written by APL or by other languages. This file format is line-oriented; a record is delimited by
a carriage return.
Therefore, each line is considered a record in the
file, and records in the file can be of different lengths.
You can
display ASCII sequential files on terminals and high-speed printers.
To display an ASCII sequential file on the terminal, return to operating system command level and type a standard system command:
TYPE filename
To display such a file on a line printer, type the operating system
command:
PRINT filename
The second type of sequential file, internal sequential, is a file
that can be read or written only by APL.
In this file format, information is read and written in internal binary format.
In internalsequential files, a record is all the data written to the file in a
single output operation, rather than a single line in an ASCII sequential file.
The third type, binary-access sequential, is a file that can be read
or written by a file in another language such as FORTRAN, as well as
APL.
APL does not open a sequential file for input or output until the
moment when the first read or write request is made. APL does not
normally close the file until you direct it to do so with a DDAS or
DCLS system function, or a )LOAD, )CLEAR, )OFF, or )CONTINUE system
command.
This implies that if user A is writing a sequential file and
user B subsequently starts to read the same file, user B will read the
copy of the file that does not have the updates just made by user A.
If your first reference to a sequential file is an input request (read)
all subsequent I/O requests to that file must be input requests, until
you close the file.
Similarly, if the first file reference is an
output request, all subsequent I/O requests must be output requests.
Note that you can store sequential files on many types of system
devices.

7-9

THE FILE SYSTEM

The following subsections describe the way in which I/O functions for
ASCII sequential and internal sequential file organizations are formatted. The description of binary-access files begins at Section 7.6.4.

7.5.1

ASCII Sequential I/O

The following format requests input from an ASCII sequential file:
@ [[mode]] channel
where
@.is the input quad function.
[mode] is one of the integer scalars listed in Table 7-3.
It
specifies both the type of data and the character set of the data
being read. mode is optional but, if present, you must enclose
it in square brackets.
channel is the channel number associated with the file.
value of the @ function is the data read.

The

The following format requests that output be written to a file:
data

ffi

[[mOde]] channel

where
data is the information you want to write to the file.
ffi

is the output quad function.

[mode] is one of the integer scalars listed in Table 7-3.
It
specifies both the type of data and the character set of the data
being written. mode is optional, but if present, you must enclose it in squar~ brackets.
channel is the channel number associated with the file.
value of ffi is data.

The

Because you can write different types of data to a file, you must tell
APL how to read the data by specifying an input mode. When reading,
you also specify whether the record was written with mnemonics or with
the APL character set. Table 7-3 lists input modes and their meaning.

7-10

THE FILE SYSTEM

Table 7-3
Input Modes
Input Type

Character Set

TTY

APL

Mode

The default input mode for TTY is 1; the default input mode for APL
is 4. For more information on input quad types, refer to Section 2.5.
For @, modes 1, 2, and 3 are equivalent and modes 4, 5, and 6 are
equivalent. When accessing APL, you have the option of specifying a
particular APL character set on output when you respond to TERMINAL ..
with TTY. The modes 4, 5, and 6 use the setting you specified at
access time. See Section 1.2 for terminal designators and section 7.9
for )INPUT and )OUTPUT to non-terminal devices.
When you are reading or writing to an ASCII sequential file, the first
thing to do is to assign the file to a channel.
If you want to append
to the file, specify /AS*.
For example:
DASS

'2 FILE/AS*'

When you are writing to a file, using the output quad @ is the same
as using D+A, except that the output is written to a file and not the
terminal. A record is a string of ASCII characters terminated by a
carriage return. APL inserts the carriage return/line feed into the
data. The current width value associated with the active workspace
is used to determine the maximum length of the line to be output.
This means that the current page width determines the length of the
record if the data is longer than the Imaximum. APL inserts a carriage
return/line feed when you reach the maximum setting. You can change
the setting with the DPW system variable (Section 4.2.15). You can
also divert output to devices other than your terminal with the )INPUT
and )OUTPUT commands, Section 7.9.
If you output to a line printer,
you should change the width value to 130.

7-11

THE FILE SYSTEM

The following example illustrates the writing and reading of an ASCII
sequential file.
If data is an expression, you must enclose it within
parentheses.
OASS

12 OUTPUT/AS 1

")
~

AU USES

THE APL CHARACTER SET
ATERMINAL IS AN LA37
1

F :1: I~: !:> T

F I f::S T

F;:ECOR:f.J 1 1]2

F;: m: c (.') I:;: f.I

'SECOND RECORD'a2
!:',ECONX;' f;:ECOI:;:f.I

:1,
I::'
,oJ

2
6

(2 4f\BHJ2
:3
4

~] I:: ~,:.:;

F:r. R:S T

:11

[lc!"'!:>

,'\
~':.

J :::.

f;:ECC>I:;:D
U[~5J2

F;:ECOI:;:D

~::'ECOHD

U[-4J2
:::. 3 4
K:t[4J:?

::5 (.; 7 B
(.~'~"r:I I:: -4::1 2

.f' (.)

() 7::5

In the previous example, the first two records are strings and the
third record is a numeric expression.
To read the output, you first
close the file because you cannot do both input and output at the same
time.
You do not need to assign the channel; DCLS does not deassign
the channel.
Notice that, because the numeric expression is a matrix, APL had to
insert a carriage return/line feed to format it properly.
Therefore,
even though you write an array as one record, it resides in the file
as more than one record.
For example, the above matrix had two records when read.
The expression A+8[4J2 requests input and assigns the value to A.
Since the file pointer was at the end-of-file, the value was a null
array.
The pA returns the null array of shape 0 75: the error number
is 75.
(See Appendix A for error messages).
This error message means
end-of-file. A blank line in a file is ignored in mode [1J and is a
null vector in modes [2J and [3J. A blank line is ignored in mode [4J
and is a null vector in modes [5J and [6J.
To write to the end of an ASCII sequential file, assign the file with
the /AS* switch.
This positions the file pointer at the end of the
file so you can append to it with write operations without overwriting
current records. A read to a /AS* file gives an EOF.

7-12

THE FILE SYSTEM

7.5.2

Internal Sequential Files

The following format performs a read from an internal sequential file:

@ channel
where

@ is the input quad function.
channel is the channel number assigned to the file.
@ is the data read.

The value of

The following format writes a record to an internal sequential file:
data @ channel
where
data is the information you want to write into the file.

@ is the output quad function.
channel is the channel number assigned to the file.
@ is data.

The value of

When performing I/O on internal sequential files, you need not specify
an input mode as you do with ASCII sequential files.
Information in
an internal sequential file is stored in the internal format of APL,
which is very different from ASCII format.
No conversion effort is
incurred by using internal sequential files; compared with ASCII
sequential files, there is practically no overhead involved in reading
and writing internal sequential files.
When you are reading or writing an internal sequential file, the first
thing to do is to assign the file to a channel.
If you want to append
to the file, use the /IS* switch. For example:
OASS

'IHT/IS*'

In an internal sequential file, a record is all the information previously written in a single output operation. A single read will
retrieve all information output at a single write rather than a single
line that would be retrieved by an ASCII sequential operation. Also,
when you write an array to an internal sequential file, APL includes
the shape of the array along with the array itself. Therefore, you
need only a single read to retrieve the array. The array is stored in
one record.

7-13

THE FILE SYSTEM

Another comparison between ASCII sequential and internal sequential is
that 0 75 indicates end-of-file in internal sequential as well as ASCII
sequential. A blank record in JIS returns blanks. For example:

o (.~ S S

1: t·rr I I S

4
I

T()Ps .... l0\~~F:·l.. I U4

TOPS .... :I. O\(.~PI...
I

TC)f'"s .... 20\(.~PL I EJ4

T()f!"!:; ····::.~O\(.~pl...

(24J-'lBHI4
:I.
~.:;

23-4
I.>
l
D
oel...s

Kl4

TOF·S .... :I. ()\('~Pl...

[14
TOf!"s····2()\(.~I::·1...

El4
:1.
~7;

2
6

:.~

4
B

[14
(.~~"[14
J-'(.~

o l~5
Note that internal sequential files can reside on many system devices.

7.6

RANDOM ACCESS FILES

The following sections describe the characteristics of files that you
can access randomly as well as sequentially: direct-access files and
binary-access files.

7.6.1

Direct-Access Files

A direct-access file is structured as a collection of variable-length
records with a directory containing pointers to each record. A record
can be any size. A direct-access file can reside only on disk but the
only limit imposed on the size of the file is the amount of disk space
available. You must specify the number of records you plan to write
to the file when you first create the file.
Unlike the procedure for
creating ASCII sequential, internal sequential, and binary-access
files, the procedure for creating a new direct-access file requires
that you use a system command, )CREATE.

7-14

THE FILE SYSTEM

The )CREATE command has the following format:

)CREATE filesize filespec [password][bloCking factor]
where
filesize is an integer that specifies the number of records you
plan to write. You are only limited by the amount of disk space
you have available.
filespec is the device name, filename, extension or type, directory, and protection code.
See Section 2.1.4. Everything but
the filename is optional.
password is optional. The default is a hyphen (-) ~
access is the only file type with a password.)
blocking factor is one of the following values:
and 128 words.
The default is 16 words.

(Direct

8, 16, 32, 64,

When you specify the )CREATE command, APL sets up the parameters of
the new file according to your specifications.
It creates a directory
that acts as an index for the file.
The filesize determines how many
records the directory, and subsequently the file, will contain. For
every record you write, there is an entry one word long (36 bits) in
the directory.
This entry contains information about the record such
as its file position and its size. This directory allows you to
access records randomly by the number position in the file.
The
directory keeps track of where the records are.
Because you can delete records in direct-access, there is another area
in the file called the free-space area.
The free-space area keeps
track of where the holes are in the file.
When you delete a record,
an entry is made in the free-space area.
The blocking factor you specify with the )CREATE command allows you to
allocate space more efficiently in your file.
By specifying a blocking factor you actually set up a fixed length for each record.
If the
data you enter is less than the number of words you need to block it,
APL fills the rest of the record with nulls.
For example, if you
specify a blocking factor of 16 words and the data you enter is 35
words, the record will occupy 48 words of space. By specifying a
smaller blocking factor, this type of waste can be minimized but
writing records with smaller blocking factor takes longer if the
record lengths are bigger than the blocking factor.
Note that you do not need to use the )CREATE command for direct-access
files that already exist. Once you create a direct-access file, its
characteristics remain until you delete the entire file.

7-15

THE FILE SYSTEM

7.6.2

Sharing Direct-Access Files

Before you do any I/O on a direct-access file, you must assign it to a
channel with DASS.
Because you can share direct-access files, you
have the option of specifying one of three switches with the DASS
operation.
They are:

/DI

multiple-user access; file can only be read.

/DA

single-user access; file can be read and
written only by one user at a time.

/DA/SHARE

multiple-user access; file can be read and
written.

If one user opens a file in /DA mode and another user attempts to
access the same file in /DA or /DA/SHARE mode, the operation will fail
and the error message 32 FILE BEING MODIFIED will be displayed.
Sharing of direct-access files is synchronized by the DENQ and DDEQ
system functions described in Section 7.8.

7.6.3

Direct-Access I/O

The following format performs a read from a direct-access file:

8 [[reCOrd]] channel
where

8 is the input quad function.

The value of 8 is the data read.

[record] is the component number of the record you want to access.
If [record] is not specified, the default is the next record.
If [record] is specified, you must enclose it in square brackets.
channel is the channel number of the file.
The following format writes a record to a direct-access file:
data ffi [[record]] channel
where
data is the information you want to write to the file.
ffi is the output quad operator.
[record] is the component number you want associated with the
record.
The default is the next record position after the last
operation.
channel is the channel number associated with the file.
value of the ffi is data.

7-16

The

THE FILE SYSTEM

The following format writes the record at the end:
data

DAPPEND

channel

where
data is the information you want to write to the end of the file.

DAPPEND is the system function that allows you to write to the
end-of-file.
channel is the channel number associated with the file.
The value of DAPPEND is data.

DAPPEND acts like 8 except for where the new record is logged into the
directory.
DAPPEND finds the highest record number used and adds one
to that number.
This becomes the record number of the new record.
The new record is logged into the directory and the record is written
for random access.
If you proceed to do a read, you will find you are
at the end-of-file.
If you then do another write 8, you perform the
same operation.
DAPPEND will not enlarge the maximum number specified
in ) CREATE.
When you write a record to a direct-access file, you or APL, associate
a record number with the data written.
For input, you specify the
number of the record you want to read.
Because the directory keeps
track of the record numbers, you can read and write records in any
order.
For example, you can write record 10 before you write record
9.
If you try to read a record that does not exist, the value of the
read is a null array.
The shape of this array is 0 75, where 75 indicates an end-of-file.
To delete a record, .write a null array of shape 0 75 in its place.
For example:
(0 75rO)U[5JC

You can access records both randomly and sequentially.
If you do not
specify a record number in your read or write operation, APL uses as
the record number, 1 plus the value of the record position used in the
previous I/O operation.
If the current S is the first I/O operation
on the channel, record one, the first record in the file is used as
the default.
The following is an example of creating and accessing a direct-access
file:
)CREATE 100 DIRACC.EXM
OASS '2 DIRACC.EXM/DA'
B~(2

4f18)U[98J2

'RECORD 8'U[8J2
RECORD 8
fD~U[98J2

2 4

7-17

THE FILE SYSTEM

ANEXT OPERATION WRITES

RECORD 99

( ,4 )[t::,~
:L 2 :3 4
[i[8::12
HECOF·:D B

[1[99:12
1. 2 :'5 4
OCI...~:i

For the sake of efficiency, APL will not write a. record across a block
boundary (128 words) unless the record is larger than 128 words. Because of this limitation, it is very inefficient to have files where
all records are between 65 and 100 words.
It is more efficient to
write fixed-length records. For example, if you realize that all
records w~ll be between 10 and 32 words, you can specify a blocking
factor of 32. This will reduce CPU time and the real time involved in
I/O operations. The file size will, however, be larger than if you
had specified a blocking factor of 8 or 16.
If most of your records
are larger than 128 words, you should set the blocking factor to 128.
You can also reduce processing time by updating the file in order of
record numbers - for example, by writing records 5, 9, and 200 in
order instead of 5, 200, and 9. When updating a file, you should
perform deletions first and then replacements and additions.
The formula for determining the number of words that data (for example, the letter A) will take up, is:
3 + ( f' r (.~ ) + r ( x / r (.~ ) .:. L.

where
L is 0.5 to indicate floating-point

1
4
36

for integer
for character
for Boolean

Note that direct-access files can reside only on disk or drum devices.

7.6.4

Binary-Access Files

API. treats a binary-access file as random-access memory. By using a
binary-access mode, you can access a file of any format or characteristics. For example, you can read and write FORTRAN or COBOL randomaccess files with an APL binary-access function.
To read or write this type of file, you specify the following:
1.

The word of the file at which reading or writing is to begin

The type of values to be found beginning at the specified
word (for example, integer, ASCII)

The number of values to' be read or written

7-18

THE FILE SYSTEM

Data is stored in variable-length records that you can access randomly
or sequentially by specifying a word position, rather than record
position as in direct-access files.
Because you specify data type when performing I/O (see Sections 7.6.6
and 7.6.7), you can read or write any type of file organization including ASCII sequential, internal-sequential, and direct-access files.
For magnetic tapes in binary-access mode, you can perform a variety of
magnetic tape operations with the DMTP system function.
Refer to
Section 7.6.8.2 for more information on DMTP.
Binary-access files can be shared with other users.
for file sharing information.

7.6.5

See Section 7.6.5

Sharing Binary-Access Files

Before you can perform I/O on a binary-access file, you must assign it
to a channel number with DASS.
You have the option of sharing binaryaccess files with other users. You control the extent of the sharing
by specifying certain switches with DASS.
They are:

/BS

File can be read or written but not both;
file can be read by multiple users but
written only by one user at a time.
Sequential access only.
S~me access privileges as /BS,

except
sequential output begins at end-of-file.
Sequential access only.

/BU

File can be read and written; only one user
can have a /BU file open at any time.
If
another user attempts to read or write a /BU
file that is already in use, an error message
32 FILE BEING MODIFIED will be returned.

/BU/SHARE

File can be read and written; multiple users
can simultaneously have the file open. A
user cannot access a file in /BU/SHARE mode
if another user has already opened the file
in /BU mode.

Note that in the case of /BS and /BS*, on output, if you specify a
word position that is less than the last word output, you erase the
entire file and create a new file with your output written at that
word position.
The DENQ and DDEQ system functions, described in detail in Section 7.8,
synchronize the sharing of binary-access files.

7-19

THE FILE SYSTEM

7.6.6

Binary-Access I/O

The following format performs a read from a binary-access file opened
as /BU t /BU/SHARE t /BS t or /BS*:

E1 [[ word]] channel [, header [, type [, length] ] ]
where

E1 is the input-quad function.

The value of E1 is the data read.

[word] is an integer specifying the word position at which reading is to begin. The default is 1 (first word).
The file pointer
is at either the beginning of the file, or at the next word after
the previous I/O operation.
channel is the channel number assigned to the file.

header is either the value
for no header, or 1 if a header is
available.
The default is 1.
If you specify header, you must
specify type and length.
If header is 0, APL takes the correct
type and length from the data.
type is an integer from 1 to 6, specifying the type of data being
read.
See Table 7-4 for data type values.
If a header exists,
you need not specify type.
length is an integer indicating the number of values to be read;
not the number of words.
If a header exists, you need not
specify the length.
Table 7-4
Data Types
Type

Data

Value Size

integer

1 per word

Boolean

36 per word

single-precision
floating-point

1 per word

double-precision
floating-point

1 per 2 words

APL 9-bit

4 per word

ASCII 7-bit

5 per word

7-20

THE FILE SYSTEM

The following format writes a record to a binary-access file.
data ffi [[word]] channel [,header [,type [,length]]]
where
data is the information you want to write to the file.
ffi is the output-quad function.

The value of ffi is data.

[word] is an integer specifying where you want the write to
begin. The default is 1 if the file pointer is at the beginning
of the file or the next word after the previous operation.
channel is the channel number associated with the file.
header is either 0 if the header does not exist, or 1 if the
header is available. The default is 1.
type is an integer from 1 to 6 specifying data type.
See Table
7-4.
If you do not specify type, APL attempts to write the data
in the proper type.
length is an integer indicating the number of values to be
written. When you specify a header, the length specification is
ignored.
The following format writes a record to the end of a binary-access
file opened as /BU or /BU/SHARE:
da ta DAPPEND channel [, header [, type [, length] ] ]
where
data is the information you want to append to the end-of-file.
channel is the channel number associated with the file.
header is either 0 or 1.
type is one of the data types listed in Table 7-4.
length is an integer indicating the number of values to be
written.
The value of DAPPEND is data.

DAPPEND writes to the physical end-of-file.

The default word number
for the next read or write to the file is now the end-of-file.
In
other words, the sequence DAPPEND, then 8 with no word specification
always gives an end-of-file, while the sequence DAPPEND then ffi with
no word specification appends a second record to the end-of-file.
To write to the end of a binary sequential file, use the /BS* switch
when assigning a channel number.
Then, the first write operation
opens the file at the end to prevent overwriting.
When you write a record with a header, APL sets up the record with the
header information first.
The header size is two words plus one word
for every dimension in your data.
The data type and length make up
the first word of the header (one half-word each). The rank of the
data is in the second word, the number of rows in the third word, the
number of columns in the fourth word, and so on.

7-21

THE FILE SYSTEM

Figure 7-1 illustrates the format of the header.

Bit

17 18

length (in words)
of value plus header

type (1-6)

Word 1
Word 2

Rank (Number of dimensions in data)

Word 3

rho 1

Word 4

rho 2

Figure 7-1

Format of Header in a Binary-Access File

If you do not specify a header when performing I/O, you must specify
the type and length of the data for input and output.
When reading a record with a header, you have the option of actually
accessing the header information itself or going right to the data.
If you specify no header (0) on a read of a record with a header, you
will access the header information when requesting word 1, 2 and so
on. APL views the header as data in this case.
If you specify header,
APL goes right to the values you input instead. Because APL creates
a header as the default, if you read the end-of-file without specifying 0 in the header position, you will receive a 15 DOMAIN ERROR.
The following example illustrates the writing then reading of a
character matrix whose shape is 3 by 2. A header is specified along
with ASCII data type (6) and length (number of values (6)).
Figure
7-2 illustrates the format of the header and the data.
[I (.) '::; ~::.

:1.

F I I... E ./ k.' 1...' I

:1.

§:I[:I.::J:I. yO?:/. y:/.
:1.3:1.0726
flr::?]:I. ~/()Y:l. Y 1

n[4JlyOylyl
''')

.,:.,

U I:: ~.:.:i ::I :1. 9 0 Y ~::; y (.

[lCI... ~:;

7-22

THE FILE SYSTEM

The data is stored as follows:
type

length in words

6
2

rank

rho 1

rho 2

Figure 7-2

values read

Record Format of a Binary-Access File

Note that the final value word is right-filled with zeroes.
In the previous example, the first read produced an integer value for
the entire word 1310726. To break this down into type and length, use
the encode function as in the following example:

The following examples illustrate the use of the file input and output
functions for binary-access files:

AIAII:;: I T E !;i

I:;: E C~ U E !;i T ;: H :::: 0 y NOH r:;: (.~ D E F;: y T :::: 1 y :t: NT E GEl:;:

(\~:.:j)I:H2YOy

12:34~:5

AWRITES REGUEST;SEGUENTIAL
(~:.:j+\B)1:§2Y()Y

6 7 8 9 10 11 12

13
AREAD BEGINNING AT 8TH WORD;4

VALUES

READ

UCB:l2!,O,:L ,4

n 9 :to :/. :1.

AREAD;SEGUENTIALLY-NEXT

WORD;2 VALUES

1:12 yO, :1. ,2
AWRITE BEGINNING AT 13TH WORD;ASCI:t: DATA
'TOPS-:/.O APLSF'nr:/.3J2,O,6
TOf'"!;i····:l.O ('~PI... SF
AREAD :I. WORD BEGINNING AT 13TH WORD
n[:/.3]2,O,6,~::j

TOP!;;····
AREAD 2 WORDS(:l.O VALUES)(AT NEXT WORD)
1:12!, (), 6 Y :1.0

:1. 0

('~PI ... !:iF

AWRITE BEGINNING AT

50TH WORD

7-23

THE FILE SYSTEM

AHEADEH

21
2:·5
2~5

(3
22
24
26

E~<

I ~:; T~:;

2r20+\6)~[50]2

AHEAD 10 VALUES BEGINNING AT SOCNO HEADEH)
1:J[~:.)O::r2vOy:l. ~ 10

262154 2 3 2 21 22 23 24 25 26
nTHANSLATE 1ST WOHD INTO DECIMAL
COY2*1B)T2621.~:54

:I. 10

AHEAD BEGINNING AT 50
II [: ~::jO::l 2
,.),.)
4·.. ~••

24
26
nNULL VECTOH INDICATES END-OF-FILE
A ~··I] 2 , 0 y 1. y 1

J' P,

o ?~5
If you open a binary-access file with IES, you can access the file
only sequentially. Because you can also specify a word number when
writing to the file, you could destroy the file by specifying a word
number that is less than the last word number written.
For example,
if the last output was written in word 40, and you specify word 15,
the data will be written in word 15 but all data before and after that
word is erased.
You can, however, write to a word number greater than the last word
number in the file (41 in this case). APL considers this preserving
the sequence. Note the following example:
CHAN~DASSIBIN/BSI

( \ 10) nCH(~N
:I. 2 3 4 5 6 7 8 9 10

(:1.0+\ 10)[lcHnN
11 12 13 14 15 16 17 18 19 20
(40+\10)Ol50]CHAH
41 42 43 44 45 46 47 48 49 50
(100+l10)Hl3JcHAN
101 102 103 104 105 106 10? 108 109 110
[lCI ... !::.

CH(~N

CHAH~DASSIBIN/BSI

U[~:.:jOJCHPIH

1 ~:5

:00 M (~ I N
r~

E I:;: r:;: (:) F;:

I:: !:':;O::l CH('~N

Ur::3::rCH{'~H

101 :1.02 :1.03 104 105 106 107 108 109 110
Ur::2JCH('~H

:I. ~.:.i

X:ODM('~ I

EJ!;:I:;:DI:;:

rJ I:::?::I CH('~N
.A.

As in direct-access files, to delete a record in binary-access,
specify a null vector in its place (0 75)pO. Also, an end-of-file is
indicated by the null vector (0 75),pO and the error message 75.

7-24

THE FILE SYSTEM

With binary-access files,
you can also input and output mixed data in
one logical record.
See Section 7.6.7 for the DCIQ and DCOQsystem
functions.

7.6.7

DCIQ and DCOQ - Accumulating Data

The DCIQ and DCOQ system functions allow you to accumulate data of
different types into a variable for storage as one logical record.
For output, use the following format:
da ta DCOQ [header [, type] ]
where
data is the value of DCOQ.
DCOQ is the system function that packs data for output.

header is either 0 or 1, with the same meaning as in Section
7.6.6.
type is a data type listed in Table 7-4.
the packed data~

The value of DCOQ is

The following format unpacks data:
variable DCIQ [header [, type] ]
where
variable is the name where the value being read is stored.
DCIQ is the system function that unpacks the data.

header is either 0 or 1.
type is a data type listed in Table 7-4.
the packed data.

The value of DCIQ is

The DCOQ system function takes any data type and turns it into an
integer vector.
In this way you can assign DCOQ packed ASCII characters to a variable and assign floating-point or APL 9-bit to another
variable and catenate them. Then you can write the record to a file
with 8 using the integer data type.
For example:
(.~ ·l·· \ ~:.:j
I::·~ .. (.~

Dec>o :I.

F:'

262:1.52 1 5 :I. 2 3 4 5
(0 2'/(1.B)1"P[1]
:I. B

7-25

THE FILE SYSTEM

To retrieve it and translate the data back, first read the data with
ffi, then use DCIQ to unpack the data types.
For example:
P

[]CI(~

1 234 5

[1.:1
[2]

[ :iJ
[4]
I:~) ]
[6]

17t:.F"ACt<[D]17
F:·~f.:IF"('!lCI<
LIST; I
A f.:IPACt< USES Dcom TO PACt< A SET OF VALUES INTO A SINGLE
A
VARIABLE.
THE VALUES CAN BE OF DIFFERENT TYPES.
USE
A
f.:IPACK WHEN CATENATE WONIT WORK
A L.. I ~>T :[ S (.~ CH('~I:::('!lCTEI::: M('~TF:::r. ~.~ ~ F'::f.!\CH I:::OW OF WHI CH CONTA I NS THF.~
A
NAME OF A VARIABLE WHOSE VALUE IS TO BE PACKED
A P IS THE RESULTANT PACKED VALUE - IT IS AN INTEGER ARRAY
p ~- \ ()
I ( .. t

[?]

[8]
[9]
[1.0]

TEST:~(I}:l.trLIST)/O
P~Py(sLISTI::I;J)Dcom

:I.

:r.(.. :I: +:1.

[:L:l :I
[12::1

.. }TE~::.T
'ii'
<:;'t.:1 UHP('~C I( I:: []:] 'i;.'
'Q

[lJ
[2]

I:: ~J J
[4::1
[ ~:j]

[6::1
[}]
[H]

P 6UNPACK LIST;DATA;I;J;LEH;ENTRY
A 6UNPACK USES DCIm TO UNPACK A VARIABLE CREATED BY 6PACK
A
INTO A SET OF VARIABLE NAMES, USING ASSIGNMENT
A ",. I~:; THE P('~CI<ED V('~I... UE? CI:::I:::('~TI:::X;' X;''r' ..~P(,~CI<
A LIST IS A CHARACTER MATRIXy EACH ROW OF WHICH CONTAIHS THE
A
HAME OF A VARIABLE TO RECEIVED ONE OF THE PACKED VALUES.
A
THE VALUES UNPACKED OUT OF P ARE STORED INTO SUCCESSIVE
A
VARIABLES HAMED IN LIST
1.)(.~T(';)<: .. P

[?]

:t: .~ .. f X) (.~ T (.~

[:to]

,.J i" :I.

TE'::; T : .. ~ ( :t: .~.(» /0
.. ~ ( ..! > :I. '1' f I... I ~:; T ) ./ ()

[1. :1. J

[:1.2]
I:: 1. ~~::I

L F.~ N (.. :I. i

(0 2

'/( :1. n ) T D I:~ T (.~ I:: :I. J

.[ :1.4]
I:::l. ~:j]
[1.6:1

ENTRY~DATA[\LEN]

[:1.7]

,.J(.. ··..I+:I.

~LIST[J;Jyt0ENTRY

OCIQ

:1. 1

D (.~ T (.~ <:.. L E H ,J,. x;. (.~ T (.:)

[:1.0]

:I:-.I.. :I: .... LI:::N

[:l.9J

.. ~TJ:::~:;T
'V

ADEFINE SOME NUMERIC VARIABLES
A~"l

(:!lAf·l
(:H!\(.H·:L

1
1. 1

ADEFIHE SOME CHARACTER VARIABLES
B(.. 1 E< 1
r.<B(.. 1 K,<B 1

7-26

THE FILE SYSTEM

nMAKE A LIST OF INPU~ VARIABLE NAMES
3r'A
AA AAAB
BB '

L1~5

1..1
A
A~~
At~(.~

F,<F,<

nPACK THESE VARIABLES INTO ONE
nCATENATE WILL NOT WORK
P~006Pt~C K

ITEM

L:L

524291 0 -34359738368 524292 1 2 -17179869184 524292 1
3 -8589934592 1310723 0 -21206401024 1310724 1 2
00. 2:L :I. t 3602048
nMAKE A LIST OF OUTPUT VARIABLE NAMES
3r'X
XX XXXY
YY ,

L2~5

L. ::.~

nUNPACK
F:o

I.~UHI::o('~C I{

nTHE
A TH('~T

~o(

THE PREVIOUS DATA

::::

INTO THESE NEW

VARIABLES

1..2

RESTORED DATA
lA.1(.)!~;
P(')C I{ ED

THE SAME AS

THE DATA

(.)

:I.

....

}o{).'

:1.

:I.

:1.

....

~., }.{ ~.,

:10

0y-

:L
°fOf

:1.

7.6.8

f,) (.~

0•.

f,) (.) (.)

1-:<

....

f< X~<

:I.

Binary-Access Magnetic Tape Files

Binary-access mode is often used to read magnetic tape files that have
been created on other systems. The following sections, Sections
7.6.8.1, and 7.6.8.2, describe the use of the /BS/DUMP switches and
the DMTP system function for magnetic tape.

7-27

THE FILE SYSTEM

7.6.8.1 /BB/DUMP Switches - If you plan to read or write a binaryaccess file on magnetic tape, you should specify the /BB switch when
assigning the file to a channel (DABB).
Output is then written to a
binary-access magnetic tape file in fixed-length blocks. The size of
these blocks is determined by the operating system; the default size
is 128 words. You can override the setting with the SET BLOCKSIZE or
SET TAPE RECORD-LENGTH monitor commands. 1
If your file consists of variable-length blocks, you should also include the /DUMP switch. When you specify /BB/DUMP, each read or write
request reads or writes one magnetic tape block.
When you perform a read, the size of each input request must be at
least as large as the block to be read or you will receive the message
74 BLOCK TOO BIG.
If the length specification in the input request is
larger than the input block, the value read will reflect the actual
block size. You should specify length with ~ because APL cannot know
the length of the data before reading the tape.
NOTE
The primary use for /BB/DUMP is to read
magnetic tapes generated on other
systems.
It is not recommended for
general use.

7.6.8.2 DMTP - Operating on Magnetic Tape - The DMTP system function
performs a variety of magnetic tape operations including rewinding,
setting density, and returning data modes.
Format
channel DMTP operation(s)
where
channel is the channel number associated with the file.

DMTP is the system function for magnetic tape operations.
operation(s) is a vector containing one or more codes indicating
the particular magnetic tape operations to be performed.
See
Table 7-5.
Some of the operations read characteristics of the tape. For each
read operation the result of that operation is placed into a result
vector.
In other words, if there are 3 read operations in the operations array, the result array will be 3 elements long.
If there are
no read operations, the result array will be null.
There are four basic types of magnetic tape operations.
1.

Tape positioning operations - These operations do such things
as rewind the tape and move it forward and backward. They
have codes in the range 0-511.

Read operations - These operations read characteristics of
the tape such as density and track status. The results of

lSee the TOPS-20 Monitor Calls Manual (version 3A or later) or the
'rOPS-lO Monitor Calls Manual (version 6.03A or later) .
7-28

THE FILE SYSTEM

these read operations are placed in the result array, as
explained above. They have codes in the range 512-1023.
3.

Write operations - These operations set characteristics of
the tape. The value which is written is taken from the next
element of the operations array. For example:
12 DMTP

102~

This example sets the density of the tape to 1600 bpi, the 4
is the value written as the tape's density. These operations
have codes in the range 1024-1535.
4.

Reserved for user definition - These must be defined by the
user.
Since APL does not know whether these are read or
write operations it assumes they are both.
In other words,
it passes the next element of the operations array to the
operation and puts the result of the operation in the result
array.
These operations have codes in the range 1536-2047.

On TOPS-IO the operation codes and results returned are identical to
those for the TAPOP UUO.
(See the TOPS-IO Monitor Calls Manual.)
On
TOPS-20 the operations listed in Table 7-5 are available.
Table 7-5
Operation Codes
wait for I/O to stop
Rewind the tape to the load point
Rewind and unload the tape
3 Skip forward one block
4 Skip forward one file
5 Skip to the logical end of the tape
6 Skip backward one block
7 Skip backward one file
8 9 Write a tape mark
513 Read density, possible values are
ounit default bits/inch
1 200 bits/inch
2 556 bits/inch
3 800 bits/inch
4 1600 bits/inch
5 6250 bits/inch
6-17 - reserved for DIGITAL
519 Read data mode, possible values are
oDEC-compatible core dump format (7-track and
9-track)
1 DEC-compatible dump format (9-track)
2 Industry-compatible, 8-bit mode (4 bytes/word)
3 6-bit mode {9-track, TU70 only}
4 7-bit mode (TU70 only)
5 DEC-compatible 7-track core dump (SIXBIT)
520 Read track status, 1=7-track, 0=9-track
521 Read write-lock bit; returns 1 if set, 0 if not set
1025 - Set density (same values as read)
1031 - Set data mode, same values as read
1 -

2 -

7-29

THE FILE SYSTEM

On success, DMTP returns a I-dimensional array with one element for
each read or user-defined operation.
If any of the operations returns
an error, DMTP returns an integer indicating the cause of the error.
For TOPS-IO the errors are the same as for the TAPOP UUO. For TOPS-20
the following errors can be returned:
-2
-1

1
3
4
6
8
9

Unknown error
Address check while storing answer
Illegal function code specified
Function code requires privileges
Value is not in legal range
Address check while reading arguments, or too few arguments
Tape has not been initialized
Termination code error
Job number associated with unit is incorrect

In addition, for both TOPS-lO and TOPS-20, the following errors can be
generated:

12 RANGE ERROR CHANNEL < 1 or CHANNEL > 12
64 CHANNEL NOT ASSIGNED - CHANNEL not assigned
9 RANK ERROR Rank of argument array NEQ 1 and length
15 DOMAIN ERROR 10 LENGTH ERROR 62 NOT A PROPER DEVICE -

of argument array NEQ 1
Operation code LSS 0
Write operation specified but there is
no argument to write.
Device is not a magtape

NOTE
When you specify DMTP, APL first writes
out any in-core buffers before performing the DMTP operations. You should
therefore issue this function with
great caution, and you should use it
only between magnetic tape files.

7.7

UTILITY SYSTEM FUNCTIONS

The following sections describe four utility system functions that
return file organization, device characteristics, record size, and
other information about files that are in the system.

7-30

THE FILE SYSTEM

7.7.1

DeHS - Returning File Organization and Status

Format
DeHS channel(s)
where
DeHS is the system function.
channel(s) is one or more channel numbers associated with the
files.
The DeHS system function returns the file organization and the open
status of the files on one or more channels in the system. The
channel argument can be a numeric scalar, vector, or a null vector.
For example:
IJCH~:;

-4

This expression returns information about the file associated with
channel number 8.
If the channel number is a vector, APL returns
information on all channels specified. One row containing two values
is returned for each channel specified. The first value identifies
the file organization, and the second value identifies the open status
of the file.
Tables 7-6 and 7-7 list the meanings of the values.
Table 7-6
File Organization
Code

Organization

channel free

1
2
3

lAS
lIS

IDI
IDA

5
6

IES
lEU

7-31

THE FILE SYSTEM

Table 7-7
Open Status
Code

Status

channel free
file assigned but not open
file open for output
file open for- input
file open for input and output

I
2

3
4

If you specify a single channel number, the result of the function is
a 2-element vector.
If the function contains N arguments, the result
is an array of shape N by 2. For example, the following function
results in a 3-by-2 array:
1::t~·.F:t: L ~:;~··nCH~>

:1.
:L
0

~:;

()

fFII...S

:-3 2

If the argument to DCHS is a null vector:
[]CH!;:.

4
!:)
0

:l
0

()

(~;

:I.

0
4
4
0

()

"to

:I.

:1.

:I.
()

0
0
:I.

APL returns information on all channels in the APL system.
specification is the same as DCHS t12.

7-32

This

THE FILE SYSTEM

7.7.2

DDVe - Returning Device Characteristics

Format

DDve channel(s)
where

DDve is the system function.
channel(s) is one or more channel numbers associated with files.
This argument can be a numeric scalar, vector, or a null vector.
The DDVe system function returns a device-characteristics word and
block size for the files on one or more channels in the system. The
device-characteristics word returned by DDVe has the same format and
meaning as that interpreted by the DEVCHR UU0 1 •
The syntax is identical to that of DeBS: one row containing two values
is returned for each channel specified. The first value is the devicecharacteristics word, and the second value represents the block size
for the device, in words.
DDVe returns a 2-element vector if a single
channel is specified.
If the function contains N arguments, the result is an array of shape N by 2.
If the argument is a null vector,
APL returns information on all channels, and the result is an array
of shape 12 by 2.
It is usually helpful to convert the device-characteristics word to
binary format before examining it. The following example illustrates
the conversion of the word returned in the example included at the
beginning of this section with the APL encode function (T).
For example:
[lCH!:~

:J.

(.~ ~ .. [] X)

4 :l
(.~

:1.

[:l J

:L 7:'~24:~76()6J
l

°ior:::~oOOtr:::~O:L l
DSK:

11
::: :

r: : :

'Ol [1+(36r2)TA[:J.]]

input
~TTY: ~Device can do output
0

lSee the TOPS-20 Monitor Calls Manual (version 3A or later) or the
TOPS-10 Monitor Calls Manual (version 6.03A or later).

7-33

THE FILE SYSTEM

7.7.3

DFLS - Returning File Sharing Information

Format

DFLS channel(s)
where

DFLS is the system function.
channel(s) is one or more channel numbers associated with files.
The argument can be a numeric scalar, vector, or null vector.
The DFLS system function returns the sharing status and other information about files on one or more channels in the system.
The syntax
of DFLS is similar to that of DCHS and DDVC except that one row containing four values is returned for each channel specified. The meaning of the values differs according to the file organization.
DFLS
is meaningful only for direct-access and binary-access files.
If the
channel number you specify is associated with an ASCII sequential or
internal sequential file, the values returned are all zeros.
The values returned for direct-access files (IDA and IDI) have certain
meanings depending on their position in the vector.
Starting from
left to right:
First value

Share bit:
sharing

0 means no sharing, I means

Second value

Value of the next record number to be used
for reading or writing (if subscript record
in the file I/O request is defaulted)

Third value

Maximum record number permitted

Fourth value

Blocking factor

Starting from left to right, the values for binary-access files have
the following meaning:
First value

Share bit:
sharing

Second value

File-word pointer to the next word to be
read or written (if subscript word in the
file I/O request is defaulted)

Third value

Length of file in words (cannot be determined for magnetic tape device)

Fourth value

Size of last read or write request in words
(Not for magnetic tapes)

7-34

0 means no sharing; I means

THE FILE SYSTEM

For example:
OFLS

o 20 2052 50
There is another important difference between DFLS and DCBS. The file
on the channel must be open to return values.
In the case of alES
file in which only reading or writing can be in effect at anyone time,
there must be a way of specifying which type of access you intend to
perform on the next operation if the file has not already been accessed.
APL allows you to include a special channel number specification for
IES files that have not already been accessed. A channel number in
the range 1 through 12 indicates that you will be reading the file.
A channel number in the range 101 through 112 indicates that you will
be writing the file.

DFLS returns a 4-e1ement vector if a single channel number is specified.
If the function contains N channels, the result is an array of
shape N by 4.
If you specify a null vector, APL returns information
on all channels, and the result is an array of shape 12 by 4.

7.7.4

DFCM - Returning File Information

Format

DFCM channel
where

DFCM is the system function.
channel is the channel number associated with the file.
The DFCM system function returns information about the records in a
direct-access file.
Unlike DCBS and the other utility function, the
DFCM function requires that the channel number be an integer scalar,
not a vector.
DFCM is meaningful only for direct-access files (IDA
and IDI files).
If the channel number is associated with another file
organization, the result will be a null array of shape 0 by 2.
For direct-access files, DFCM returns one row containing two values,
one row for every record in the file.
The first value is the record
number; the second value is the number of blocks in the record.
If
the file contains N records, the result is an array of shape N by 2.
For example:
DFCM 3

76
98
99

7-35

THE FILE SYSTEM

7.8

DENQ AND DDEQ - SYNCHRONIZING SHARED FILE ACCESS

Format

DENQ channel lock number share bit
DDEQ channel lock number share bit
The DENQ and DDEQ system functions allow you to synchronize access to
shared direct-access and binary-access files.
These functions should
be used only by advanced APL users familiar with the ENQ and DEQ monitor calls. 1 In addition, the issuing of DENQ and DDEQ functions
should be restricted to a cooperating group of users who require
shared access to common files and who have decided upon a mutual protocol for synchronizing file usage.
Synchronization of file access proceeds as follows: A user assigns a
file and specifies that it is to be available for shared access
(/SHARE). However, to protect the file while a read or write is being
performed, some method is needed for temporarily locking the file from
access by other users.
DENQ performs this lock function. The file
remains under the control of the user who issued DENQ until that user
releases it for continued shared access with the DDEQ function.
The
arguments to both functions specify the degree to which the file is
locked against other users.
The first two arguments, channel number and lock number, are considered a lock pair. The first element identifies the channel number
on which the file to be shared is assigned. The second element represents the particular type of lock being performed. Depending on the
conventions adopted by file users, this number might be a file record
number, a range of record numbers, or some other representation. The
lock number must be in the range 0 through 2*33-1.
It has no inherent meaning to APL; its only significance is that agreed upon by
cooperating users.
The share bit is discussed later in Section 7.8.3.
The channel number is not particularly significant. The file to be
shared must be associated with the specified channel, but several
users can have the same file assigned to several different channels.
This is illustrated in the next example. The chronological order in
which operations are performed is significant and proceeds from top to
bottom.

USER[4,204]
DASS ' 12

FRT/BU/SHARE'

USER[4,205]
DASS '11

FRT[55,12]/BU/SHARE

DENQ 12 99
FILE OPERATIONS ON 12

DENQ 11 99
USER ENTERS A WAIT STATE

DDEQ 12 99
o

FILE OPERATIONS ON 11

DDEQ 11 99

ISee the TOPS-20 Monitor Calls Manual (version 3A or later) or the
TOPS-IO Monitor Calls Manual (version 6.03A or later).
7-36

THE FILE SYSTEM

You issue OENQ and ODEQ on lock numbers as well as on channel numbers.
An OENQ succeeds if another user is not already enqueued on the specified lock.
If the lock is currently enqueued, the second user enters
the wait state until the first user issues a ODEQ to free the locked
file.
When you close a file, all locks on the channel associated with
the file are dequeued.
A successful OENQ or ODEQ returns a 0 as the function result.
If an
error is encountered, a scalar value representing the error condition
is returned.! A return code of -1 means that the system does not
support the use of OENQ and ODEQ.
Only the channel number is required in an OENQ or ODEQ specification.
The function:
OENG

o
is equal to:
DENG

6 0

o
You can specify a matrix as an argument.
For example:

o
M is a matrix in which each row specifies a lock pair.
APL enqueues
on all locks specified in this matrix. All locks must be successful
for an OENQ to succeed.

If you include only a channel number with ODEQ, APL clears all locks
on the file.
If you include a null vector as a channel number, APL
clears all locks on all channels. For example, the ODEQ expression:
DDEG

lr 5 6 7

o
clears all locks on channels 5, 6, and 7.

lSee the TOPS-IO Monitor Calls Manual (version 6.03A or later) for
an explanation of value errors returned under TOPS-IO.

7-37

THE FILE SYSTEM

7.8.1

File Locks

The lock pair:

OENQ channel 0
ODEQ channel 0
has special significance in APL. This lock pair is considered to be
the file lock and is used primarily by the file system itself to
control access to shared files.
APL automatically issues internal
OENQ and ODEQ functions on the file lock for the following organizations:

/DA and /DA/SHARE
/DI
/EU/SHARE
These functions are performed to ensure efficient access to the incore disk buffers maintained by APL.
When you specify a /DA file without sharing, APL issues an OENQ on the
file lock. When the file is closed, an automatic ODEQ is performed.
If /DA/SHARE, /DI, or /EU/SHARE is specified, APL issues an OENQ on the
file lock when the file access is first issued.
It issues an automatic ODEQ on the file lock whenever a terminal input request is
expected. Before performing the ODEQ function, APL writes out all
output buffers and clears all input buffers.
You can explicitly issue an OENQ function on the file lock.
If you do
this, APL will not issue an automatic ODEQ until you issue a corresponding explicit ODEQ on the file lock or until the file is closed.
You can issue an explicit ODEQ function on the file lock at any time,
thus causing APL to clear all in-core buffers for the corresponding
file.
For certain applications, it is more efficient to issue explicit OENQ's and ODEQ's.

7.8.2

Determining Lock Numbers

The group of APL users who will be sharing files and issuing OENQ and
ODEQ functions for these files should agree upon the significance of
the lock-number arguments included in the function lock pairs. As
previously mentioned, this argument can be any number in the range 0
through 2*33-1, where 0 has a special meaning. The only meaning
associated with a particular lock number is that agreed upon by the
group of cooperating file users. The following function provides an
example of users cooperating in sharing a file.
This function can be
executed by several users simultaneously.
It controls access to the
file by locking individual records of the file while they are being
accessed by file users. A lock-number specification here refers to a
file record number.
VF[OJV
V
[lJ
[2J

F CHAN;CMP
CHAN,CMPNUM)/ENGFAIL

NCMP~CMPNUM

~(OtOENG

CMP~n[CMPNUMJCHAN

[3J

4(OtO DEG

[4]

NCMP~PROCESS

[5]

NCMP~NCMParCMPNUMJCHAN

[6J

~(OtODEG

[7]

CHAN~O)/DEGFAIL

CMP

CHAN)/DEGFAIL

7-38

THE FILE SYSTEM

[8]
[9]

EN~FAIL:'EN~
DEGFAIL:'DE~

FAILED'
FAILED'

OSIGNAL
OSIGNAL

501
502

'if

o F DASS'PAYROLL.FE9/DA/SHARE'
:1.2

7.8.3

Specifying a Share Bit

The third argument in the OENQ and ODEQ system function, the share
bit, can be specified if you are willing to share access to a lock.
If the share bit is set to 1, sharing of a lock is established; if it
is set to 0, you have exclusive use of the lock. The default share
bit is O.
If several users specify a share bit 1 in an OENQ function,
it is possible for all of the OENQs to succeed at the same time.
Only
one user can have exclusive access to a lock at anyone time.
The following example illustrates the interaction of four users accessing the same file.
The chronology of the functions issued and executed
is shown in the time component. Note that requests are queued in a
first-in-first-out fashion.
Time

User 1

User 2

User 3

User 4

l2:00 ... 0ENQ 12 1 0

l2:00 ... obtains
exclusive
access
12 : 02 . . . . . . . . . . . . . . . . . . . OE N Q 1 2 1 1
12:04 .......•.....•..... waits ......... . OENQ 12 1 1
12:06 . . • . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . waits ........... . OENQ 12 1 0
12:08 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . • . . . . . . . . . . . . . . . . . . . • waits
12:10
l2:l2 ••• 0DEQ 12 1 ••••••• obtains ........ obtains
shared access shared access

12 : 14 ....•......•....... ODE Q 12 1
l2:l6 ••. 0ENQ 12 1 1 ....•••••.••.•.•••.. 0DEQ 12 1 O •••••• obtains
waits
exclusive
access

12:18 ... obtains ....••.......•...•..•....••.•..........• • ODEQ 12 1
exclusive
access

7-39

THE FILE SYSTEM

7.9

)INPUT AND )OUTPUT HANDLING I/O FROM NON-TERMINAL DEVICES

Format
)INPUT[filespec][/character set]
)OUTPUT[filespecH[/character set]
The )INPUT and )OUTPUT system commands allow you to divert immediate
mode and quad I/O to devices other than your terminal. A file specification can be included in the command to indicate the device and
filename to be used for input or output. The file specification has
the same format as a workspace name, and, as with a workspace name,
you need not include all five parts of the file specification. See
Section 2.1.4. When you omit parts of the name, the default values
in Table 7-8 are assumed.
If you om~t the file specification, APL
defaults to the terminal.
Table 7-8
File Specification Defaults
Component

Default

Device name

DSK:

Filename

Input for )INPUT
Output for )OUTPUT

File extension or type

.AAS

File protection

Installation dependent

File owner ID

User's directory

You can specify an optional parameter (the character-set switch) to be
used in handling the data being read or written. Legal values are
/APL for the APL character set and /TTY for the TTY character set.
The default is the character set of the user's terminal.
For TTY terminals, /APL means use the APL character set specified when
you first accessed APL. When APL prompts with TERMINAL .. , you have
the option of specifying a particular APL terminal, for example,
TTY/4013.
The default is LA36. See Table 1-1.

)INPUT and )OUTPUT are typically used to divert input and output
requests to devices other than the terminal.
For example:
)ClUTI"'UT

I...I"'T!

7-40

THE FILE SYSTEM

This response intercepts all output normally directed to the terminal
and routes it instead to the line printer. For example:
)OUTPUT DSK:APL

This command causes all normal terminal input requests to come from a
disk file named APL.AAS.
If you use an )OUTPUT command to divert output from the terminal,
input is echoed to the output file as well, so that the output file
has the appearance of a normal terminal sheet. This alleviates the
potential confusion involved in trying to match up input and output
requests.
Special processing is also performed to help you synchronize input and output in the following two cases:
1.

input from the terminal and output to another device

input from another device and output to the terminal

In the first case, APL displays the usual six spaces at the terminal
to signal the completion of the last output request.
In the second
case, the names of the functions whose definitions appear in the input
file are listed on the terminal upon successful closing of the
function.
If errors occur in a function definition, the number of errors encountered is displayed along with the function name.
If the APL
system encounters an I/O error when )INPUT and )OUTPUT commands have
diverted both input and output from the terminal, I/O in the direction
of the error reverts to the terminal. For example, if an error occurs
on input, subsequent input is directed to the terminal, but output continues to be sent to the output device.

7-41

APPENDIX A
ERROR MESSAGES

If an error is detected during the evaluation of an expression, APL
(1) displays an appropriate error message from the list included below
and (2) the line in which the error occurred. A null array with the
shape 0 ERROR NUMBER is returned as the value of the expression that
produced the error when executed with E.
The following example of a
null array indicates an end-of-file error condition:
(.~+x~(

:I.:L v (:~ I... U I:::

E I:;: I:;: (;) I:;:

(.~+x·:(

A
C'i"~:

(.~+x·:( I

.A.

F'C

() :1.:1.

The meaning of error-number values is summarized below.
Error
Number

Meaning/Explanation/Action

IMPROPER LIBRARY REFERENCE
Attempt to )SAVE a disk area that is not your own and not
a public library area.

WS NOT FOUND
No workspace or file with the name found in the disk area
specified.

SYSTEM ERROR
Internal APL system error.
your software specialist.

Please report this error to

WS FULL
The active workspace cannot retain all the information
requested, nor can it expand further.
Erase unneeded
objects, issue a )MAXCORE command to enlarge the workspace,
or do a )SAVE, )CLEAR and )COPY sequence on the needed
information.

NOT A VALID SV IDENTIFIER
Attempt to use a shared variable not supported by this APL
implementation.

A-I

ERROR MESSAGES

Error
Number
------

Meaning/Explanation/Action

DEFN ERROR
Improper function definition syntax (function name may have
been defined elsewhere) or improper edit request syntax.
Function may be locked.

LABEL ERROR
Improper use of a colon or improper variable name.

SYNTAX ERROR
Invalid syntax, such as two variables without an intervening operator, a function call with missing arguments, or
an unmatched parenthesis.

INDEX ERROR
Index value out of range, for example trying to reference
the tenth item of a 9-element vector.

RANK ERROR
Ranks of two operands are not conformable.

LENGTH ERROR
Shapes of two operands are not conformable.

VALUE ERROR
Value for the variable in question has not been previously
specified, or a function with an explicit result did not
return a value.

12
13

RANGE ERROR
Value of result exceeds capacity of machine word.
POSSIBLE SI DAMAGE
A function in the state indicator has been erased or edited.

DEPTH ERROR
Too many right brackets or parentheses on a line.

DOMAIN ERROR
Function not defined for given values of arguments.

UNBALANCED DELIMITER
Execute string does not contain a closing quote or, function
definition does not contain a closing 'del' character.

EDIT ERROR
Improper line editing request.

ATTENTION SIGNALED
Attention signal detected during function execution (not
all attention signals produce this message).
Attention is
signaled on ASCII terminals by two CTRL/C characters and
by the ATTN key on 274l-style terminals.

DEVICE DOES NOT EXIST
Improper device specification.

DEVICE NOT AVAILABLE
The desired device is already assigned to another job.

A-2

ERROR MESSAGES

Error
Number
21

Meaning/Explanation/Action

INCORRECT COMMAND
A system command is incorrectly spelled.

22
23

INCORRECT PARAMETER
Improper command syntax for a recognized system command.
WS LOCKED
An improper password (or none at all) has been given to
access a workspace with a )LOAD, )COPY, etc., command.

NOT GROUPED, NAME IN USE
The group-name specified has been defined elsewhere.
The
objects in the group-member-list have not been grouped.

EXECUTE ERROR

PROTECTION FAILURE
Attempt to )LOAD or )SAVE a read-protected workspace from
disk area other than your own, or a directory is full.

FILE BEING MODIFIED
Two users are trying to )SAVE the same workspace simultaneously, or a file is already in use (by another user)
during direct-access file I/O.

UNEXPECTED FILE ERROR

DIRECT I/O ERROR
An error has occurred during a directory read or write.

NO SUCH DIRECTORY

NO ROOM ON THIS FILE STRUCTURE OR QUOTA EXCEEDED
File structure is full or disk allocation is exceeded.
In
the latter case, files must be deleted from the user's disk
area before more files can be added.

WRITE-LOCK ERROR
Device is physically write-protected (usually a magnetic
tape). Write-enable the device.

NOT ENOUGH TABLE SPACE IN MONITOR
The system has run out of space to perform certain functions
for the user.
See the systems programmer at your installation.

PARTIAL ALLOCATION ONLY
Entire space request for a disk file allocation could not
be fulfilled. The space that was available has been
allocated.

BLOCK NOT FREE ON ALLOCATED POSITION
A disk block that the monitor allocated to APL as free is
not available.
See the systems programmer at your installation.

MESSAGE TOO LONG
The maximum message length for the HI message has been
exceeded. Maximum length is 384 characters.

A-3

ERROR MESSAGES

Error
Number
47

Meaning/Explanation/Action

LINE TOO LONG TO EDIT
Line editing is not permitted on multiple-line statements
(such as statements that overflow to the following line or
multiple-line quoted strings).
It is sometimes possible
to edit the line by changing the ) WIDTH parameter, to set
the whole statement on one single line.

INPUT LINE TOO LONG
FILE CONTAINS A DAMAGED WS

.50

ERROR IN GARBAGE COLLECTION

Please report this error to
Internal APL system error.
your software specialist. Workspace damage is probable.
51

ERROR IN COpy
Please reAn error has occurred during a )COPY command.
port this error to your software specialist. Workspace
damage is probable.

LINKAGE ERROR
Internal APL error. Workspace damage has been detected.
Please report this error to your software specialist.

NOT ENOUGH CORE AVAILABLE
Not enough memory is available for the task requested. This
error results when the user is within the limit specified
by the )MAXCORE command, but the system itself does not
have enough memory to allow the workspace to expand. Revise your needs for memory, use virtual storage facilities,
or try to run at a time when more memory is available.

STACK OVERFLOW
Internal APL error.
There is not enough room on the stack
for APL operations to continue.
Please report this error
to your software specialist. Workspace damage is probable.

LOGICAL NAME DSK DOES NOT REFER TO PHYSICAL DISK
APL has determined that the logical name DSK does not refer
to a physical disk structure.
Reassign the name DSK to a
disk (necessary for direct access I/O).

INCORRECT MODE FOR DEVICE
The I/O mode for the action requested is improper for the
chosen device (e.g., trying to )SAVE to a terminal).

FILE DOES NOT CONTAIN A WORKSPACE
Attempt to )LOAD or ) COpy a file that does not contain an
APL workspace.

I/O ERROR
A data-transmission error was detected during input or
output.
This message is usually associated with a nonrecoverable device error.

FILE ALREADY EXISTS WITH GIVEN NAME
Attempt to )SAVE a workspace with the same filename as an
existing file that is not a workspace.
Either rename the
existing file on disk or change the )WSID of the APL
workspace.

A-4

ERROR MESSAGES

Error
Number

Meaning/Explanation/Action

WS NOT SAVED, THIS WS IS
Attempt to )SAVE a workspace with the same filename as an
existing workspace, without specifying the )WSID first.
This error message is to prevent inadvertent overwriting
of previously saved workspace.

RENAME ERROR
An error has occurred during file deletion or protection
alteration.
This frequently occurs when a file or workspace is already protected and cannot be renamed.

NOT A PROPER DEVICE
Improper device selection, for example trying a )SAVE to a
device which supports dump-mode I/O but which is not a DSK.

CHANNEL NOT ASSIGNED
The channel specified in a file operation has not been
previously associated with a file via a DASS system
function.

CANNOT DO BOTH INPUT AND OUTPUT
Either input or output, but not a combination of both, is
allowed to a sequential file.
Close the file and reopen
it to perform the desired operation.

CANNOT INPUT FROM FILE
The user has tried to input from an output-only device,
such as a line printer.

CANNOT OUTPUT TO FILE
The user has attempted to output to an input-only device,
such as a card reader.

FILE LOCKED
An improper password has been given for a direct-access
file.

FILE FORMAT NOT DIRECT ACCESS
An attempt has been made to perform direct-access I/O to a
non-direct access file.

FILE FORMAT NOT INTERNAL SEQUENTIAL
An attempt has been made to perform internal sequential I/O
to an non-internal sequential access file.

IMPROPER MODE OR SOFTWARE CHECKSUM ERROR
A file operation is attempting to use a mode that is improper for the device specified in an DASS system function.
Issue an DASS to a device that supports the necessary mode.

DEVICE ERROR
Physical device error during file I/O.
to your operations staff.

Report this error

DEVICE DATA ERROR
A checksum or parity error during file I/O has occurred.
The file is possibly recorded incorrectly on the specified
device.

A-5

ERROR MESSAGES

Error
Number
74

Meaning/Explanation/Action

BLOCK TOO BIG
A data-transfer error has occurred during I/O. Specifically, the last user has attempted to read a block of data
that is too large.

75
End-of-file (EOF) detected (no message is printed;
execution continues).
78

END OF TAPE
End-of-reel on a magnetic tape (MTA) detected.

SYSTEM FUNCTION ILLEGAL IN EXECUTE OR IMMEDIATE MODE

A-6

APPENDIX B
SUMMARY

This appendix contains the following items in the form of tables:
Primitive Scalar Functions

Table B-1

The Dyadic Circle Function

Table B-2

Relational and Logical Functions

Table B-3

Primitive Mixed Functions

Table B-4

Operators

Table B-6

System Variables

Table B-7

System Functions

Table B-8

Keyboard I/O Functions

Table B-9

System Commands

Table B-ll

B-1

SUMMARY

Table B-1
Primitive Scalar Functions
(Section 3.2)
Dyadic

Monadic

Meaning

Function

Meaning

Function
+Y

X+Y

Add X to Y

-Y

Negative of Y

X-Y

Subtract Y from X

Sign of y 1

xxy

Multiply X and Y

Reciprocal of Y

X~Y

Divide X by Y

E to the Yth power

X*Y

X to the Yth power

Magnitude of Y

XIY

X residue of Y

Ceiling of Y

XiY

Maximum of X and Y

Floor of Y

XLY

Minimum of X and Y

Natural logarithm of Y

X~Y

Log of Y to the
base X

Factorial of Y

X!Y

Binomial
coefficient
(number of combinations of Y
things taken X at
a time)

A random integer of lY

X?Y

number of random
integers in the
range 1 through Y

Pi times Y

XoY

Trigonometric
operators (Y is in
radians. See
Table B-2.)

IDefinition:

XY is -1 if Y<O
XY is 0 if Y=O
xY is 1 if Y>O

B-2

SUMMARY

Table B-2
The Dyadic Circle Function
Expression

Result

oox

(1-X*2)*.5

lOX

Expression

Result

sine X

-lOX

arcsin X

20X

cosine X

-20X

arccos X

30X

tangent X

-30X

arctan X

40X

(1+X*2)*.5

-40X

(-1+X*2)*.5

50X

sinh X

-50X

arcsinh X

60X

cosh X

-60X

arccosh X

70X

tanh X

-70X

arc tanh X

The functions in Table B-3 return 1 if the relationship is true, and
if it is false.
Table B-3
Relational and Logical Functions
(Sections 3.2.1 and 3.2.2)
Function

Meaning

X<Y

X less than Y

X~y

X less than or equal to Y

X=Y

X equal to Y

X;::::Y

X greater than or equal to Y

X>Y

X greater than Y

X~Y

X not equal to Y

XI\Y

X and Y

xvY

X or Y

X1'<Y

X nand Y (not both X and Y)

X¥Y

neither X nor Y

"'Y

not Y

B-3

SUMMARY

Table B-4
Primitive Mixed Functions
Function

Section

Meaning

X,Y

3.3.1

Catenate X to Y along the last dimension
of X

X/Y

3.3.2

X (logical) compression along the last
dimension of Y

X/[N]Y

3.3.2

X (logical) compression along the Nth
dimension of Y

X/Y

3.3.2

X (logical) compression along the first
dimension of Y

X?Y

3.3.3

Deal X integers selected randomly in
range 1 through Y without duplication

Xl.Y

3.3.4

Decode the representation of Y in number
system X

X+Y

3.3.5

For X>O, drop first X elements of Y - for
X<O, drop last Ix elements of Y

XTY

3.3.6

Encode Y in number system X

X\Y

3.3.7

X (logical) expansion along the last
dimension Y

X\[N]Y

3.3.7

X (logical) expansion along the Nth
dimension of Y

X\Y

3.3.7

X (logical) expansion along the first
dimension of Y

3.3.8

Generate an index vector such that
X[tY] is in descending order

3.3.9

Generate an index vector such that
X[~Y] is in ascending order

B-4

SUMMARY

Table B-4 (Cont.)
Primitive Mixed Functions
Section

Meaning

3.3.10

Generate the first Y consecutive integers
from current origin

X1Y

3.3.11

Find the first occurrence of Y in vector

Function

X.[N]Y

3.3.12

Laminate X to Y along the Nth dimension
of X

3.3.13

Determine the membership of X in array Y

3.3.14

Return the ravel of Y (make Y a vector)

<f>Y

3.3.16

Reverse along the last dimension of Y

<f>[N]Y

3.3.16

Reverse along the Nth dimension of Y

3.3.16

Reverse along the first dimension of Y

3.3.18

Return the shape of X

XpY

3.3.15

Reshape Y to make dimension X

x<f>Y

3.3.17

Rotate by X along the last dimension of Y

X<f>[N]Y

3.3.17

Rotate by X along the Nth dimension of Y

XeY

3.3.17

Rotate by X along the first dimension of
Y

XtY

3.3.19

For X>O, take first X elements of Y - for
X<o, take last Ix elements of Y

3.3.20

Transpose the dimensions of Y (for a
matrix, exchange the rows and columns)

3.3.21

Transpose array Y according to X

X~Y

B-5

SUMMARY

B-6

SUMMARY

In the following table, f and g stand for any primitive scalar dyadic
function.
Table B-6
Operators
Operator

Section

Xf.gY

3.5.1

Inner product

XofY

3.5.2

Outer product

f/Y

3.5.3

The f reduction along the last dimension
of Y

f/[N]Y

3.5.3

The f reduction along the Nth dimension
of Y

flY

3.5.3

The f reduction along the first
dimension of Y

f\Y

3.5.4

The f scan along the last dimension of Y

f\[N]Y

3.5.4

The f scan along the Nth dimension of Y

f~Y

3.5.4

The f scan along the first dimension of
Y

Meaning

The format function is used with the following syntax:

FMT $' V;V2; ... VN
or

FMT $' V
where
V can be any variable or expression

FMT must be a character vector containing one or more format
fields chosen from the following list:
Format

Meaning

'MAW'

Character data; cannot be used with
numeric values

'MEW.D'

Floating-point numeric data with
exponent

'MQFW.D f

Fixed-point numeric data

'MQIW'

Integer numeric data with automatic
rounding

'MXW'

Blanks inserted in edited line

'M[!]text[!],

Literal text inserted in edited line

B-7

SUMMARY

where
M is the optional repetition factor.

W is the field width.

D is the number of decimal positions.
Q is any number of qualifiers chosen from the following list:

Qualifier

Meaning

Blank field if value is 0

Insert commas

Left-justify

Zero-fill

M[!]text[!]

Insert text left of negative result

N[!]text[!]

Insert text right of negative result

P[!]text[!]

Insert text left of nonnegative result

Q[!]text[!]

Insert text right of nonnegative
result

R[!]text[!]

Insert text in background

You must separate format fields with commas.
ficant digits can be specified.

Up to eight signi-

The symbol A can be used instead of [!] (" for TTY terminals).

B-8

SUMMARY

Table B-7
System Variables
Variable

Section

Meaning

Can be reset:
DAUS

4.2.5

Automatically backs up the active
workspace if value is 1.

OCT

4.2.7

Sets the degree of tolerance or relative
fuzz to be applied in performing
comparisons, value must be in exponent
form; range 0 through lE-S.

DERRDR

4.2.9

contains three lines describing the error
that occurred.

DGAG

4.2.10

Inhibits messages sent from other users.

DID

4.2.11

Changes the setting of the index origin
to a or 1.

DPP

4.2.15

Sets the precision of non-integer output.
Legal values are integers in range 1
through lS.

DPW

4.2.16

Sets the maximum number of characters
that can appear in an output line.
Legal
values are integers in range 30 through
390.

DRL

4.2.17

Determines a link in the chain of random
numbers used in the roll and deal
functions.

DSF

4.2.18

Sets a new prompt or signal message for
evaluated input.

OTIMELIMIT

4.2.19

Sets a limit to the amount of time you
have to respond to a quote-quad input
request.

B-9

SUMMARY

Table B-7 (Cont.)
System Variables
variable

Section

Meaning

Retain system-specified values:

OAI

4.2.1

Stores account information on the current
APL session, including user identification and CPU connect, and keying time.

OALPHA

4.2.2

Contains a vector of 27 characters 6 and
A through Z.

OALPHAU

4.2.3

Contains a vector of 27 underlined
characters ~ and d through ~.

OASCII

4.2.4

Contains 128 ASCII characters.

OAV

4.2.6

Contains a vector of every character in
APL.

OCTRL

4.2.8

Contains a vector of 32 characters listed
in Table 4-3.

OLC

4.2.12

Stores a vector of line numbers in the
APL workspace state indicator, arranged
in order of most recently suspended
function first.

ONUM

4.2.14

Contains a vector of the 10 digits 0, 1,
2,

OTIMEOUT

4.2.20

Reports whether a user ran out of time
during a quote-quad input request.

OTS

4.2.22

Stores the current data and time in base
format.

OTT

4.2.23

Determines the time of terminal being
used in current session.

OUL

4.2.24

Stores the system job number associated
with the current APL session in base 10
format.

OWA

4.2.25

Determines the maximum amount that the
active workspace can increase.

B-I0

SUMMARY

Table B-8
System Functions
Function

Section

Meaning

OBREAK

4.3.1

Suspends function execution and returns
you to immediate mode.

ODL

4.3.3

Delays the execution of the function in
which it is included by the number of
seconds specified.

OEX

4.3.4

Erases an existing use of a name in the
workspace.
It will not erase a label, a
group, a suspended or pendent function,
or a system variable.

OFI

4.3.5

Takes a character argument and converts
it to a numeric, placing zeroes in each
position that does not correspond to a
valid number.

ONC

4.3.7

Returns the classification of a name or
list of names.

ONL

4.3.8

Constructs a list of named objects
residing in the active workspace.

OQLD

4.3.9

Loads a workspace.

OQCO

4.3.9

Copies a workspace.

OQPC

4.3.9

Copies a workspace with certain
protection.

OVI

4.3.11

Converts a character vector into a
numeric vector.

B-11

SUMMARY

B-12

SUMMARY

B-13

SUMMARY

B-14

SUMMARY

Table B-10
Keyboard I/O Functions
Function

Section

Meaning

X+O

2.5.1

Quad (evaluated) input from keyboard

2.5.2

Quote-quad (character) input from
keyboard, up to but not including
carriage return

X+~

2.5.3

Quad-del (unedited) input from keyboard

O+X

2.5.5

Quad output (display value of X)

B-15

SUMMARY

Table B-12
System Commands
Meaning

Command

Section

[n ]

5.7.1

Generates a mask in a random
pattern of length n for concealing confidential input.
If n is not specified, the
default length is 25.

)C [n] file spec.

5.6.1

Ends current session after saving
active workspace; returns you to
operating system command level
and runs program specified. The
default device searched is SYS:.

) CALL [n] file spec.

5.6.1

Same as )C except the default
device searched is DSK:.

)CHARGE

5.7.2

Displays a record of activity
during the current APL session.
Information is insta11ationdependent, but includes connect
time, CPU time, and the number
of APL statements and operations
executed.

)CLEAR

5.2.1

Replaces the active workspace
with the clear workspace.

)CONTINUE [HOLD]

5.6.2

Saves the currently active
workspace as the continue
workspace and exits from APL.
Unless HOLD is specified, the job
is logged off the system. On
disk, the workspace appears with
the name CONTIN.APL in your disk
area.

)BLOT

B-16

SUMMARY

TableB-12 (Cont.)
System Commands
Command

Section

)COpy wsname
[password]
[named-object-list]

5.4.1

Copies objects identified in
the named-object-list from
username into the current
workspace.
If the list is
omitted, variables, functions
and groups are copied.

5.5.1

Displays or changes the number of
significant digits displayed on
output. The maximum number is
18. The default is 10.

5.2.2

Deletes the workspace username
from your disk area.
Information
specified by switch-list is displayed as the files are deleted.

5.5.2

Allows or suppresses the display
of error lines. The default
setting is ON.

5.4.2

Erases the objects identified in
name-list from the active
workspace.

[letter]

5.4.3

Displays an alphabetical list of
function names in the current
workspace.
If letter is included,
the list begins at the specified
letter.

) GROUP group-name
[group-number-list]

5.4.4

Collects named objects in the
group-member-list into the groups
specified by the group-name.
If
you omit the list, the group-name
is dispersed.

)GRP group-name

5.4.5

Lists the members of the group
identified by the group-name.

)GRPS [letter]

5.4.6

Displays an alphabetical list of
group-names.
If letter is included, the list begins at the
specified letter.

) DIGITS

[n]

)DROP wsname
[switchlist]

)ERASE

) FNS

name-list

Meaning

B-17

SUMMARY

Table B-12 (Cont.)
System Commands
Command

Section

Meaning

)LIB wsname
[switCh-list]

5.2.3

Displays the names of workspaces.
If you omit wsname, all workspaces
in your disk area are listed.
The switch-list argument controls
the display of additional
information about the workspaces.

5.2.4

Retrieves a workspace from a
secondary storage device.
If you
include a password, it must match
the password of the file.

)MAXCORE[{p-Of-memor y }] 5.3.1

Displays or changes the current
setting for the maximum workspace
size. The standard default is
20K words on TOPS-IO and 40P
words on TOPS-20 for the data
segment. The maximum value for
K-of-memory is the smaller of
l76K words or the system memory
limit. For P-of-memory, the
maximum value is 352P.

)LOAD

]

[magtape-position
wsname [paSSword]

K-of-memory

)MINCORE[{p-Of-memor y }] 5.3.2

K-of-memory

Displays or changes the current
setting for the minimum workspace
size. The minimum and standard
default on both systems is o.

)MODE [{KEYWORD}]

5.5.3

Displays or changes the current
mode of output for terminals that
do not have an APL character set.
The default is KEYWORD.
The mode
setting does not affect input
from the keyboard and either mode
is acceptable on input.

)MON

5.6.3

Returns you to operating system
command level, leaving your
workspace intact. While at
command level, you can issue any
command that does not alter your
memory image. You can subsequently return to APL by typing
the CONTINUE monitor command.

)OFF [HOLD]

5.6.4

Ends the current APL session.
Unless you specify HOLD, your job
is also logged off the system.

ESCAPE

B-18

SUMMARY

Table B-12 (Cont.)
System Commands
Command

Section

Meaning

)ORIGIN [n]

5.5.4

Displays or changes the index
origin for the currently active
workspace.
n can be 0 or 1. The
default setting is 1. The origin
is preserved with the workspace
when it is saved.

) OWNER

5.3.3

Displays the directory of the
user who created the currently
active workspace, the date on
which it was created, and the
terminal number of the device at
which it was created.

)PASSWORD [password]

5.2.5

Displays or changes the password
of the currently active
workspace.

)PCOpy W$name
[password]
[named-object-list]

5.4.7

Copies objects identified in the
named-object-list from wsname
to the current workspace,
protecting names already in use.
If you omit the list, all
variables, functions, and groups
are copied.

[n] file spec.

5.6.5

Ends the current APL session and
runs the specified program.
If n
is specified, the value is added
to the starting address of the
program to be run.
The file
specified must contain a readyto-run program (that is, an .EXE
file).
The default device
searched is SYS:.

)RUN [n] file spec

5.6.5

Same as )R except that the
default device searched is DSK:.

) SA VE [magtape
position][wsname]
[password]

5.2.6

Saves a copy of the currently
active workspace on a secondary
storage device, under the name
and password specified.
If you
omit the password, the current
password is assumed.
If you omit
both wsname and password, the
current workspace is used

()WSID).

B-19

SUMMARY

Table B-12 (Cont.)
System Commands
Section

Meaning

5.3.4

Displays the current setting of
the workspace seal or turns the
seal on or off. When the seal is
on, only the user who turned the
seal on can copy objects from the
workspace or can turn the seal
off. The default is off. This
command has no effect on the
)LOAD command.

)SI

5.4.8

Displays the workspace state
indicator which reports on the
progress of function execution.

)SIV

5.4.9

Displays the workspace state
indicator, along with local
variable names at each level.

)SIZE

5.3.5

Displays the size of the currently
active workspace, in P-of-memory on
TOPS-20 and K-of-memory on TOPS-IO.
It also displays the number of
pages (TOPS-20) or the number of
blocks (TOPS-IO) the workspace
would occupy if saved on disk.

)TABs[n]

5.5.5

Displays or changes the increment
between tab settings for APL
output. The default tab setting
is O. This command is designed to
be used with terminals that have
physical tab stops.

) TIME

5.3.6

Displays connect and CPU time
accumulated while the current
workspace has been active.

) VARS [letter]

5.4.10

Displays an alphabetical list of
global variables in the currently
active workspace.
If you include
letter, the list begins at the
specified letter.

) VERSION

5.3.7

Displays the APL version number
with which the currently active
workspace was saved.

5.5.6

Displays or changes the maximum
width of the output line; n must
be an integer in the range 30
through 390.

5.2.7

Displays or changes the name of
the currently active workspace;
optionally changes the password
associated with the workspace but
does not display it.

Command

) WIDTH

[n ]

)WSID [wsname]
[password]

B-20

SUMMARY

Arguments
Meaning

Argument

Character set

The identifier APL or TTY, representing the
character set of a user's terminal.

filename

Same format as wsname, except that the name
itself has no default and the default
extension depends on the type of file.

file size

An integer specifying the maximum number of
records that a direct-access file can have.

file spec

Same format as filename.

group-name

An identifier that names a group of
variables, functions, or other groups.

group-member-list

A list of variables, functions, or
group-names separated by spaces.

identifier

Any sequence of letters or numbers
beginning with a letter. Only the first 31
characters in an identifier are
significant.

K-of-memory

An integer value representing the number of
lK-word blocks of memory.
Users of virtual
memory systems should note that lK is equal
to two pages of memory.

letter

One of the characters A-Z, ~, or the
under struck characters 4-~, or ~.

magtape-position

An integer that specifies that the action
of the command is to take place following
the nth end-of-file mark on the magnetic
tape.
If no position is specified, the
action takes place with the tape in its
current position.

An integer value.

name-list

A list of identifiers that name variables
and/or functions, separated by spaces.

named-object-list

A list of identifiers that name variables,
functions, and/or groups, separated by
spaces.

number

One of the digits, 0, 1, 2, 3, 4, 5, 6, 7,
8,

password

Up to eight characters preceded by a hyphen
(-).
The null and default password is the
hyphen (-).

P-of-memory

An integer value representing the number of
pages of memory.
B-21

SUMMARY

Arguments
Argument
switch-list

wsname

Meaning
A list of switches in which each switch
consists of a slash(/) followed by one of
the letters A, B, C, L, M, N, P, or T.
Valid switches include:

Access: the date the file was last
read (disk only)

Blocks: the number of blocks required
for the file

Creation:
file

Long:

Mode:
the mode in which the file was
written (disk only)

No header:
suppresses the printing of
the display header line

Protection:
the protection code
associated with the file (disk only)

Time:
the creation time of the file
(disk only)

the creation date of the

equal to typing

IEIPIC

A standard name in the following format:
device:name.extension<prot> [directoryJ
All fields are optional.
If you specify a
protection, also type the angle brackets.
If you specify a directory, enclose it in
square brackets. Names are a maximum of
six letters and/or numbers. An extension
(or filetype) consists of a period (or
comma in TTY mode) followed by a maximum of
three letters and/or numbers.
Defaults are
the following:
Component

Default

device

DSK:

name

name of active workspace (from
)WSID)

extension

.APL

protection

installation-dependent