Digital PDFs

AA-P142E-TE

June 1991

344 pages

Original

21MB

view download

OCR Version

18MB

view download

Document:	VAX APL User's Guide
Order Number:	AA-P142E-TE
Revision:	000
Pages:	344
Original Filename:

OCR Text

VAX APL

User’s Guide
AA-P142E-TE

June 1991

This manual describes the VAX APL interpreter and the environment in
which it operates.

Revision Update Information:

This is a revised document.

Operating System and Version: VMS Version 5.4
Software Version:

Digital Equipment Corporation
Maynard, Massachusetts

VAX APL Version 4.0

The information in this document is subject to change without notice and should not be
construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation
assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied
only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not
supplied by Digital Equipment Corporation or its affiliated companies.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013.
© Digital Equipment Corporation 1982, 1984, 1985, 1987, 1988, 1991.
All Rights Reserved.
The Reader’s Comments form at the end of this document requests your critical evaluation to
assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DEC, DECnet, DECwindows,

Digital, GIGI, VAX, VAXcluster, VAXstation, VAX DATATRIEVE, VAX FORTRAN, VMS, VT320,

VT330, VT340, and the Digital logo.
HDSAVT, HDS201 and HDS221 are trademarks of Human Design Systems, Inc.
Tektronix is a trademark of Tektronix, Inc.

Contents
Preface . ..... .. ....,

Xiii

The VAX APL Operating Environment
1.1

Terminal Support . . .. ...

...

. .. . e,

1.1.1

APL Terminals . . .. ........ ... .. . . . . ...

1.1.2

Non-APL Terminals ... ....... ... ...

...

1.2

APL Character Set . . .. ... ... .. .. . ... . .

1.3

Starting an APL Session . ...............
.. ... .. .. ......

... ... ... .. ......
.

... . . ... . .

Initialization File . . . . .. ...

1.3.2

Command Line.

...

1-12

1.3.3

Initialization Qualifiers . ...... ... ... ... . ... . .. . . . ...

1-13

.. ... ... ... . .. . ... . .

1-11

1.3.1

1-12

1.4

Order of Processing . ... ..... ... .. ...

1-20

1.5

Terminal Designators .. . .. ........ . ... .. . . . . . .. .

1-21

...

1.5.1

Terminal Designator Values . . . . . .....................

1-22

1.5.2

Character Sets . . ... ... ... . . . . ...

1-23

1.5.3

Overstruck Characters . . ... ... ....... ... ... .........

1-25

1.5.4

OTLE and (0GAG Settings . . . . ... .. ... . . .. ...
..

1-25

Font Files.

1-26

1.5.5

.. ... .. .. . . . i

1.6

APL Operating Modes . ..........
. ...
..

1-27

1.7

Keyboard Editing . . . ...

... . . . . . . ..

1-28

1.8

APL Workspaces

... .... ...
e e

1-29

1.8.1

Workspace Types ... .. ...

1.8.2

Workspace Names and File Specifications ...............

1.8.2.1
1.8.2.2

.....

VMS File Specification Format
Workspace

....................

Name Defaults . . ......................

1-31

1-31
1-31

1.8.3

Workspace Passwords

1.8.4

The CONTINUE Workspace.

.. ..........
... .c.0oioi....

1-32

1.8.5

5 070 1 0=

1-32

1.8.6

The State Indicator . .........
... ... . ... . . .. . .. .. ....

1-32

Workspace Size

1-33

1.8.7

. ..........
... ... ... . . . .. ....

1-30

. ..........
... ...

1-31

1.9

Interrupting APL . . ... ...

. . . . ...
.

1-33

1.10

Endingan APL Session . .............
.. .0 ...,

1-35

Character Sets .

oooooooooooooooooooooooooooooooooooooo

1-37

Character Set Used by Non-APL Terminals . ... ..........

1-38

Composite Character Set . ... ....... ... .. ...

... .....

1-42

. ..................

1-44

ASCII Character Set . ... ..... ... ... .. .. . . . . . . . . . .. ...

1-45

Elements of JAV . . . . . ... ... ..

1-46

Digital Multinational Character Set

1-36

Character Sets Used by APL Terminals . ................

VAX APL Language Concepts
2.1

Array Types . ..

2.2

Array Structure

oooooooooooooooooooooooooooooooooooooo

2—1

2—-2

2.2.1

Rank of an Array ... ... ... ... . . . . . . ..

2—3

2.2.2

Shape of an Array . ..........
... ... ... . . ... . ... ...

2—-4

2.2.2.1

Shape and Reshape Functions . . ... ................

2.2.3

Depth of an Array . ..........
... . . . . . .. ...

2-8

2.2.4

Shape Domains of Primitive Function Arguments . ......
..

2-9

2.3

Scalar Product and Singleton Extension . ..................

2—-10

2.4

Empty Arrays

2—12

oooooooooooooooooooooooooooooooooooooo

2.4.1

Array Prototypes . ... ...

.. . . ...

2—14

2.4.2

Fill Items in Arrays . . .. ... .. i

2—-15

2.5

APL Expressions

2.5.1

Identifiers

2.5.2

ooooooooooooooooooooooooooooooooooooo

oooooooooooooooooooooooooooooooooooooo

--------------------------------------

2.5.3

oooooooooooooooooooooooooooooooooooooo

2—-16

2—17

2-18

2.5.3.1

2-18

2.5.3.2

2—-19

254

Vector Notation . . .. ... ... . .

2.5.5

Functions . .

2.5.6

Operators . .

2—20

oooooooooooooooooooooooooooooooooooooo

2—-21
2-21

2.5.7

Spacesand Tabs. ..........
... ... ... .. . . ... . . . ... ...

2—22

2.5.8

Evaluating Expressions . ... ....... ... ... ... .. ... .....

2-22

2.5.9

Statements .

2.5.10

Lines .. ...

2.5.11

oooooooooooooooooooooooooooooooooooooo

2.6

Forming Arrays

2.7

Editing Variables .. ... ...

2.71

oooooooooooooooooooooooooooooooooooooo

2—-24
2—-25

2—25
2—25

... . . ... . ...

2—27

Editing Character Variables . . . . .. .......
... .. ... .....

2—28

2.7.2

Editing Numeric Variables . . .. .......................

2—-30

2.7.3

Editing Variables with the DECwindows Interface Editor . . .

2—-30

2.7.4

The Character-Cell Interface Editor.

. .. ................

2-32

2.7.5

The YEDIT System Commmand Editor .................

2-34

2.8

Indexing Arrays

oooooooooooooooooooooooooooooooooooooo

2—-34

2.8.4

Selecting All Items Along an Array Axis . ............. ..

oooooooooooooooooo

------------------

2.8.5

Indexing Constants and Expressions .

2.8.6

Using an Expression to Generate Indexes . ..............

2.8.7

Shape of an Indexing Result

2.8.8

Replacing Selected Items in Arrays . .

2.9

2.9.1

Error Handling

. .... ..

oooooooooooooooooo

. . ..................

Order of Error Checks . ...........

oooooooooooooooooo

2.9.2

NOO

Selecting More Than One Array Item

oooooooooooooooooo

2.8.3

.........

Selecting One Array Item

WM N

Index Origin....................

2.8.2

T
l\)l\)[\)l\)l})l\)l\)l\)[\)l\)
|
I
Il
e
ol
b WWwWwWwww

2.8.1

User-Defined VAX APL Operations
3.1

Defining Operations . . ... ............

3.2

Operation Header

3.2.1

..................

3.24

..................

Function Header Form . ........
...

3.2.2
3.2.3

oooooooooooooooooo

Local Symbol List

. ..............

3.3

Operation Body ....................

3.4

Symbolic Names in Operations

.. ... ...

oooooooooooooooooo

..................

------------------

oooooooooooooooooo

3.4.1

Local Symbols

. .................

3.4.2

Global Symbols

.................

3.4.3

Localizing Function and Operator Names ...............

3.4.4

Precedence of Local Symbols ... .. ..

3.5

Branching Within An Operation

.......

3.5.1

Unconditional Branches . . ... ... ...

3.5.2

Conditional Branches . . . . ... ... ...

3.5.3

Labels

3.5.4

.........
... .. ... .......

Examples of Branching

Comment Lines . ...................

3.7

Locking an Operation. ...............

3.8

Executing User-Defined Functions . . . . ..

3.9

Executing User-Defined Operators . ... ..

3.10

Printing Operations . ................

3.11

Editing Operations . .. ...............

3.11.1

Support Considerations ...........

3.11.2

The DECwindows Interface Editor. . .

3.11.3

3.11.4

oooooooooooooooooo

3-3

3—4
3—4

3-5
3-5
3-6

------------------

3—-6

3-8
oooooooooooooooooo

oooooooooooooooooo

------------------

oooooooooooooooooo

...........

3.6

3-2
32

oooooooooooooooooo

Operation Result ................

3—1

3—-10
3—10

3—11
3—-12

3-13
oooooooooooooooooo

..................

oooooooooooooooooo

------------------

oooooooooooooooooo

3-14

3—-14

3—-15

3—-16
3—-16
3—-17

oooooooooooooooooo

3—-17

3-18
..................

.................

3—20
3—22

3.11.5

3.11.5.1
3.11.52

3-23

3—-24
3—-28

Search and Replace Strings . ......................

3—-29

3.11.5.4

Editing the Operation Header .. ... ................

3—31

3.11.5.5

Character Editing . .
Editing Lines That Contain Control Characters

3—-32

3.11.5.6
3.11.5.7

... ... iieie...
Editing in Immediate Mode . .......

3—-36

Examples of Defined Operations .........................

3—-37

oooooooooooooooooooooooooooo

3.12.1

Niladic Function

......

3.12.2

Monadic Function

... ..

3.12.3

Dyadic Function.

... ...

3.12.4

Ambivalent Function . ..

3.12.5

Function with Axis. . ...

3.12.6

Dyadic Operator. . ... ..

3.13

Debugging Operations . . ...

.......

oooooooooooooooooooooooooooo

............................

..........................

............................

oooooooooooooooooooooooooooo

3—-36

3-37
3-38

3—-38
3—-39

3—39

3—41

3—-42

3.13.1

Suspending Operation Execution . . .................
...

3—-42

3.13.2

Examining the State Indicator. .......................

3—44

3.13.3

The Trace Vector

3.13.4

......

The Stop Vector . ......

............................

oooooooooooooooooooooooooooo

3—-46

3—48
3—-49

3.14

Examples of Error Trapping.

3.14.1

System Variable Change
User-Defined Error Messages . . . .. .. ..o i ittt
Execute Trap Expression
Programming Considerations for VAXAPL .................

3—-49

Speed Optimizations in VAX APL Primitives.............
Space Considerations in VAX APL . . .........
... .. ....
Efficient Uses of VMS Subprocesses. . . . ................

3—-54

3.14.2
3.14.3

3.15

3.15.1
3.15.2
3.156.3

oooooooooooooooooooooooooooo

............................

3-50
3-53

3-54

3-57

3-58

The Report Formatter
4.1

4.1.1
41.2

41.3

Format Phrases ..........

oooooooooooooooooooooooooooo

Too Few or Too Many Format Phrases . ... ..............
Treatment of Empty Arguments. ......................
Format Phrase Types . . .
............................

4.1.3.1

Type A—Character. .

4132

Type E—Floating-Point with Exponent .. ............

41.3.3

Type F—Fixed-Point

oooooooooooooooooooooooooooo

4-2

4-3

4-4

4-5
4-5

4-6
4-8
4-9

Type G—Pattermn Data . ...........
... ... ... .....
..

4-12

41.3.6

Type Y—Byte Data
. .

4-13

4.1.3.7

Type T—Absolute Tab

41.3.8

Type X—Relative Tab

41.3.4
4.1.3.5

oooooooooooooooooooooooooooo

Line Editing Commands .........................
Displaying Operation Lines . ... ...................

3.11.5.3

3.12

The Line-Editor . ..
.. ..

Type I—Integer . .

oooooooooooooooooooooooooooo

...........................

............................

4-15

4-16

4.1.3.9

Type Literal ... ... ... .. .. . . . . . .

...

4-18

4.1.4

Format Phrase Parameters .. ... ..... ... ... ... ........

4-18

4.1.5

Format Phrase Qualifiers and Decorators .. .............

4-19

4.1.5.1

B—Blank When Zero . . . . ... ... .. ... ... ... ... ..

4-21

4152

C—Insert Commas...................
...
.....

421

4.1.5.3

Kn—Scale Factor ... ....... ... ... .. . . . . . . . .. ....

4-22

4154

L—Left-Justify . . ....... ...

...

4-22

4.1.5.5

S—Standard Symbol Substitution ..................

4-22

4.1.5.6

Wn—Exponent Digits.

... ... ......

4-23

4157

Z—Zero Fill ... . ... ...

4-23

4.1.5.8

M and N—Negative Left and Right Decorators ......
..

4-24

4.1.5.9

P and Q—Positive Left and Right Decorators

4-24

4.1.5.10

O—Zero Decorator . .. ...... ... . . . . .. . . . .

...

4-24

4.1.5.11

R—Background Decorator ........................

4-25

.. ... ... ... ...

. . ...

...

.........
i

4.2

Right Argument . .. .... ... . ... . .. ... .. . ...

4.3

Result Array

4.4

Formatting Character Data . ............................

. ... ... .. .. . . .

4-25
4-27

4-28

VAX APL Input and Output
5.1
5.1.1

Terminal Input and Output .. ..... ...

... ... ... ..........

Terminal Input Variables . . . .. .......................

5-2

5.1.1.1

Quad Input

51.1.2

Quote Quad Imput ... ... ... ... . ... ... . ...

51.1.3

QualDelImput.......

51.2

......... ... ... ... ...

5-4

... ... ... .. ... .. ... . ......

5-5

Terminal Output ........ ... ... ... . . ... . .. ...

. ...

5.1.2.1

Output Catenator. .. ... ... .. ... ... ... . 0. ..

5.1.2.2

Quad Output ......... ... ... . .

51.2.3
5.1.3

5.2
5.2.1

5-3

... ..

5-8

5—-10

Bare Output..........
... ... ... ... .. ... ... .. ...,

5-10

Diverting Input and Output to Another Device ...........

5-11

File Input and Output . .........
... ... ... ... .. ... ..
...

5-13

...

5-14

52.1.1

File Access Methods . . . . ...

. ... .. ... . ......

5-15

5212

The Next-Record Pointer . ........................

5-16

52.1.3

Record Handling and Sequential Operations . .........

5-17

5.2.2

Basic File Concepts . ... ...

...

. .....................

5-17

5.2.2.1

Querying File Assignments . ......................

5-21

5222

Returning Channel Numbers . . . ... ................

5-22

Opening Files and Reading and Writing Records . . ... ... ..

523

5.2.3

Associating Files with Channels

... . . ... .
...

5.2.3.1

Writing and Reading ASCII Sequential Files.

.. .......

52.3.2

Writing and Reading an Internal Sequential File

... ...

5-23
5-25

52.3.3

Writing and Reading a Direct-Access or Relative File . ..

5-26

5234

Writing and Reading a Keyed File . . . ... ............

5-27

Vil

5.2.4

Resetting Next-Record Pointer to Start of File

5.2.5

Closing Files and Disassociating Files from Channels

5-31

5.2.6

Determining Information about Files and Devices

5-33

5.2.6.1

Returning File Organization and Open Status

5.2.6.2

Returning File Information

5.2.6.3
5.3

5.3.1

oooooooooo

ooooooooo

oooooooooooooooooooooo

ooooooooo

5—-35

5-37

5-38

----------------------------

Sharing Sequential Files .. ... ...........

5-38

5.3.1.2

Sharing Direct-Access, Relative, and Keyed Files

542

5.3.1.3

Unlocking Shared Records

5.3.1.4

Limiting Time on Read Functions

5.3.2.1
5.3.2.2

5.3.3
5.3.3.1

Event Flags

5-42
ooooooooo

ooooooooooooooooooooooooooooo

Associating Events Flags with Channels
Event Flag System Functions

oooooooooooo

Mailboxes . . . . .. .

e e

ooooooooo

Associating Mailboxes with Channels

Sending and Receiving Messages . .........

5.3.3.3

OMBX—Mailbox System Function

5.3.34

Sample Functions That Use Mailboxes
Pure Data Records

oooooooooo

ooooooooo

Reading Pure Data Files Sequentially

5.3.4.2

Reading Pure Data Files Randomly

5.3.4.3

Data Type Conversion Tables

5-44

5—44
5—45

5-46
5-48
5>—48

5—48
5-55

oooooooooooooooooooooooo

5.3.4.1

5—43

5-46

5.3.3.2

5.3.4

5-58

------

5—-60

ooooooooooooo

ooooooooo

5—61

Calling External Routines
6.1

Linking a Routine into a VMS Shared Image

6.2

Mapping the Routine into APL

6.2.1

Dyadic Map

6.2.2

Monadic Map

6.3

viii

Sharing Files

5-33
5-34

Returning Device Characteristics
Advanced 1/0 Techniques

ooooooooo

5-30

5.3.1.1

5.3.2

------------

oooooo

6-3

6-3
............................

Invoking External Routines

oooooooooooooooooooo

6.4

Debugging External Routines

6.5

Examples of Calls to External Routines

oooooooooooooooooo

ooooooooooo

ooooooooo

. .....

6—-5
6—-16

6—-18
6—-19

6.5.1

Example 1: Calling RTL MTH$DACOSD

6.5.2

Example 2: Calling RTL LIB$ERASE_PAGE

6.5.3
6.5.4

Example 3: Calling LIB$PUT_SCREEN .......
Example 4: Calling RTL LIB$GET_SCREEN

6.5.5

Example 5: Calling VMS SORT ... ...........

6.5.6

Example 6: Calling VAX FORTRAN ..........

6.5.7

Example 7: Calling VAX DATATRIEVE . . . .. ...

6—-25

6.5.8

Example 8: Using OMAP with /VALUE ... ... ...

6—-32

6.5.9

Example 9: Calling a VMS System Service . . ...

6—-33

6—-19

6—-20
6—20
.........

ooooooooo

621
622

6-24

6.5.10

Example 10: Calling SMG$ Routines.

... ...............

VAX APL Workspace Interchange Standard
A.1

Converting VAX APL Workspaces to WSIS-Formatted
Workspaces

... ... ...
e

Converting WSIS-Formatted Workspaces to VAX APL
Workspaces

. ... ... .

A.3

Sample WSIS Session

. ............
... ... ...,

Error Messages and Warnings Generated by WSIS Software
i

et e e

. ..

A-3
A-5

A-9

A.41

WSOUT MeSsages . . ..o v v it

e e

A-9

A4.2

WSIN Messages . . ... ...

. it
e e,

A-9

A.4.3

APLTAP Messages . . . ... ... i
ieeee

A-11

Index
Figures
1-1

The Digital LK201 APL Keyboard . ....................

1-3

1-2

DECwindows Interface Window . .. ....................

1-17

1-3

APL Session Using the Character-Cell Interface .. ........

1-18

1-4

DECwindows Interface Commands Options . . ... .........

1-34

DECwindows Interface Edit Options . ... ...............

2-30

DECwindows Interface Edit New Variable Dialog Box. . . . ..

2—-31

2-3

DECwindows Interface Edit Session Commands Options

. ..

2—-32

Character-Cell Interface Variable Edit Example ..........

2—33

3—1

DECwindows Interface Operation Name Dialog Box ...
.. ..

3-18

3-2

DECwindows Interface Edit Session Example . ... ... ... ..

3-19

3-3

Character-Cell Interface Operation Edit Example . ... ... ..

3-21

5—1

APL Internal Record Format .. .......................

5—-59

Documentation Conventions Table . . . ... ...............

APL Single-Strike Characters . .......................
Common APL Overstruck Characters

..................

APL Support for ASCII Graphics . . .. .. ................
APL Support for ASCII Control Characters . .............
Support for Alternate APL Graphies ... ................

1-6

APL Terminals and Designators

1-7

APL Character Set Characteristics

......................

1-22

....................

1-24

1-8

Overstruck Character Key ... ...... ... .. ... .. .........

1-25

1-9

OTLE and OGAG Settings.

...

1-26

1-10

Terminal Designator Font Files . . . ...... ... .. .........

1-26

1-11

Editing Characters.

1-29

. ... ...

.. ... ... . ...

. .. ....... ... ... ... ... . . .. ......

1-12

Workspace Name Defaults . .. ........
... ... ... .......

1-31

1-13

APL-ASCII Key Pairing (Typewriter Pairing)

1-37

1-14

APL-ASCII Bit Pairing

1-15

TTY Character Set . . . ...

1-16

APL COMPOSITE Character Set.

1-17

Digital Multinational Character Set

...................

1-44

1-18

ASCII Character Set .. ....... ... .. .. ...

145

1-19

Elements of DAV (OIO<0) . .o

1-46

. ... . ...

...

............
...

1-37

.. ... . ..

.. . . . . . ..

1-39

. ....................

i i it it

e e e e e e e e i

1-43

4—1

Summary of Format Phrase Syntax . .. .................

4-5

4-2

E Format Phrases ... ....... ... .. .. . ...

4-7

4-3

F Format Phrases

4-4

G Format Phrases .. ..... ...

............
... .. . . .. . . . ... ..
..

.. . . .. . . . . .. . . . .

4-9

...

4-11

4-5

I Format Phrases . .. ........ ... .. .. .. . . . . .

. ...

4—-12

4-6

Y Format Phrases . .............
... .. . . ... .. .......

4-15

4-7

Summary of Format Phrase Parameters ... .............

4-18

4-8

Summary of Format Phrase Qualifiers and Decorators . .. ..

4-20

4-9

Valid Qualifiers, Decorators, and Paremeters for Format
15,72
o 7= O

4-21

5-1

Character Set for )INPUT and )OUTPUT Files ... .........

5-12

5-2

File Organization Qualifiers.

. . ... ....................

5-18

5-3

/AS Input and Output Modes.

. ... ....................

5—23

5-4

Possible OCHS Codes

. i,

5-33

Device Characteristics Longword . . ... .................

5-36

5-6

Data-Type Parameter Values . . ... ....................

5-57

Converting APL Internal Values to External Values .......

561

5-8

Converting External Data Types to APL Values

..........

5-64

5-9

Converting APL Characters to ASCII (D010 <~»0)..........

5-66

5-10

Converting from APL to Digital Multinational Characters
(I0“0) oo it

5-11

. ...

e e e e e

e e e e e e e

e e e

5-67

Converting from APL to Digital Multinational Characters
(OI0 “30)

t ittt et e e

e e e

e e et et e

5—68

5-12

Converting from Digital Multinational Character Set to APL

Characters (OI0<=>0) ...

it ittt

it e e

5-73

6—1

Characteristics of External Data Types ... ..............

6-5

6—2

Converting Internal Data to External Data Types . ... ... ..

6—7

6—3

Converting External Data Types to Internal Data . ...
.. ...

6—12

VMS Data Structures.

6—15

. . . ........ ... .. ...

...

Preface
Manual Objectives
This manual describes the VAX APL interpreter, including APL language

and programming elements, facilities for controlling the APL environment,
the interaction between APL and the VMS operating system, and APL’s I/O

capabilities.

Intended Audience
The primary audience for this manual is experienced APL programmers. This
manual is not a tutorial and is inappropriate for novice users. Programmers

experienced with other languages such as FORTRAN or BASIC can learn
VAX APL from this manual, but are advised to study it in conjunction with an
APL language primer.

Associated Documents
The VAX APL Reference Manual documents the VAX APL functions, operators,

system variables and system commands. The VAX APL Installation Guide
contains instructions for installing VAX APL on the VMS operating system.
The VAX APL Installation Guide also explains how to install QAPL, the

execute only version of VAX APL that is available, license-free to sites using
VAX APL without vector processing.
This manual contains information about the VMS operating system, RMS

files, the VAXTPU editor, VAX DATATRIEVE and VAX FORTRAN. The VMS
DCL Dictionary and the Introduction to VMS System Management provide

detailed information you may need to know to use some of the features of
VAX APL. To find out more about the VMS system, refer to the VMS system

documents listed in the Introduction to VMS or use the help utility by typing

help at the system promt ($). The VMS Record Management Services Manual
and VMS Analyze/RMS_File Utility Manual contain more information about
RMS files. For more information about VAXTPU, consult the VMS Guide to

VAXTPU /|EVE Programming and the VAX Text Processing Utility Manual. The

Xiii

VAX FORTRAN Language Reference Manual and the VAX FORTRAN User
Manual describe VAX FORTRAN. Information about VAX DATATRIEVE can
be found in the VAX DATATRIEVE Handbook, the VAX DATATRIEVE User’s
Guide, the VAX DATATRIEVE Reference Manual and the VAX DATATRIEVE
Guide to Programming and Customizing.

Product References
In this document, VMS software products are sometimes referenced according
to the following list:
VAX APL is referred to as APL.

VAX BASIC is referred to as BASIC.
VAX BLISS is referred to as BLISS.
VAX C is referred to as C.

VAX DATATRIEVE is referred to as DATATRIEVE.
VAX FORTRAN is referred to as FORTRAN.

VAX LISP is referred to as LISP
VAX PASCAL is referred to as PASCAL.
VAX PL/1 is referred to as PL/1.

Xiv

Conventions Used in This Document
The following conventions are used in this manual.

Table 1

Documentation Conventions Table

Conventions

Meaning

Default values used in

The default value for the index origin (070) is 1, unless

examples

explicitly stated to be 0. Numeric print precision (JPP) is

10 digits. Enclosed arrays are displayed with boxes around
enclosed items and with all values in the top left corner of

the display areas. This is done using:
ODC
<+

(1 123)'"++++]|--"

Delimiting pairs

This manual uses s texts ; other delimiting pairs may be any
of the following pairs:

UPPERCASE

Uppercase words and letters indicate that you should type

the word or letter exactly as shown.
A BK

The APL characters 4, B, and X are used in generic
descriptions of command formats. 4 represents a left
argument, B represents a right argument, and ¥ represents

an axis argument.

ttalics

Italicized lowercase words and letters, used in format
examples, indicate that you are to substitute a word or

value of your choice. italics should not be confused with 4P~
CHARACTERS.

Quotation mark (')

The term quotation mark refers to the APL single quotation
mark ().
The equivalence symbol means “is equivalent to”.

The double square brackets indicate that the item or string
of items inside the brackets is optional. Individual items
within a string of items are delimited by the | character,

which indicates that you may choose only one item from the
string.

[ ]

Single square brackets that appear in the format
specification for a language element are required syntax
for the element being described.
(continued on next page)

Table 1 (Cont.)

Documentation Conventions Table

Conventions

Meaning

Braces are used to enclose lists from which one item must
be chosen. The items in such a list are delimited by the
| character. For some user-defined operation headers, the
braces are required syntax (this requirement is described in
Chapter 3).

Color

Color in examples shows user input. Note that all examples
in the manual are executable, and that comments beginning
with the lamp (a) symbol are part of the examples;
comments surrounded by parentheses are not part of the
examples.

The <CR> and <LF> symbols indicate the presence of a
control sequence representing a Carriage Return and a Line
Feed.

Ctrl/X

The Ctrl/X symbol indicates that you must press the key
labeled Ctrl while you simultaneously press another key, for
example, Ctrl/C, Ctrl/Y, Ctrl/O.
A symbol such as

indicates that you press a key on

the terminal. For example, the

symbol represents a

single stroke of the Return key on a terminal; the | Compose |
symbol represents a single stroke of the Compose key.

Unless otherwise noted:

XVi

All numeric values are represented in decimal notation.

You terminate commands by pressing the Return key.

You can use the equal sign delimiter (=) in place of the colon (:)

The VAX APL Operating Environment
VAX APL (A Programming Language) is a compact and versatile programming
language that is especially suited for handling array-structured data
containing numbers or characters. APL is ideal for solving engineering and

scientific problems, and it has proved to be an efficient general data processing
language as well.

APL is easy to learn; however, it differs considerably from other commonly

used languages such as FORTRAN, COBOL, and PASCAL. The distinctive
characteristics of APL are immediately apparent:
e

APL is an interpreter, not a compiler, so lines may be executed immediately
after they are entered.

APL has an extensive character set including Greek letters, such as p, A,

and 1, and a variety of other special symbols, such as +~, [J, and .
*

APL evaluates expressions from right to left; for instance, the result of the
expression 8-4+1 1s 3.

APL has built-in editors. You do not need to go outside the language to
write or change programs.

APL users do not have to know much about their host operating system to be

highly productive. The interpreter supplies virtually everything that will be
needed during a terminal session. In addition to providing a built-in editor,
APL provides debugging aids, system communication facilities, and a file
system.

The APL interpreter is shareable and reentrant. Each user has a private copy
of his or her programs and data, but many users may share one copy of the
interpreter.

VAX APL Users Guide

1-1

The VAX APL Operating Environment

1.1 Terminal Support

1.1

Terminal Support
APL language functions and operators are represented by a variety of special

characters. The way these characters are supported depends on the type of

terminal you have. On APL terminals, you can enter these special characters
directly; on non-APL terminals, you must substitute ASCII or TTY mnemonics.

1.1.1

APL Terminals
APL terminals support the full APL character set, which may be entered

directly from keyboards similar to the one illustrated in Figure 1-1. Note that
letters, numbers, and some of the special characters appear in the conventional

typewriter keyboard positions. You can set most APL terminals to ASCII mode
when you want to use the standard ASCII character set, and then switch to

APL mode when you want to use the APL character set.
APL terminals operating in APL mode use one of three APL character

sets: APL key-paired (also called typewriter-paired), APL bit-paired, or
APL COMPOSITE character set. The APL COMPOSITE character set is a
superset of the APL key-paired character set. The terminal designator you
specify when you invoke APL, determines which character set your terminal
uses (see Section 1.5). The key-paired and bit-paired character sets are
presented in Section 1.11.1. The APL COMPOSITE character set is presented
in Section 1.11.3.

1-2

VAX APL Users Guide

The VAX APL Operating Environment
1.1 Terminal Support
The Digital LK201 APL Keyboard

%
+

~——

Smmi
nj

"'—’T:

j
T

+—

i
-

f-‘-

L
0.

—_0

MLO-006284

Figure 1-1

o
q

-l

—

o ol
_

LA S N

1
x

o I~

0] (=]

@N l

=
~1

—

~
N

|—

=5N V
= I

—

]

EB
.

(0]

8"5
Q_E

\_‘

—

-_—

eeq-VI

T .

* oM

N o

—

——

A
—

—
o

-8
oA -

—

= | |2

LQ—;‘_(D&
—

VAX APL Users Guide

1-3

The VAX APL Operating Environment
1.1 Terminal Support

1.1.2

Non-APL Terminals
Terminals that do not have an APL keyboard are known as non-APL terminals.
On non-APL terminals, you can represent APL symbols using a special set

of ASCII characters and mnemonics called TTY mnemonics. For example, to
represent the APL rho symbol (p ) on a non-APL terminal, enter the mnemonic

RO.
Section 1.11.2 describes the special handling that APL uses for TTY characters.
Table 1-15 in Section 1.11.2 provides an alphabetical listing of the TTY

character set.

1.2 APL Character Set
The APL character sets supported by APL terminals have 95 printing graphics
plus 32 ASCII control characters. The full APL character set, however, has
more than 95 printing characters. These additional characters (known as
overstruck characters) must be constructed by combining two characters from

the APL terminal’s character set. For example, the B symbol combines the [
and < symbols.
Different terminals form overstrikes in different ways. Some terminals allow

you to enter the first character, a Backspace (or F12) and the second character

on top of the first. Other terminals allow you to press the Compose key
(or Ctrl/D) and then to enter the two characters. On these terminals, only
the resulting overstruck character is displayed. The order in which the two
characters are combined is not significant. On non-APL terminals, overstruck

characters are represented by regular characters or ASCII mnemonics. For
more information on terminal types and their method of forming overstruck

characters, see Section 1.5.
For example, key-paired and bit-paired APL terminals use the Backspace

technique. To construct the logarithm symbol (e ), you would type the circle
symbol (o ), Backspace, and the exponentiation symbol ( = ). (You could also

type the symbols in the reverse order.) Note that the dollar sign ($ ) may
be a single-strike or an overstruck character, depending on the type of APL
terminal you are using.
An overstruck character that is not in the APL character set is known as an
illegal overstrike; if you enter an illegal overstrike, APL signals CHARACTER

ERROR, unless the overstrike is part of a character constant, comment, quote
quad input, or quad del input.

1-4

VAX APL Users Guide

The VAX APL Operating Environment
1.2 APL Character Set
APL generally allows you to combine two characters that create an overstruck

character that looks like a valid APL single-strike character. For example, if
you enter + then Backspace, and then - APL accepts the overstruck character
as a valid + symbol. Similarly, a character overstruck with itself or with a

space is a valid representation of that character. Also, an overstruck character
that is overstruck with either of its constituent characters remains valid.
(For example, o Backspace » Backspace o is a valid representation of ¢.) A

character overstruck with a tab, however, is an illegal overstrike (but it is legal
to create a tab character by overstriking a tab with a space or with another
tab).

The elements of the APL character set are listed in this section . Included
are the ASCII mnemonics for TTY users, the characters used in individual
APL overstruck characters, and the names commonly associated with each
character.

The elements of the APL character set are arranged in the following groups:
*

APL single-strike characters

Common APL overstruck characters

APL support for ASCII graphics

APL support for ASCII control characters

Support for alternate APL graphics

The APL single_strike characters, Table 1-1, are the 95 printing graphics that
are in the key-paired, bit-paired and COMPOSITE character sets.

Table 1-1

APL Single-Strike Characters

APL Set

TTY Set

A -7

A-7

letters

TTY Mnemonic

APL Name

0 —9

0-9

numbers

plus

—

minus

times

divide

star

(continued on next page)

VAX APL Users Guide

1-5

The VAX APL Operating Environment
1.2 APL Character Set

Table 1-1 (Cont.)
APL Set

TTY Set

APL Single-Strike Characters
TTY Mnemonic

APL Name

high minus (NeGation)

Under Score

comma

period

colon
;

semicolon

dollar sign

’

quote

question mark

tilde (NoT)

stile (ABsolute value)

ALpha

.BX

quad (BoX)

Dieresis (Double Dot)

€

EPsilon

IO0ta

.OM

OMega

RhO

[

P
A

and
.OR

less than

greater than

equal

Not Equal

.LE

Less than or Equal

.GE

Greater than or Equal

(

left parenthesis

)

right parenthesis

[

left bracket

(continued on next page)

1-6

VAX APL Users Guide

The VAX APL Operating Environment
1.2 APL Character Set

Table 1-1 (Cont.)
APL Set

TTY Set

APL Single-Strike Characters
TTY Mnemonic

APL Name

]

{

.LB

right bracket
Left Brace

}

.RB

Right Brace

backslash

slash

[

.CE

CEiling

.FL

FLoor

jot (Small O)

.LO

circle (Large O)

.LD

delta (Lower Delta)

DiaMond

v
«

DL
B

>
4

DelL
left arrow

.GO
A

right arrow (GO to)
up arrow

Down Arrow

Left U

Right U

UpU

Down U

Left tacK

.RK

Right tacK

up tack (ENcode)

down tack (DEcode)

The overstruck characters provided in most APL implementations, Table 1-2,

must be constructed by combining two characters from the APL terminal
character set.

VAX APL Users Guide

1-7

The VAX APL Operating Environment
1.2 APL Character Set

Table 1-2

Common APL Overstruck Characters

APL Set

Characters to Combine

TTY Set

APL Name

A —7Z

A—7Z

LA - 77

underscored letters

.UD

Underscored Delta

shriek

lamp

I-Beam

hydrant (eXecute)

thorn (ForMat)

domino (Divide Quad)

Input Quad

.0Q

Output Quad

[

.QQ

Quote Quad

.QD

Quad Del

.GU

Grade Up

.GD

Grade Down

.PD

Protected Del

NoR

NaNd

LoGarithm

ReVerse

TRanspose

.CR

Column Reverse

.CC

Column Comma

.CS

Column Slash

.CB

Column Backslash

SubSet

.CO

COntains

MaTch

[

]

Squish Quad

Table 1-3 lists the overstruck characters provided by this APL implementation
to represent certain ASCII graphics.

1-8

VAX APL Users Guide

The VAX APL Operating Environment

1.2 APL Character Set

Table 1-3

APL Support for ASCIl Graphics

ASCII

Graphic

Characters

APL Set

to Combine

TTY Set

Name

Accent Grave

"
=

AT sign

double QUote

.PS

Pound Sign

PerCent sign

AmPersand

.CF

CircumFlex

a—z

a-—z

A -7

JA — JZ

lowercase letters

The overstruck characters used to represent ASCII control characters in
literals are listed in Table 1-4.

Table 1-4

APL Support for ASCIHl Control Characters

ASCIl Set

APL
Set

Characters to
Combine

TTY
Set

Name

NUL

Ctrl/

SOH

Ctrl/A (Start Of Header)

(NULD

STX

Ctrl/B (Start of TeXt)

ETX

Ctrl/C (End of TeXt)

EOT

Ctrl/D (End Of Transmission)

ENQ

Ctrl/E (ENQIiry)

ACK

Ctrl/F (ACKnowledge)

BEL

Ctrl/G (BELI)

Ctrl/H (BackSpace)

Ctrl/I (Horizontal Tab)

KdJ

Ctrl/J (Line Feed)

Ctrl/K (Vertical Tab)

Ctrl/L (Form Feed)

(continued on next page)

VAX APL Users Guide

1-9

The VAX APL Operating Environment
1.2 APL Character Set

Table 1-4 (Cont.)

APL Support for ASCIl Control Characters

APL

Characters to

TTY

ASCIl Set

Set

Combine

Set

Name

Ctrl/M (Carriage Return)

CtrI/N (Shift Out)

Ctrl/O (Shift In)

DLE

Ctrl/P (Data Link Escape)

DC1

Ctrl/Q (Device Control 1)

DC2

CtrI/R (Device Control 2)

DC3

Ctrl/S (Device Control 3)

DC4

Ctrl/T (Device Control 4)

NAK

Ctrl/U (Negative AcKnowledge)

SYN

Ctrl/V (SYNchronize)

ETB

Ctrl/W (End-of-Transmission Block)

CAN

Ctrl/X (CANcel)

Ctrl/’Y (End of Medium)

SUB

Ctrl/Z (Substitute)

ESC

Ctrl/[ (ESCape)

Ctrl/\ (File Separator)

Ctrl/] (Group Separator)

Ctrl/ (Record Separator)

Ctrl/_ (Unit Separator)

DEL

)

DEL (DELete)

Table 1-5 lists the overstruck characters that allow you to enter characters
that are not available on some APL keyboards.

Table 1-5

Support for Alternate APL Graphics

APL Set

Alternate Graphic

Characters to Combine

(continued on next page)

1-10

VAX APL Users Guide

The VAX APL Operating Environment

1.2 APL Character Set

Table 1-5 (Cont.)

APL Set

Support for Alternate APL Graphics

Alternate Graphic

Characters to Combine

{

[

}

]

[

(

)

1.3 Starting an APL Session
To access APL, you first log in to the VMS operating system. When you receive
the system prompt, you are ready to enter the DCL command line to start
APL.

When APL first starts executing, it looks for qualifiers and parameters in
two places, first in the initialization file, and then on the DCL command line

that called APL. The initialization file and the DCL command line are called
initialization streams.
Qualifiers modify the action taken by the command. APL qualifiers are
available to do the following:

Specify the APL interface. (Use in the command line only.)

Invoke the APL run-time system. (Use in command line only.)

Display an informational file.

Execute a file of APL statements.

Suppress the printing of start-up messages.

Identify your terminal type.

Turn on the vector processor.

The optional parameter specifies what a command acts upon; an APL
parameter specifies the name of a workspace to be loaded at the start of an
APL session instead of the CONTINUE or CLEAR workspace that APL loads by
default when the session begins.

VAX APL Users Guide

1-11

The VAX APL Operating Environment
1.3 Starting an APL Session

1.3.1

Initialization File
The first place APL looks for qualifiers and a parameter is in the initialization

file pointed to by the VMS logical name APL$INIT. There are two steps to
creating an APL initialization file.
1.

Edit a file to include the desired qualifiers and parameter.

The initialization file may contain qualifiers that are described in

Section 1.3.3except for the following:
e

/EXECUTE_ONLY

/INTERFACE

/EDIT

APL looks for qualifiers and a parameter only in the first record of the
initialization file; thus, anything in the file after the first <CR><LF> is

ignored.

In the following example, the first qualifier specifies the terminal type and
the second qualifier suppresses the printing of the startup messages (see
Section 1.3.3). The parameter specifies that the workspace PAYROLL be
loaded upon startup.

Stype startapl.ini

/terminal=decterm/silent=all payroll

Assign the logical name APLS$INIT to the file.
Use the DCL command ASSIGN to create the logical name APL$INIT and
assign the name of the initialization file to that logical name.

The command string in the following example shows how to assign the log-

ical name APLS$INIT to the initialization file DBA2:[USER]STARTAPL.INI.
Sassign dba2: [user]startapl.inil apl$init

The VMS User’s Manual provides more information on associating a file

specification with a logical name.

1.3.2

Command Line
The command line to invoke the APL interpreter consists of the command APL,

any of the optional qualifiers listed in Section 1.3.3, and optionally a parameter
to indicate the workspace to be loaded upon startup. The format is:

$ APL [[/[NO]qualifier] [wsname]

1-12

VAX APL Users Guide

The VAX APL Operating Environment

1.3 Starting an APL Session
dollar sign ($)
is the VMS operating system prompt.
qualifiers

are the optional qualifiers described in Section 1.3.3. Note that for each
qualifier that initiates an action, there is a corresponding qualifier that negates
the action.
wsname

is the optional name of the workspace to be loaded instead of the CONTINUE
or CLEAR workspace that APL loads by default when the session begins. The

workspace name may appear at any position in either of the initialization
streams; that 1s, qualifiers are legal both before and after the workspace name.
If a workspace name is specified in both initialization streams, APL loads the

workspace specified on the command line.

1.3.3

Initialization Qualifiers
Qualifiers can be used in both the DCL command line and the initialization
file.
If the same qualifier is specified more than once in the same initialization

stream, APL uses the qualifier specified last, or the righmost value. For

example, the /INOINPUT qualifier prevents the execution of a file that was
specified by a /INPUT qualifier earlier (to the left) in the same initialization
stream.

If the same qualifier is specified in the initialization file and the command line,
APL processes the qualifiers as if those that appear on the command line are
appended to those that appear in the initialization file. Then, APL discards
all but the rightmost value. The /[NO]JHI qualifier is an exception; APL will

process the rightmost /INOJHI qualifier, which identifies a file to be displayed
when APL starts, from both the initialization streams.
You may abbreviate qualifier names to the shortest unambiguous length.

Spaces or tabs are allowed between qualifiers or between a slash (/) and the
beginning of a qualifier name.
Note that a colon (:) or the equal sign (=) may be used to specify keyword
values to the qualifiers. (See the specifications and example shown below.)
In the following example the DECwindows interface is used, the vector

processor is not used and no startup messages are displayed.

VAX APL Users Guide

1-13

The VAX APL Operating Environment
1.3 Starting an APL Session
Sshow logical apl$init
"APLSINIT"

"APLSTART.INI"

(LNMSPROCESS TABLE)

Stype aplstart.ini
/silent/novector

Sapl/int=dec
The APL qualifiers are listed below. Qualifiers and keywords with [NO] are

negatable; the negated form does not take values.

[EXECUTE_ONLY
Invokes QAPL, the execute only version of APL; it does not support the
interactive sessions or features necessary for program development. You can
use QAPL to run APL applications on VMS operating systems that are not

licensed to support VAX APL. QAPL can be copied to any valid VMS system
free of charge. Instructions to set up the QAPL environment are included
in the VAX APL Installation Guide. QAPL cannot be run with the vector
processor support unless the APL-HPD License is purchased and installed.

You must specify the terminal designator on the command line and you may
specify any other qualifiers except /NOTERMINAL. For example:
Sapl/execute/ter=vt220 payroll

Because QAPL does not support interative sessions, a workspace name must

be specified by the command line. If a workspace is not provided, DCL prompts
you for one. If you specifiy a workspace that does not exist, QAPL signals FILFE
NOT FOUND, then TMMEDIATE MODE IS NOT AVAILABLE, and then exits to the
DCL command level.

QAPL treats all operations in the workspace as locked operations. When QAPL

signals an error within an operation, JERROR contains the line on which the
error occurred and the line containing the caret (1) symbol. If your QAPL
application does not trap the error (using 0TRAP), QAPL displays the error
message (including the line of the operation causing the error) and exits to
DCL. This behavior overrides the lock protection on operations in APL in order
to facilitate error handling. (The VAX APL Reference Manual shows the APL
error messages.)

There are three system funtions and three system commands that allow you
to bring objects into a QAPL workspace. These are 0QPC, 0QC0, OQLD, ) COPY,
YPCOPY, and )L0AD. QAPL locks all operations in the workspace when the

workspace is loaded or copied. QAPL also clears stop, trace, and monitor bits
for all operations and watchpoints for all variables.

The following features of VAX APL are not included in QAPL.

1-14

Immediate mode

Quad Input

VAX APL Users Guide

The VAX APL Operating Environment

1.3 Starting an APL Session
e

The DECwindows and Character-Cell interfaces

The system variables and functions listed below:

OAUS

UBREAK

OCR

OFX

[OMONITOR

OSTOP

TRACE

[IVR

OWATCH

All system commands except special cases of the following:
) COPY

YEDIT

)LOAD

) PCOPY

/INOJEDIT=(TPU_values)
Valid only with the /INTERFACE=CHARACTER_CELL qualifier. Specifies
the qualifiers and parameters to be used with the TPU-based interface for

Character-Cell terminals. Any of the TPU qualifiers and parameters may be
used. For example:
Sapl/int=cha/edit=(sec=Saplgrp: [apluser]edit.sec,com=Saplgrp: [apluser])

If a specific set of values are frequently used, you may want to modify the APL
symbol.
This qualifier is not available for use with QAPL sessions or in initialization

files.
The VMS Guide to VAXTPU /| EVE Programming and the VAX Text Processing

Utility Manual contain more information on TPU qualifiers and paramters.
/INOJHI=(vmsfilespec,APL)
(vmsfilespec,KEY)
(vmsfilespec,BIT)

(vmsfilespec,TTY)
(vmsfilespec, COMPOSITE)

vmsfilespec must include at least a file name. (see Section 1.8.2.1.)

Specifies a hi file to be displayed during apl initialization. You can use the
/HI qualifier in both initialization streams; thus, two HI files may be printed.
The file contents are interpreted in the specified character set and are read in
quote-quad input mode. (See Chapter 5.)

VAX APL Users Guide

1-15

The VAX APL Operating Environment
1.3 Starting an APL Session
/INOJINPUT=(vmsfilespec,APL)
(vmsfilespec,KEY)
(vmsfilespec,BIT)

(vmsfilespec,TTY)
(vmsfilespec,COMPOSITE)

vmsfilespec, described in Section 1.8.2.1 must include at least a file name.

Specifies a file to be automatically executed in ) INPUT fashion when the APL
session begins. (See Section 5.2.3 and the VAX APL Reference Manual.)
/INOJINTERFACE-=interface
CHARACTER_CELL
DECwindows
LINE

Selects the type of APL interface to use. The default is LINE. This qualifier is
not available for use with the /EXECUTE_ONLY qualifier or in initialization
files.

The DECwindows value invokes full DECwindows support of the APL product
to more easily develop applications interactively. In addition to the initial APL
DECwindow, you can open one or more sessions to edit user-defined operations
and variables. VMS DECwindows Motif User’s Guide and VMS DECwindows
Motif Applications Guide have more information on using the DECwindows
environment.

The DECwindows interface opens a window, shown in Figure 1-2, with the
APL title bar, two scroll bars (vertical and horizontal), a command line at the
bottom for input and the large center transcript area to record the session.

1-16

VAX APL Users Guide

The VAX APL Operating Environment
1.3 Starting an APL Session
Figure 1-2

Enmmands

DECwindows Interface Window

Ennts

% YAX ARPL V4. 0-nnn
§ SYS$INPUT:
CLEAR

dow dd-mmm-yyyy hh:mm:
ss. mm user

[droup,user]

If the INTERFACE=DECwindows qualifier is included on the command line,
the APL session ignores any value assigned to the /TERMINAL qualifier.

The CHARACTER_CELL value causes the invocation of a VAXTPU-based
interface, which makes windows available to more easily develop applications
interactively. The /EDIT qualifier should be used to specify the TPU options

preferred to enhance this APL interface.
VAXTPU uses a buffer, a temporary holding area, to manage your APL
session. The contents of the APL interactive session are shown in an area of
the screen that is called a window. The End of Buffer message defines the

end of the workspace. It is only visible on the screen and is not interpreted

by APL. A highlighted status line, located at the bottom of the window, shows
the buffer name (APL. SESSION), current mode (insert or overstrike), and the
current direction (forward or reverse). Figure 1-3 shows an APL session using
the Character-Cell interface.

VAX APL Users Guide

1-17

The VAX APL Operating Environment

1.3 Starting an APL Session
Figure 1-3

APL Session Using the Character-Cell Interface

DECterm 2
Commands

=
Edit

Customize

Help

VAX APL ++ CCT USER INTERFACE
VAX

APL

DEY:

¥WN,U-EDIT

DAY DD-MMM-YYYY HH:MM:SS:
TT NAME

CLEAR

[UIC]

[End of buffer]

Buffer: APL SESSION

Command:

| Fead-grnly | Insert | Forwarerd LJ

HELP

The VAXTPU manages the APL buffers with commands that do the following:
List all of the buffers used in this APL session
Delete a specified buffer

Change the buffer displayed in the window
Create a new buffer that contains the contents of a specified file
Write the contents of a buffer to a specified file

The Character-Cell interface allows you to view more than one window on
your terminal screen at the same time. For example, you can have the
interactive session in one window and an edit buffer in another window.

To help you manage the APL windows, VAXTPU commands are available to do
the following:

Split the screen into more than one window
Put the cursor in the next; previous or other window
Restore the current window as a single, large window
Enlarge or shrink the current window by a specified number of lines

1-18

VAX APL Users Guide

The VAX APL Operating Environment
1.3 Starting an APL Session
For more information about windows, buffers and the VAXTPU commands,

access the online Help utility. Press the Do or PF4 key or enter Ctrl/B to
reveal the Command: prompt and enter HELP. (See Figure 1-3.)

/INOJSILENT[[=(silentmodes)]]
ALL
HI

BANNER
WSMESSAGE
NONE
Controls whether the APL banner line (see Section 1.4), HI files, and initial

workspace message (see Section 1.4) are printed. The default is /NOSILENT,
which indicates that the APL banner line, the HI files, if specified, and the

initial workspace message will be printed. You can specify more than one

keyword to the /SILENT qualifier by separating the desired keywords with
commas and surrounding the argument with parentheses. APL evaluates the
keywords cumulatively; thus, the specification /SILENT=(ALL,HI) is the same
as /SILENT=ALL.

/[INOJTERMINAL=terminal
terminal specifies the terminal designator as listed in Table 1-6.

Specifies the terminal type. If you do not specify a terminal type in the
initialization file or the command line, APL prompts you for one. If you specify
/TERMINAL but omit the terminal value, APL signals MISSING QUALIFIER
OR KEYWORD VALUE and returns you to the DCL command level.)

/NOTERMINAL negates a previously specified terminal designator. If the
negated terminal qualifier,/

NOTERMINAL, is the last occurrence of a terminal

qualifier in the initialzation stream (see Section 1.3.3), APL will prompt for the
terminal type (see Section 1.5).

/INOJVECTOR[=threshold]
threshold specifies the minimum data size for APL to use vector processing
hardware. A value of 1, indicates that the vector processor will always be used;

a value of 0 indicates that the vector process will never be used.
Note that the VAX APL HPO license must be loaded before VAX APL can use
the vector processor.

When you invoke a session, APL determines whether a vector processor is
available. If no vector processor is available, the vector processor threshold

value will be set to 0. If a vector processor is available, it will be set to the
threshold value specified with this qualifier, or if this qualifier is not included

VAX APL Users Guide

1-19

The VAX APL Operating Environment
1.3 Starting an APL Session
in an initialization stream, the threshold value will be set to the non-negative,
near-integer default.

1.4 Order of Processing
APL initialization processing proceeds in the following sequence of steps:

Sessions facilitated by the Character-Cell or DECwindows interface start
the interface first, then pass the APL qualifiers and parameters to start

the APL session. The Character-Cell interface uses a TPU-based screen

and displays a session manager message in the following form:
VAX APL

CCT User Interface

The initialization stream qualifiers are checked for syntax errors, and an
error message identifying any invalid qualifiers is displayed. If an error is
detected, APL returns you to DCL. (Refer to Section 1.3.3.)
APL determines whether there is a vector processor.

The user is prompted for a terminal type (if the /TERMINAL qualifier was
not specified). (See Section 1.5.)

The APL banner line is displayed.
If a vector processor is not available, the APL banner line has the form:
VAX APL

Iv.u-edit

dev:day dd-mmm-yyyy hh:mm:ss.tt name

[uic]

The APL banner line has the form if a vector processor is not available:
VAX APL HPO/VMS

lv.u-edit

dev:day dd--mmm--yyyy hh:mm:ss.tt name

[uic]

1 1s the support letter.
v 1s the version number.

u is the update number.
edit i1s the edit number.
dev:

identifies your terminal device.

day is the day of the week.
dd--mmm--yyyy and hh:mm:ss.tt are the date and time.
name is your VMS user name.
uic is your vms user identification code.

1-20

APL HI files are displayed. (See Section 1.3.3.)

VAX APL Users Guide

The VAX APL Operating Environment
1.4 Order of Processing
7.

The file named by the /INPUT qualifier is opened, thus establishing the
file, rather than the terminal, as the default source of input.

Note that the default source of input is changed from the terminal to the
/INPUT file before the workspace is loaded. This could be important if the
value of JLX (see OLX, Latent Expression, the VAX APL Reference Manual)
in the workspace to be loaded is not empty. If JLX initiates processing that

calls for input, APL takes the input from the /INPUT file.
8.

The applicable workspace is loaded, and the appropriate message is

displayed.
The workspace that APL loads is determined by the following criteria.

The last workspace specified in an initialization stream.
The CONTINUE workspace saved from a previous APL session, if one

exists in your default area (see Section 1.8.1).
c.

A clear workspace, if neither of the first two choices applies.

If a clear workspace is loaded, APL displays the following message:
CLEAR WS

If the CONTINUE workspace or a workspace specified in an initialization
stream is loaded, APL displays a standard ) LOAD message, such as:
SAVED THURSDAY

16:32:14.28

4-APR-1979

14 BLKS WAS F0O

The file named by the /INPUT qualifier is read.

After displaying the appropriate load message, APL indents six spaces to

signify that it is ready to accept input, unless JLX causes execution of an
expression or unless there is an operation executing at the top of the )sI
stack.
Some steps in the sequence may be eliminated, depending on the settings of
the initialization stream qualifiers.

1.5 Terminal Designators
When you begin an APL session, you must tell APL what type of terminal you
are using. Your APL working environment is set up according to the terminal

designator value you specify.

VAX APL Users Guide

1-21

The VAX APL Operating Environment
1.5 Terminal Designators

1.5.1

Terminal Designator Values
You can specify the terminal type in either the command line or the
initialization file; if you do not, APL prompts you for it with the following:
terminal..

You respond with one of the terminal designators listed in Table 1-6. If you are

unsure of how to respond, enter a question mark (?) and press the Return key.
APL then lists the possible designators and prompts you again. For example:
terminal..?
one of the following:
apl
la
key
vt102
composite
hds201

hds221

hdsavt

bit

tty

4013

vt220

vt240

vt320

decterm

vt330

gigl

vt340

terminal..

If you enter Ctrl/Z or Ctrl/C at the terminal prompt, APL returns you to DCL.
Table 1-6 lists the terminal devices and designators supported by VAX APL.

Table 1-6

APL Terminals and Designators

Terminal

Designator

Bit-paired ASCII/APL terminal

BIT

Key-paired ASCII/APL terminal

KEY or APL

terminal using APL. COMPOSITE character set

COMPOSITE

Digital LA12, LA34, LA36, LA37, LA38, LA100, LA120, LS120

Digital VK100 (GIGI) terminal

GIGI

Tektronix 4013

4013

Tektronix 4015

4015

HDS201

HDS221

HDSAVT

Digital VT102-PA/RA with APL feature!

VT102

Digital VT220

VT220

Digital VT240

VT240

1f you do not have the optional APL feature for the VI'102 terminal, specify TTY as your terminal

designator.

(continued on next page)

1-22

VAX APL Users Guide

The VAX APL Operating Environment
1.5 Terminal Designators

Table 1-6 (Cont.)

APL Terminals and Designators

Terminal

Designator

Digital VT320

VT320

Digital VT330

VT330

Digital VT340

VT340

Digital VAXstation using VMS Workstation Software

Digital VAXstation using DECwindows

DECTERM

Any terminal without APL character set

TTY[ /terminal]l

Note that you can use any APL terminal in ASCII mode as a non-APL terminal
by specifying TTY as your terminal designator when you invoke APL, or you
can set JTT<2 once inside APL.
The TTY designator takes an optional qualifier, /terminal, which can be any

one of the other terminal designators in Table 1-6. This qualifier is relevant
only when you use the )

INPUT and )OUTPUT system commands, or the § and

B file system functions (see Chapter 5). The default value for /terminal is /key.
If you respond to the terminal prompt with TTY, followed by any character

other than a <CR> or a slash (/) with a legal terminal designator, APL displays
the following:
type ? for help
terminal..

If you enter tty/? at the terminal prompt, APL displays the list of possible

designators that can follow TTY/. If you attempt to use the /terminal qualifier
on a designator other than TTY, APL displays the following message before
continuing:
qualifier ignored for non tty terminal

Note that TTY/terminal is not available when you specify your designator
in an initialization stream. It is available only in response to the terminal
prompt.

1.5.2

Character Sets
When you invoke APL, the APL interpreter selects the character set to be used
with your terminal based on the terminal designator you specified.
If you specified the BIT terminal designator, APL uses the Bit-paired character
set.

VAX APL Users Guide

1-23

The VAX APL Operating Environment
1.5 Terminal Designators
The terminal designator also determines whether the APL character set is

loaded automatically by APL or manually by the user.
Table 1-7 shows the APL character set characteristics for each terminal
designator.

Table 1-7

APL Character Set Characteristics

Terminal

Qualifier

Designator

Character Set

Mode

APL

Bit-paired

Manual

BIT

Bit-paired

Manual

KEY

Key-paired

Manual

Key-paired

Automatic

GIGI

Key-paired

Manual

Map

{ GO - 7-bit ASCII

}

G1 - APL Character Set
4013

Key-paired

Automatic

4015

Key-paired

Automatic

HDS201

Key-paired

Automatic

HDS221

Key-paired

Automatic

HDSAVT

Key-paired

Automatic

VT102

Key-paired

Automatic

{ GO - 7-bit ASCII
G1 - APL Character Set

COMPOSITE
( VT220

APL COMPOSITE

Manual

APL COMPOSITE

Automatic

GO - 7-bit ASCII

VT240

G1 - APL Character Set

VT320

G2 - DEC Supplemental

VT330

G3 - Special Graphics

VT340

DECTERM

| VS
TTY

TTY

Does not map an APL character set

Note that the LA, 4013, or 4015 terminal users could specify key as their
terminal designator, and then load character sets manually.

1-24

VAX APL Users Guide

}

The VAX APL Operating Environment

1.5 Terminal Designators

1.5.3

Overstruck Characters
The key used to create overstruck characters depends upon the terminal
designator specified in the initialization stream. Table 1-8 shows which key is

used for each terminal designator.
For example, to create an APL overstruck character on terminals using the
Backspace key, enter the first character, press the Backspace key and enter the

second character. For example, Shift/l Backspace Shift/k produces quote_quad
(). The constituent characters may be entered in either order.

Terminals using the TTY designator use TTY mnemonics and do not need to
create overstruck characters.

Table 1-8

Overstruck Character Key

Backspace

Ctrl/D

Compose

APL

VT220

VT240

KEY

VT320

BIT

VT330

4013

VT340

4015

DECTERM

GIGI

VT102
HDS201
HDS221

HDSAVT

1.5.4

[JTLFE and [JGAG Settings
When you invoke APL, the terminal characteristics for line editing, O07LE, and

the characteristic for broadcasts, 0GAG, are set by APL. These settings are
determined by the terminal designator value you specified in the initialization
file or command line and the VMS terminal characteristics.
Table 1-9 shows the default settings for each terminal designator.
You can change these settings by assigning new values to OTLE or [1G4G. (See

the VAX APL Reference Manual.)

VAX APL Users Guide

1-25

The VAX APL Operating Environment
1.5 Terminal Designators

Table 1-9

[7LE and [JGAG Settings

Terminal
Designator
(APL

OTLE

OGAG

0 (noline_edit)

Inherits terminal characteristics;
1 (refuse messges)
2 (trap,translate, and display message)

BIT

4013
4015
GIGI
VT102

HDS201
HDS221

| HDSAVT
( TTY
COMPOSITE
VT220

VT240
VT320
VT330
VT340

)

Inherits terminal
characteristics;
0 (noline_edit)
1 (line_edit)

Inherits terminal characteristics
0 (display message)
1 (refuse message)

DECTERM

Because [ITLE<1 means the Backspace key sends the cursor to the beginning of
the line, you must use the arrow keys to change the position of the cursor on
an input line.

1.5.5 Font Files
APL character support for the designators listed in Table 1-10 use font files
provided with the APL software. Logical names are used to find the associated
font file. You can define these logical names to point to your own font files.
Otherwise, APL uses the font files installed with VAX APL.
Table 1-10

Terminal Designator Font Files

Designator

80-column Mode Logical

132-column Mode Logical

VT220

APL$VT220_FONT

VT240

- APL$VT240_FONT

APL$VT240_FONT
_132
(continued on next page)

1-26

VAX APL Users Guide

The VAX APL Operating Environment
1.5 Terminal Designators

Table 1-10 (Cont.)

Terminal Designator Font Files

Designator

80-column Mode Logical

VT320

APL$VT220_FONT

VT330

APL$VT330_FONT

APL$VT330_FO132
NT

VT340

APL$VT340_FONT

APL$VT340_FO132
NT

132-co|umn Mode Logical

APL$VT320_FONT_132

1.6 APL Operating Modes
There are two operating modes in APL:
¢

Immediate mode

Function-definition mode

In immediate mode (sometimes called execution mode), a line is executed
immediately after you enter it and press the Return key. You must be in

immediate mode to execute APL statements. You enter function-definition
mode only to define or edit an operation (for more information, see Chapter 3).

In immediate mode, APL clearly differentiates between what it prints out
and what you enter. APL displays its output at the left margin, but indents
six spaces before echoing your input; thus, the data APL prints out begins in
column 1, and the data you enter in begins in column 7. The six spaces APL
indents can be thought of as an input prompt. For example:
2

12345

The DECwindows interface echoes input on the command line. When you press
the Return key, APL transfers the input to the transcript window and executes

the command.
Text can be copied from the transcript window or from another window on the

display to the command line. To copy text, position the mouse pointer at the
beginning of the text, hold down Mouse Button 1 (MB1) and drag the mouse
until all of the text you want to Cut is highlighted. Release MB1. Position
the mouse pointer on the command line and press Mouse Button 2 (MB2) to
copy the text onto the command line. Press Return to execute the command.
Input on the command line can be a mixture of entered and pasted text. For
example, you could enter 4, copy «2 3 o112 from a previous command shown
in the transcript window, and press Return.

VAX APL Users Guide

1-27

The VAX APL Operating Environment
1.6 APL Operating Modes

APL sessions using the Character-Cell interface can copy lines previously
entered in the current session. Use the up arrow key or the mouse to position
the cursor on the line you want to copy and press the Return key. The line 1s
copied to the input line and TPU displays a message indicating that the copy
was successful. The line is executed when you press the Return key.

1.7 Keyboard Editing
The order in which you enter characters in an input line is insignificant;
as 1t appears on
regardless of how you enter the line, APL evaluates it exactly

the terminal.

If you discover an error in a line before you enter it (in other words, before you
press Return), and OTLE is set to 0 (noline_edit), backspace to the error and
press the Line Feed (LF) key. Everything from the <LF> to the right is ignored
by APL. You can then complete the line by entering the correct text directly
below the part in error.

If OTLE is set to 1 (line_edit), use the arrow keys or the Delete key to change
the position of the cursor on the input line to correct the error. Press Return to

execute the command. APL inputs the entire line, regardless of the location of

the cursor.

If you are using the DECwindows and Character-Cell interfaces, the mouse can
be used to point to and click on a new cursor position in the input line. Enter
new text or edit the existing text, and press Return to execute the command.

You can use the v editor to edit the last immediate mode line that was
executed; for details, see Section 3.11.5.7.

The VMS operating system recognizes several ASCII control characters as

keyboard editing characters. Table 1-11 lists some of these characters and
their meanings. One particularly important control character, the attention
signal, is referred to throughout this manual; use it to interrupt APL operation
execution and expression evaluation. For more details about the attention
signal, see Section 1.9. For more details about how other control characters
are implemented, see the VMS DCL Dictionary.

1-28

VAX APL Users Guide

The VAX APL Operating Environment
1.7 Keyboard Editing

Table 1-11

Editing Characters

Character

Meaning

Backspace

Positions the cursor one character to the left. If the VMS
terminal line-editing feature is enabled, Backspace positions

the cursor at the left margin. OTLE controls the setting of
the terminal line-editing feature (see the VAX APL Reference
Manual).
Ctrl/C

Interrupts APL operation execution and expression evaluation.

One Ctrl/C is the weak attention signal; two, the strong attention
signal. For details, see Section 1.9.
Ctrl/O

Suppresses output to the terminal. Entering a second Ctrl/O
resumes output to the terminal, if the program is still executing.

Ctrl/R

Performs a line feed and displays the corrected line starting at
column 1.

Ctrl/T

Causes APL to display an informational message. The contents
of this message are discussed in Section 1.5 under the description
of HDS terminals.

Ctrl/U
CtrlI/X

Deletes the current input line and reprompts for input.
Deletes all lines that you have entered but that have not yet

been executed.
Ctrl’Y

Panic exit; returns you to DCL. Depending on your terminal
type, you may or may not be able to return to your APL session

with the DCL command CONTINUE.

Delete

Deletes the previous character. On an LA terminal, echoes as a
~ character.

Tab

Advances cursor to the next horizontal tab stop. APL cannot
change tab stops. Tabs are passed to the operating system for
interpretation.

1.8 APL Workspaces
APL uses a block of storage called a workspace to store the following:

Operations, variables, and their values

Information about the status of operations

Group descriptions

Temporary results obtained while executing APL statements

Other work completed in an APL session

VAX APL Users Guide

1-29

The VAX APL Operating Environment
1.8 APL Workspaces
In this manual, the term workspace refers to either the active workspace or
a version of an active workspace that is being saved on secondary storage and
thus is inactive.

As an APL user, you have extensive control over the activity and characteristics
of the workspaces in the system. You can clear, save, load, name, and delete
workspaces, and you can copy operations and variables from a saved workspace
into an active workspace.

1.8.1

Workspace Types
There are three workspace types:
e

(lear workspace

Active workspace

Inactive (or saved) workspace

A clear workspace is just what the name implies: a workspace that is
entirely clear of operations, variables, and other signs of work done during
APL sessions. You receive a clear workspace at the beginning of an APL
session, unless a CONTINUE workspace is available or unless you ask for a
specific workspace when you invoke APL. (For a complete description of the
characteristics of a clear workspace, see the VAX APL Reference Manual).

The active workspace is the workspace you are currently using. When
you begin to do work in a clear workspace, it becomes the active workspace
(although it retains the name CLEAR WS until you explicitly name it). The
effects of the work you do during an APL session are temporarily stored in
your active workspace.

When you save an active workspace with the ) SAVE command, the work you
did while it was active is permanently stored on a secondary storage device,
usually in your default area. The version of the workspace that you save
is known as an inactive workspace. The saved work includes operations,
variables, the APL symbol table and state indicator, some system variable
settings, and so forth. An inactive workspace can be reloaded into memory and
can become the active workspace once again, thus reproducing the environment
that was in effect when the workspace was saved. (Note that files left open
when the workspace was saved are now closed, but not deassigned, and a few
system variable settings may have changed.)

1-30

VAX APL Users Guide

The VAX APL Operating Environment
1.8 APL Workspaces

1.8.2

Workspace Names and File Specifications

Each APL workspace defined in your disk area must have a unique name. The
formats for workspace names are the same as those for other operating system

file specifications.
1.8.2.1

VMS File Specification Format

Under the VMS operating system, the format for file specifications is as follows:
node::device:[directory]filename.filetype;version
An example of a complete VMS workspace name is:
NODEA: :DB1:[APLGRP]SAMPLE.APL;6

The maximum length for a VMS file specification is 255 characters. For more
details about VMS file specifications, see the VMS User’s Manual.
1.8.2.2

Workspace Name Defaults

You do not have to specify all the parts of a file specification. The defaults are
summarized in Table 1-12.

Table 1-12

1.8.3

Workspace Name Defaults

Component

Default

Node

The computer node you are using.

Device name

Your default device.

Directory

Your default directory.

File name

Generally must be specified, but sometimes defaults to the
name of the active workspace.

File type

APL

Version

For input, the highest version number. For output, the
highest version number plus one.

Workspace Passwords
You may use the )SAVE, YWSID, or ) PASSWORD system commands (see the

VAX APL Reference Manual) to assign a password to an APL workspace.
Passwords are eight characters long. If you specify a password that is longer,
it 1s truncated after the first eight characters; if you specify one that is shorter,
it is padded on the right with blanks. For example, the following command

assigns the password SESAME to the workspace F0o0:
)SAVE F00/PASSNORD=SESAME

VAX APL Users Guide

1-31

The VAX APL Operating Environment
1.8 APL Workspaces
The password SESAME is padded on the right with two blanks.

The characters that are valid in password names are the same as those that
are valid in identifiers.

When a workspace has a password associated with it, you must specify that
password before APL allows you to retrieve the workspace or copy objects from
it. By default, a workspace has no password (the password is eight blanks).

1.8.4 The CONTINUE Workspace
When you end an APL session with the ) CONTINUE command, APL saves the
active workspace in your default directory and names it CONTINUE.APL.
If files named CONTINUE.APL already exist in your directory, the new
CONTINUE workspace will have a version number that is one higher than the
next most recent version. Just like any inactive workspace, the CONTINUE
workspace is an image of the active workspace as it existed when it was saved.
If a CONTINUE workspace exists in your default directory when you access
APL, it is loaded as your active workspace (unless the command line or the
initialization file specifically asks for another workspace).

1.8.5

Groups
Selected user-defined operations and variables in a workspace can sometimes
be easier to work with when they are treated as elements in a single logical
collection, called a group. APL provides system commands that allow you
to define groups, obtain a list of groups, list the members of a group, add
members to or delete members from a group, and erase or disband a group.
For details, see the VAX APL Reference Manual.

1.8.6 The State Indicator
APL workspaces contain a status vector, known as the state indicator, which
stores information about the execution of operations within the workspace. You
can use the ) SI system command (see the VAX APL Reference Manual) to list
the contents of the state indicator. The list identifies suspended operations
(user-defined functions or operators that have stopped executing for some
reason) and pendent operations (user-defined functions or operators that have
called other operations, and are waiting for them to complete).
If the state indicator has no value, no operations are currently suspended or
pendent. For more information about the state indicator, see Chapter 3.

1-32

VAX APL Users Guide

The VAX APL Operating Environment
1.8 APL Workspaces

1.8.7 Workspace Size
The size of an APL workspace is dynamic; its maximum size is 2 million pages
(512 bytes per page). Note, however, that the maximum size depends on your

operating system resources—you may not be able to access APL’s limit of 2
million pages. The default maximum workspace size is 512 pages. You can use
the YMAXCORE system command tochange this value.

1.9 Interrupting APL
You can interrupt APL execution by entering any of the three forms of the
attention signal:

Ctrl/C—The weak attention signal. It means suspend execution of the
current operation after executing the current statement and return control
to immediate mode. During terminal output, this signal acts as a strong
attention signal, immediately stopping the output. When this signal is
used during a delay caused by the execution of (IDL (see the VAX APL

Reference Manual), the delay is canceled but attention is not signaled.
e

Ctrl/C Ctrl/C—The strong attention signal. It means suspend the current
operation as soon as possible, even in the middle of the statement, and
return control to immediate mode.

Ctrl/Y—The panic exit. It means suspend the current operation
immediately and give control to the operating system. After a panic
exit, you can return to where you left off by executing the VMS operating
system command CONTINUE. If you enter the panic exit while an
operation is executing, the operation is suspended; if you then enter
CONTINUE, the operation resumes execution at the point where it was
interrupted.

If you are using the DECwindows interface, you can use the the Interrupt

option that is displayed if you click on Commands located in the menu bar of
the transcript window. (See Figure 1-4.) The Interrupt option sends a Ctrl/C
signal to the APL session.

The abort input signal allows you to escape to immediate mode when APL
is waiting for input. The abort input signal is particularly useful when APL is
executing [, 1, or @ input, or when APL is in the v editor or super-edit mode.
(You can also use the abort input signal in immediate mode if you do not want
to enter a line that you have entered.) In all cases, APL cancels the current
input request.

VAX APL Users Guide

1-33

The VAX APL Operating Environment
1.9 Interrupting APL
Figure 1-4

DECwindows Interface Commands Options

Eummands ] Eunts
Edit New

Interupt

Continue (Exit)

| off (Quit)

When you use the abort input signal to escape from a [0, 1, or ¥ input that is
inside an operation, the operation is suspended (unless it is locked), and APL
returns you to immediate mode.
When you use the abort input signal to escape from the W editor, APL restores
the operation to the definition it had before the edit session began. If you
escape from super-edit mode, APL prompts you to begin entering the current
line again.
Different terminal types form the abort input signal differently as follows:

1-34

VAX APL Users Guide

The VAX APL Operating Environment
1.9 Interrupting APL

Signal Form

Terminal Designator

0 Backspace U Backspace T

APL, BIT HDS201, HDS221, HDSAVT, KEY, LA,

O Backspace U Backspace T

TTY

o Backspace u Backspace t

TTY

.OU or .ou

tty

Ctr/Do U

VT220, VT240, VT320, VT330, VT340, DECTERM

Compose 0 U

0 Backspace(F12) U

DECterm using DECwindows interface

4013, 4015

For terminals that form the abort input signal with 0 Backspace U Backspace

T, you must enter the five keystrokes in the order shown, with no embedded
spaces or tabs.
For a non-APL terminal, note that the dot (.) of .OU (or .ou) must appear in

the first column of a line or must be preceded by a space. For example, in TTY
mode:
"First,

the

.0U is part

of a filetype

JOUTPUT DATA.0UT

"Now,

the

JOUTPUT DATA

.0U is

the abort

Iinput

signal

.OUT

51 INPUT ABORTED
)OUTPUT DATA

.0UT
A

For terminals that form the abort input signal with Ctrl/D 0 U or Compose 0 U
the order in which you enter the 0 and U does not matter.

1.10 Ending an APL Session
You can end an APL session and return to operating system command level

by entering an )OFF or ) CONTINUE system command, or by typing Ctrl/Z.
The )OFF and ) CONTINUE system commands also give you the option of
logging off without first returning to the DCL level. APL sessions using the
DECwindows interface can also use the Continue (Exit) and Off (Quit) options

to end a session. Click on the Commands option shown in the menu bar of the
transcript window to display these options. (See Figure 1-4.)

VAX APL Users Guide

1-35

The VAX APL Operating Environment

1.10 Ending an APL Session
When you enter Ctrl/Z, APL responds as though there were an )OFF in the

input line. Thus, Ctrl/Z works anywhere that the )O0FF system command
works. Anything that appears on the input line before the Ctrl/Z is executed

before the session is terminated. For example:
1+1

ANOW ENTER CTRL/Z AFTER THIS COMMENT

TWAY:

WEDNESDAY

23-JAN-1991

CONNECTED 00:01:21.62
0

STATEMENTS

148

16:30:43.63

CPU TIME 00:00:00.62

OPERATIONS

PAGE FAULTS

383

BUFFERED I0

DIRECT IO

S
Ctrl/Z works inside the v editor even during character-editing (superedit)

mode:
VF

[1]
[2]
[3]

C«2 3 30 42
A<C+24

53 75

AUSER ENTERS CTRL/Z
EXIT

I'WA4:

WEDNESDAY

CONNECTED

0 STATEMENTS

148

23-JAN-1991

00:01:21.62

PAGE FAULTS

16:30:43.63

CPU TIME

00:00:00.62

OPERATIONS

383 BUFFERED I0

DIRECT IO

5
For more information about the YOFF and )CONTINUE commands, see the

VAX APL Reference Manual.
Note

If you end an APL session by disconnecting a dialed-in terminal’s
telephone connection, the active workspace is lost unless your terminal
1s defined as a virtual terminal to the VMS operating system. For more

information, see the VMS DCL Dictionary.

1.11

Character Sets
When you access APL, your terminal uses one of the character sets listed in
the following subsections: APL key-paired, APL bit-paired, APL COMPOSITE,

or TTY. Be careful not to confuse the character set your terminal uses
with the character set the APL language uses internally (see Table 1-19 in

Section 1.11.6).

1-36

VAX APL Users Guide

The VAX APL Operating Environment

1.11 Character Sets

1.11.1

Character Sets Used by APL Terminals
Most terminals that have an APL keyboard use either the key-paired
(Table 1-13) or bit-paired (Table 1-14) character set. Digital LA, GIGI,

and VT102 terminals use the key-paired character set. The HDS201, HDS221,
HDSAVT, 4013, and 4015 terminals also use the key-paired character set.

Table 1-13

decimal

APL-ASCII Key Pairing (Typewriter Pairing)

112

NUL

DLE

SOH

DC1

STX

DC2

)

ETX

DC3

EOT

DC4

ENQ

NAK

€

ACK

SYN

BEL

ETB

]

8
9

CAN

SUB

(

ESC

[

{

;

}

DEL

112

Table 1-14

decimal

APL-ASCII Bit Pairing

NUL

DLE

SOH

DC1

STX

DC2

ETX

DC3

[

(continued on next page)

VAX APL Users Guide

1-37

The VAX APL Operating Environment
1.11 Character Sets

Table 1—14 (Cont.)
decimal

APL-ASCII Bit Pairing

112

EOT

DC4

ENQ

NAK

€

ACK

SYN

BEL

ETB

CAN

SUB

)

]

ESC

(

[

;

{

}

usS

DEL

1.11.2 Character Set Used by Non-APL Terminals
Terminals that cannot enter APL characters must use the TTY character set,

which uses ASCII mnemonics to represent APL characters.

Note that when you enter lowercase letters from a non-APL terminal, APL
converts them to uppercase letters (except in literals or comments). Unknown
TTY mnemonics, however, are not changed to uppercase. For example, notice

the error message returned when the user tries to load a file that does not
exist:
)load myfile.lst

1 FILE NOT FOUND

(FILE NOT FOUND)

JLOAD MYFILE.IST
A

APL changed everything except .Is to uppercase because it did not recognize .Is
as a character.
APL recognizes the TTY mnemonics for the characters {

} ~

and |

and

for the lowercase letters (.JA — .JZ) only if your terminal is not capable of

producing the actual characters or lowercase letters.

1-38

VAX APL Users Guide

The VAX APL Operating Environment
1.11 Character Sets
Backspaces are allowed on non-APL terminals, but the only permissible
overstruck characters are characters overstruck with themselves or with
spaces. If you attempt to enter any other overstrikes, APL signals CHARACTER
ERROR.

Table 1-15 lists the TTY characters in alphabetical order and shows their
ASCII and APL equivalents.

Table 1—-15
TTY Set

TTY Character Set
Name

ASCIIl

APL

Characters

Set

to Combine

stile (ABsolute value)

Accent Grave

ALpha

AmPersand

quad (BoX)

[

.CB

Column Backslash

.CC

Column Comma

.CE

CEiling

.CF

CircumFlex

.CO
.CR

‘

o
&

r
A

COntains

Column Reverse

.CS

Column Slash

.DA

Down Arrow

.DD

Dieresis

.DE

base (DEcode)

DelL

DiaMond

Divide Quad

Down U

represent (ENcode)

EPsilon

€

FLoor

(continued on next page)

VAX APL Users Guide

1-39

The VAX APL Operating Environment

1.11 Character Sets

Table 1-15 (Cont.)

TTY Character Set
ASCIl
Set

APL
Set

Characters
to Combine

TTY Set

Name

JFM

thorn (ForMat)

.GD

Grade Down

.GE

Greater than or Equal

.GO

right arrow (GO to)

.GU

Grade Up

I-Beam

I10ta

Input Quad

JA - JZ

lowercase letters

a—z

a-—z

A -7

Ctrl/A

SOH

Ctrl/B

STX

Ctrl/C

ETX

Ctrl/D

EOT

Ctrl/E

ENQ

Ctrl/F

ACK

Ctrl/G (Bell)

BEL

Ctrl/H (BackSpace)

Ctrl/I (Horizontal Tab)

KdJ

Ctrl/J (Line Feed)

Ctrl/K (Vertical Tab)

Ctrl/L (Form Feed)

).y

Ctrl/M (Carriage Return)

Ctrl/N (Shift Out)

Ctrl/O (Shift In)

Ctrl/P

DLE

Ctrl/Q

DC1

Ctrl/R

DC2

Ctrl/S

DC3

(continued on next page)

1-40

VAX APL Users Guide

The VAX APL Operating Environment

1.11 Character Sets

Table 1-15 (Cont.)

TTY Character Set

TTY Set

Name

ASCIl
Set

APL
Set

Ctrl/T

DC4

Ctrl/U

NAK

Ctrl/V

SYN

Ctrl/'W

ETB

Ctrl/X

CAN

Ctrl/Y

Characters
to Combine

Ctrl/Z

SUB

.LB

Left Brace

{

delta (Lower Del)

.LE

Less than or Equal

LoGarithm

Left tacK

circle (Large O)

Left U

MaTch

Not Equal

high minus (NeGation)

NaNd

[

NoR

tilde (NoT)

.OM

OMega

.0Q

Output Quad

.OR

PerCent sign

.PD

Protected Del

Pound Sign

.QD

Quad Del

Quote Quad

v
%

(continued on next page)

VAX APL Users Guide

1-41

The VAX APL Operating Environment
1.11 Character Sets

Table 1—15 (Cont.)

TTY Character Set

TTY Set

Name

ASCII
Set

APL
Set

double QUote

.RB

Right Brace

}

.RK

Right tacK

Characters
to Combine
4

RhO

Right U

ReVerse

jot (Small O)

Squish Quad

[

]

SubSet

TRanspose

]

.UD

Underscored Delta

UnderScore

.UU

UpU

DEL (DELete)

DEL

Ctrl/[ (ESCape)

ESC

CtrI/\

Ctrl/]

Ctrl/@ (Null)

NUL

Ctrl/?

Ctrl/_

hydrant (eXzcute)

ZA - 77

underscored letters

A-2Z

1.11.3 Composite Character Set
DIGITAL VT220, VT240, VT320, VT330, VT340, DECterms and VAXstations
use the APL COMPOSITE character set listed in Table 1-16.

1-42

VAX APL Users Guide

The VAX APL Operating Environment

1.11 Character Sets

Table 1-16
dec

APL COMPOSITE Character Set

128

160

192

224

NUL

unused

SOH

unused

STX

unused

ETX

unused

EOT

IND

ENQ

NEL

ACK

SSA

BEL

ESA

]

(

HTS

)

HTJ

VTS

PLD

PLU

€

)

SS2

SS3

DLE

DCS

PU1

DC1

DC2

PU2

DC3

STS

DC4

CCH

NAK

SYN

SPA

ETB

EPA

[

CAN

unused

SUB

ESC

;

[

{

CSI

“

(continued on next page)

VAX APL Users Guide

1-43

The VAX APL Operating Environment
1.11 Character Sets
Table 1-16 (Cont.) APL COMPOSITE Character Set
dec

128

160

192

224

]

}

0OSC

DEL

APC

Note that in column 1 dee is an abbreviation for decimal.

1.11.4 Digital Multinational Character Set
Table 1-17 shows the DIGITAL Multinational Character Set (MCS).
Table 1—17

Digital Multinational Character Set

dec

128

160

192

224

00
01

NUL

’

unused

SOH

STX

!
"

A
B

a
b

unused
unused

i
¢

A
A

a
a

ETX

unused

EOT

IND

unused

ENQ

NEL

ACK

SSA

unused

BEL

ESA

08
09
10

BS
HT
LF

(

HTS

)
*
+
:

E
E
E
1

é
é
é
i

HTJ

J
K

j
k

VTS
PLD

]

PLU

unused

SS2

unused

SS3

unused

DLE

DCS

unused

DC1

PU1

(continued on next page)

1-44

VAX APL Users Guide

The VAX APL Operating Environment

1.11 Character Sets

Table 1-17 (Cont.)

Digital Multinational Character Set

dec

128

160

192

224

DC2

PU2

DC3

STS

DC4

CCH

unused

NAK

SYN

\Y4

SPA

ETB

EPA

CAN

unused

(%,

unused

SUB

unused

ESC

;

[

{

CS1

]

}

OSC

unused

UsS

DEL

APC

unused

Note that in column 1 dec is an abbreviation for decimal.

1.11.5 ASCII Character Set
You can set most APL terminals to ASCII mode when you want to use the

standard ASCII character set, then switch to APL mode when you want to use
the APL character set. Table 1-18 shows the ASCII character set.

Table 1-18
dec

ASCII Character Set

112

NUL

DLE

SOH

DC1

‘

STX

DC2

ETX

DC3

EOT

DC4

(continued on next page)

VAX APL Users Guide

1-45

The VAX APL Operating Environment
1.11 Character Sets

Table 1-18 (Cont.)
dec

ASCII Character Set

112

ENQ

NAK

ACK

SYN

\'%

BEL

ETB

’

CAN

(

)

SUB

ESC

;

[

{

]

}

)

DEL

Note that in column 1 deec is an abbreviation for decimal.

1.11.6 Elements of [J]AV
04V contains a vector of the 256 characters known to APL. Table 1-19 shows
the characters and their positions in the vector based on an index origin of 0.
Table 1-19
dec

Elements of AV

([0I0<0)

NUL

SOH

STX

)

ETX

EOT

ENQ

128

160

192

224

[

€

ACK

BEL

]

(continued on next page)

146

VAX APL Users Guide

The VAX APL Operating Environment

1.11 Character Sets

Table 1-19 (Cont.)

Elements of 04V (010+0)

dec

128

160

192

224

0
[

DLE

DC1

DC2

DC3

)

DC4

NAK

SYN

ETB

CAN

[

SUB

(

[

ESC

[

{

;

)

}

[

)

DEL

The index of a character in 04V is the sum of its row and column numbers.
Note that in column 1 dec is an abbreviation for decimal.

VAX APL Users Guide

1-47

2
VAX APL Language Concepts
In the VAX APL language, you form expressions by applying functions to
arrays, and the APL interpreter evaluates the expressions. An array is a
collection of one or more data elements called items. An item may be a scalar

data element, or it may include many data elements. An item may be numeric,
character, or a combination of the two.

This chapter discusses arrays, describes the syntax of APL expressions, and
explains how expressions are evaluated by the APL interpreter.

2.1

Array Types
There are two types of arrays in APL: simple and enclosed. In a simple array,
each item is a single data element. In an enclosed array, one or more items are
an array. For example:

[J«B<«23
23

ACREATE B,

SIMPLE ARRAY,

5 SCALAR ITEMS

ACREATE C,

ENCLOSED ARRAY,

A
[«C«13

98)

ITEMS

U4 SIMPLE SCALARS AND 1 ENCLOSED SCALAR
29

There are two types of data elements: character and numeric. Any given

array may contain either or both of these types. When the items of an array
are entirely character or entirely numeric, the array is called homogeneous.
When the items are a mixture of character and numeric data elements, the
array is called heterogeneous. For example:

VAX APL Users Guide

2-1

VAX APL Language Concepts
2.1 Array Types

aCREATE SIMPLE HOMOGENEOUS

0«B«23 15 9 83 99
23

99
6WCREATE SIMPLE HETEROGENEOQUS

D+C+'P'

P31 N

'N'

1CD

aCREATE ENCLOSED HOMOGENEOQUS
D*D*'X'

t----- +

"APPLE'

'[!

(va

vsr)

t---t

aCREATE ENCLOSED HETEROGENEOUS

O«F<'P"

(31

P+----- + N 1

24)

'N'

('CRIB')

+----+

|31 1 24|

| CRIB|

t----+

A character array may include any value from the atomic vector returned by

JAV (the niladic system function whose value is the 256 characters known

to APL; see the VAX APL Reference Manual.) To designate that an array
constant is of type character, you enclose it in single quotation marks. For
more information on character arrays, see Section 2.5.3.2.
The numeric data type can be subdivided into the following:
*

Boolean—a 1 or a 0.

Integer—the positive and negative integers and zero.

Near-integer—a number equal to an integer within the tolerance defined

by OCT (see the VAX APL Reference Manual).

Floating-point—the integers and real numbers.

Although you cannot control the internal precision of numeric representation,

you do have some control over numeric output representation. The PP system
variable (see the VAX APL Reference Manual) allows you to specify the output
precision of floating-point numbers, and you can use the APL format functions
(OFMT and =) to control the output precision of specific arrays.

For more information on numeric arrays, see Section 2.5.3.1.

2.2 Array Structure
Arrays are also characterized by their structure. The structure of an array

1s the way in which the array’s items are arranged. Specifically, an array’s
structure is defined by three properties: rank, shape, and depth.

2—-2

VAX APL Users Guide

VAX APL Language Concepts
2.2 Array Structure

2.2.1

Rank of an Array
The rank of an array is determined by the number of axes (sometimes called
dimensions or coordinates) along which its items are arranged. For practical
purposes, there is no intrinsic limit on the number of axes in an APL array. As
long as the size of the array does not exceed the size of your workspace, you
can have up to 65,535 axes. The special terms associated with arrays of rank
0, 1, and 2 are, respectively, scalar, vector and matrix.
A rank O array, or scalar, is a single numeric or character value that has zero

axes (thus, it cannot be indexed). APL considers any of the following, when
entered, to be scalars:
1

32.28
LA

99999
17

Nk
151

It is possible for a single data element to have a structure, that is, one or
more axes. In this case, the item is not a scalar (which never has an axis)
but a singleton. For example, any of the values in the preceding list could

be converted to nonscalar singletons with the reshape (p ) or the ravel (, )
function. The following subsections include more information on singleton
arrays.

A rank 1 array, or vector, consists of any number of numeric or character
values arranged along one axis. A singleton vector is a vector containing only
one value. The following are all vectors:
12345

'VECTOR!
23

197

2543

23 +---—------- t+ t------ +

1197 6 2543]

|14 29

oo L

'THIS IS A

11 2|
+

CHARACTER STRING'

Note that the items in a numeric vector must be separated by at least one
space. The spaces are not part of the vector, but they are necessary in order
to delimit the end of one item and the beginning of the next. In a character

vector, as in any character array, spaces that are embedded between quotation
marks are part of the vector.

VAX APL Users Guide

2-3

VAX APL Language Concepts
2.2 Array Structure
A rank 2 array, or matrix, consists of any number of numeric or character
values arranged along two axes, commonly called rows and columns. A
singleton matrix is a matrix containing one row and one column. The following
matrix has three rows, and four columns:
1

In an array of rank 3 or more, the leading axes are known as planes. For
example, the following array has a rank of 3. There are two planes, three rows,

and four columns. Note that the planes are separated by a blank line.

The rank of an enclosed array is not affected by the rank of any of the

individual items. In the following example, R is an enclosed vector with length
3. The first item is a scalar (rank 0); the second item is a matrix (rank 2); and
the third item is a vector (rank 1). The rank of R is 1. Note that the enclosed
items of R are created with a combination of parentheses and the enclose

function (< ).
«R<317,(c
317

5Sp'ALPHABET

+----- +

t----——=- +

|ALPHA|
|BET
|

+-------- +

| SOUP

SOUP

'),c3

317

317|

aQUERY FOR SHAPE OF R

poR

AnQUERY FOR RANK OF R

2.2.2

Shape of an Array
The shape of an array is the number of items along each of its axes. An array
1s known as an empty array if the length of any of its axes is 0.

Scalars do not have a shape because they have no axes. Vectors have one axis,
and the shape (also known as the length) is represented by a single value. For
example:

2-4

VAX APL Users Guide

VAX APL Language Concepts
2.2 Array Structure
12345

ALENGTH =

'VECTOR'!

ALENGTH = 6

197

(197

2543

2543)

'THIS IS A

(14

ALENGTH =

5
8

RLENGTH =

CHARACTER STRING'

ALENGTH =

Matrices have two axes, and the shape is expressed as two values. The first
value is the number of the rows. The second value is the number of the

columns. As the following example shows, a matrix is always rectangular; the
product of the number of rows times the number of columns equals the total

number of items in the array.
1

aSHAPE

VECTOR =

Singletons can have any number of axes, but none of the axes can have a
length other than 1. To reveal the shape of a singleton, you would use the

shape (p ) function, which is discussed briefly in the next section.
The shape of an enclosed array is not affected by the shape of any of the

individual items. In the following example, R is an enclosed vector array. The
first item is a scalar (no shape); the second item is a matrix (shape 3 5); and
the third is a vector (shape 3). The shape of R is 3. To show the shapes of the
individual items of R, the example uses the each (~ ) operator with the shape
(p ) function as a left operand. The = operator applies its operand to each item
In R.
O«R<317,(c
317

+----- +

Sp'ALPHABET

SOUP

'),c3

317

|ALPHA|

|3 28

|BET

+-------~ +

317|

| SOUP

$--—-- +

PR
3
4

aQUERY FOR SHAPE OF R

0 'R
===+

fQUERY FOR SHAPE OF FACH ITEM IN K
-+

113 51

+-+

+---+

VAX APL Users Guide

2-5

VAX APL Language Concepts
2.2 Array Structure
2.2.2.1

Shape and Reshape Functions

The monadic p function (known as shape) takes an array as its argument and
displays the current shape of the array. The display is a vector that contains

one number for each axis in the array. The values of the numbers represent
the lengths of the axes.
The dyadic p function (known as reshape) builds an array of a specified shape.
The left argument determines the new shape vector. The right argument
contains the items that will populate the new array. When you use the o
function for this purpose, you are reshaping the array.

Scalars do not have a shape because they have no axes. If you query for the
shape of an array that is scalar, APL returns an empty numeric vector, as
follows:
B<5

RCREATE B,

AQUERY FOR THE SHAPE OF B

A NUMERIC SCALAR

C<«TAT

ACREATE C,

aQUERY FOR THE SHAPE OF C

(APL outputs a blank line)
A CHARACTER SCALAR

(APL outputs a blank line)

Vectors do have a shape because they have one axis. The value of the result is

the length of the axis as follows:
B«<5

RCREATE B,

3-ITEM VECTOR

nQUERY FOR THE SHAPE OF B

Matrices have two axes, and the shape vector contains two values as shown in
the following example. The first value is the number of the rows. The second
value 1s the number of the columns.
ACREATE M,

A MATRIX OF

3 ROWS AND

COLUMNS

aNOTE SPACE CHARACTER IN 2ND ROW 7TH COLUMN

(«M<«3

7p'GEORGIEPORGIE EATSPIE!

GEORGIE

PORGIE

EATSPIE
pM
3

nQUERY FOR SHAPE OF M

An array arranged in three planes would have a shape vector of three values.

For example, an array with three planes, four rows, and five columns has the
following shape:
3

2-6

VAX APL Users Guide

VAX APL Language Concepts

2.2 Array Structure
A singleton can have any number of axes, but none of the axes can have a

length other than 1. This means that a value that appears to be a scalar can
be multidimensional. For example:
J«J«1p162

ACREATE J,

VECTOR SINGLETON

nQUEKY FOR SHAPE OF

aSHAPE

VALUE

162
1

J«K<1

1p'A!

VECTOR HAS

aCREATE K,

MATRIX SINGLETON

A
oK

aQUERY FOR SHAPE OF K

aSHAPE

O«M<1

1p8

VECTOR

WCREATE M,

HAS

RANK

VALUES

SINGLETON

|
oM

AQUERY FOR SHAPE OF M

111

aSHAFE

VECTOR

HAS

VALUES

Because the monadic shape (p ) function returns a vector that contains one

number for each axis in the array, the shape of the shape of an array (pp)
returns the number of axes, or the rank, of the array. For example:
RASSIGN AND DISPLAY A

0«G«3
12

3p1

456

MATRIX

AQUERY

FOR SHAPE OF G

ppG

RQUERY FOR THE RANK OF G

(1«55

nASSIGN AND DISPLAY A SCALAR S

aQUERY

0pS

aQUERY FOR THE RANK OF S

2
5

FOR

THE SHAPE OF S

(APL outputs a blank line)
0

VAX APL Users Guide

2-7

VAX APL Language Concepts
2.2 Array Structure
The following examples use reshape (dyadic p ):
V<'RANK2ARRAY'
2 5p ¥V

aSIMPLE CHARACTER VECTOR

H<4 3p112
pH

ACREATE MATRIX H
nSHAPE OF H

(O«H«3 4 pH

ARESHAPE AND REASSIGN H

ARESHAPE V INTO MATRIX

RANK?2

ARRAY

43
2

aNEW SHAPE OF H

When displaying arrays that have three or more axes, APL inserts one blank
line between each plane and one additional blank line for each additional axis.
For example:
A«'"ABCDEFGHIJKLMNOPQRSTUVNXYZ123u5"
2

UpA

ABCD
EFGH
IJKL

MNOP

QRST
UVWX
Y7212
454

For more information on the p functions, see shape and reshape in the
VAX APL Reference Manual.

2.2.3 Depth of an Array
Depth refers to the levels of nesting that occur in an array. A simple array has
one level of nesting (zero if the array is a simple scalar). An enclosed array has
a depth of at least two.

The monadic = function (known as depth) takes an array as the argument

and returns an indicator of the deepest level of nesting among all items of
the array. (The depth function is described in greater detail in the VAX APL

Reference Manual.) For example:

2-8

VAX APL Users Guide

VAX APL Language Concepts

2.2 Array Structure

aSIMPLE SCALAR
aDEPTH OF B

ool

0<«B+9

RSIMPLE VECTOR ARRAY

O«C«'WHERE ARE YOU GOING?'

WHERE ARE YOU GOING?
=C
1

aDEPTH OF C
,

(«D«2

10pC

aSIMPLE MATRIX ARRAY

WHERE ARE

YOU GOING?
=D

aDEPTH OF D

aENCLOSED ARRAY,

O«E«1

(5 6 7)

NESTING LEVEL

11 12

nDEPTH OF F
WENCLOSED ARRAY WITH MORE NESTING

D+F+1

(567

(89

10))

sDEPTH OF F

2.2.4 Shape Domains of Primitive Function Arguments
Many APL primitive functions restrict their argument domain to arrays of a
particular shape. They may require arguments to be:
*

Singletons—1-item arrays of any rank (note that this includes scalars); can

be thought of as the scalar domain.
*

In the vector domain—a singleton or a vector.

In the matrix domain—a singleton, a vector, or a matrix.

The following are formal definitions for the scalar, vector, and matrix domains:
Scalar domain:

(02ppARG)Vvi=x/pARG

Vector domain:

(12ppARG)Vvi=x/pARG

Matrix domain:

(22ppARG)Vv1=x/pARG

VAX APL Users Guide

2-9

VAX APL Language Concepts
2.2 Array Structure
From these, a more general definition may be induced:
N -array domain:

(N2ppARG)v=x/pARG

where N is the rank of the domain to be defined.

2.3 Scalar Product and Singleton Extension
Many dyadic functions, functions with two arguments, require the shapes

of their arguments to conform to each other in some way. For example, the
scalar functions (such as + - x %) require that the left and right arguments
have the same shape. When you execute a scalar function, APL applies the
function over each corresponding pair of items. This process is known as
scalar product.
aSCALAR FUNCTIONS EXTEND OVER

38+

FACH SUCCESSIVE PAIR OF ITEMS

aTHIS IS A

SCALAR PRODUCT

Scalar product is applied pervasively , that is, at all depths (levels of nesting)
of an array. For example:
«2

(456

(14

C«5

(29

(4 02))1(07)

B
2

2))5

aENCLOSED

VECTOR

aC = SAME SHAPE

onDISPLAY B

tmmmmmmmmmmm
o+

+---+

|4 5 6 +----- + |
|
14 2]

|8 8]
+---4

to---- + |

fom e +

C
5

aDISPLAY C

+----—-=----=- +

+---+

12 9 2 +----- + |
|
|t 0 2]

to-oe- t]

B+
74

aADD APPLIED AT ALL DEPTHS

fmmmmmmm e +

|6
|

10 7]
+---+%

14 8 +----- + |
15 4 4]

+----+

|8 15|
4----t

t----- +|

fom e +

Some of the dyadic functions permit one argument to be in the singleton
domain (either a singleton or a scalar) while the other argument has a

different shape. APL reshapes the singleton (or scalar) to conform to the
shape of the other argument. This reshaping is known either as singleton
extension or scalar extension. For example:

2-10

VAX APL Users Guide

VAX APL Language Concepts
2.3 Scalar Product and Singleton Extension
fEXAMPLE OF SINGLETON EXTENSION

[«B+1
O«C«2

B+
2

2p1l

aCREATE AND DISPLAY B,

A SCALAR

«CREATE AND DISPLAY C,

A MATRIX WITH SHAPE 2

cAPL

RESHAPES B

CONFORM TO

Singleton extension is applied pervasively at all depths of an array. For

example:
«B«2

(14

2))

D<2

aD IS A SCALAR

B+ D

0D GETS RESHAPED,

|36

aCREATE B,

AN ENCLOSED

VECTOR

THEN ADDED

+----- +

When the argument to be extended is a singleton, APL makes the singleton a
scalar (by removing all of its axes) and then reshapes the scalar. For example:
(1

1p1)

2p14

ASINGLETON PLUS MATRIX

becomes
1+

2pud

ASCALAR PLUS MATRIX

and finally
(2

2p1)

2p14

AMATRIX PLUS MATRIX

If both arguments are singletons, APL reshapes them in a way that satisfies
the particular function’s conformance rules. In the following example, the ¢

function (known as rotate) requires the left argument to have a rank that is
one less than the right argument:
(11 1p2)

¢ 1 1 1p3

aTWO SINGLETONS

becomes
(1

1p2)

1 1p3

AFUNCTION'S CONFORMANCE RULES SATISFIED

VAX APL Users Guide

2-11

VAX APL Language Concepts

2.3 Scalar Product and Singleton Extension
If both arguments are singletons, but the particular function has no applicable
conformance rule, the result is a singleton whose rank is the larger of the
argument ranks. For example:
(1 1p2) + 1 1 1p3

aTWO SINGLETONS WITH DIFFERENT RANKS

becomes
(11 1p2) + 1 1 1p3

AaSMALLER RANK ARGUMENT CONFORMS TO LARGER

and the result is
11 1p5

ARESULT RANK CONFORMS TO LARGER ARGUMENT

Note that singleton extension is not limited to the scalar functions; any mixed
function whose argument domain permits a singleton shape will perform the
extension. For example, the monadic index generator (1 ) takes a singleton
argument and returns a vector regardless of the number of the argument’s
axes.

REXAMPLE OF SINGLETON AND
n

545

A MIXED PRIMITIVE FUNCTION

aS IS A SCALAR

I «1 1pS
al IS A MATRIX SINGLETON
alU IS A RANK 5 SINGLETON
U< 1111 1pS
AALL

3 ARGUMENTS RESHAPED

BY SINGLETON EXTENSION

45
1

12345
12

2.4 Empty Arrays
Empty arrays are arrays that have shape, depth, and type, but have no items.
APL often returns an empty array—displayed as a blank line—when no other
result is appropriate. For example, the shape of a scalar is an empty vector:

W<p5

RQUERY FOR SHAPE OF A SCALAR AND ASSIGN

anQUERY FOR SHAPE OF THE EMPTY ARKRAY

opW

nQUERY FOR RANK

aDISPLAY EMPTY

2-12

VAX APL Users Guide

|
(APL outputs a blank line)

VAX APL Language Concepts

2.4 Empty Arrays
Note that the rank of this empty array is 1. Empty arrays may have any rank
except 0. They may be simple or enclosed, and their type may be homogeneous

or heterogeneous. Generally, the type of an empty array is disregarded.

However, in some expressions, the type of an empty array can determine
the type of the result (even an empty result). This applies to the following
operations:
catenate (, )

replication (4 /)

disclose (o)

reshape (p )

drop (+)

reverse (¢ )

enclose (c)

take (+)

expansion (4 \ )

transpose (&)

first (+)

union (u)

indexing ([X ])

unique (u)

intersection (n)

without (~)

ravel
(, )

For the catenate (, ), union (v ), intersection (n ), without (~ ), and indexing ([X ])
operations, the left argument determines the type of the result; for the other
functions, the right argument is the controlling argument. For example:
(t0)

ALEFT ARG IS NUMERIC,

ALEFT ARG IS

EMPTY IS NUMERIC

CHARACTER,

EMPTY IS

Q10

aRIGHT ARG IS NUMERIC,

Qr!

ARIGHT ARG IS CHARACTER,

18§

ARIGHT ARG IS NUMERIC,

o«

ARIGHT ARG IS CHARACTER,

CHARACTER

EMPTY IS NUMERIC
EMPTY IS CHARACTER

The rule is particularly significant for the take (+ ), disclose (> ), expansion

(4\), and replication (4 /) operations, which produce fill items based on the
prototypes (described in Section 2.4.1) of their right arguments:
0\

«> 0

1 7°202/123+«>100
1 2

0 2/"ABC'

(C!

aNUMERIC FILL ITEMS

(ZEROS)

aCHARACTER FILL ITEMS

(BLANKS)

0
!

VAX APL Users Guide

2-13

VAX APL Language Concepts
2.4 Empty Arrays
In all other cases, the type of an empty array is disregarded, and the result
type is the type of the defined result domain of the function. For example:
'Yy

«>

'Toprl

aBECAUSE

(10)p11

aNOTE:

THE

[JI0O

RESULT

NUMFRIC

You may find empty arrays useful when you write user-defined operations. For
instance, you can use empty arrays in conditional branching or to initialize an
array (see Chapter 3).

2.4.1

Array Prototypes
During certain operations, APL inserts fill items as it builds a new array. APL
defines the shape and kind of fill items based on the prototype of an array.
The prototype of an array B is an array with the same shape as the first
item in B. The contents of the prototype are character blanks in positions
corresponding to characters and numeric zeros in positions corresponding to
numbers. You can determine the prototype of an array with the expression
+0pB . For example:
N«LIS<«12
12

13 15

AFIRST ITEM = SIMPLE NUMERIC SCALAR

+0pLIS

aSHOW THE PROTOTYPE OF LIS

O«AL«'"ACE'

ACE

AFIRST ITEM = SIMPLE CHARACTER SCALAR

+0pAL
GIE«(2

aPROTOTYPE OF AL IS A BLANK CHARACTER
2p'Y'3

GIE
t---+

|Y 3]
|5 X|

352

5'X')

352

'"AB(C'

aDISPLAY GIE, A 3-ITEM VECTOR

+---+

|ABC|
+-——

+--—+

aFIRST ITEM = ENCLOSED,

}0pGIE

2-14

VAX APL Users Guide

HETEROGENEOUS MATRIX

aSHOW THE PROTOTYPE OF GIE

VAX APL Language Concepts
2.4 Empty Arrays

2.4.2

Fill tems in Arrays
A fill item is an array (consisting of spaces, zeros, or a combination of the

two) that APL inserts into another array. A fill element is a scalar data
element inside a fill item. There are two kinds of fill elements: character
blanks and numeric zeros. The prototype (described in Section 2.4.1) of an
array determines the shape of a fill item and the kind of each element in the
fill item.
The derived function expand ( A\B ) is an example of an operation where APL
inserts fill items into an array. For example:
LIS«12

+0pLIS

aSHOW THE PROTOTYPE OF LIS

0«B0O«1 0

1 0

10101

aZEROS IN BOO DECIDE LOCATION OF FILL

BOO\NLIS
12

ITEMS

REXPAND LIS

In the preceding example, the shape of the fill item is a simple scalar and the
fill element is a numeric zero. In the next example, the fill item is again a

simple scalar, but the fill element is a character blank.
J«AL«'"ACE"
ACE
+0pAL

BOO«1

aPROTOTYPE OF AL

IS A

CHARACTER BLANK

eEXPAND AL,

ITEMS ARE BLANKS

BOO\ AL

FILL

ACE

In the next example, the shape of the fill item is an enclosed matrix of shape 2
2 and the fill elements are heterogeneous (a combination of zeros and blanks).
GIE«(2

2p'Y'3

5'X'")

+0pGILE

BOO«1

'Y 3]

4+-=-+

|5 X|

tmmmt

-t

"AB(C'

BOO\GIF
$-==4

352

aSHOW THE PROTOTYPE OF GIE

352

AEXPAND GIE,
4-——+

0]
|

NOTF SHAPEF/KIND OF FILL

ITEMS

+-——+%

|ABC|

+---+

-t

VAX APL Users Guide

2-15

VAX APL Language Concepts
2.4 Empty Arrays
Expand is not the only operation that requires APL to insert fill characters.
There is also the derived function replicate (4/B), the take (+ ) and disclose
(> ) primitive functions, and the 0B0X, OEXP, and OREP system functions.

Note that APL always uses scalar blanks as the fill items for 0B0X because
the 0B0X argument is always a simple character array. (Expand, replicate,
take, disclose, 0B0OX, OEXP, and OREP are described in the VAX APL Reference
Manual.)

2.5 APL Expressions
The line is the basic unit of work in APL. It consists of one or more statements
which, in turn, consist of one or more expressions.
An APL expression is:

A variable or constant standing alone.

A function and its arguments (arguments are represented by variables,
constants, or expressions).

An operator and its operands (operands are represented by variables,
constants, functions, or expressions) and the arguments to its derived
function.

An expression enclosed inside of parentheses.

The following sections define identifiers, variables, and constants, explain the
use of spaces in expressions, describe how APL evaluates expressions, and then
discuss APL lines and comments.

2.5.1

Identifiers
APIL has several kinds of identifiers:

Variable names—Names that represent values that can be changed.

Label names—Names that represent line numbers in user-defined
operations (see Chapter 3).

System variable and system function names—Names that are predefined
and begin with the quad symbol (O ).

User-defined function or user-defined operator names—Names you assign
to programs you write (see Chapter 3).

Group names—Names that represent collections of names (see the
VAX APL Reference Manual).

2-16

VAX APL Users Guide

VAX APL Language Concepts
2.5 APL Expressions
The rules for forming all but the system identifiers are as follows:

The maximum length is 31 characters. Identifiers longer than 31
characters are truncated on the right without any message.

Allowable characters include 4 through Z, 4 through Z, a through z, _, A,
A, and O through 9. Embedded spaces are not allowed.

The first character must be 4 through Z, 4 through Z, a through z, A, or
A ; in other words, the first character may not be 0 through 9 or _.

For example:
Legal Identifiers

lllegal Identifiers

ABC63b8

1AC¢75

(Begins with a number)

A7 U4

Zz 9436

(Contains an embedded space)

AG956HA

Pv7u2B (Contains invalid character v )

Note that you can use upper and lower case alphabetics interchangeably when
forming identifiers. APL recognizes the lower case characters and converts
them to upper case.

2.5.2 Wildcards
When you specify an identifier as an argument in a system command or system
function, you can often substitute the » and + wildcards for all or part of the
identifier’s name. The star (x ) symbol represents 0 or more characters, and the
divide (+ ) symbol represents a single character. If you use the TTY character
set, use the asterisk (*) and percent (%) symbols, respectively.
For example, if you specify a variable TR« , you refer to all variables of any

length that begin with the letters TR . If you specify a variable TRAC+, you
refer to all variables that begin with the letters TRAC and end with one
additional character.

The system commands and system functions that use identifiers with wildcards
in their arguments are as follows:
)

COPY

YNMS

0Qco

YERASE

JOPS

geprPC

YENS

)PCOPY

) GROUP

) VARS

)GRPS

For more details about the » and + wildcards, see the VMS DCL Dictionary.

VAX APL Users Guide 2-17

VAX APL Language Concepts

2.5 APL Expressions

2.5.3

Constants
A constant is a numeric or character item whose value is literally the constant
1tself; it 1s not a symbol for some other value.

2.5.3.1

Numeric Contants

A numeric constant is either of the following:
®*

One or more decimal digits with an optional decimal point.

A decimal quantity followed by £ and the power of 10 by which the

quantity is to be multiplied (no embedded spaces are allowed).

For example, all the following constants are valid representations of the same
value:
712

712.0

7120F 1

07.12E2

Whenever possible, APL prints numbers without decimal points and exponents:

O0«A<712 712.0 7120E1 07.12E2
712

712

To represent a negative number in APL, you enter a numeric constant preceded
by a negative sign (~ ). Embedded spaces are not permitted. Note that the
negative sign, or high minus sign, is not the same character as the minus sign

(- ), which i1s used to indicate the subtraction function.
APL signals an error if a constant is not well-formed:
1F,

SYNTAX ERROR

(ILL FORMED NUMERIC CONSTANT)

1F.
A

1E99
27 LIMIT ERROR
1E99
A

1B1
11

1B1
A

2-18

AEVALUATED AS

1 B1

aEVALUATED AS

1 B1

VALUE ERROR

VAX APL Users Guide

VAX APL Language Concepts
2.5 APL Expressions
2.5.3.2

Character Constants

A character constant is one or more characters from the atomic vector JAV
(including spaces, carriage returns, line feeds, control characters, and so on)
enclosed in quotation marks. For example:
"ABCDEFG'

"((pVv)=vav)/V!
'THIS IS A CONSTANT.'
112345!

When APL prints a character constant, it omits the enclosing quotation marks.
If you want APL to output a quotation mark, enter one extra quotation mark
next to the one you want printed. Do not precede the extra quotation mark
with a space. If you do, you create two separate items instead of a single item.
For example:
B«'TONY''S TENNIS RACQUET'
ACHARACTER

RCREATE SIMPLE
VECTOR

TONY'S TENNIS RACQUET

C<«'TONY'

'S TENNIS RACQUET'
ACHARACTER

ACREATE 2-1ITEM
VECTOR

Because carriage returns and line feeds may be items of a character constant,
you can have a vector composed of several lines. In the following example, B 1s
a vector:
B«'THIS IS A
MULTIPLE LINE
LITERAL.'
B

THIS IS A

MULTIPLE LINE
LITERAL.
pB
i

If it is included inside a character constant, an illegal overstruck character
does not generate an error. It is recognized as three characters within the
character constant. Note that a valid overstruck character within a character
constant is recognized as one character.

VAX APL Users Guide

2-19

VAX APL Language Concepts
2.5 APL Expressions

Note

If you enter a character constant with an unbalanced number of
quotation marks, APL interprets that you are still defining the constant

when you press the Return key to enter the line. Consequently, APL
includes a <CR><LIF> as part of the constant. You can spot this error

by noticing that APL does a not indent six spaces after you press the
Return key. APL continues to treat everything you enter as part of

the constant until you enter a closing quotation mark, enter a weak
attention signal (see Section 1.9), or enter more than the maximum

number of characters allowed in a line (see Section 2.5.9).

2.5.4

Vector Notation
Vector notation (also known as strand notation) is a method of combining a
list of arrays into a single vector. When you specify a list of arrays separated

by spaces, APL joins them together. If the value of each array in the list is a
simple scalar, the arrays are combined into a simple vector. If the values are

not all simple scalars, the result is an enclosed vector. For example:

123

[«SHO«1 2 3

A3 SCALARS BECOME SIMPLE VECTOR OF 3 ITEMS

B<43
C<24

D65
43

O«SHO«B C D
65

B<43

aRESULT IS 3-ITEM SIMPLE VECTOR

C<24

C<65

U«SHO«B C D

aRESULT IS 3-ITEM ENCLOSED VECTOR

You can use parentheses in a strand to create more deeply nested vectors. In
the following example, SHO is a 3-item vector whose third item is a 2-item
vector, and this 2-item vector is composed of a 3-item vector and a scalar. The
overall depth is 3.
O«SHO«1

2-20

VAX APL Users Guide

((3

VAX APL Language Concepts
2.5 APL Expressions

2.5.5

Functions
APL performs operations by evaluating functions that are applied to arrays.
There are several kinds of functions in APL:

Primitive functions are functions provided by APL that implement the
basic operations of the APL language. The names of primitive functions
are symbols from the APL character set (see the VAX APL Reference
Manual).

System functions are functions provided by APL that affect the APL
environment. The names of system functions are valid APL identifiers that
start with the 0 symbol (see the VAX APL Reference Manual).
User-defined functions are programs defined by the APL user to implement
algorithms. The names of user-defined functions conform to the rules for
the formation of identifiers. User-defined functions may be APL code or
external routines (see Chapter 3 and Chapter 6.)

Derived functions are functions created by APL operators (see the VAX APL
Reference Manual).

In addition, functions are divided into four groups called niladic, monadic,
dyadic, and ambivalent functions, which take 0, 1, 2, or either 1 or 2
arguments, respectively.

2.5.6 Operators
APL can also apply operators to functions and arrays to produce derived
functions, which may then be applied to arrays.
There are two kinds of operators:

Primitive operators include slash (/), backslash (\ ), each ("), and dot (.).
For more information, see the VAX APL Reference Manual.
User-defined operators are operators defined by the APL user to implement
algorithms. The names of user-defined operators conform to the rules for
the formation of identifiers. User-defined operators are formed with APL
expressions. For more information, see Chapter 3.

In addition, operators are divided into two groups called monadic and dyadic
operators, which take 1 and 2 operands, respectively.

VAX APL Users Guide

2-21

VAX APL Language Concepts
2.5 APL Expressions

2.5.7 Spaces and Tabs
Spaces and tabs generally are not significant in APL. They have meaning when
you use them to separate identifiers and constants from each other, but they

do not have meaning when you use them to separate primitive functions from
their arguments or from each other. For example, note the following groups of

equivalent expressions:
B«

B«

C«16
C«

A«B+1-C

B+

-C

X<§B
X<y B
A+14p+4B
A«

D«11

D«1

You cannot set tab stops in APL. APL passes tabs to the operating system for
interpretation.

In this manual, any combination of spaces and tabs is referred to as white
space.

2.5.8

Evaluating Expressions
APL evaluates unparenthesized expressions in strict right-to-left order,
regardless of the particular functions in the expression. 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 from right to left, and the result is 27, rather
than 17:
3x14+5

You can control the order in which individual functions are evaluated by
enclosing parts of an expression in parentheses. To cause the expression in the
preceding example to evaluate to 17, you would enter the following:
(3x4)+5
17

2—-22

VAX APL Users Guide

VAX APL Language Concepts
2.5 APL Expressions
Note, however, that parentheses do not take absolute precedence; APL
evaluates the line from right to left for as long as possible. For example:
A<1

(A<2)+A
3

A
2

The right-to-left evaluation rule does not explain how APL evaluates

expressions in all situations. There is also the concept of binding strength,
which refers to how APL groups objects for evaluation. The relative binding
strengths for various objects are listed below in descending order:
Object

Binding Strength

Brackets

To what is on the left

Left assignment

To the identifier on the left

Right operand

To dyadic operator

Strand

Array to array

Left operand

To the operator

Left argument

To the function

Right argument

To the function

Right assignment

To the value on the right

Left assignment and right assignment both refer to the left and right
arguments of the assignment function (<« ).

Note that the binding strength of parentheses depends on the evaluation of
their contents. Also note that brackets and monadic operators do not bind to
the right.

As a result of the binding hierarchy, operators have a long left scope, and
functions have a long right scope.

Brackets are at the top of the list, and they bind most strongly to the object to
the left than to anything else. Thus, APL evaluates brackets and the object to
their left first. For example, APL evaluates A+B[I] as A+(B[I]) and not as
.
(A+B)[1]

A strand is a list of arrays separated by spaces. APL binds the arrays more
strongly to themselves than it binds a function to its arguments or an operator
to its left operand. For example, in the expression 4 B F 3 where F is a
function, APL binds the 4 and B together and uses the result as the left
argument to F.

VAX APL Users Guide

2-23

VAX APL Language Concepts
2.5 APL Expressions
However, note that arrays do not bind more strongly to themselves than do

dyadic operators to their right operands. For example, note the following
expression:
LOPERAND DYADICOPERATOR G H K

APL does not bind the strand ¢ # X together, because the binding of the right
operand to its operator ranks higher in the binding hierarchy. APL evaluates

the preceding expression as follows:
(LOPERAND DYADICOPERATOR G)

H K

Note that the expression 1 2 3[2]

results in an error. This is because the

binding strength of brackets and the object to their left is greater than that of

strands, and APL evaluates the expression as 1 2 (3[2])not as (1 2 3)[2].

2.5.9 Statements
Statements consist of one or more expressions executed as a unit. You can
include more than one statement on a line if you separate the statements with
the diamond character (¢). For example:
A«bld

B«92

A:B

0.6956521739

Statements separated by diamonds are executed from left to right. (However,
the expressions that make up the statements between the diamonds are still

evaluated from right to left.) For example:
«A<b6U4

[J«B«92

¢ A=+B

X!
92
0.6956521739

If APL encounters an error in a multistatement line, statements to the right
of the statement in error are not executed. For example, the identifier B is

undefined in the following multistatement line:

2-24

VAX APL Users Guide

VAX APL Language Concepts
2.5 APL Expressions
YCLEAR
CLEAR WS
A«<1

(<3

VALUE FERROR
A<1

¢ B ¢

(<3

A
C

VALUE ERROR
¢
A

Do not confuse the purpose of the semicolon with that of the diamond
character: the semicolon is an output catenator, not a statement separator. For
details, see Section 5.2.

2.5.10

Lines
An APL line consists of the statement or statements that you enter beginning

at column 6 and ending when you press the Return key (unless you are inside
a character constant). APL does not begin to evaluate the expressions in a line
until you complete the line by pressing the Return key.
The maximum length of a line in APL is 2048 keystrokes. APL automatically
echoes a long single line as several lines on your terminal. So, when you reach
the end of a line on your terminal, you should continue typing; you do not have
to enter a special character to indicate that the line is being continued.
If you enter more than 2048 characters, APL signals

2.5.11

INPUT LINE TOO LONG .

Comments
Comments begin with the » character, and you may position them at the end
of lines containing APL expressions or you may write them on separate lines.
APL ignores everything to the right of the a character.

2.6 Forming Arrays
To form a scalar array or a vector array containing two or more items, you
simply enter the data. To form matrix arrays or vector arrays containing one
item (a vector singleton), you must use a function such as dyadic reshape,
which was introduced in Section 2.2.2.1. When you enter a single number or

character, you create a scalar. When you enter more than a single number or
character, you create a vector.

VAX APL Users Guide

2-25

VAX APL Language Concepts
2.6 Forming Arrays
The following expressions create and display simple arrays. Note that numbers
are separated with spaces, pairs of parentheses, or characters. Characters can

be grouped together or can be separated, but they are always delimited with
single quotation marks. Note that adjacent quotation marks are evaluated as
part of a character string and not as delimiters; when you want delimiters,

separate the marks with a space.
ACREATE A
505

SCALAR AND

(5)(3)(7)

VECTORS

"A'5'B'3'C'7

5
5

3C7
ACREATE A
IAI

)

IABCI

)

SCALAR AND

IAI

lB!

VECTORS

ICI

A
ABC

ABC
ASHOW QUOTATION MARKS AS NON-DELIMITERS
a
IAI

ONLY THE OUTERMOST MARKS ARE DELIMITERS

lBllC‘KIDl

A'B'C'D

To create enclosed arrays, use parentheses and single quotation marks to group

and separate items. For numeric data, use parentheses. For example:
AENCLOSED ARRAY OF LENGTH

O«ENC« 5
5

+--—+

241

t---+

241

(45

84)

4-—----—---- +

|3 +--——- + 2|
|

|u5

84|

|t
o+

=ENC

ADEPTH =

TWO LEVELS OF NESTING

APARENTHESES GROUP,

O0«G<(1

DO NOT SEPARATE

AG IS NOT ENCLOSED

123

aTHIRD FLEMENT GROUPED SEPARATELY

O«E«'4"

'B'"

'CD'"

@ENCLOSED

VECTOR,

LENGTH

AB +--+

|CD
+-=+

aIN F,
a

O«F<512
512

+------- +

'DOUBLED'
1024

| DOUBLED|
t-——---- +

2—-26

VAX APL Users Guide

1024

THE

CHARACTERS FORM

SEPARATE GROUP

aF IS ALSO LENGTH 3

VAX APL Language Concepts
2.6 Forming Arrays

To enclose a value that cannot be grouped and separated, such as a simple
vector, you would use the monadic enclose (< ) function (for more details,
see the VAX APL Reference Manual). Enclosing a scalar has no effect, but
enclosing a singleton does. For example:
<R« c21b

AATTEMPT TO ENCLOSE SCALAR

ADEPTH = 0 SIMPLE SCALAR

0«@< c,21u4

aENCLOSE RAVEL

=¢

aDEPTH = 2 ENCLOSED

(«R« c'ABCD'

aENCLOSE A SIMPLE VECTOR

AQUERY FOR DEPTH

214
0

(,)

OF SCALAR

+--—+

| 214|
+--—1

2
+---—+

| ABCD|
+----+t

2.7 Editing Variables
Frequently arrays are assigned to variables. After the array is created and
assigned to a variable, that array can be included in commands by entering the
variable name. For example:
J<«A<«4 9 p
239

3 12 9 43 2 84 23 3 23

239

342

239

323

254

342

84
239

23
12

323

1 4 2 b4 342

Axy

172

336

4 16

216

1368

956

172

336

216

1368

956

[J«C<«6

p A+3

956

128

242

3u5

242

Uue

345

242

Variables can be edited if you are using the DECwindows or Character-Cell
interface. You can also use the )EDIT system command to edit variables. You
cannot edit system variables.

VAX APL Users Guide

2-27

VAX APL Language Concepts
2.7 Editing Variables
Depending on the specific attributes of any given variable, the shape
information may change when the variable enters the editor and again

when it is reestablished in the APL environment.
If an object has a rank greater than two, it is displayed in the VAXTPU session
as a matrix of the following shape:

(x/~ 1+ pobject),(” 1+p object)
When you exit from VAXTPU, the object remains rank two; it does not return
to its original shape. When you quit from VAXTPU, the object returns to APL

with its original shape intact.
If an object has a rank of two or less, its rank remains intact both in the
VAXTPU session and when it returns to APL. The exception to this rule is the

scalar object, which returns to APL as a vector.

If you edit a new or empty variable, APL generates an empty temporary file
for VAXTPU. If the VAXTPU file is empty (contains 0 records) when it returns

from VAXTPU, it arrives in APL as an empty vector (if it did not previously
exist in APL), or as an empty object (if it did previously exist in APL). In this

case, the rank of the returned object is the same as the original unless the
orginal was greater than two, in which case the object’s shape is 0 0.

2.7.1

Editing Character Variables
When a character variable is a vector containing embedded <CR><LF>s, it is
written out to VAXTPU as two records:
Vector Data 1n APL

Data in VAXTPU

"aa<CR><LF>aa’

"aa

aa<CR><LF>aa

aa’
aa

When a vector returns to APL, it enters as the ravel of the catenation of all
the records in the VAXTPU file. APL embeds a <CR><LF> at the end of each
record. If any single record contains a <CR><LF>, you must use the system

command editor, ) EDIT and specify /MODE: 3 for it to remain intact; in mode 2

and with the DECwindows and Character-Cell interface editors, the <LF> will
not return. (/MODE: 3 is the only method that allows you to return embedded

<CR><LF>s from VAXTPU to APL.) If any records are empty, APL marks them
with <CR><LF>s. If the last record in the vector is empty, it is marked by a

<CR><LF>; if it is not empty, it is not followed by a <CR><LF>.

2-28

VAX APL Users Guide

VAX APL Language Concepts
2.7 Editing Variables
Vector Data
in VAXTPU
"aa

Data in APL
Mode 3
Mode 2
"aa<CR><LF>aa’
"aa<CR><LF>aa’

aa’

aa<CR><LF>aa

"aa<CR><LF>aa’

"aa<CR>aa’

aa<CR><LF>aa

aa<CR>aa

When a row of a character variable matrix contains embedded <CR><LF>s

inside quotation marks, it is written to VAXTPU as a single record (and the
shape of the matrix is preserved).
Matrix Data in APL

Data 1n VAXTPU

"aa<CR><LF>aa’

"aa<CR><LF>aa'’

"aa<CR><LF>aa’

"aa<CR><LF>aa'

When a matrix returns to APL, it has one row for each record. All of the rows
will have the same number of columns as the longest record (shorter records
are extended with blanks). Any empty records return as rows filled with
blanks. If any single record contains a <CR><LF>, and you specify /MODE: 3,
APL treats the <CR><LF> as the end of a row and forms a new record; if you
specify /MODE: 2, the <LLF> will not return.
Matrix Data
in VAXTPU

Data 1n APL
Mode 3
Mode 2

"aa

aa’

"aa<CR><LF>aa’

"aa

"aa<CR>aa’

"aa<CR><LF>aa'’

aa’

"aa<CR>aa’
"aa

aa’

aa<CR><LF>aa

aa<CR>aa

aa<CR>«<LF>aa

aa<CR>aa
aa

Note that in the preceding examples, the <CR><LF> symbol does not appear
visually in the APL environment, although it does cause data to be displayed
on a new line.

VAX APL Users Guide

2-29

VAX APL Language Concepts
2.7 Editing Variables

2.7.2

Editing Numeric Variables
When you edit a numeric variable that is initially of rank two or greater,
VAXTPU returns a numeric matrix of the following shape:
(pmatrix)

(no.

records in file), (no.

numeric values in first record)

When a numeric matrix returns to APL, all records in the matrix must be
numeric, and all must have the same number of items as there are in the first

record. Empty records are not allowed unless the entire matrix is empty.

If you edit a numeric variable that is initially a vector, VAXTPU returns a
vector that is the ravel of all the records in the VAXTPU file. The returning
array may not contain any nonnumeric data. Empty records are ignored.

2.7.3

Editing Variables with the DECwindows Interface Editor
The DECwindows interface provides full DECwindows support of the APL
product. In addition to the interactive area in the initial APL DECwindow, you
can open one or more sessions to edit user-defined operations and variables.

(See Section 3.11.2 for more information on editing user-defined operations.)
Defining a new variable is similar to editing an existing variable. One
difference is that you have to specify information about the variable if you are

defining a new variable. Follow these steps to start an edit session.
1.

Click on the Commands option located on the Menu Bar in the transcript
sesssion to expose the Commands menu. (See Figure 2—1.)

Figure 2-1

DECwindows Interface Edit Options

Enmmands I Fonts
Edit New

| Variable

_ Interupt

Function

Euntinue {Exit)

Operator

—

| off (Quit

2-30

VAX APL Users Guide

VAX APL Language Concepts

2.7 Editing Variables
2.

Select the Edit Existing or Edit New option. If you select the Edit New
option, another menu will display a choice of object types. Select the
Variable option.

Select the appropriate options to describe the variable you want to edit
from the Edit New Variable dialog box. Figure 2-2 displays this box.
Click on either the Numeric or Character option depending on the type of
variable you are editing. Select the rank by clicking on the appropriate
rank option. Finally, click in the input area at the bottom of the dialog box

and enter the name of the variable.
Figure 2-2

Commands

DECwindows Interface Edit New Variable Dialog Box

Fonts

==———PL Edit New Variahle=——1
4 Numeric

<> Rank 0

{> Character

& Rank 1
<> Rank 2

The Title Bar in the edit session is the name of the variable. If you are
editing an existing variable, the array will be displayed.

You can enter text to edit the variable or you can use the mouse to copy

text from one edit session to another edit session. The mouse can be used
to copy text from the transcript window, to an edit window. You cannot
copy text into the transcript window.
5.

When you have finished editing the variable, select one of the edit session
options that are displayed when you click on the Commands option in the

menu bar of the edit session. Figure 2-3 shows these options.

DECLIT
VAX

APL

VAX

user’s

P142E
guide

VAX APL Users Guide

2-31

VAX APL Language Concepts
2.7 Editing Variables
Figure 2-3

DECwindows Interface Edit Session Commands Options

% Eommands I

[ Exit
_l!pdate Workspace
g_uit

You can update the transcript session with the new array by chosing the

Update Workspace option. When you return to the transcript session, you
can enter commands to call the variable. You do not have to close the edit

session to return to the transcript session.
If you select the Exit option from the edit session Commands menu, the
transcript session is updated with any changes to the variable, and the edit
session is closed. The Quit option closes the edit session without saving
changes.

2.7.4 The Character-Cell Interface Editor
The Character-Cell interface provides a VAXTPU based window environment
for APL sessions on the Digital V1220, V1240, VT320, VT330, VT340 and

DECterm terminals. This environment inserts the text of the operation you

are editing into a temporary holding area, a buffer. You can display more than
one buffer on the screen at one time and edit more than one variable during an
APL session. (See Section 1.3.3.)
To edit a character variable, press the Do or PF4 key or enter Ctrl/B to display
the Command: prompt. Enter the following command, substituting the name
of the variable being edited for variable.
GET variable< [

To edit a numeric variable, enter the following command at the Command:
prompt, substituting the name of the variable for variable.
GET variable<« []

The variable is displayed in the window of the new buffer. The end-of-file
marker defines the end of the buffer. It is only visible on the screen and is not

saved as part of the variable, The status line shows the name of the buffer.
You can edit the variable by using one of the following methods:
e

2-32

Entering the APL characters from the keyboard

VAX APL Users Guide

VAX APL Language Concepts
2.7 Editing Variables
e

Inserting text copied from the APL SESSION Buffer or another edit buffer

Including entire files

The VAXTPU Help utility has specific information about copying text. Enter
HELP at the Command: prompt and look at copy, cut, paste and restore.
Enter HELP INCLUDE FILE at the Command: prompt to get more information
about including files. (Press the Do or PF4 key or enter Ctrl/B to reveal the
Command: prompt.)

To update the interactive apl session with the variable, use the command
WRITE in the following form in response to the VAXTPU Command: prompt:
WRITE [[variable]

The name of the variable is optional. If you do not specify the name of the
variable, the name associated with that buffer is used.

Figure 2—4 displays a session using two windows, the APL. SESSION and an
edit session.

Figure 2-4

Character-Cell Interface Variable Edit Example

DECterm 1

Commands

Edit

Customize

Help
<3

651.24

2.4

5.6

1.2

5.6

0.9

[End

Biuuffer:

2.4

FRead-only

Insert

Forward

Insert

Forward

file]

Whrite

To return to the interactive session, enter BUFFER APL SESSION at the

Command: prompt. (See Section 1.3.3.) Alternatively, if you are using a
split screen with the interactive session in one window and an edit session in

VAX APL Users Guide

2-33

VAX APL Language Concepts
2.7 Editing Variables
another, you can return to the interactive session by entering OTHER at the

Command: prompt or, if you are using a mouse, by clicking on the window.

2.7.5 The )FEDIT System Commmand Editor
The )EDIT system command allows you to edit APL objects with the VAXTPU
editor. The default object type is a function. To edit a variable, you must
specify a value 2 for the name class qualifier (/NC: 2).

Use the form following form to edit an APL object:
JEDIT operation{[qualifiers]]

operation
Is the name of the APL operation you want to edit.

qualifier
Is one or more of the optional qualifiers. See the VAX APL Reference Manual
for more documentation on the )EDIT system command.
Depending on the value you specify for /NG when you invoke )EDIT , negative
numbers appear in VAXTPU preceded by a high minus sign (TM ), a minus sign

(- ), or an ASCII minus sign (—), which appears as an APL plus sign (+ ). If
you do not specify the /NG qualifier, APL uses the current setting for ONG as
the default.
The display of numbers passed from APL to VAXTPU is dependent on OPP.
Therefore, you could lose precision when editing numbers. You can use the

/ PP qualifier when you invoke )EDIT to specify a different value for the print
precision.
Depending on the [PW setting in effect when you invoke )EDIT , some numbers

may be segmented such that the digits span more than one record. If these
numbers are not repaired in the VAXTPU file before returning to APL, then

each segmented number will return as two separate values.

2.8 Indexing Arrays
To access an individual item stored in an array, you must know its position, or
index value, within the array. The number of index values, or indexes, needed

for an array depends on the array’s rank. In general, the number of indexes
must match the number of axes of the array; thus, a vector requires one index,
a matrix requires two indexes, an array with three axes requires three indexes,

and so forth. Scalars may not be indexed.

2-34

VAX APL Users Guide

VAX APL Language Concepts
2.8 Indexing Arrays
To index an array, specify the array name, followed by the indexes enclosed
in square brackets and separated with semicolons. Note that the number of
semicolons in an index specification is equal to one less than the rank of the
array being indexed. Each index must be a simple near-integer array (which

may be empty), or an expression that evaluates to a simple near-integer array.
Examples:
V<5

Vi3]

aV IS A

a1l AXIS MEFANS

INDEX

VECTOR

VALUE,

NO SEMICOLON

M<2

3p5

MU2:2]

aM IS5 A MATRIX

a2 AXES MEANS

2 INDEX VALUES,

1 SEMICOLON

In some cases, you must use parentheses when you want to group a vector of

values. Note the difference in the following expressions.
(7
6

5432

1)[2

APARENTHESES REQUIRED

765432

1[2

36 INDEX RANK ERROR
765432

1[2

AINDEX BINDS TO

ITEM ON THE LEFT

(CANNOT INDEX A SCALAR)
4]

RINDEX BINDS TO ITEM ON THE LEFT

In the previous example, the first expression contains a vector that is grouped

in parentheses. The index expression binds to the entire group and selects the
second and fourth items. There is no grouping in the second expression. It is

1llegal because the index binds only to the scalar value 1.

2.8.1

Index Origin
The first position along each axis of the values stored in an array is called the
index origin; it may be 1 or 0. If the index origin is 1, the indexes of arrays

begin with position 1; thus, members of a 3-item vector named 4 would be
numbered A[1], A[2], A[3]. Similarly, if the index origin 1s 0, items would be
numbered A[0], A[1], A[2].

The index origin setting applies to all arrays in a workspace. The default index

origin in a clear workspace is 1, but you can change it by setting the 010
system variable. See the VAX APL Reference Manual for details.
For all examples in this manual, it is assumed that the index origin is 1, except
where an example explicitly states that it is O.

VAX APL Users Guide

2-35

VAX APL Language Concepts

2.8 Indexing Arrays

2.8.2

Selecting One Array Item
To select a single item from an array, specify the array name and the indexes
that refer to the item’s position in the array. (This may also be done with the
pick (> ) function; see the VAX APL Reference Manual for more information.)
For example, to access the first item stored in vector 4, specify the name of the

vector followed by the index 1:
Al1]

If 4 is the following vector, then A[3] is 25, as shown:
O«4«72
72

91 25 46 87

aCREATE AND DISPLAY A

AL3]
25

If the array is a matrix, you must specify two indexes. The first index
designates the row, and the second index designates the column. Use

semicolons (;) to separate the indexes as follows:
(0«B+2
12

U4p18

aCREATE AND DISPLAY B

B[2;3]

ASELECT ITEM IN ROW 2,

COLUMN 3

When you select an enclosed item from an array, the item remains enclosed.
You can disclose the item by using the first or disclose function with your
index expression. First (4 ) selects the first item of an array and discloses it.

Disclose (> ) removes one level of nesting from an array each time it is used.
For example:

2—36

VAX APL Users Guide

VAX APL Language Concepts
2.8 Indexing Arrays
O«T«2

3p1 2

4 5

ACREATE A NESTED ARRAY

123
4

+----- +

t----- +

O«Z« (c'TABLE'),(cT),"
t----- S

| TABLE|

|1 2 3

t---=- +

|45 +----- + |

|
|

LIST
LI S5T

',22

25 753

nZ CONTAINS T

2225753

|62 3]
to---- +]

fommm e +

aQUERY FOR THE DEPTH OF 2

Z[2]
fomm e +

|1 2 3
|
|4 5 +----- +|

|
|

|6 2 3]
t----- + |

e it +

+Z[02]

aUSE FIRST TO DISCLOSE ONE LEVEL

123

+----- +

|6
2 3]
————— +

+(+Z202])[2;3]

aUSE FIRST TO DISCLOSE TWO LEVELS

557[2]

aUSE

TWICE

TO DISCLOSE BOTH LEVELS

100
2

00
0

For more information on the first and disclose functions, see the VAX APL
Reference Manual.

2.8.3 Selecting More Than One Array ltem
By specifying the indexes in the form of an array, you can access more than
one array item at a time. Again, use semicolons (;) to separate the indexes.

VAX APL Users Guide

2-37

VAX APL Language Concepts
2.8 Indexing Arrays
[«V<«32
32

44,6

V(3

44,6

0.8

97.2

aINDEX 3

TIMES FROM V

97.2

[«M<2

U4p18

4
8

M[2:1]

aINDEX 1 ITEM FROM M

M[1
2

2:;2

aINDEX 2 ITEMS FROM M

Indexing is not affected by the type of the array—simple or enclosed, character,

numeric, and heterogeneous arrays are all indexed in the same way. Also, note
that you can duplicate an item by specifying its position more than once. For

example:
A«'"ABCDEFGHIJKLMNOPQRSTUVWXYZ
AELEMENT

BABY«A[10

IS BLANK

14 9

BABY

JENNIFER LYNNE

2.8.4 Selecting All ltems Along an Array Axis
To select all items along an array axis, you omit the index for that axis in the

index specification. You must include a semicolon to indicate which index has
been omitted. For example:
<A<t
1

3p112

Al1;]

ACREATE AND DISPLAY A

AOMIT SECOND AXIS,

SELECT ROW 1,

ALL COLUMNS

123

Al;2
2

@OMIT FIRST AXIS,

SELECT COLUMNS 2 AND

Note that it is legal to omit all the indexes (but not the semicolons) from an
index specification; the value returned is the array itself. For example:

2-38

VAX APL Users Guide

VAX APL Language Concepts
2.8 Indexing Arrays
(4«15

nCREATE AND DISPLAY 4

123145

Al]
1.2

[«B<«2

Lp:18

ACREATE AND DISPLAY B

1234
567

BL;]

ROMIT ALL INDEXES

1234
56

2.8.5 Indexing Constants and Expressions
The array being indexed need not be a variable. It can be a constant set of
values or an expression enclosed in parentheses.
(7

1)[2

APARENTHESES REQUIRED
APONER FUNCTION EXTENDS TO

16*2)[1

FACH ITEM OF 2

When a set of values is not enclosed in parentheses, the index binds only the
rightmost value, and APL signals an error because it cannot index a scalar.
For example:
RINDEX BINDS TO ITEM ON THE LEFT
7654

1[2

36 INDEX RANK ERROR

(CANNOT INDEX A SCALAR)

765432
1[2 4]
A

2.8.6 Using an Expression to Generate Indexes
The index can be an expression which is evaluated to generate the item
positions. For example:
K«2

4 5

V«10

VIK+1]
31

In this example, Vv and ¥ are both vectors. The expression V[XK+1] accesses
the items of vV referenced by k+1, that is, the third, fifth, and sixth members of
vector V.

VAX APL Users Guide

2-39

VAX APL Language Concepts
2.8 Indexing Arrays

2.8.7 Shape of an Indexing Result
When a variable is indexed, the shape of the result is equal to the catenation
of the shapes of all the indexes. If the variable is indexed using the following

form:
Z+21Kd_;K2;}(3;

.«

. e

,KTfl

then

(pZ)=(pK1),(pK2),(pK3),

. . .

,(pKn).

For example:
V«'ABCDEF'!
nA
V(e

M«<2

3p2

VECTOR INDEXED WITH A
3

VECTOR IS A

VECTOR

FEDCBA

VECTOR INDEXED WITH A MATRIX IS A MATRIX
5

VIM]
BED
FED

nA MATRIX INDEXED WITH TWO 2-DIMENSIONAL
A

M<2

2p1

INDEXES RESULTS IN A

M
12
1

A<M[M;M]
A
12

2-40

VAX APL Users Guide

4-DIMENSIONAL ARRAY

VAX APL Language Concepts
2.8 Indexing Arrays

pA
2

M<«2

Up1b

M
M

ASCALAR RESULT

A<M[11]
A
pA

(APL outputs a blank line)
AEMPTY ARRAY

pM[10;]
a1-ITEM

VECTORS

B«M[1:1]
B2«M[,1;1]
B
B2
pB

(APL outputs a blank line)
pB?2
a2-ITEM

VECTOR

CeM[;2]
C
pC

2-BY-1 MATRIX

DeM[;,2]
D

VAX APL Users Guide

2-41

VAX APL Language Concepts
2.8 Indexing Arrays

2.8.8 Replacing Selected Items in Arrays
You can combine indexing with the specification function (see Section 1.5) to
change the values of items already stored in an array. For example:

(«A+2

3p16

A[1:2

3]<7

aCREATE AND DISPLAY A

aREPLACE AT COLUMNS 2 AND 3

OF ROW 1

A
179

AT2;1

219

aSINGLETON EXTENSION OF 9

4
179
6

AT1;1]+12

aREPLACE AT COLUMN 1 OF ROW 1

A
12

A[1:1

1]<2

oINDEX ASSIGNMENT WORKS LEFT TO RIGHT

A
379
9

2.9 Error Handling
Once APL evaluates a primitive function, it does one of two things: determines

a result, or signals an error. When APL signals an error, it prints a 3-line error
message that includes:
*

A description of the error.

The text of the line in which the error occurred.

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

For example, if you try to display the variable B, and B has not been assigned
a value, APL displays the following:

11 VALUE ERROR
B
A

The description of the error consists of an error number, a primary error

message (such as VALUE ERROR ), and, if applicable, a parenthesized secondary
error message that provides more information about what caused the error.

(You can prevent the display of secondary error messages by setting the

2-42

VAX APL Users Guide

VAX APL Language Concepts

2.9 Error Handling
system variable [JTERSE to 1; see the VAX APL Reference Manual for more

information.)
If the operating system detects an error, its message—if it provides any useful
information—is displayed as a secondary error message.
The display of error messages is dependent on JPW. (See the VAX APL

Reference Manual.)
*

If the description of the error is longer than O0Pw characters, it is truncated;
it is not continued on the next line.

If the text of the line in which the error occurred is longer than QrPw
characters, the text is truncated, except when the truncated part includes

the particular point in the line at which the error was discovered. In that
case, APL truncates enough characters from the beginning of the line to

allow the location of the error to be displayed.
The entire message generated by the last error that occurred is always stored
as the value of the system variable JERROR even if part of the message was

truncated when it was displayed.

For a complete list and description of APL error messages, see the VAX APL
Reference Manual.

2.9.1

Order of Error Checks
When APL evaluates expressions, it usually checks for errors in the same
order regardless of whether the evaluation involves a primitive function, a
system function, a primitive operator, or an assignment to a system variable.
In general, this order is as follows:
SYNTAX
VALUE.

AXIS RANK
AXIS LENGTH

AXIS DOMAIN
INDEX RANK
INDEX LENGTH
INDEX DOMAIN

RANK
LENGTH
DOMAIN

LIMIT

If an expression contains more than one error, APL reports only the error that

is discovered first.

VAX APL Users Guide

2-43

VAX APL Language Concepts
2.9 Error Handling

2.9.2 Errors in User-Defined Functions and Operators
When an error occurs during execution of a user-defined function or userdefined operator, APL suspends operation execution (unless the function or
operator is locked; see Section 3.6 for details) and prints the appropriate 3-line
error message. Line 2 of the message includes, in addition to the text of the
line in which the error occurred, the name of the function or operator and the
line number (and statement number, if applicable) of the line displayed.
APL allows you to write your own routines to handle errors that occur during

execution of user-defined functions and operators. For details, see Chapter 3.

2-44

VAX APL Users Guide

3
User-Defined VAX APL Operations
User-defined functions and user-defined operators in VAX APL are
equivalent to what are known as programs in other languages. In APL, these

programs are called functions and operators because you use them the same
way that you use APL’s primitive functions and primitive operators.

Together, the user-defined functions and operators are known as user-defined
operations. They allow you, in effect, to extend the APL language. You can
define your own operations and store them with workspaces. Then, you can
call on them as easily as you call on primitive operations.

3.1

Defining Operations
There are two operating modes in APL: immediate mode and function-

definition mode. In immediate mode, APL lines are executed immediately
after you enter them. In function-definition mode, the lines you enter are

considered to be part of the body of a function or operator. It is in functiondefinition mode that you develop, edit, and save user-defined functions and
operators.

User-defined operations consist of two parts: a header and a body. The
header provides a name for the operation and indicates its valence, how
many arguments or operands the operation takes. The body is a sequence of
statements that defines the actions to be performed by the operation when it is
executed.

Examples in the VAX APL manuals that include an operation definition
number each line and use the del character (v) to mark the beginning and
the ending of a definition. When you define an operation, you do not need
to enter line numbers. You enter the del character only if you are using the
function-definition mode of the line-editor. For example:

VAX APL Users Guide

3-1

User-Defined VAX APL Operations
3.1 Defining Operations
V 4

FOO B

[1]

1 (A+B)

[2]

v
3

FOO

123456738

3.2 Operation Header
The operation header provides a name for the operation, indicates how many
arguments or operands it takes (the valence) and whether it returns a result,
indicates whether the operation accepts an axis argument, and identifies any
local symbols.

3.2.1

Function Header Form
When the user-defined operation is a function, the type of the function, niladic,
monadic, dyadic or ambivalent depends on the number of arguments it takes.

The forms of the headers for the function types are as follows:
Type

Form

Niladic

[result-id < ] function-name [{{k1}1 [;loc-id; . .. ]

Monadic

[result-id <1 function-name [{[k]}] arg [;loc-id; . .. 1

Dyadic

[result-id < 1| arg2 function-name [{[k1}] argl [;loc-id; . . . ]

Ambivalent

[ result-id <1 larg2ifunction-name [{[E]}}] argll;loc-id; . . . 1

The arg, argl, and arg2 in the headers are dummy arguments. They serve as
placeholders for the actual arguments (values) you supply when you call the
function. The number of dummy arguments in the header indicates whether

the function is niladic (no arguments), monadic (one argument), dyadic (two
arguments), or ambivalent (either one or two arguments). Note that you

use braces ({}) around arg2 to distinguish between a dyadic and ambivalent
function.

The optional result identifier (result-id) in the header is also a dummy
argument; it is a placeholder for the value that is the result of the function.
The optional list of local symbol identifiers (loc-id) indicates identifiers that are
local to the function. (The list items are separated by semicolons.)

The optional axis argument ({[k]}) must be enclosed with braces and brackets.
For an example of axis in a user-defined operation, see Section 3.12.5.

3-2

VAX APL Users Guide

User-Defined VAX APL Operations
3.2 Operation Header
You can use any valid variable name to represent a dummy argument; in fact,

result-id and one of the args may have the same name. In this case, result-id
assumes an initial value when the function is called. However, you cannot use
the same name for both arguments of a dyadic or ambivalent function. Also,
function-name cannot be the same as result-id, k, either of the args, or the

name of any label inside the function. (It may be the same as a loc-id.)

3.2.2 Operator Header Form
User-defined operators differ from user-defined functions in the following ways:
e

An operator can be monadic or dyadic, but not niladic or ambivalent.

The result (not result-id) of an operator is a derived function.

The derived function can be monadic, dyadic, or ambivalent, but not
niladic.

The headers for user-defined functions and operators are very similar. The

forms of the headers for operators are as follows:
Type of Derived
Function

Form of Operator Header
Monadic Operators

Monadic

[result-id<1 (lop op-name [{[k]}]) arg [;loc-id; . .. ]

Dyadic

[result-id<1 arg2 (lop op-name [{[k}}1) argl [;loc-id; . . . 1

Ambivalent

[result-id<1 {arg2} (lop op-name [{[kI}]) argl [;loc-id; . . . ]
Dyadic Operators

Monadic

[result-id+<] (lop op-name [{[k1}]l rop) arg l;loc-id; . . . 1

Dyadic

[result-id<1| arg2 (lop op-name [{[K]}]) rop argl [loc-id; . .. ]

Ambivalent

[result-id<1 {arg2} (lop op-name [{[k1}] rop) argl [;loc-id; . . . ]

All user-defined operators have a left operand (lop). If you specify a right

operand (rop), the operator is dyadic. If you do not specify the right operand,
the operator is monadic. The parentheses are required around the name of the
operator (op-name), the operands, and the axis argument (if specified).
The resulting derived function always has a right argument (either arg or

argl). If you specify a left argument (arg2), the derived function is dyadic.
If you place braces ({}) around the left argument, the derived function is
ambivalent.

VAX APL Users Guide

3-3

User-Defined VAX APL Operations
3.2 Operation Header
Note that arg, argl, arg2, result-id, loc-id, and k in the headers serve the same
purposes for user-defined operators as they do for user-defined functions. (For
more information, see the previous section.) However, note that result-id is the

result of the derived function and not of the operator.

You can use any valid variable name to represent a dummy argument; in fact,
result-id and one of the args (or operands) may have the same name. In this
case, result-id assumes an initial value when the function is called. However,

you cannot use the same name for both arguments of a dyadic or ambivalent
function. Also, op-name cannot be the same as result-id, k, either of the args,
either of the operands, or the name of any label inside the function. (It may be

the same as a loc-id.)

3.2.3

Operation Result
If you include result-id in the operation header, the function (or derived
function) returns an explicit result that is temporarily stored in the result
identifier. Then, by including the operation’s name in an expression, you can

use the value of the function (or derived function) as an argument to other
operations. Note that the function (or derived function) returns an explicit

result only if you assign a value to result-id in the body of the operation.
(If you use an operation’s name in an expression when there is no result-id

specified in the header, or if you do not give a value to result-id in the body of
the function, APL signals VALUF ERROR when the function is executed.)
If you do not include result-id in the header, the function (or derived function)

cannot return an explicit result. An operation that does not return an explicit
result may print some data when you execute it, but you cannot directly use

that data (and thus, the operation) as an argument to another operation or in
any situation that requires a value.

3.2.4

Local Symbol List
Headers may also include names of local symbols used in a user-defined
operation. You place these symbols to the right of the rest of the operation
header, separating them from the rest of the header and from each other by

semicolons. For example, the following operation header indicates that X, LocC,

and G are local symbols:
NAME; X;LOC;G

Dummy arguments and operands are also considered to be local symbols, so the
names that appear in the local list must not be the same as dummy arguments

and operands in the same definition. The operation name itself, however, may
appear in the local list. For more details about local symbols, see Section 3.4.1.

3-4

VAX APL Users Guide

User-Defined VAX APL Operations
3.3 Operation Body

3.3 Operation Body
An operation can have up to 9,999 APL lines and a header. All valid APL

statements are valid within an operation, including calls to other operations.
You can include system commands, but they must be arguments to the execute

function (¢ ). If you are using the line-editor to define or edit an operation
APL executes system commands immediately, provided the right parenthesis

that begins the system command is the first nonblank character after the line
prompt or edit command. For example:
vV

(11
[2]

FOO

AQXQ')LOAD MYWS'
YJWIDTH

[2]

Here, the system command in line [1] is an argument to the JXQ execute

function; it will be executed when line [1] of the function is executed. Before

entering line [2], the user executed the system command )WIDTH . APL
returned the value 80, and then prompted for the next line of the function
definition.

If you enter a system command in the middle of an expression, APL signals
SYNTAX ERROR when you attempt to execute the operation. Notice what

happens if you try to execute a system command immediately, but the right

parenthesis that begins the command is not the first nonblank character after

the line prompt:
vV

[1]
(2]
[3]

FOO

BOXQ')LOAD MYWS'
B )WIDTH
alncorrect syntax

Whenever an operation line 1s entered with unbalanced parentheses or
brackets, APL signals SYNTAX ERROR. In this example, the user began to enter

line [2], and then decided to check the terminal width. APL accepted )WIDTH
as part of function line [2]. When F00 is executed, APL will reject line [2]
because of the incorrect syntax.

3.4 Symbolic Names in Operations
Each APL workspace contains an area, called the symbol table, that includes

the names and values of all the variables, functions, operators, and groups you
defined in the workspace. The symbol table is saved with a workspace; in a
clear workspace, it is empty.

VAX APL Users Guide

3-5

User-Defined VAX APL Operations
3.4 Symbolic Names in Operations
Symbols are classified as being either local or global, depending on how their
values are treated before, during, and after the execution of a user-defined
function or operator.

3.4.1

Local Symbols
Local symbols have significance only during the execution of a particular
operation. To specify a symbol as being local, include it at the end of the
operation header.

You establish local symbols when you call an operation; you cannot bring
values into the operation using localized symbols. There is one exception to

this rule: system variables retain their current value when the operation is
invoked. Any local values are lost when you exit from an operation. If the

operation changes the value of a system variable, the change is local only
and the system variable reverts to its original setting when the operation
terminates. If you use a local symbol before assigning it a value, APL signals
VALUF ERRORK.

Operation-line labels are treated as local variables. They are initialized when
you call the operation; however, you cannot assign values to them. Dummy
arguments and operands are also treated as local variables, and they get their

values when the operation is activated.

3.4.2 Global Symbols
Symbols that you use in the operation body, but that you do not include in

the local symbol list in the operation header, are considered to be global

symbols. They have the same value inside and outside of the operation; thus,
if execution of an operation changes the value of a global symbol, the value of
that symbol remains changed after execution of the operation completes.
Because naming conventions for functions, operators, and variables are

the same, you cannot duplicate names among your global functions, global
operators, and global variables. You can, however, have a local and global

symbol with the same name. In that case, certain rules apply for determining
which value takes precedence, global or local. See Section 3.4.4 for details.

3.4.3 Localizing Function and Operator Names
Although an operation header’s local symbol list is generally used to localize
variable names, you can localize function and operator names as well. Like
local variables, local functions and operators have significance only during the
execution of a particular operation.

VAX APL Users Guide

User-Defined VAX APL Operations
3.4 Symbolic Names in Operations
One use of local functions and operators is to execute operations that are

stored on an external device. This technique allows you to execute a particular
operation whenever necessary without having to keep it in the workspace
permanently. For instance, to execute a function LOC stored in canonical form
(see OCR in the VAX APL Reference Manual) in a file called EXTLOC.AIS, you
could code the following:
RFIRST DEFINE THE FUNCTION LOC AND
RnSTORE ITS

aIN A

CANONICAL

REPRESENTATION

FILE CALLED EXTLOC.AIS

LOC

(1]

'THIS IS THE FUNCTION LOC!

(21

CHAN<[JASS

'EXTLOC/IS'

(OCR'LOC')

CHAN

LocC

THIS IS THE FUNCTION LOC

[IDAS CHAN

JERASE LOC
aNOW DEFINE A FUNCTION THAT EXECUTES THE
aFUNCTION YOU STORED.
A

V EXLOC;LOC;CHAN;CRLOC

[1]

CHAN<[JASS

(2]

CRLOC< B CHAN

[3]

LOC<[JFX CRLOC

[u]

LOC

[5]
[61

ODAS CHAN

'EXTLOC/IS'

aEXECUTE LOCAL FUNCTION LOC

EXLOC

THIS IS THE FUNCTION LOC
LoC
11

VALUE ERROR
LOC
A

You can accomplish the same objective by including the operation’s own name
in its local symbol list. The header for the preceding example would be as
follows:
LOC

;LOC;CHAN;CRLOC

Then, the 5-line function Lo¢ that is permanently in your workspace
establishes and executes the local function ZocC , which is stored on disk
and could consist of many more than five lines.

VAX APL Users Guide

3-7

User-Defined VAX APL Operations
3.4 Symbolic Names in Operations
When an operation’s own name is localized, it does not necessarily have to be

used as the name of a local function or operator. For instance, the function 700
uses the symbolic name F00 as a local variable name:
vV

[1]
[2]

FOO

;F00

F0O+5
v

The global value of FOO is the name of the function; the local value of F00

within the function is 5 (or whatever other value you assign to it). Note that
if you localize an operation’s own name in this manner, you cannot call the
operation recursively.

3.4.4

Precedence of Local Symbols
During operation execution, the value of a local symbol shadows (supersedes)

the value of a global symbol with the same name. Also, depending on the
particular operation being executed, a local symbol can shadow another local

symbol with the same name.
In the following example, APL uses the value of a local variable 4 during

operation execution; then, when APL exits from the function, 4 retains its
global value:

[1]
[2]

A+0

aDEFINE GLOBAL A

VF:4

aDEFINE LOCAL A

[O<«A«1
v

aPRINT VALUE OF LOCAL 4

F
nLOCAL A SHADOWS GLOBAL A DURING
AOPERATION EXECUTION

A
AGLOBAL A

UNSHADOWED AFTER FUNCTION DEFINITION

If two user-defined operations have a local variable with the same name, APL

uses the value from the operation in which it is currently executing. For
example:

3-8

VFUNC1:B

AaDEFINFE LOCAL B

[1]
[2]
[3]
[4]

[«<B+«10
FUNC?2
[J«B
v

APRINT VALUEF OF LOCAL B
ACALL FUNC?2
APRINT VALUE OF B AGAIN

VEUNC2:B

anDEFINE LOCAL B

[1]
[2]

[J«B<25
¥

APRINT VALUE OF B

VAX APL Users Guide

User-Defined VAX APL Operations
3.4 Symbolic Names in Operations
FUNC1

AEXECUTE FUNC1

10
25
10

B
VALUE ERROR
B
A

Here, the local variable B has a value of 10 in FUNC1 and a value of 25 in
FUNC2. While executing FUNC1 , APL uses 10; while executing FUNC2 , APL
uses 25. When APL returns to FUNC1 , B reassumes the value 10. Finally,
when APL exits from FUNC1 , B has no value.
Local values act like global values within nested operations. For example:
VFUNC1:4
p<10
g

[1]
(2]

[31

aDEFINE LOCAL A

FuNC2

(4]

[5]

(1]

[2]
[3]

A<?2 x A
y

VFUNC?2

FUNC1
10
10

A
VALUE ERROR
A
A

The local variable 4 in FUNC1 is global with respect to its nested function,
FUNC2 . However, once the execution of FUNC1 is complete, 4 has no global
value.
System variables can be localized within operation definitions. In the following

example, the function F1 localizes the value of the system variable 070. After
F1 executes, [170 retains its global value. The function F2 , however, does not

localize the value of 0I10. Thus, after F2 executes, 0I0 retains the value it was
assigned in F2.

VAX APL Users Guide

3-9

User-Defined VAX APL Operations
3.4 Symbolic Names in Operations
VF1

[1]
[2]

;010

0I0<0
15V
VF?

[1]
[2]

[10+0
15V
15

aI0 IS

12345

allI0 IS 0

WITHIN F1

012
3 4
15

ABUT GLOBAL

VALUE IS STILL

12
3 45

F2
012

012

aFUNCTION F2 DOES NOT LOCALIZE (0I0
nS0 GLOBAL

VALUE OF [I0 IS NOW 0

3.5 Branching Within An Operation
Normally, APL lines in operations are executed in the order of their line
numbers; execution begins at the first line following the operation header and

ends with the last line in the operation. You can modify this standard order
of execution by using the branch function, which changes the sequence of

execution by transferring control to another line in the operation.
The branch function is monadic; its argument array must be in the vector

domain (or APL signals RANK ERROR), and its first value must be a nearinteger (or APL signals DOMAIN ERROR). When the argument array is not a

singleton, APL takes the array’s first item as the object of the branch.
There are two types of branches: unconditional and conditional.

3.5.1

Unconditional Branches
Unconditional branches consist of a branch symbol (=), followed by a
representation of the number of the operation line to which you want to

transfer control. For example, the following statement causes an unconditional
branch from line [5] (the current line) to line [1], thus making line [1] the next
statement to be executed:
[5]+1

The argument you specify after the -~ can be a label, a constant, a variable,

or an expression. If its value (or, if it is a vector, the value of its first item) is

equivalent to an integer line number within the current definition, execution
continues at that line. If the integer does not reference a line number in the
current operation, the branch statement exits the operation and returns you to

immediate mode or to the calling operation.

3-10

VAX APL Users Guide

User-Defined VAX APL Operations
3.5 Branching Within An Operation
APL users often deliberately specify out-of-range numbers to stop execution.

Line number [0] , the operation header, is considered to be an out-of-range
number; therefore, when you specify -0, you force an exit from the operation
and a return to immediate mode or to the calling operation.

If the object of the branch is an empty array, the branch function is ignored and
the normal order of execution continues (control passes to the next statement,
which is not necessarily on the next line).

The possible line number specifications that can be the arguments of a branch
function, and the effects of each, are summarized below.
Line Number Specifications

Kind of Line Number Specification

Effect of the Branch

A line number within the operation

Execution continues at that line.

Zero or a line number NOT within the
operation

Operation execution ends and control
returns to immediate mode or the calling
operation.

An empty array

The branch is ignored; execution continues
at the next statement.

No argument (bare branch)

Terminates a suspended operation and all
preceding pendent operations.

3.5.2 Conditional Branches
Conditional branches execute as the result of the evaluation of an expression,

not in response to any specific IF logic. There are several popular ways to
write conditional branches. One is to use the following form:
-~ line-number x 1 logical-expression

For example:
[1]

+ 9x14>B

Here, APL evaluates the logical expression that is the right argument of 1.

Logical expressions return either a 1 (true) or a 0 (false); therefore, if 4 is
greater than B, the value of the expression is 9x11 , and control passes to line

number [9]. If 4 is less than or equal to B, then the value of the expression is
9x 10, and control passes to the next statement.
Another conditional branch form is:
~ logical-expressions / line-numbers

VAX APL Users Guide

3-11

User-Defined VAX APL Operations
3.5 Branching Within An Operation
For example:
(1]

> ((A>B),(A<B),A=B)/7 8 9

In this type of conditional branch, several line numbers are specified as
possible branch destinations. Each line number is associated with a logical
expression. When the statement executes, APL transfers control to the first
line number whose corresponding expression evaluates to 1.

You can also use this form with one logical expression and one line number.
For example, in the expression ~(4<B) /13 , if the logical expression A<B
evaluates to 1, then control passes to line number [13]; if it evaluates to O,

then control passes to the next statement (because the expression 0/13 returns
10 )

A third conditional branch form is as follows:
-~( line-numbers) [ K]

For example:
(1]

(LABEL1,

LABEL2,

LABEL3)

[K]

Here, the value of K is used as an index for selecting a branch destination from

among a group of labels representing line numbers.

3.5.3

Labels
Because APL automatically renumbers operation lines as consecutive integers

when it exits from function-definition mode, problems can occur when branches
refer to explicit line numbers. Alternatively, 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:
[4]

INCR: X+ X+1

[8].

> (X<IMAX)/INCR

As shown, a label consists of a distinct identifier followed by a colon (:). When

you specify the label in the branch function, 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: its value is local to the operation in which it

appears. Label values are internally respecified upon each exit from function-

definition mode. You cannot explicitly define a value for a label, and you cannot
place the name of a label in the operation header.

3-12

VAX APL Users Guide

User-Defined VAX APL Operations
3.5 Branching Within An Operation

3.5.4

Examples of Branching
The following are examples of user-defined functions that use branching (user-

defined operators would use branching in an identical manner). In the first
example, the conditional branch in line [2] controls the number of times that

lines [3], [4], and [5] are executed. When N is greater than 0, the value of the
expression 0x10=N is an empty array, so control passes to the next statement.

When N equals 0, the value of the expression is 0, so APL exits from the
function.
V

[1]

R« FACTORIAL N

Re«1

[2]

LOOP:

[3]
[4]
(5]

R«RxN
NeN-1
> LOOP V

+ 0x10=N

FACTORIAL

120

In the next example, the unwinding back through the recursive calls of the
function begins when the branch function on line [1] transfers control to line

[5]:
V

[1]
[2]
[3]
[4]
[5]

7« FAC N

-+ NZEROx1N=0
Z«NxFAC N-1
+ 0
NZERO:

aNOTICE THAT RECURSIVE
aDEFINITIONS ARE PERMITTED

7« 1 ¥

FAC 5
120

A third example shows that when the argument to a branch function is an
empty array, control passes to the next statement (which is not necessarily on

the next line):
V NEXTS

[1]

10 >

[2]

NEXTS
1

2
3

VAX APL Users Guide

3-13

User-Defined VAX APL Operations
3.6 Comment Lines

3.6 Comment Lines
You can include comments in an operation definition at the end of the operation
header, at the end of lines containing APL statements, or on separate lines.

The first character in a comment must be a lamp character (s ), which is
formed with n and -. APL treats the text to the right of this symbol as a

comment; this text has no effect on the execution of the function. The text
of a comment can consist of any combination of valid APL characters; an
illegal APL overstruck character is not invalid within a comment, because it is
considered to be three valid APL characters.
Note that a comment cannot extend across line boundaries. If you want a
multiline comment, you must repeat the lamp character at the beginning of
each line of the comment.

3.7 Locking an Operation
APL allows you to lock operation definitions so that they cannot be displayed

or changed. To create a locked operation, or to lock an existing operation, you
open or close the operation with a del-tilde (¥) character (known as protected
del) rather than with a simple del (v). Del-tilde (¥#) is formed with v and ~.
The following example shows the locking of a previously unlocked function
definition:
V

[19j

TRIG

Locked operations have the following characteristics:
e

They can be erased.

They cannot be unlocked.

They cannot be displayed or edited in any way.

Trace, stop, and monitor vectors cannot be set for them; any trace, stop, or
monitor vectors in effect at the time a function is locked are automatically

cleared.

If an error occurs during execution of a locked operation, APL does not suspend
the operation; instead, it exits from the locked operation and from all locked

pendent operations until the operation on the top of the SI stack is not locked.
If all operations on the SI stack are locked, APL clears the SI stack.

3-14

VAX APL Users Guide

User-Defined VAX APL Operations
3.7 Locking an Operation
Note that the second line of the resulting error message includes the operation
name in which the error occurred, but not the line number nor the contents

of the line. A ¥ appears inside brackets ([ ]), instead of the line number, to
indicate that the operation is locked.
You should be cautious about calling an unlocked operation from a locked
operation; if the unlocked operation becomes suspended, the environment of

the locked operation is available for examination.
For example, if a locked function called PAY uses a local variable called
SALARY , the value of SALARY cannot be displayed if an error occurs during the
execution of PAY , because APL would exit from PAY . However, if PAY calls an

unlocked function called PRINT , and PRINT becomes suspended, the value of
SALARY 1n PAY may be displayed (unless PRINT also has a local variable called

SALARY ).

3.8 Executing User-Defined Functions
When you call a function that has arguments, you must supply the values for
APL to use during execution. You include the values described in the calling
syntax of the operation name. For example, the following function header
indicates that the function CALC has two dummy arguments:
A

CALC B

Thus, when you execute CALC, you must supply two values, one for 4 and one
for B:
25

CALC 42

Then, when APL executes CALC the values 25 and 42 are used wherever 4 and
B appear in the body of the function.

Operations that do not return explicit results, such as CALC, must be either
the only operation or the leftmost operation in a statement. For example, the
following statement is legal because the function CALC is the last function

executed in the statement:
25

CALC

(There 1s no output)

VAX APL Users Guide

3-15

User-Defined VAX APL Operations
3.8 Executing User-Defined Functions
Note that APL signals VALUE ERROR if CALC is not the last operation executed.
For example:
(25
11

CALC 42)

1 +

VALUE FERKOR
(25

CALC 42)

If the header includes a dummy argument for axis ({{£]}), you can optionally
include an axis specification when you call the function. The axis argument is
specified in the same manner for user-defined operations as for APL primitive
functions; it follows the operation name and is enclosed in brackets ([ ]). The

braces ({}) are part of the header definition and are not allowed when you call
the operation.

3.9 Executing User-Defined Operators
User-defined operators are called in the same manner as user-defined
functions. You must supply the operator name and all required arguments and
operands.

If the header includes a dummy argument for axis ({{£]}), you can optionally
include an axis specification when you call the operator. The axis argument is
specified in the same manner for user-defined operations as for APL primitive
functions; it follows the operation name and is enclosed in brackets ([ ]). The

braces ({}) are part of the header definition and are not allowed when you call
the operation.

3.10 Printing Operations
The APL workspace SYS$LIBRARY:WSPRINT.APL, contains a function which
can be used to print APL objects on an LNO3 printer.

To use the function, copy the workspace into the APL session and execute the
function using the following form:
[queue] wsaPRINT[pw] object
queue

Is the name of the LNO3 print queue. If you do not specify the queue, the file

will be sent to the default print queue SYS$PRINT.
pw

Is an optional value to specify the print width. The APL object will be printed
in portrait mode if pw is 80 or less. If pw is greater than 80 the object will be
printed in landscape mode.

3-16

VAX APL Users Guide

User-Defined VAX APL Operations
3.10 Printing Operations
object

Is the name of the APL object you want to print.
For example:
)COPY SYS$LIBRARY:WSPRINT.APL
"LNO3_PRINT'

3.11

WSAPRINT

[132]

'FO0O!

Editing Operations
APL provides four tools to allow you to define and edit operations.
*

The DECwindows interface invokes full DECwindows support to more

easily develop operators, functions and variables. (See Section 3.11.2.)
®*

The Character-Cell interface provides a TPU-based window environment
to facilitate development of operators, functions and variables. (See
Section 3.11.3.)
The )EDIT system command allows you to edit global APL objects with the
VAX TPU editor. (See Section 3.11.4.)

3.11.1

Line-edit mode can be used in any APL session. (See Section 3.11.5.)

Support Considerations
When edited operations are returned to the interactive session, the lines in the
operation are automatically renumbered sequentially, beginning with line [1].
Therefore, lines you insert with fractional numbers retain those numbers only

while the operation is open for editing.

APL preserves leading and embedded white space (blanks or tabs) in function

lines so you can format the operation (using indentation) to make it more
readable. APL does not force any special spacing on labels, numeric constants,
or comments when displaying the operation. Trailing white space is removed

from lines to conserve storage.
Note that PP (Print Precision) is an implicit argument when the an editor

displays numeric constants. If you are using the Character-Cell interface editor

or the system command ) EDIT, numeric constants in the operation could lose
precision when displayed in VAXTPU.

VAX APL Users Guide

3-17

User-Defined VAX APL Operations
3.11 Editing Operations

3.11.2 The DECwindows Interface Editor
The DECwindows interface provides full DECwindows support of the APL
product. In addition to the interactive area in the initial APL. DECwindow,
the transcript session, you can open one or more sessions to edit user-defined
operations and variables. (See Section 2.7.3 for more information on editing
variables.)

Defining a new operation, is similar to editing an existing operation. One
difference is that you have to specify the type if you are defining a new
operation. Follow these steps to start an edit session.
1.

Click on the Commands option located on the Menu Bar in the transcript
sesssion to expose the Commands menu.

Select the Edit Existing or Edit New option. If you select the Edit New
option, you must also select the object type. Select either the Function or
Operator option.

Click on the input area of the dialog box, shown in Figure 3-1, and enter
the name of the operation.

Figure 3—-1

Commands

DECwindows Interface Operation Name Dialog Box

Fonts

E==APL: Edit New Funclion——

The Title Bar in the edit session is the name of the operation. If this is
a new operation, only the header will be displayed. If you are editing an
existing operation, the definition will be displayed.
You can enter text to edit the header or body of the operation or you can
use the mouse to copy text from one edit session to another edit session.
The mouse can be used to copy text from the transcript window, to an edit
window. You cannot copy text into the transcript window.

3-18

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations
5.

Finish defining the function by selecting Exit, Update Workspace or Quit

from the Commands option on the menu bar in the edit session. Figure 2—3
shows the options that are available after you click on the Commands

option in the edit session.

When you return to the transcript session, you can enter commands to call

the operation. You do not have to close the edit session to return to the
transcript session. For example, in Figure 3—-2 the edit session window has

not been closed. The command entered on the input line uses the operation
recently defined in the edit session.

If you select the Exit option from the edit session Commands menu, the
definition is written to the workspace and the edit session is closed. The
Quit option closes the edit session without saving changes in the operation

definition.

Figure 3—2

Eummands

DECwindows Interface Edit Session Example

Fonts

OUT132=

Enmmands

| ouT132 FUNC
| =" )COPY SYS$LIBRARY:WSPRINT.APL’
| "$PRINTER_1’ WSAPRINT [132] FUNC

Hloutisz ‘sTAT’

VAX APL Users Guide

3-19

User-Defined VAX APL Operations
3.11 Editing Operations

3.11.3 The Character-Cell Interface Editor
The Character-Cell interface provides a TPU/EVE based window environment
for APL sessions on the Digital VT220, VT240, VT320, VT330, VT340 and
DECterm terminals. This environment inserts the text of the operation you
are editing into a temporary holding area, a buffer. You can display more than
one buffer on the screen at one time and edit more than one operation during
an APL session. (See Section 1.3.3.)

You can view operations that are suspended or pendent, but you cannot modify
them. If you attempt to edit an operation that is suspended or pendent, APL
puts the appropriate message in the TPU/EVE message buffer.
To start an edit session, press the Do or PF4 key or enter Ctrl/B to display the
Command: prompt. Enter the following command, substituting the name of
the operation being edited for operation.
GET operation< v

The contents of the operation are displayed in the window of the new buffer.
The end-of-file marker defines the end of the buffer. It is only visible on the
screen and is not saved as part of the operation. The status line shows the
name of the buffer, operation« v. (See Figure 3-3.)

You can edit the header and the body of the operation. Text can be added by
using one of the following methods:

Entering the APL characters from the keyboard

Inserting text copied from the APL SESSION Buffer or another edit buffer

Including entire files

The EVE Help Utility has specific information about copying text. Enter
HELP at the Command: prompt and look at copy, cut, paste and restore.
Enter HELP INCLUDE FILE at the Command: prompt to get more information
about including files. (Press the Do or PF4 key or enter Ctrl/B to reveal the
Command: prompt.)

To write the contents of a buffer to the interactive APL session, use the
following form:

WRITE [ operation < V1]

The name of the operation is optional. If you do not specify the name of the
operation, EVE uses the name associated with that buffer.

3-20

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations
Figure 3-3 shows an APL session using the Character-Cell interface. In the

figure, two windows are open. The top edit window shows the user-defined
operation 0UT80. The bottom window is the interactive session APL SESSION.

The command on the command line updates the interactive session with the
contents of the edit window.

Figure 3—-3

Character-Cell Interface Operation Edit Example

Edit

ouTE0

STAT

Customize

Help

Commands

[End

Euffer:

guUTs0

buffer]
APL

2" YCOPY

Read-only

Insert

Forward.

Imsert

Forward

SYS$LIBRARY:WSPRIMT.APL’

"$PRINTER_1"

[End

SEZSION

FUNC

Buffer:

WSAPRINT

[80]

FUNC

file]

Write

[]
O

To return to the interactive session, enter BUFFER APL SESSION at the

Command: prompt. Alternatively, if you are using a split screen with the
interactive session in one window and an edit session in another, you can

return to the interactive session by entering 0THER at the Command: prompt.
If you are using a mouse and multiple windows, you can position and click the
mouse on the interactive session to make that the active session.

When an operation returns to APL, APL embeds a <CR><LF> at the end of

each line. If there is a <CR><LF> inside any single record, APL treats the
<CR><LF> as the end of an operation line and forms a new record (note that if
the resulting record contains an unbalanced delimiter, APL signals an error).
When a line of an operation contains embedded <CR><LF> characters, it is

written out to VAXTPU as two records. For example:

VAX APL Users Guide

3-21

User-Defined VAX APL Operations
3.11 Editing Operations
(Defined with line-editor in APL)
vV

FOO

< 'AA

[1]
AA'Y

(Opened for edit with Character-Cell interface editor)
Foo

'AA

(This returns to APL)
V FOoOo
vV

(01

FOO

[1]

Z«

[2]

AA!

'AA

3.11.4 The ) EDIT System Commmand Editor
The )EDIT system command allows you to edit APL operations with the

VAXTPU editor. The default object type is a function. If you want to edit an
operator, you must specify a value 4 for the name class qualifier (/NC: u4).
When you invoke )EDIT, APL creates a temporary file containing the object

you want to edit and then invokes VAXTPU. When you exit VAXTPU,
APL reads the edited file from VAXTPU into the workspace. You can view

operations that are suspended or pendent, but you cannot modify them. APL
returns you to the VAXTPU editor if an error occurs as the file reenters the
workspace.

Use the form following form to edit an APL object:
YEDIT operationqualifiers]

operation

Is the name of the APL operation you want to edit.
qualifier
Is one or more of the optional qualifiers.See VAX APL Reference Manual for
more documentation on the )EDIT system command.

When you invoke )EDIT for an existing operation, you can specify the /LC
qualifier if you want to view the line numbers associated with the lines of the

operation. However, these line numbers may change since APL reassigns them

when the file returns to the APL environment. If you add new lines to the
operation during the VAXTPU session, it is not necessary to specify new line
numbers. If you do not specify /LC when you invoke )EDIT, APL sends the

canonical representation of the operation (no line numbers) to VAXTPU.

3-22

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations
The display of a user-defined operation passed from APL to VAXTPU is

dependent on JPP. Therefore, numeric constants in the operation could lose
precision when displayed in VAXTPU. You can use the /PP qualifier when you
invoke )EDIT to specify a different value for the print precision.

When you invoke )EDIT for a new or empty operation, APL generates an
empty temporary file for VAXTPU. If the file is empty (contains O records)

when it returns to APL, it arrives as an empty operation and has the same
name you specified when you used the )EDIT

expression. By definition, an

empty operation contains no lines and has a header that includes only the
name of the operation; the header does not include specifications for local
variables.

When a line of an operation contains embedded <CR><LF> it is written out to
VAXTPU as two records. When an operation returns to APL, APL embeds a

<CR><LF> at the end of each line. If there is a <CR><LF> inside any single
record and you specify /MODE: 3, APL treats the <CR><LF> as the end of an

operation line and forms a new record. If the resulting record contains an
unbalanced delimiter, APL signals an error. If you specify /MODE: 2, the <LF>

will not return.
Data in VAXTPU

Line in APL
Mode

"aa

Mode 2

"aa<CR><LF>aa’

'aa<CR><LF>aa’

APL signals

'aa<CR>aa'

aa’

"aa<CR><LF>aa’

EDIT

COMMAND ERROR
aa<CR><LF>aa

Note that the <CR><LF> symbol does not appear visually in the APL
environment, although it does cause data to be displayed on a new line.

3.11.5 The Line-Editor
APL provides a line editor that allows you to add, delete, and change definition
lines, alter the operation header, or even edit individual characters in a line.
You must be in function-definition mode to edit an operation. To open an
existing function or operator for editing, type the del (v) character followed

by the operation name; do not type the entire operation header. To edit a new
operation, type the del character and the full operation header.
You cannot modify a pendent operation.

VAX APL Users Guide

3-23

User-Defined VAX APL Operations
3.11 Editing Operations
APL responds with a display of a line number (in brackets). If this is an
existing operation, the number will be equal to the last line number in the
operation plus one. For new operations, the number will be 1. (The operation

header is on line 0.) In turn, you respond, on the same line, with an edit
command or with the text of a line that you want to append to the operation
definition. For example, the following deletes line [5] from the function STAT :
V

[7]

STAT

[A5]V

Alternatively, you could enter an editing command immediately following the

operation name. Thus, the following also deletes line [5] in STAT :
V

STAT[AS]V

Once you have control of the editor, you may enter as many editing commands
as you need. When you complete the editing session, you type a v to close the
operation and return to immediate mode. You may type the closing v on the

same line as an edit command.
You can execute system commands from within function-definition mode, and
APL interprets them as if they were entered in immediate mode. If you desire

the system command to be executed as part of a user-defined operation, you

can use any of the execute functions (see the VAX APL Reference Manual).
YEDIT and )

STEP cannot be executed from inside function-definition mode.

Note that if you type a closing v immediately after entering the header for a
new operation, you create an empty operation, that is, an operation that has a
header but no body.

If you want to abort an editing session, enter the abort input signal. APL
returns you to immediate mode and leaves the operation as it was before the
editing session. If you abort an editing session while defining a new operation,

the new operation is not created.

3.11.5.1

Line Editing Commands
You use line editing commands to add, change, or delete lines in an operation

definition. The function editor commands are summarized below.

Form

3-24

Meaning

V operation-name

Open operation for editing.

End operation editing.

End operation editing and lock operation.

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations

Form

Meaning

[n]

Define or change line n.

[An]

Delete line n.

[An,l]

Delete [ lines beginning at line n.

|A ]

Delete the current line.

[n0]

Display line n.

[On]

Display all lines, beginning with line n.

[On,l]

Display [ lines beginning at line n.

(0]

Display all lines of function.

(n$/s1//s2/]

Beginning at line n search for string s and replace it with
string s2.

[mOn]

Do character editing of line m; begin at character position 7.

[eOn]

Open last entered line for character editing, beginning at

character position n.
[- O]

List last entered line.

In character editing, type beneath each character you want
to delete.

In character editing, insert n (a numeric digit) spaces before
current character.

letter

In character editing, insert multiples of 5 spaces—A4 inserts

5 spaces, B inserts 10 spaces, and so on.
,text

In character editing, insert text before the current character.

line feed

Delete everything on the line to the right of the line feed.

You can enter more than one editing command at a time. For example, the

following directs APL to open the function F00 for editing, delete line [8],

display the entire function, and then begin character editing of line [5] at
character position 16:
V

FOO[A8][0IL5016]

If you enter an invalid editing command, APL signals DEFN ERROR

(definition

error). APL often includes a secondary error message that provides specific
information about what caused the error. When you open an operation

for editing, you can add lines in response to the bracketed line numbers.
For example, the function named STAT exists in form shown (an incorrect

algorithm) in the example.

VAX APL Users Guide

3-25

User-Defined VAX APL Operations
3.11 Editing Operations
V

[1]
[2]
(3]
[4]
[5]
[6]

[6]
[7]
[8]
[9]

STANDX«NSUBJ STAT X

SUMX++X
SUMX2++/(X*2)
aCOMPUTE MEAN, VARIANCE, STANDARD DEVIATION
MEANX«SUMX:NSUBJS
MEANX<SUMX:NSUBJ
v
STAT

aFUNCTION RETURNS VALUE OF STANDARD
a DEVIATION OF X
STANDX<VARX%0.5
v

To replace existing lines in an operation definition, specify the number (in
brackets) of the line you want to replace, followed by the new text for the line.
For example, you can replace line [1] of the function STAT as follows:
vV STAT
[9]

[1]

[2]

SUMX<+/X

The line number you specify must be a nonnegative number less than 10,000.
If the line does not currently exist, it is inserted.
To insert a new line between existing lines of an operation definition, specify
the new line number (in brackets) followed by the text of the new line. The line
numbers you insert must be positive numbers up to but not including 10,000,
with or without a decimal point, and with no more than five decimal places.
For example, to insert a line between lines [5] and [6], you could specify any
number from [5.00001] to [5.99999]; to insert a line before line [1], you could
use any number from [0.00001] through [0.99999], and so on. In the following

example, new lines are inserted between existing lines [0] and [1], and [5] and
[6], respectively:
V

[1]
[0.6]
[5.6]

STAT

[0.5]
aSUM ITEMS OF ARRAY X
[5.5])VARX<+(SUMX2:NSUBJ)-MEANX*?2
V

After each insertion, APL prompts with the next line number after the inserted

line. To determine the next line number, APL truncates trailing zeros and then

increments the current line number by 1~
D, where D is the number of decimal
places in that line number. Thus, the next line after [0.5] is [0.6], the next line
after [5.5] 1s [5.6], and the next line after [8.29] is [8.3].

3-26

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations
Caution
Note that line number [6] follows [5.9], and then line number [7], not
[6.1], follows [6].

To delete existing lines in an operation definition, type a delta (o) and a line
number or range of line numbers within square brackets.

For example, to delete line [5] of STAT, you would type the following:
V

[11]
[6]

STAT

[A5]
v

To delete a range of line numbers, specify two numbers after the a: the first

number identifies the starting point for the deletions, and the second number
specifies the total number of lines to be deleted. Thus, the delete command

[A 3,4] deletes four lines beginning with line [3].
When you specify a range of numbers, only existing lines are counted; for

example, if during an editing session the existing lines in the function are lines
[1], [2], [4], [5], and [6], then the delete command [A 2,3] deletes lines [2], [4],
and [5]. Note, however, that the initial line is still counted even if it does not

exist; that is, if the previous delete command had been [A 3,3] , then only two
lines ([4] and [5]) would have been deleted.

If the number of lines remaining in the operation following the starting point
1s less than the number of lines specified by the second argument in the

delete command, all the remaining lines are deleted. After the deletions, APL
prompts with the next available line number.
You can delete the current line of the operation by responding to the line

number prompt with [A ]. In the following example, lines [5], [6], and [7] are
deleted:
V

[11]
[6]
[7]
[8]

STAT

[A5]
LA]
[A]
V

APL displays the number of the next line after the deleted one. You can then

type a new line, edit another line, or exit from function-definition mode by
typing a v. After you close the operation, APL renumbers the lines.

VAX APL Users Guide

3-27

User-Defined VAX APL Operations
3.11 Editing Operations
3.11.5.2

Displaying Operation Lines

APL allows you to display individual operation lines, all of an operation’s lines,
a range of an operation’s lines, or all of an operation’s lines from a specified
line to the end cf the operation.
To display an individual line, type the line number and a quad (O) in square
brackets. For example, to display line [3] of function STAT , type:
vV STAT [30]
SUMX2++
[ (X*2)

[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 then perform any editing operation,
or you can exit from function-definition mode by typing a v.

To display an entire operation definition, type the quad (in brackets) without a
line number. The following example displays the entire function named STAT
(now a correct algorithm):
vV STAT[O]V
V STANDX+NSUBJ STAT X
[1]

aSUMX ITEMS OF ARRAY X

[2]

SUMX+«+/X

[3]

SUMX2«+
/[ (Xx2)

[4]
[5]

MEANX«SUMX+NSUBJ

(6]

VARX<(SUMX2+NSUBJ)-MEANX+2

ACOMPUTE MEAN,

VARIANCE, STANDARD DEVIATION

AFUNCTION RETURNS VALUE OF STANDARD
a DEVIATION OF X

[7]
[8]
[9]

STANDX«VARXx0.5
v

The v characters preceding the operation header and following line [9] delimit
the operation and identify its name. The characters do not change the mode as
the operation prints. APL displays the number of the next line after the final
line of the operation to give you the opportunity to add new text, perform any

other editing operation, or exit from function-definition mode by typing a v.
To display the operation definition from a particular line number to the end,

type the quad character and the line number at which you want the display to
|

begin. For example:
V STAT(O8]V

[7]
[8]
[9]

aFUNCTION RETURNS VALUE OF STANDARD
a DEVIATION OF X
STANDX<«VARX%0.5
v

[10]

3-28

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations
APL displays the number of the next line after the final line of the operation

definition, in this case [10], to give you the opportunity to add more text. You
can then perform any editing operation or exit from function-definition mode

by typing a v.
To display a range of line numbers, specify two numbers after the [J: the first
number identifies the starting line number, and the second number specifies

the total number of lines to be listed. Thus, the list command [[05,3] displays
three lines beginning with line [5].

When you specify a range of numbers, only existing lines are counted; for
example, if during an editing session the existing lines in the function are lines
[1], [2], [4], [5], and [6], then the display command [[02,3] lists lines [2], [4], and
[5]. Note, however, that the initial line is still counted even if it does not exist;
that is, if the previous display command had been [[03,3], then only two lines
([4] and [5]) would have been listed.
If the number of lines remaining in the operation following the starting point is

less than the number of lines specified by the second argument in the display
command, the list ends with the last line of the operation. After the display,

APL prompts with the next available line number.
Another way to exit from function-definition mode after displaying all or part

of an operation is to type the closing v on the same line as the display request.
For example:
V STAT[[8]V

[7]
[8]

[9)]

AFUNCTION RETURNS VALUE OF STANDARD
a DEVIATION OF X

STANDX<VARX*0.5
v

Because you have already typed the closing v, APL does not prompt you for

the next line of the function.
3.11.5.3

Search and Replace Strings
To replace one string with another in an operation, you can specify a search
and replace expression using the following form:
[ [[1ine-number]]

S$dl[{search-string]ld|[d[[replacement-string]]d]]]

line-number

Specifies the operation line where you want the search to begin. The search
continues from this line to the end of the operation or until an occurrence of

the search string is found. If you do not specify line-number, the search begins
at the current line. If you specify the o symbol, the search occurs on the most
recently entered immediate mode line.

VAX APL Users Guide

3-29

User-Defined VAX APL Operations
3.11 Editing Operations
d

Specifies a delimiter that is any character you choose to separate the fields
of the search and replace expression; it cannot be a carriage return. Once
you declare the delimiter in any given expression, it must not change. The
important consideration when choosing a character for a delimiter is that it
does not appear in either the search string or the replacement string.
search-string
Is the string of characters that you want to search for. APL searches for exact

matches on each line of the function; a match that spans more than one line
is not considered a match. If you do not specify a value for search-string, APL

searches for the string specified in the previous search and replace expression.
If there is no previous search-string value, APL signals DEFN ERROR (NO

PREVIOUS SEARCH STRING). If APL cannot find the string, it prompts you for
the next line at the end of the function.

Although search string is an optional parameter, the before and after delimiters
are not. You must specify these delimiters.
replacement-string

Is the string of characters that you want to put in place of the search
string. When APL finds an occurrence of the search string, it is deleted
and replaced with the value of replacement-string. If you specify a value
for replacement-string, the delimiters are required. If you do not specify

a value for replacement-string, you do not have to specify its before and after

delimiters. However, the meaning of the search and replace expression changes
depending whether these delimiters are specified in this optional situation. If
you specify them, the search string is deleted. If you omit them, APL finds the
search string (if possible) but does not delete it. For further description of this
behavior, see the following list of form variations.

Note that the combined length of search-string and replacement-string should
be less than the current [JP¥ setting.

Since both the search and replace strings are optional, there are six variations
of the search and replace expression. The forms for the variations are shown

below. Note that the slash (/) symbol is used as the delimiter, s1 equals
search-string, and s2 equals replacement-string:

3-30

Variation

Meaning

[$/s1//52/]

Replace s1 with s2.

[$///s2/]

Replace next occurrence of the previous search string with s2.

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations

Variation

Meaning

[$/s1///]

Delete s1.

[$/s1/]

Search for s1, but do not delete it.

[$////]

Delete next occurrence of the previous search string.

[$//]

Search for the previous s1, but do not delete it.

Note that APL begins each search on the current line unless you specify a
value for line-number. When you are doing successive searches using the
simple search form (no deletes), you must specify the current line number plus

one after you have found the first occurrence of the string.
3.11.5.4

Editing the Operation Header
You can edit the name or arguments of an operation header by accessing line
number [0]. You can display and replace the operation header just as you
can any other line in the operation, but you cannot delete the header using

[A 0]. You must have specified a valid operation header before leaving functiondefinition mode. If an error occurs while you are changing the header, the
original header is retained.
The following example displays the operation header:
V

[0]

STAT

Lol

(121

STANDX«<NSUBJ STAT X

Notice that the header is displayed without a line number. When you specify
a character position in the header, APL types the header with line number [0]

and without the v. For example:
V

STAT

[10]

[007]

(0]

STANDX<NSUBJ STAT X
0

Note that the up-arrow in this example indicates the position of the cursor or
terminal head. It does not appear on your terminal.

VAX APL Users Guide

3-31

User-Defined VAX APL Operations
3.11 Editing Operations
3.11.5.5

Character Editing

In addition to providing a way to edit operation definitions line by line, APL
provides a way to edit lines character by character.

To begin character editing, specify the line number of the line to be edited

and the estimated character position at which editing is to begin using the
following form:

[ line-number]character-position]
For example:
V DIESEL

(7]
[1]

[107110]
A<R x GAMMA -

APL displays the line, performs a <CR><LF>, and positions the cursor or
terminal head at the position you specified (the up-arrow in the example

indicates the position specified; it does not appear on the terminal). Once you
are in the desired position, you can enter the commands to delete unwanted
characters and insert blanks in the line where new text is needed or inserting
text. Use the keys in the following table to enter the commands.
Note that if you want to add characters to the end of a line without changing
any of the rest of the line, you should specify character position 0. APL will

place the cursor just after the end of the line, and will be ready to insert the

text. editing commands. Thus, you may immediately make your additions to
the end of the line.
Character

Meaning

Space

Moves the cursor one character to the right.

Backspace

Moves the cursor one character to the left (provided that terminal
line editing is turned off; see 0 TLE in the VAX APL Reference
Manual).

3-32

Slash(/)

Deletes the character above the slash.

Digit

Inserts, preceding the character above the digit, a number of
spaces equal to the value of the digit.

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations

Character

Meaning

Letter

Inserts, preceding the character above the letter, a number of
spaces equal to 5 times the relative position of the letter. Typing
an A inserts 5 spaces; typing a B inserts 10 spaces, and so forth.

Comma (,) text

Inserts, preceding the character above the comma, the text
that follows the comma. (APL does not process other editing
characters to the right of the comma editing command.)

Any other

(GGives an error.

If the number of spaces and text (minus the number of slashes) that you add
extends the length of the current line to exceed the length of the terminal
line (the value of 1PW¥ ), APL signals OUTPUT LINE TOO LONG (PAGE WIDTH
EXCEEDED)

If the character position is negative or greater than either the page width (OPW¥)
or 255, APL signals EDIT FRROR (COLUMN POSITION OUT OF RANGE).

When you finish entering your commands, press the Return key; APL responds

by displaying the line without the deleted characters and with the inserted
spaces and text. Then, APL positions the cursor at the first inserted space on
the line to be edited, or, if you did not insert spaces, at the end of the line. If
necessary, you can enter new text in the spaces or at the end of the line. If you
used the comma command, APL positions the cursor after the text inserted by

the comma and not at the first inserted space.
Press the Return key to return to function-definition mode. APL replaces the

existing line in the operation with the new one and prompts with the next
line number. If you used a comma, you can perform another character-edit

operation. To return to function-definition mode after using the comma, press
the Return key twice.

If you change the line number while you are editing the line, any edits you
make are associated with the new line number; the original line remains

unchanged.
If you edit the header (line 0) and change the operation’s name, then when you
exit from function-definition mode, a new operation is created with the new

name. The new operation is an edited version of the old one; the old operation
still exists in its original form.

You cannot delete a line by typing a slash (/) beneath all of its characters.

VAX APL Users Guide

3-33

User-Defined VAX APL Operations
3.11 Editing Operations
While you are in character editing mode, APL keeps track of your current line

with an internal pointer mechanism. If you enter a string of edit commands,
APL interprets the commands sequentially from left to right and updates the

current line after each one. For example, [A 2][A 4][01] deletes lines 2 and 4 of
an operation, and then displays the operation. After APL deletes line 2, the
current line is line 3. After APL deletes line 4, the current line is line 5. After

APL displays the operation, the current line is the last line plus one.
If you append data to a series of edit commands, the last edit command in the

series determines the current line that is created by the data. The following

example illustrates the need to foresee the current line when you append data
in this manner:
vV F

[1]

[2]

[107]

[1]

1
il

[1]
[2]

(07121
(0]
vV

[1]
[2]

1
21
V

The following example illustrates how character editing is used to correct line
[1] of a function named FRYER:
[1]

T«(LETTR=STRING/18P,STRING

There are several errors in this line:
*

The word LETTER is misspelled LETTR.

The right parenthesis is missing after the first occurrence of

The 8 should not appear at all.

The P should be p.

You could edit this line as follows:
A

FRYER

[5]

[101u]

(1]

T<(LETTR=STRING/18P,STRING

[1]

T«(LETT R=STRING /v

3-34

VAX APL Users Guide

//1

,STRING

STRING .

User-Defined VAX APL Operations
3.11 Editing Operations
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. (On some terminals, using the space bar to move over text that you

want to preserve will cause the text to disappear from the video screen.) The
new line looks like this:
[1]

T<(LETTER=STRING)/1p,STRING

When you press the Return key, the new line replaces the existing line [1] in
your function definition.

You could also use the comma character-editing command to correct line [1] of
FRYER:
AN

FRYER

[5]

[1014]

[1]

T«(LETTR=STRING/18P,STRING

[1]

T<(LETTER=STRING/18P,STRING

;)
(move cursor,

[1]

add command and text)

T«(LETTER=STRING)/18P,STRING

[],p
(move cursor,

[1]

add commands

and text)

T<«(LETTER=STRING)/1p,STRING

[2]

You cannot include an unbalanced quotation mark when using comma editing.
When there is an unbalanced quotation mark, APL waits for the matching
mark just as it would when you enter a quoted string outside of comma editing
mode.
Note that when you use the comma character-editing command after
repositioning the cursor with the Backspace key, you may insert unexpected

blank spaces:
V

rars 15 A LINE

[1]
[2]
[1]

[10015]
THIS IS A LINE

[2]

(APL positions cursor here)

X
(User types

8 Backspaces,

Space X Space)

(New line contains 4 extra spaces)

[1]

THIS IS A LINE
+

VAX APL Users Guide

3-35

User-Defined VAX APL Operations
3.11 Editing Operations
The extra spaces are inserted because of the original placement of the cursor.
APL does not recognize whether the spaces belong to the comma string or not,
and so they are included in it.
You can cancel the revision of the operation line by typing a deliberate

character error (such as an illegal overstrike) after a character-editing display.
When APL encounters a character error, it displays both an error message
and the line, with a caret (») pointing at the illegal character. The old line is

retained; you may edit the new line in immediate mode.

You can escape from character-editing mode at any time by entering the abort
input signal. APL cancels any changes you have made to the line. You may
then enter another editing command or exit from the function editor by typing
V.

Note that if you are in character-editing mode and you want to abort the
editing session entirely, you must enter the abort input signal twice: once to

escape from character-editing mode and once to abort the session and return to
immediate mode. APL ignores any changes you have made during the session.
3.11.5.6

Editing Lines That Contain Control Characters
In character-editing mode, APL outputs ASCII control characters differently.

Normally, APL sends control characters to the terminal for interpretation by
the terminal. However, if the control character is part of a literal that you are
editing in character-editing mode, it is displayed as the overstruck character
(see Table 1-4 and is not sent to the terminal for interpretation.
This way of displaying control characters is particularly important when a

literal in an operation definition contains a <CR><LF>. If the <CR><LF> were
output for interpretation by the terminal, it would be impossible to edit the

literal. Instead, APL displays the <CR><LF> as M X ; then, you can edit the
literal using the normal character editing techniques.
3.11.5.7

Editing in Immediate Mode

The way you edit lines in immediate mode is similar to the way you edit
them in function-definition mode. In immediate mode, line edits affect the
last nonblank line entered from the keyboard (not including any previous
immediate-mode or v editor editing commands). Because immediate-mode

lines do not have line numbers, to initiate editing you type, in brackets: a jot

character (- ), a quad character (), and an integer representing the character
position at which editing is to begin. For example:

3-36

VAX APL Users Guide

User-Defined VAX APL Operations
3.11 Editing Operations
ACRON<«INIT1,
11

INIT2[ INIT3

VALUE ERROR

ACRON«INIT1,

INIT2[ INIT3
A

[o025]
ACRON<INIT1,

INIT2[ INIT3

ACRON<INIT1,

INIT2,

INIT3

You could perform this immediate-mode edit with the comma-insertion
command. In the following example, the user recalls the last line, enters a
slash (/) to delete a character, follows the slash with the comma-insertion
command, and enters a second comma as the inserted character. After the

user enters a Return, the line is displayed again with the cursor underneath
the character following the inserted comma. After a second Return, the
line is displayed with the cursor at the end of the line (awaiting additional
modification). Finally, APL executes the line after the third Return.
[o025]
ACRON<INITA1,
ACRON<INIT1,

INIT2
INIT2,

[INIT3

/s,
INIT3
,f

ACRON<INIT1,

INIT2,

(APL executes

INIT3

line)

Then, immediate-mode editing proceeds exactly as character editing in
function-definition mode. Note, however, that after you press the Return
key to conclude the final edits, APL executes the line. If you merely want to
display (but not execute) the last line entered from the keyboard, type [- 0]
(with no character position).

3.12 Examples of Defined Operations
This section gives an example of niladic, monadic, dyadic, and ambivalent
user-defined functions as well as a function that takes an axis. There are also
examples of a dyadic operator and a monadic operator that take an axis.

3.12.1

Niladic Function
The function AVG is niladic; it takes no arguments. 4VG does not return an
explicit result; thus, it cannot be used as an argument to another operation.

Also note the value of VECTOR , both as a global variable outside the definition
of

4VG and as a local variable inside 4AVG :

VAX APL Users Guide

3-37

User-Defined VAX APL Operations
3.12 Examples of Defined Operations
V AVG:;VECTOR

[1]

M «

[2]

"THE RESULT IS '

"ENTER THE VECTOR TO BE AVERAGED:

[3]

:;(+/VECTOR)<p,VECTOR«[XQM

VECTOR<'ABCD'
AVG

ENTER THE VECTOR TO BE AVERAGED:

THE RESULT IS 5
VECTOR
ABCD

100%xAVG
ENTER THE VECTOR TO BE AVERAGED:
THE RESULT IS 5

VALUE ERROR

(FUNCTION DOES NOT RETURN A RESULT)

100%xAVG
A

3.12.2

Monadic Function
The function AVERAGE is monadic; it takes one argument, which is placed to
the right of the function name.

AVERAGE returns an explicit result; thus, it can

be used as an argument to another function (in this case, the multiplication
function).
V ANS<«AVERAGE

[1]

[2]

VEC

ANS<«(+/VEC)=+p,VEC

v
AVERAGE

100xAVERAGE

500

3.12.3

Dyadic Function
The function I¥ is dyadic; it takes both a right and a left argument:
V LETTER IN STRING;T
[1]

ARETURNS NUMBERIC POSITION WHERE LETTER

[2]

AAPPEARS IN STRING

[3]

T«(LETTER=,STRING)/1p,STRING

[4]

+ENDx10=pT

[5]
[6]
(71

»0,[0«T
END: 'NO OCCURRENCES'
v
LETTER+'
(!
T«'GLOBAL'
LETTER IN

3-38

VAX APL Users Guide

'"ABCACBC(C

User-Defined VAX APL Operations
3.12 Examples of Defined Operations
LETTER IN

'LMNOP'

NO OCCURRENCES
T

GLOBAL
LETTER
¢

3.12.4 Ambivalent Function
The following function is ambivalent: it may take either one or two arguments.

If two values are supplied, the function adds them together; if a single value 1s
supplied, the function adds one to the value:
Vv

[1]

Z«{A}

PLUS B

+(0=0NC 'A'")/MONAD

[2]

Z+A+B

(31
[4]

MONAD:

[5]

a(NC=0 MEANS NAME NOT IN USE

Z+<1+8B

PLUS 6

PLUS 7
8

3.12.5 Function with Axis
The following example defines a dyadic function that accepts an axis argument
when invoked. In the header, the dummy argument for the axis is enclosed
by brackets ([1) and braces ({}). The brackets indicate an axis argument, the
braces indicate that the axis is optional.

The FIRST ROTATE function performs the same operation as the primitive
o function except that it counts the axes in reverse order. You can call

FIRST ROTATE just as you would call a similar primitive function.
[1]
[2]
[3]

V Z«A FIRST ROTATE {[K]} B
~(020NC 'K')/L o K+[I0
L: Z«A¢[(0I0+ppB)-K+~0I0]B
v

0I0<«1

X«3

3p'ABCDEFGHI'

X
ABC

DEF
GHI

36X

DHC
GBF

AEI

VAX APL Users Guide

3-39

User-Defined VAX APL Operations
3.12 Examples of Defined Operations
1

FIRST ROTATE

e[1]X

FIRST ROTATE[1]X

o[2]1X

FIRST ROTATE[2]1X

FIRST ROTATE X

e[0]X

FIRST

e[1]X

FIRST ROTATF([1]X

BCA

FDF
GHI

DHC
GBF

AFT

BCA4
FDE

GHI
BCA

FDFK
GHI
DHC
GBF
AFT

DHC

GBF
AF]I
BCA
FDE
GHI

DHC
GBF

AFI
ROTATE[O0]X

BCA

FDE
GHI

BCA
FDE
GHI

DHC

GBF

AFI

If you specify an axis when you call a user-defined function that is not defined
as accepting an axis argument, APL signals AXI.S DOMAIN ERROR (INCORRECT
OPERATION). If you omit the optional axis argument of such a function, and

the body of the function attempts to reference the axis value when the function

340

VAX APL Users Guide

User-Defined VAX APL Operations
3.12 Examples of Defined Operations

is called, APL signals VALUE ERROR and suspends the function at the point of
the reference. For example:
VZ<+FIX

7I<X
v

[1]
[2]

F[1]

aSPECIFY AXIS

F{1]

aSPECIFY AXIS

30 AXIS DOMAIN ERROR (INCORRECT OPERATION)
A

Z <« G{[K]}

[1]
[2]

7+« ¢[K] X
v

G 6
VALUE ERROR

GL1)

Z« ¢[K]

aNO AXIS

)SI

G[1]

3.12.6

Dyadic Operator
The following example defines a user-defined operator named BASE_N, which
applies a function on arguments of different number system bases.

BASE
N is a dyadic operator. When BASE_N is invoked, the user specifies
a function as the left operand ( FNC ) and the number system base of
the arguments as the right operand (¥). The resulting derived function is
ambivalent.
V

[1]
[2]
[3]
(4]
[5]
[6]
[7]

7 « {A}

(FNC BASE
N N)

0=0NC '4') / MON
>
7« (N14A) FNC NLB
Lo: » (12X < p,N) /L1
X<« [NeTl/,Z
Li: Z«(XpN)TZ
¢ = 0
MON: Z<FNC N1B
o > L0
v
aADD

101

aCHECK FOR DERIVED FUNC VALENCE
aDYADIC EVALUATION
aCHECK FOR 1-ITEM BASE
aCOMPUTE LEFT ARG TO ENCODE
aCONVERT BACK TO BASE N
aMONADIC EVALUATION

IN BINARY GIVING

(+ BASEN 2)

110

010

IN OCTAL

1011

TIMES 28

(x BASE
N 8)

FEET 3

BASE
N 3

3
INCH MINUS 2
12)

FEET 9

INCH

VAX APL Users Guide

3-41

User-Defined VAX APL Operations
3.13 Debugging Operations

3.13 Debugging Operations
APL provides several features that help you find logic errors in the operations

you write. These features include the following:
Feature

Description

Status Vector

Reports on the state of active operations in your workspace (see
) ST in the VAX APL Reference Manual)

Trace Vector

Reports on the execution of designated lines of operations (see
OTRACE in the VAX APL Reference Manual)

Stop Vector

Halts operation execution before designated lines are executed
(see 0STOP in the VAX APL Reference Manual)

[IMONITOR

Reports on execution counts and CPU times of designated lines

OWATCH

Reports references and modifications to variables (see the
VAX APL Reference Manual)

)STEP

Executes individual lines of an operation one at a time (see the
VAX APL Reference Manual)

of operations (see the VAX APL Reference Manual)

3.13.1

Suspending Operation Execution
When you debug an operation, you often need to be able to stop its execution

and examine its environment before the normal completion point. Operation
execution can be suspended before normal completion by means of any of the

following:
®

An error report generated by APL (see JERROR in the VAX APL Reference
Manual)

An attention signal generated by the user

The 0STOP system function (see the VAX APL Reference Manual)

The OBREAK system function (see the VAX APL Reference Manual)

When operation execution is suspended, APL displays the name of the
suspended operation and the line (and statement) that was being executed.
APL then begins a new line, indents six spaces, and awaits input in immediate

mode.

While an operation is suspended, its local variables remain active. (Note
that the arguments and operands to a user-defined operation are also local
variables.) You can examine those variables, or you can specify new values for
them by using an immediate-mode assignment.

3-42

VAX APL Users Guide

User-Defined VAX APL Operations
3.13 Debugging Operations
To determine the contents of an operand whose value is a function, use the
OVR system function. VR returns a character representation of the value of
its argument (for more information, see the VAX APL Reference Manual). 1f
you attempt to display an operand without using OVR , APL executes it. If
the operand is a variable, APL displays the value. If the operand is a nonniladic function (system or user-defined), APL signals SYNTAX ERROR because
it expects one or more arguments to accompany the function on the command
line. For example:
V

Z «

(LO UOP)

[1]

/< LO B

[2]

aMONADIC OPERATOR

aJOP APPLIEFS LO TO B
a0

®/

JOP

LOG

UNDEFINED

15 DOMAIN FRROR

UOP[1]

Z« LO B

aUOP APPLIES LO TO B

aDISPLAY B

AATTEMPT DISPLAY OF OPERAND
L0

7 SYNTAX ERROR (NON-NILADIC FUNCTION HAS NO ARGUMENTS)
Lo
A

UVR

'"LO!

®/

You can use any editor to display an unlocked pendent, suspended or monitored
operation, but you cannot use an editor to modify an operation while it
is pendent. However, you can use the v editor to modify a suspended or
monitored operation, with the following restrictions:

You cannot do any editing that will cause any line number to change.

You cannot edit the operation header.

You cannot add, delete, or change any labels.

A suspended operation remains active until you terminate or clear it from the
state indicator. You can resume execution at any time by entering:
~line-number

where line-number identifies the line at which execution is to be continued.
Note that the OLC system function contains the line number of the line
where execution was suspended. Therefore, ~ [ILC restarts the suspended
operation at the beginning of the line that was interrupted, ~0LC+1 restarts
the operation at the line following the line that was interrupted, and so on.

VAX APL Users Guide

3-43

User-Defined VAX APL Operations
3.13 Debugging Operations
To exit from a suspended operation (and to remove it from the state indicator),
enter a branch to line 0, as follows:
>0

To terminate a suspended operation and all preceding pendent operations,

enter a bare branch (the branch function without a line number):
-

You can also use )SIC or ORESET to clear the state indicator. However, these
commands clear all suspended and pendent operations while bare branch
clears only the most recent suspended operation and its accompanying pendent
operations.

3.13.2 Examining the State Indicator
The state indicator is a vector in your active workspace that includes
information about the status of all the active operations in the workspace.
You can examine the state indicator by specifying the ) SI system command

(see the VAX APL Reference Manual for more information).
You can use the )SINL or ) SIS system commands (see the VAX APL Reference

Manual) to obtain a more extensive display of the state indicator. In addition
to returning the information displayed by ) SI, ) SINL returns a list of local and

dummy variables for each operation, as well as the current line being executed
by the execute function. )

SIS displays the line that is currently being executed
and the argument expression of any pendent execute functions. For example:
VZ<«AFB;[0I0;q

[1]
[2]
[3]

L:
aLABELED LINE
OBREAK 'LINE 2 OF F?
Vv

(1]
[2]

S
¥

V R

[1]
[2]
[3]
[4]

3-44

aNOTE F IS A LOCAL

VARIABLE IN S

q
A
F«T 15
v
V

[1]
[2]
[3]

§:F

F«<T X

F«+5-pX
V¥

VAX APL Users Guide

aNOTE F IS A LOCAL PARAMETER IN T

A
AaLINE 2 WILL CAUSE ERROR

User-Defined VAX APL Operations
3.13 Debugging Operations
AEXECUTE F (WHICH WILL SUSPEND) AND
a THEN R (WHICH EXECUTES S WHICH EXECUTES)
a
1

T WHICH SUSPENDS)

LINE 2 0 FF
R

15 DOMAIN ERROR (DIVISION BY ZERO)
aLINE 2 WILL CAUSE ERROR
T[2] Fe:b5-pX
A

)SI

re2]

S[3]
R[1]

FL2]
T(2]

~ F X

S[3]

R[1]
F[2)

2 @ 1I0 B AL

)SIS

T[2]
S[3]
R{1]

F[(2]

% F«:5-pX
F<«T

aLINE 2 WILL CAUSE ERROR

= (OBREAK

'LINE 2 OF F'

The state indicator listing displays global and local operations in the order
in which they were most recently active, and, for each operation, the number
of the last line executed. Thus, in the preceding example, function 7 was
suspended during the execution of line [2], which was called in line [3] of
function S, which was called in line [1] of function R. In addition, prior to this
sequence of calls, function F was suspended during execution of line [2].
Suspended operations in the ) ST display are marked by a star () following
the name and line number. The other operations in the list are pendent; that

is, they are awaiting return from another operation.

In the above example, note that the current value of the symbol F is a value
that is local to the function 7; the variable F in function S and the global
function named F are currently inaccessible:

The ) ST listing also indicates pending quad-input requests, as well as execute
operations ( 1XQ or ¢) that have been invoked. Continuing the preceding
example:

VAX APL Users Guide

3-45

User-Defined VAX APL Operations
3.13 Debugging Operations
SI+{]

0xQ

")SI!

0Xe

0
T[2]
S[3]

R[1]
F[2]

You can clear the state indicator by ending the execution of the suspended

operations in the list. There are several ways to accomplish this:
*

Use the )SIC system command.

Type a bare branch (+) for each operation marked by a star.

Use the ORESET system function (see the VAX APL Reference Manual) to
clear the state indicator completely.

Save the active workspace, then clear and copy it again.

When the state indicator is clear, there is no output when ) ST is executed.

3.13.3 The Trace Vector
When debugging, you may find it helpful to obtain a printout of intermediate
results of operation execution. The trace vector allows you to print the values
computed by one or more operation statements each time those statements
execute.

To set the trace vector, use the OTRACE system function (see the VAX APL

Reference Manual). You can set the trace vector either in immediate mode or
within an operation. Each time a statement on one of the line numbers you

specify executes, the following information is displayed in the order shown:
*

The operation name.

A bracketed statement line number, for the first or only statement on the

line; for subsequent statements, the line number, a ¢, and the statement
number, all in brackets.

The final value returned by the statement.

You may set the trace vector within an operation to aid in selective tracing.
You may, for instance, want to initiate tracing if certain conditions are in effect

and disable it when a specified value exceeds a defined maximum.

3-46

VAX APL Users Guide

User-Defined VAX APL Operations
3.13 Debugging Operations

In the following example, lines [1], [2], and [3] of function F are traced:
V

12 0 Lu

[1]
[2]

[3]
[4]

26 ¢ 55
v
2

3 [OTRACE

'F!

F
12

F[1]

u4u

F[102]
F[2]

-3

F[3]1

F[302]

If the statement being traced is a branch statement, the value printed is the

line number to which control is passed by the branch.

To trace all the statements of an operation, enter the following:
(tN)UTRACE

'F!

where N is a number at least as large as the number of statements in F.
You can also trace the end of an operation—that is, after the last statement
executes but before the operation exits—by specifying line number [0], as
follows:
0

UTRACE

'F'

To disable the trace vector, enter the following:
(10)JTRACE

'F!

To examine an operation’s trace vector, use TRACE in its monadic form; APL
returns an integer vector representing the line numbers being traced. For
example:
OTRACE 'F'
4

The trace vector setting is saved with the workspace. Note that the trace
vector setting is associated with lines of APL code, not with specific line
numbers; the lines to be traced are not affected by the v editor. Operation
lines set to be traced before the editor is invoked are still set to be traced after
the editing session is completed (provided the line has not been modified), even
though some of the lines to be traced may have new line numbers. Note that
each of the following system commands or system functions clears the trace

VAX APL Users Guide

3-47

User-Defined VAX APL Operations
3.13 Debugging Operations
vector: 0FX, OMAP, and )EDIT. Locking or replacing an operation for which a

trace vector is defined or clears the trace vector.

3.13.4 The Stop Vector
The stop vector allows you to suspend execution of an operation at
predetermined points. While the operation is suspended, you can examine
its environment. To set the stop vector, use the 0STOP system function (see the

VAX APL Reference Manual).

The syntax of the stop vector is similar to that of the trace vector. For example
the following stops execution of the function F before lines [4], [6], and [7]:
4

7 OSTOP

'F!

You can set the stop vector either in immediate mode or within an operation.

When you execute the operation, the stop vector suspends execution at the
first line number you specify, and then displays the operation name and the
line number. You can resume execution by typing a branch to the desired line
number or to OLC . The stop vector then suspends execution at the next line

you have specified.
Each time operation execution is suspended because of a stop bit, APL signals
STOPSET . Be careful if you want to set stop bits in operations that use OTRAP
(see the VAX APL Reference Manual); the STOPSET error will initiate execution
of the OTRAP expression.

To examine an operation’s stop vector, use (JSTOP in its monadic form; APL
returns an integer vector representing the line numbers at which execution is

to be stopped. For example:
USTopP
4

'F!

The stop vector setting is saved with the workspace. Note that the stop vector
setting is associated with lines of APL code, not with specific line numbers;
thus, the lines to be stopped are not affected by the v editor. Operation lines
set to be stopped before the editor is invoked are still set to be stopped after

the editing session is completed (provided the line has not been modified),

even though some of the lines to be stopped may have new line numbers. Note
that each of the following commands or functions clears the stop vector: Jrx,
OMAP, and )EDIT. Locking or replacing an operation for which a stop vector is

defined clears the stop vector.

3—-48

VAX APL Users Guide

User-Defined VAX APL Operations
3.14 Examples of Error Trapping

3.14 Examples of Error Trapping
Error trapping allows you to handle errors in user-defined operations in the

same way that APL handles errors in primitive functions, that is, by informing
the caller that the function failed and explaining why.
Normally, if APL detects an error while executing an operation, it suspends

execution and prints the error information on the terminal. Error trapping
enables you to gain control when an error occurs so that you can prepare
alternatives to the default error processing.

The following system variables and system functions help you create your own

error-handling routines. They allow you to determine where errors occur and
why, and to halt operation execution, check the logic flow, and then resume
execution.

The OTRAP system variable—You use [JTRAP to gain control when an error
occurs. It contains an APL expression to be executed if an error occurs
during execution of a user-defined operation. The expression to be executed
often is a branch to an error-handling routine.

The O0SIGNAL system function — Indicates that an error occurred. You can
use it in your error-handling routines to display a standard APL error
message or a user-defined error message.

The OERROR system variable — Contains the text of the error message for
the last error that occurred.

The OBREAK system function — Suspends operation execution, prints the

value of its argument, and returns control to immediate mode. Often used
as the last statement in an error-trapping routine, to be executed if the
error is not one of the errors that the routine checks for. Note that OTRAP
cannot trap an operation suspended with JBREAK .

For more details on these system functions and system variables, see the
individual descriptions in the VAX APL Reference Manual. The following
sections give three examples of error-trapping techniques.

3.14.1

System Variable Change
In the first example, a trap is set to ensure that the index origin is set to 1.
If an error occurs during operation execution, APL ¢« executes the expression

associated with OTRAP . In this case, the expression transfers control to label
10, where APL checks whether 110 is equal to 0. If 070 equals 0, APL
proceeds to label SET and resets 170 to 1. Control is then transferred to label
p1v , where APL executes the expression again, this time with 070 set to 1.

VAX APL Users Guide

3-49

User-Defined VAX APL Operations
3.14 Examples of Error Trapping
V

[1]
[2]
[3]
[4]
[51
[6]
7]
[8]
[9]
[10]
[11]
[12]

ZI<A DIVIDE B;

[OTRAP

ATHIS PROGRAM TAKES A NUMER, A,
e AND DIVIDES IT BY 1B,
REXAMPLE: 2 DIVIDE 3 WILL RETURN A
a 3-ITEM VECTOR OF (2:1), (2:2), 2+3
[OTRAP<«'» IO
DIV:Z<«A+1B
-0
I0:~(0=0I0)/SET
[OBREAK 'DIVIDE ERROR!
SET:0I0<«1
> DIV
v
0I0+«0
25 DIVIDE 5

12.5

8.333333333

6.25

UERROR
15 DOMAIN ERROR

DIVIDE[6]

(DIVISION BY

ZERO)

DIV:Z+«A+1B
A

010
1

Notice in this example that APL executed the function even though 010 was
set to 0. JERROR contains the error that occurred, but the trap handled the

error condition. Note that (170 is now set to 1.
The value of (10 is all that is checked by the error-trapping routine. If another
error occurs, the JBREAK system function is executed (line 8), thus suspending

execution and returning control to immediate mode. For example:
"A'

DIVIDE 5

DIVIDE ERROR

HERROR
15 DOMAIN ERROR
DIVIDE[6]

(INCORRECT TYPE)

DIV:Z<A+1B
A

OBREAK prints the argument you supplied and suspends execution.

3.14.2

User-Defined Error Messages
The next example involves three functions: MASTER, ERROR , and
SNIGGLE .MASTER takes a scalar or a vector argument, adds 50 to each
item, and passes the vector or scalar to SNIGGLE.SNIGGLE tries to turn the

argument into a square matrix. If the argument cannot be squared (its shape
does not have an integer square root), SNIGGLE signals the user-defined error
550 NOT SQUARE and exits back to MASTER.MASTER has a trap set to send
errors to the function ERROR . Here are the functions:

3-50

VAX APL Users Guide

User-Defined VAX APL Operations
3.14 Examples of Error Trapping
V

Z«MASTER

VECTOR;0TRAP

[1]

OTRAP«'ERROR ¢ ~»[LC"

[2]
[3]
[4]
[5]
[6]
[7]

aMASTER ADDS 50 TO EACH ITEM IN VECTOR.
aSNIGGLE MAKES THE VECTOR SQUARE.
SNIGGLE VECTOR+50
alF IT REFUSES TO BE SQUARED, SEND IT TO ERROR.
J+<MATRIX
v
V

SNIGGLE

[1]

VEC;0OTRAP

aTURNS A

VECTOR INTO A SQUARE MATRIX;

alF THE VECTOR WON'T GO, SIGNAL THE CALLER.
OTRAP«'+SNIG'
MATRIX«(((pVEC)*0.5),(pVEC)*0.5)pVEC

[2]
[3]
[4]
[5]
[6]
[7]

-0
SNIG:
v

[1]

+('550"'#

[2]

A<[(pVECTOR)x0.5

'"NOT SQUARE'

[SIGNAL 550

ERROR:A

3+[FRROR)/BREAK

[3]

aMAKE VECTOR VALID,

[4]

a TRY AGAIN.

THEN RETURN TO MASTER TO

EXECUTION RESTARTED BY SECOND

[5]
[6]

VECTOR<VECTOR,
( (A%2)-pVECTOR)p0

n STATEMENT IN MASTER'S TRAP ARGUMENT (-[LC).
¢ -0

(7]
[8]

BREAK:
v

[BREAK '"INVALID ARGUMENT'

A sample execution of MASTER is as follows:
MASTER
51

560

UERROR
550 NOT SQUARE

MASTER[4]

SNIGGLE VECTOR+50
A

)SI

(There 1s no output)

This is what happened:

MASTER is called with a vector that is not square, 18.

MASTER sets up the localized OTRAP.

MASTER calls SNIGGLE with the argument 50+ 1 8.

SNIGGLE sets up its localized 1TRAP.

At SNIGGLE[u4], execution of the expression at line [4] results in a DOMAIN
ERROR, thereby invoking the error trap.

VAX APL Users Guide

3-51

User-Defined VAX APL Operations
3.14 Examples of Error Trapping
*

The expression associated with JTRAP is ' >SNIG', so ¢« [OTRAP redirects
execution to line [6].

At this point, JERROR contains the DOMAIN ERROR. At line [6], SNIGGLE
uses JSIGNAL to set JERROR to the user-defined error message.

[SIGNAL terminates execution of SNIGGLE and forces an error at

MASTER[ 4], where SNIGGLE was called.
o

At MASTER[u4], error trapping is invoked. (Note that MASTER is on top of

the ) SI stack now.)
®

[TRAP 1s equal to ' ERROR ¢ ~[JLC', so ¢« [ITRAP executes the function

ERROR. (Note that JLC currently is line [4], where the error occurred.)
e

The function ERROR checks whether [JERROR contains error number 550. If
it does not, FRROR breaks to the terminal for assistance.

®*

The function ERROR corrects error 550 by extending the argument VECTOR

with enough zeros to make it square.
®

FERROR returns control to MASTER, where the second statement in the

argument to the O0TRAP transfers control to 0L ¢, which equals 4.
*

Execution of MASTER resumes, this time with a valid argument. Because

the error was corrected and the function was restarted, the state indicator
1s clear.
The following illustrates what happens when MASTER is executed with an

invalid argument that FRROR cannot fix:
MASTER

'ABC'

INVALID ARGUMENT

UERROR
15 DOMAIN ERROR
MASTER(4]

(INCORRECT TYPE)

SNIGGLE VECTOR+50
A

)SI
ERROR[7]

]

MASTER[4]

)SI
MASTER[4]

In this example:
®

MASTER tries to invoke SNIGGLE with ' ABC'

+ 50. A DOMAIN ERROR

results.
*

3-52

Execution of the trap expression invokes the function ERROR.

VAX APL Users Guide

User-Defined VAX APL Operations

3.14 Examples of Error Trapping
*

Because JERROR does not contain error number 550, the function ERROR

transfers control to the label BREAK.
*

The OBREAK system function displays its argument and suspends the
EFERROR.

The )SI display indicates that FRROR is suspended at line [7], MASTER is
suspended at line [4], and there is an ¢ execute (of JTRAP) pending.

A bare branch removes ERROR and the ¢ function from the state indicator.
The trap expression is never completed; APL leaves MASTER suspended at
lIine [4].

3.14.3

Execute Trap Expression
In the next example, the function F calls the function ¢ to perform matrix
inversion. Notice what happens when a DOMAIN ERROR in G triggers execution

of the trap expression (+4) in the calling function, F:
V

I«F A

[1]

[OTRAP«

[2]
(3]
[4]
[5]
[6]
(71

<G A
=0
"MATRIX INVERSION ERROR, MATRIX WAS:
4
[ERROR
v
V

'-4!

7I«G 4

[1]

Z<HA

[2]

A«2

1E20 0 0

1F 20

X<F A
MATRIX INVERSION ERROR,
120

0F0
11

MATRIX WAS:

QF0

1E 20
VALUF FERROR

F[2]

(FUNCTION RESULT UNDEFINED)

7I«G A
A

VALUF ERROR

(FUNCTION RESULT UNDEFINED)

X<F A
A

)SI

There 1s no output

This is what happened:
e

F[1] sets OTRAP to go to line [4], where inversion errors are reported.

F[2] calls ¢ with the singular matrix 4.

VAX APL Users Guide

3-53

User-Defined VAX APL Operations
3.14 Examples of Error Trapping
G[1] gets a domain error, which invokes error trapping.
OTRAP is set to the global value ' ~u4', so APL tries to do « JTRAP and go
to line [4].

There is no line [4] in G, so G exits back to F[2], without setting its return
value for Z.
APL signals the following error:
11

VALUF ERROR

F[2]

(FUNCTION RESULT UNDEFINED)

I«G A
A

APL then invokes error trapping, which again does ¢« [JTRAP and goes to
line [4].

The message at line [4], the value of 4 at line [5], and the unexpected
OERROR at line [6] are printed.

F exits but never sets its return value Z. Therefore, APL signals the
following:
11

VALUE ERROR (FUNCTION RESULT UNDEFINED)
A<F A
A

3.15 Programming Considerations for VAX APL
The following subsections describe methods you may want to consider as you
use APL.

3.15.1

Speed Optimizations in VAX APL Primitives
The behavior of the primitive functions listed below has been optimized to
produce a result in the least amount of time. Sometimes the optimization
occurs on a subset of all possible arguments to the primitive, based on rank
(for example, vector versus general array) or internal type (Boolean, integer,
floating-point, or character).
118B,12 &B, and 2 1 § B for any matrix
B

These expressions with the transpose (&) function are used for three
purposes:

3-54

—

To select the diagonal items: 1 1 & matrix

—

To derive the identity function: 1 2 & matrix <+ matrix

—

To build an ordinary transpose: 2 1 & matrix <+ & matrix

VAX APL Users Guide

User-Defined VAX APL Operations
3.15 Programming Considerations for VAX APL
A/ B for Boolean singleton 4 and any array B

This expression with the slash (/) operator is often used in branching (- 4

/B). When 4 is 1 (true), the control of a user-defined operation moves to the
label specified in B. Otherwise, the control moves to the next statement.
Two common conditional forms include the following:

Boolean-singleton [ label

Boolean-singleton p label

Ap B where A is a Boolean scalar or an integer scalar equal to 0 or 1
This expression is often used with branching; see slash (/) above for more

explanation. 1p B selects the first item of B and 0p B creates an empty
vector of the same type as B.
A0 and Ax1 and 4*2 for any array
4
By definition, 40 is always 1. 4x1 requires no computation since 1 is
the exponential identity item: (4x1 «+4). 4x2 is computed as 4xA since

multiplication is faster than exponentiation.
A, B where 4 and B are either singletons or vectors
This expression shows the optimization of two frequent operations:
catenating one item onto the front or back of a vector, and catenating

two vectors together.

f/ B where fis ~ or v function, and B is a boolean vector
The result of these expressions is always 1 or 0. When B is a Boolean

vector, the APL interpreter is often able to evaluate the result before
looking at all the items contained in B.

For A / Boolean-vector, the result is 0 as soon as an item in the vector is 0.

When all items are 1, the result is 1.
For v / Boolean-vector, the result is 1 as soon as an item in the vector is 1.
When all items are O, the result is O.

f\B where fis A, v, <, or < and B is a Boolean vector
These expressions are often used for producing masks.
A \ Boolean-vector turns off all bits after the first 0.
v\ Boolean-vector turns on all bits after the first 1.

<\ Boolean-vector turns off all bits after the first 1 (only the first 1 is left

turned on).
< \ Boolean-vector turns on all bits after the first 0 (only the first 0 is left

turned off).

VAX APL Users Guide

3-55

User-Defined VAX APL Operations
3.15 Programming Considerations for VAX APL
Since these expressions often use numeric vectors as arguments, VAX APL
1s optimized to perform the operation quickly.
+ / num is the sum of the numbers in num.

x / num 1s the product of the numbers in num.
[ / num is the largest number in num.
| / num is the smallest number in num.

A.:B and AeB where 4 and B are of the same type and either Boolean,
character, or integer
A1 B finds where B isin A.

A ¢ B determines which items of 4 are in B.

Since the comparison technique is exact (and not fuzzy, see OCT in

VAX APL Reference Manual), the APL interpreter makes quick comparisons
between the items of the arguments.
e

An.=B and Av . 2B where 4 is a character matrix and B is a character
vector shorter than 65,536 characters

This expression is used to look up a string in a table.
An . =B determines which rows of 4 are equal to B.
Av . #B determines which rows of 4 are not equal to B.

Ao .fB wherefis <, <,=,2>,>,0r# and A4 and B are either character or
integer arrays

These expressions are often used for producing masks. They build tables of
the comparisons of all items of 4 versus all items of B.
e

Ao.+B and A-.xB where 4 and B are any numeric arrays
These expressions are often used for building addition and multiplication
tables.

Ao .xB for any array 4 and Boolean array B

This expression builds a table of 4 versus B that contains a 1 wherever
B contains a 0 and contains the item of 4 where B is 1. Because of the
multiplicative identity in the vacant spots (flagged by the zeros in B), the

table is useful as a mask that will be multiplied times another array.
e

oppB and 4/ 1B are handled as special cases.
o p B 1s the rank of B.

A / 1 B determines the indices into B of where the 1s are in 4. (See JOM 1In
the VAX APL Reference Manual.)

3-56

VAX APL Users Guide

User-Defined VAX APL Operations
3.15 Programming Considerations for VAX APL
®

AfB wherefis+,-,<,<,=,2,>,0r

and4 and
B are either Boolean or

integer scalars
e

A+B and A4 B where B is a scalar or vector

A/ B where either 4 is a Boolean singleton or vector and B is any array, 4

1s an integer singleton and B is any array, or A is an integer vector and B
1s a singleton
®*

0¢B «+> B

In 4¢ (k] B for any conforming 4 and B, let L be (o B) [ K1) (The length
of the axis being rotated). Then, if L is 1, or 4 | L is O, the result is B.

3.15.2

Space Considerations in VAX APL
This section describes how APL allocates and deallocates memory from VMS.

It also describes techniques for reducing the amount of memory required by a
workspace.

APL allocates memory from VMS dynamically as you create objects in a
workspace. The memory remains allocated when you reduce the size of an
object or even when you expunge an object from a workspace. You can release
this unused memory by performing the following steps:
®

)SAVE the workspace. The saved version does not contain the unused

memory. If you clear the SI stack (with the ) SIC command) before the

) SAVE, you release additional memory.
®
*

)CLEAR the workspace. A clear workspace has no allocated memory.
)COPY the entire workspace. The copied workspace does not contain
symbols that have no values (unless a symbol is referenced in a user-

defined operation).
*

)SAVE the smaller version of the workspace.

In addition, there are several system variables that can occupy a great deal of
storage in the workspace. These are as follows:
®

[ERROR—the last error message

[L—the name of the last variable that hit a watchpoint

[ R—the previous value of a watched variable

You can make more memory available to APL by setting each of these system

variables to the empty character array (' ' ). This value takes up the least
amount of memory possible.

VAX APL Users Guide

3-57

User-Defined VAX APL Operations
3.15 Programming Considerations for VAX APL
) NMS reports all of the symbols in the symbol table. If the name class of a
symbol is 0, it has no previous value, even though the symbol table entry uses
memory. Symbols that have a name class of 0, which are not referenced by a
user-defined operation, can be released from the workspace by following the
steps listed in the preceding description.

3.15.3

Efficient Uses of VMS Subprocesses
There are four APL system commands that spawn VMS subprocesses: ) Do,
YDROP, )LIB, and ) PUSH.

Each time you use )D0, )DROP, /CONFIRM, or ) PUSH, APL creates a subprocess,
uses the subprocess, and then stops it.
Each time you use )LIB or )DROP (without specifying the /CONFIRM qualifier),
APL creates a subprocess that remains active for the remainder of your APL
session. If you continue to use either of these commands, you do not incur the
additional overhead required to spawn a new subprocess.

3-58

VAX APL Users Guide

4
The Report Formatter
The OFMT system function allows you to combine and reformat character and

numeric data, and to output the data as a character matrix. Typically, the
character matrix represents a report—a summary of data generated when

VAX APL was used to solve a problem. JFMT edits the data as it is moved
to an output field. For example, OFMT fills or erases zeros in numeric fields;
rounds numeric data; and inserts commas, dollar signs, and other text where
appropriate.

The OFMT system function has the general form:

format-phrases OFMT {array |

(array; array; ... )]

The right argument is either one array or a list of arrays of any type or rank.

If the argument is a list, it must be surrounded by parentheses and the arrays

must be separated by semicolons.
The right argument may also be an enclosed array of depth 2 which is in the
vector domain and its items are simple homogeneous arrays. Each item of the
vector 1s treated in the same manner as an element of a list type argument.
The left argument is a character vector composed of one or more format

phrases of the form described in Table 4-1, Section 4.1.3. The phrases must be

separated by commas.
OFMT combines the data from all of the arrays in the right argument and
arranges 1t as a single matrix whose columns are then formatted according to

corresponding format phrases specified in the left argument.

VAX APL Users Guide

4-1

The Report Formatter

For example, OFMT could combine two arrays and format the result as follows:
J«FIRST<«2

123

O«SECOND<3 2p ¢

'12,13,15,17,1I8' [OFMT (FIRST;SECOND)
1

Because the phrases in the left argument control how the columns of data are
output, and because there are five target columns in this example, the left
argument to the OFMT function contains five format phrases:
'12,13,15,17,18" (QFMT(FIRST;SECOND)

The format phrase I2 governs how the first target column from the reformatted
right argument is output, phrase I3 affects the second target column, and so
on (see Section 4.1 for an explanation of format phrases).
Note

Semicolons in the right argument do not function as output catenators;
they merely separate the arrays that make up the right argument.
When it contains more than one array, 0FMT’s right argument must be
surrounded by parentheses, to distinguish its semicolon list from lists
containing the output catenator.

4.1

Format Phrases
The left argument to OFMT is a character string that consists of one or more
format phrases that govern how corresponding target columns in the right
argument are output. The format phrases must be separated by commas.
Format phrases have the form:
[repllqualsiitype[width].digl]

4-2

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases
A number for rep (repetition) specifies that the format phrase is to apply to

that number of consecutive target columns in the right argument. Thus, using
the repetition parameter, the format phrase
'13,13,13,13,I3,F9.2'

OFMT

(NUMS;TOTALS)

can be represented as:
'513,F9.2'

[JFMT

(NUMS;TOTALS)

The quals (qualifiers) parameter refers to one or more of the format phrase

modifiers called qualifiers and decorators (see Section 4.1.5). For example,
the qualifier L. means that the data fields in the target column should be

left-justified in the OFMT output:
TOTALS«479.59
'LF9.2,F9.2"
479.59

29.99

29,99
OFMT

12799.50

1444,09

325,88

(TOTALS;TOTALS)

479.59

29.99

12799.50

444,09

1444,09

325.88

The type of a format phrase refers to the type of the data to be formatted.
The possible types are identified in Table 4—1 (see Section 4.1.3). Some of the
more commonly used types are I, for integer data; F, for fixed-point data; E, for
floating-point data; and A, for character data.

The width is the width in the OFMT output of the values in the corresponding
target column. For example, the format phrase 75 means that each of the

integers in the target column is to be five characters wide in the QFMT output.
The dig (digits) parameter refers to the number of decimal places (fixed-point

data) or significant digits (floating-point data) to be included in the [JFMT
output. For example, the format phrase 8.2 means that the fixed-point data

should have two decimal places in the OFMT output.

4.1.1

Too Few or Too Many Format Phrases
If there are more format phrases in the left argument than target columns in
the right argument, the extra format phrases are ignored. If there are fewer

format phrases than target columns, the format phrases are reused starting
with the leftmost phrase. For example:

VAX APL Users Guide

4-3

The Report Formatter
4.1 Format Phrases
1.27 305.25
43 586 1289

SUBTOT«24.29
ONHAND<112 7

297.98

44.59

TOTALS+279.59 29,19 2799.50 1444.09 325.88
'F8.2,I5" OFMT (SUBTOT;ONHAND;TOTALS)
279.59

24,29

112

1.27

29.19

3J05.25

2799.50

297.98

586

1444.09

Ly,59

1289

325.88

Here, the format phrase F8.2 affected the first target column (the values in
SUBTOT ), the phrase I5 governed the output of the second target column (the
values in ONHAND ), and then the first format phrase, F8.2 , was reused to
affect the output of the third target column (the values in TOTALS ).

4.1.2 Treatment of Empty Arguments
If OFMT ’s left argument is an empty character array, APL signals a LENGTH
ERROR
.

In general, empty items in the right argument’s semicolon list are ignored. If
the right argument is an empty array, 0FMT ’s result is an empty character
matrix. For example, the argument (5 ;;7) is equivalent to (5;7) . However, if
the number of columns in an empty array is not zero, the appropriate format
phrase is applied, as in the following example.
NOCOLS+1

0p1

NOROWS<0

'I5'

OFMT (5;N0COLS;7)

v75"

OFMT (5;NOROWS;7)
7

OFMT

(

)

'I5"

'I5" OFMT ()

'I6"

OFMT 0

'I6'

OFMT 4 0p0

'I5"

OFMT (2 0p0;3 0p0)

4-4

VAX APL Users Guide

4p0

The Report Formatter
4.1 Format Phrases

4.1.3

Format Phrase Types
The format phrase types identified in Table 4-1 can be organized into two
categories: those that control the output of a target column from the right
argument, and those that are not associated with a target column.

The format phrase types A, E, I, F, G, and Y are in the first category. They
determine how the values in a target column are output. The format phrase
types T, X, and literal are in the second category. Types T and X affect the
output positioning but not the content of data fields from the right argument,

and type literal outputs literal text.
Table 4-1

Summary of Format Phrase Syntax

Phrase

Type of Data

[repll [qualsll A width

Character

[repll lqualsl E width.dig

[repl [qualsl F width.dig

4.1.3.1

Floating-point with exponent

Fixed-point

[repll Iqualsl G a patterna

Picture

lrepl lquals]l I width

Integer

[repl [quals]l Y width

Byte

[repl T [colll

Absolute tab

[repl X [colll

Relative tab

lrepll a texta

Literal

Type A—Character

Data fields that are in target columns formatted by a type A format phrase
are placed in the output matrix right-justified in a field with a width specified
by the width parameter. You may use the L qualifier (see Section 4.1.5.4) to
left-justify the data in the output field. The R qualifier (see Section 4.1.5.11) is

the only other qualifier that may be used in type A format phrases.
Type A phrases format character data only. If you try to use a type A phrase to
format numeric data, APL signals DOMAIN ERROR.
Note that type A format phrases affect target columns that are exactly one

character wide. You can use the repetition parameter (rep) to apply the same
format phrase specification to a string of characters:

VAX APL Users Guide

4-5

The Report Formatter
4.1 Format Phrases
NAME<3 5o 'SMITHJONESBROWN'
4675

AMT«1999

2345

'541,16"

[JFMT (NAME;AMT)

SMITH

1999

JONES

2345

BROWN

4675

For more information about formatting character data, see Section 4.4.
4.1.3.2 Type E—Floating-Point with Exponent

Type E format phrases output numeric data values in exponential form. The
values are rounded to the number of significant digits specified by the digits
parameter (dig), and are then written in exponential form to an output field
that has a width specified by the width parameter.

For example, the format phrase £8.u4 means that the values in the target
columns are to be converted to exponential form and written, with four
significant digits, to an 8-character output field.
Exponential data values consist of two parts: the fraction and the exponent.
For example, in the number 1.25u4E3, the fraction is 1.254 and the exponent

is £3. OFMT displays the fraction in the range greater than or equal to 1 and
less than 10, or O.

OFMT uses 4 as the default exponent width: 1 character for the E, 1 character
for the possible negative symbol, and 2 characters for the exponent digits. You
can use the Wn qualifier (see Section 4.1.5.6) to reduce the default number
of exponent digits to 1 or to increase it to 3. Within the exponent part, the
exponent digits are left-justified without leading zeros or a sign (if none 1s
needed).

Note that the width specified (by the width parameter) for the output field
should be large enough to accommodate the following:

A leading negative symbol on the fraction of the number (when necessary).

A decimal point (when necessary).

The number of significant digits specified by the digits parameter.

The default width of the exponent of the number (4 unless you use the Wn
qualifier to change the number of exponent digits).

If the width specified is greater than the width of the formatted value, the
value is right-justified in the output field, and leading spaces are inserted to
fill the field. Note, however, that the value may not seem to be right-justified
because any unused positions in the exponent are output as spaces:

4-6

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases
O0«0UT<«'F10.u4"

OFMT 1234

,00000000001234

1.234E3

1.234EF
11
p
2

OUT

Two spaces were included following the 3 in the first output value because the

default field width for the exponent of the number was 4.
If the width specified is too small, the formatted value is output as a field of
stars:
"E8.4,E9.4"

[OFMT

p1254

*kxxxxkxx1,25U4F3

Here, a minimum of 9 character positions was needed to write 1254 in
exponential form: 1 for the decimal point, 4 for the significant digits, and the

default 4 characters for the exponent. If the right argument had been ~ 1254,
10 character positions would have been needed for the formatted output.
The qualifiers B, K, L, O, R, S, and W are permitted with type E format
phrases. Table 4-2 lists the type E format phrases.
Table 4-2

E Format Phrases

Format Phrase

Value in Target Column

Formatted Result’

E10.4

24,414

A2.441ELAA

E10.4

T 24,415

T2.442FE1AA

E10.5

24,415

X Kk ok ok ok ok ok ok ok K
T2.4415FE1A

W1E10.5

T 24,415

E10.2

24 . 41y

AAA2
. LELAA

LE10.2

2U, U1y

2.UE1AAAA
A

E10.3

.005555

AAS.56E
3A

Eg.2

AO.OEOAA

BE8.?2

AAAAAAAA

LE12.5

7.7000E1AAAA

K3E12.5

~77

A~ 7.7000Eu4A
A

OMZEROMES . 2

2.5

A2.5E0AA

'Note that the delta(a ) represents the space character
(continued on next page)

VAX APL Users Guide

4-7

The Report Formatter
4.1 Format Phrases

Table 4-2 (Cont.)

E Format Phrases

Format Phrase

Value in Target Column

Formatted Result’

O[ ZEROMES .2

AAAAZERO

E11.5

“1.0000E0AA

INote that the delta(a ) represents the space character

4.1.3.3

Type F—Fixed-Point

Type F format phrases output numeric data values in fixed-point form. The
data values are rounded to the number of decimal places specified by the digits
parameter (dig) and placed in an output field that has a width specified by the
width parameter.

For example, the format phrase F8 .4 means that the values in the target
columns are to be written in fixed-point form to an 8-character output field,
and rounded to four digits to the right of the decimal point.
If the value to be formatted has fewer than the number of decimal places
specified by the digits parameter, trailing zeros are added:
'FR.ut

[JFMT 123.4

123.4000

55.0000

Note that the width specified (by the width parameter) for the output field
should be large enough to accommodate:
A leading negative symbol (when necessary).

At least one digit to the left of the decimal point (the digit 0 is used if the
magnitude is less than 1 or equal to 0). (A leading negative symbol (7) is
used in place of the digit 0 when the output is a negative number.)

A decimal point (when necessary).

The number of digits (specified by the digits parameter) to the right of the
decimal point.

If the width specified is greater than the width of the formatted value, the
value is right-justified in the output field, and leading spaces are inserted to
fill the field.

4-8

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases
If the width specified is too small, the formatted field is displayed as a field of
stars:
"F8.4'

[OFMT 123.4

kK kkkkkk

55.0000

Table 4-3

F Format Phrases

Format Phrase

Value in Target Column

Formatted Resulit'

F9.u4

1254

1254.0000

F10.3

.0056

AMAAAO.O0OB

F8.u

T24L.415

T 24,4150

F8.5

24,415

Xk Kk Kk k Kk Kk X

F10.2

2U . 41y

AMNAAA2Y
41

LF10.2

24 . 415

2U LU2AAAAA

F10.3

.005555

AAAAAO.O006

F10.6

.005555

AAO.005555

F8.2

AAAAO.OO
AAAAAAAA

BF8.2

LF15.5

77 .00000AAAAAAA

K3F15.5

~77

AAAT77000.00000

OMZeroMF8.?2

2.5

AANAA2.50

OMZerollF8.2

AANAAZero

F8.6

0.1

T .1000000

'Note that the delta(a ) represents the space character

All of the qualifiers and decorators listed in Table 4-8, Section 4.1.5, are
permitted with type F format phrases.

4.1.3.4

Type G—Pattern Data

The data fields in target columns formatted by a type G format phrase are
rounded to integers and then placed in the output field as specified by the given
pattern. Each character position in the pattern corresponds to a character

position in the output field.

VAX APL Users Guide

4-9

The Report Formatter
4.1 Format Phrases

The following codes may be included in the pattern:
Pattern code

Meaning

Put a digit in this position.

7 Or z

Put a digit in this position unless the digit is a leading or trailing
zero; in that case, put a blank in this position.

any character

Put the specified literal character in this position (spaces are
permitted).

Put the @ character in this position; however, you may replace the @

character using standard symbol substitution (see Section 4.1.5.5).
This is intended primarily to allow TTY users to include decimal

points in the pattern.

The pattern ZZZZ99, for example, means that a digit from the target column
should be placed in each of the six positions in the output field, except that
any leading zeros in the leftmost four positions of the output field should be
replaced by blanks.

There should be a Z or a 9 in the pattern for each digit in the target column;
if there are more digits than Zs and 9s, the output field is filled with stars (x ).
APL signals DOMAIN ERROR if the pattern does not include at least one 9 or
one Z.

Note that type G format makes it easy to mix numeric and character data:
'G<999-99-9999>"'

[JFMT 144590701

144-59-0701

'G<79/99/99>"

OFMT 41784

4/17/84

A 7 pattern code blanks out only leading or trailing zeros, not embedded

zeros; thus, the pattern ZZ997Z77997Z has the same effect as the pattern

7.7999999977.

Literal characters (including trailing blanks) that occur in the pattern to the
right of Z pattern codes are inserted only if there are digits output to the left of
the literal. For example:
'G<$Z,22ZM>"
$1,234M

U55M

4 4M

4-10

VAX APL Users Guide

OFMT 1234 455

44 1 0

The Report Formatter

4.1 Format Phrases
You can use standard symbol substitution to change a pattern code to another

character. For example, the following substitutes lowercase f for pattern code
Z, thus allowing Z to be inserted as a literal character:
'S

<Zf>G<ZZZfF9>"

[JFMT

ZZ77F8

Note that although lowercase f assumed the function of pattern code Z,
uppercase I did not and was placed in the output field as a literal.
TTY users who need to include decimal points in their patterns can do so

by using the @ character in the pattern and then using standard symbol
substitution to replace the @ with a decimal point:
'G<ZZ.2Z>'"

.BXFMT 12

.22 IS UNDERSCORED 1Z

12.7217
'5<@.>G<Z22@7ZZ>"

,BXFMT

123

1.23

The qualifiers B, K, M, N, P, Q, R, and S are permitted with type G format

phrases listed in Table 4—4.

Table 4—-4

G Format Phrases

Format Phrase
<Z92797Z>

Value in Target Column

Formatted Result’

10101

A10101

G<Z792297Z>

101

A00101

G<Z92297Z>

9000

A0900A

G<Z92729Z>

543210

54321A

G< 729247297~

6543210

* ok ok Kk kK

G<Z7,7229.99>

47799

AA477.99

G<Z,229.99>

AAMAAO.38

G<Z,2729.99>

1234567

ok ok ok ok K Kk ok

G<Z,27Z9.99DOLLARS>

47799

AA477.99ADOLLARS

G<TOTAL IS Z27279>

1227

TOTALAISAAN1227

G<TOTAL IS 7277

428

TOTALATISA428AUNITS

UNITS>

'Note that the delta(a ) represents the space character
(continued on next page)

VAX APL Users Guide

4-11

The Report Formatter
4.1 Format Phrases

Table 4-4 (Cont.)

Format Phrase

G Format Phrases

Value in Target Column

G<TOTAL IS 777

Formatted Result’

TOTALAISAAAAAAAAA

1234

* Kk ok kkkkk
Kk kxK

G<Z7Z.99>

25.3

AAA25

K2G<27Z.99>

25.3

25.30

UNITS>

G<TOTAL IS 7277
UNITS>

1Note that the delta(a ) represents the space character

4.1.3.5

Type I—Integer

Type I format phrases output numeric data values in integer form. The data
fields in the target columns are rounded to integers and then placed in output
fields that have a width specified by the width parameter.
For example, the format phrase I7 means that the values in the target columns
are to be converted to integers and written to a 7-character output field. If
the width specified (by the width parameter) is greater than the width of the
formatted value, the value is right-justified in the output field, and leading
spaces are inserted to fill the field.
If the width is too small to accommodate all of the integer’s digits (and a
negative symbol, if necessary), then the entire output field is filled with stars.
Table 4-5

| Format Phrases

Format Phrase
18

Value in Target Column
LY3322

Formatted Result'
AAL4U3322

L43322

4y3322

LY3322

K K K
ok

221.6764

AN222

T221.6764

AT 222

.002u5

AAAAO

1Note that the delta(A ) represents the space character
(continued on next page)

4-12

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases

Table 4-5 (Cont.)

Format Phrase

| Format Phrases

Value in Target Column

Formatted Result’

ZI5

00000

BI5

ANAAA

BIS5

.00245

AAAAA

LIS

OAAAA

KuIs

50000

KuIs

* ok ok ok

O ZERO[MLIS8

2.5

BAAAAAAA

O ZERO[MLIS8

ZEROAAAA

1Note that the delta(a ) represents the space character

All of the qualifiers and decorators listed in Table 4-8, Section 4.1.5, are
permitted with type I format phrases.
4.1.3.6

Type Y—Byte Data
Type Y format phrases output the internal representation of the target data
values in hexadecimal notation.

APL stores all data internally as one of four possible data types: Boolean,
character, integer, or floating-point. Because each hexadecimal digit in the type
Y formatted value represents four bits of internal data, you need to specify an

output field width of at least 1 (representing 4 bits) for Boolean values, 2 (8

bits) for character values, 8 (32 bits) for integer values, and 16 (64 bits) for
floating-point values. (See Table 4-6.)
When integer values are formatted, the high-order bits are the leftmost bits
in the output field, and they are the first bits to be truncated if the width
specification is less than 8. The formatted integer value is right-justified in the
output field, and leading zeros are suppressed. For example, the integer value
47 is stored internally as the following:
0000002F

Thus:
'Yg'

[OFMT 47

VAX APL Users Guide

4-13

The Report Formatter
4.1 Format Phrases
Or, if you use the zero fill qualifier:
vZ2Y8'

0OFMT 47

0000002F

If you specify a width smaller than 8, the internal value is truncated on the

left. If the truncation would include any significant digits, the output field is
replaced by stars. For example:
ry2r

QFMT u7

rY1'

QOFMT u47

2F
*

When floating-point (VAX D-floating) values are formatted, they are leftjustified in the output field. The bytes are rearranged so that the sign and
exponent appear first (on the left), followed by the fraction part with trailing
zeros suppressed (unless you use the Z qualifier, which makes the value look
similar to customary binary representations of floating-point data). Thus, type
Y format floating-point values display the bits from the internal value in the
following order: bits 15 through 0, bits 31 through 16, bits 47 through 32, and

bits 63 through 48. (For details about how VAX stores D-floating values, see
the VAX MACRO and Instruction Set Reference Manual.)
Note that if one value in an array must be stored in floating-point form—
either because it was input in fixed- or floating-point form, or because it could
not be stored as an integer (because it was not in the range ~ 2147483648 to
2147483647) then all the values in the array are stored in floating-point form:
'Y8'

[OFMT

2
3

'Z2Y8'"

[JFMT

1F1,13

42200000

40800000
41000000
41400000

The qualifiers B, L, S, Z, O, and R are permitted with type Y format phrases.

4-14

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases

Table 4-6

Y Format Phrases

Format Phrase

Value in Target Column

Formatted Resuit’

rA!

TA!

A61

S 1+2% 31

* Kk Kk Kk ok kK

2147483647

JFFFFFFF

T 2147483648

80000000

Y16

T1+2%31

UFFFFFFFFEOOOOOU4

24440

AAMAASFE7C

7Y8

2444y

00005F7C

BLY8

2444y

SF7CAAAA

BLYS8

AAMAAAAAA

Y16

2.5E7

4CBEBC?2

7Y16

2.5E7

4CBEBC2000000000

ZY16

T 2.5E7

CCBEBC2000000000

1Note that the delta(a ) represents the space character

4.1.3.7

Type T—Absolute Tab

Type T format phrases are not associated with values in the right argument;
they affect only the positioning, not the format, of the next output field in the
OFMT result.

APL has an internal pointer, called the print column pointer, that references
the column that 1s to the right of the rightmost column in the output field that
received the last formatted value of the OFMT result. This pointer indicates the
leftmost position of the next field to be output.
Type T format phrases change the value of the pointer to the column specified
in the column parameter. For example:

1234

"I5'

[OFMT 1 3p1234 5566

5566

5874

"75,15,T715,I5,725,1I5"
1234

5566

5874

(OFMT 1

3p1234 5566

5874

VAX APL Users Guide

4-15

The Report Formatter
4.1 Format Phrases
The column parameter, if specified, must be an integer in the range 0 through

255. If you omit the column parameter (or specify 0), the pointer is moved to
the next column to the right of the rightmost column:
"715,1I5,75,I5,T,I5"
5566

1234

[OFMT

3p1234

5566

5874

When columns in the JFMT result are overlapped, the new values overwrite

any values written previously, except that blanks which occur as fill characters
in the new value do not overwrite the old value. For example:
OLD<1

o'THIS IS THE OLD

NEW«1

219

'21A1"

[FMT OLD

THIS IS THE OLD VALUE
'2141,T5,18,713,19"
THIS IS T2190LD

VALUE'

L4455

[OFMT

(OLD;NEW)

Vuuys5s

Note that the fill characters generated by the I8 and I9 format phrases did not

overwrite the previously written values.
If a type T format phrase moves the pointer beyond (to the right of) the
rightmost previously used column, the OJFMT result is extended with blanks:
O«RESULT<'I5,T35"'

[JFMT 12345

12345

o RESULT
1

Here, the pointer was left at column 35. Because no more values were output,

column 35 was not used and the result has 34 columns.
No qualifiers are permitted with type T format phrases. If a repetition

parameter (rep) value is specified with this format phrase, it is ignored.
4.1.3.8

Type X—Relative Tab

Type X format phrases are not associated with target values in the right
argument; they affect only the positioning, not the format, of the next output
field in the OFMT result.
APL maintains internally a print column pointer which references the column

in the OFMT result that is to the right of the rightmost column in the output
field that received the last formatted value. This pointer indicates the leftmost
position of the next field to be output.

4-16

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases
Type X format phrases change the value of the pointer by the number of

column positions specified in the column parameter (col). A negative value for
the column parameter moves the pointer to the left; a positive value moves the
pointer to the right. (A negative value may be indicated by either the minus or
the high minus sign.) For example:
'I15,X10,I5,X 10,I5"
777

999

[OFMT 1 3p777 888 999

888

When columns in the OFMT result are overlapped, the new values overwrite
any values written previously, except that blanks which occur as fill characters

in the new value do not overwrite the old value. For example:
'I5,X3,1I5,16,X
5,I5" (JFMT 1 4p555 66666
559

66666

77777 888

77888

Note that the fill characters generated when the 75 format phrase formatted
888 did not overwrite the 7s remaining from the previously written field.
If a type X format phrase moves the pointer beyond (to the right of) the

rightmost previously used column, the [JFMT result is extended with blanks:
O«RESULT«'I5,X35"

OFMT 12345

12345

oRESULT
1

Here, the pointer moved from column 6 to column 41. Because no more values
were output, column 41 was not used and the result has 40 columns.
If a type X format phrase specifies the pointer value to be less than 1, JFMT
makes the pointer value 1. For example:
"[5,X 10,16,X5,15"
2222

[JFMI 1 3p555

2222 666

666

'I5,X 10,I6,X 10,I5"

OFMT 1 3p555 2222 666

6662

The value of the column parameter in type X format phrases must be an

integer in the range ~ 255 through 255. If col has the value zero, the column
referenced by the print column pointer does not change. If the col is omitted,
the effect is as if the column parameter had the value 1.

No qualifiers are permitted with type X format phrases.

VAX APL Users Guide

4-17

The Report Formatter
4.1 Format Phrases
4.1.3.9

Type Literal
You can use the literal format phrase to insert literal data into the OFMT result.
This type of format phrase is not associated with a target field in the right

argument. The literal text surrounded by the delimiters is copied unchanged
to the output array, in the position referenced by the current value of the print

column pointer. For example:
"aTHE
THE

VALUE IS:s8,F6.3'

VALUE IS:

[FMT 2.415

2.415

The literal text may be empty. No qualifiers are permitted with the literal
format phrase.

4.1.4

Format Phrase Parameters
The format phrase type identifies the data type of the values to be formatted;

the format phrase parameters described in Table 4-7, specify additional
information about how the values are to be formatted. For example, format
phrase parameters control the output field width, the position of the values in
the output field, and the insertion of special symbols or text to the right or left
of the values in the output field.

One of the parameters specified in Table 4-7, the qual parameter, actually
refers to a series of format phrase modifiers called qualifiers and decorators.
These modifiers are listed in Table 4—8, and are further described in the
remaining sections of this chapter.

Table 4-7

Summary of Format Phrase Parameters

Parameter

Meaning

rep

The number of consecutive target columns to be affected by the format
phrase, or the number of times a parenthesized group of format phrases

1s to be repeated (to a maximum of 65534).
qual

One or more of the format phrase qualifiers or decorators listed in

Table 4-8.
width

The width in the result array of the formatted value from the target
column in the right argument. The width must be an integer in the
range 1 through 255.
(continued on next page)

4-18

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases

Table 4-7 (Cont.)

Summary of Format Phrase Parameters

Parameter

Meaning

dig

The number of decimal places (F, or fixed-point, format) or significant
digits (E, or floating-point with exponent, format) to be included in the
result array. The digit parameter’s value must be an integer in the
range 0 through 127.

column

For the T (absolute tab format), an integer in the range 0 through 255
(0 is the same as T by itself) that identifies the leftmost column that the
next formatted value is to occupy in the result array. For the X (relative
tab) format, an integer in the range ~ 255 through 255 that identifies
the number of columns to be shifted before the next formatted value is
output.

4.1.5

Format Phrase Qualifiers and Decorators
The format phrase qualifiers and decorators modify the actions of the basic
format phrase types. Each format phrase may include multiple qualifiers

and decorators specified in any order, but a particular qualifier or decorator
may appear only once in the phrase. The qualifiers and decorators that are
permitted with each format phrase type are summarized in Table 4-9.

When more than one qualifier or decorator is specified and their actions
conflict, the following rules apply:
*

The B qualifier overrides the effects of the Z, C, and O qualifiers and the

M, N, P, and Q decorators.
*

Zeros inserted because of a Z qualifier are not affected by an L qualifier.

The M qualifier overwrites the minus sign usually displayed with negative

values.

The O qualifier overrides the effects of the P and Q decorators.

The R qualifier has no effect on zeros inserted because of a Z qualifier, or

on blanks in the M, N, O, P, and Q decorators. The R qualifier, however,
does overwrite blanks inserted because of a B qualifier.

VAX APL Users Guide

4-19

The Report Formatter
4.1 Format Phrases

Table 4-8

Summary of Format Phrase Qualifiers and Decorators

Qualifiers

Meaning

For types 1, E, F, G, and Y, if the value of the item in the target

column is zero, make the field in the target column blank in the

result array.

For types I and F, insert commas between each group of three

For types I, F, E, A, and Y, left-justify the fields in the target

digits in the integer part of the formatted value.

column.

For types 1, F, G, and E, before formatting the fields in the target

S symbol pairsa

For types I, E, F, and Y, replace, in the formatted output, all
occurrences of the first character in each symbol pair with the
corresponding second character of the symbol pair. For type G,
replace, in the pattern, all occurrences of the first character in
each symbol pair with the corresponding second character of the

column, multiply the fields by the scale factor 10 n.

symbol pair.

Decorators

Mba textn
Na textn

On textn

Pa texta
Qn textn

Ra texta

For type E, use n exponent digits in the formatted output.

For types I, F, and Y, fill leading blanks in the formatted output

with zeros.

Meaning

For types I, F, and G, replace the sign of negative formatted

values with a texta placed to the left of the value.

For types I, F, and G, place text to the right of negative formatted

values.

For types I, F, G, and Y, replace formatted zero values with fext.

For types I, F, and G, place text to the left of positive formatted

values.

For types I, F, and G, place text to the right of positive formatted

values.

For types I, F, E, A, G, and Y, fill unused columns in the

formatted output with fext.

Note that text may be empty for M, N, P, and Q.

4-20

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases

Table 4-9

Valid Qualifiers, Decorators, and Paremeters for Format Types

Format
Phrase

Permitted Qualifiers

Permitted Decorators

Parameters

MNOUPI

MNOUP

QIR

widr

Kn Wn

QUR

literal

Key to Parameters
w—uwidth parameter. A value must be specified and must be a positive integer.
d—dig parameter. A value must be specified and must be a positive integer.
r—rep parameter. A value is optional, but if specified must be a positive integer or zero.
c¢—column parameter. A value is optional. If specified with the T format phrase, it must be a
positive integer or zero. If specified with the X format phrase, it must be an integer.

4.1.5.1

B—Blank When Zero

The B qualifier replaces the output field with blanks if the formatted value is
equal to zero. For example:
'F8.2"
249,54

[0FMT
0.00

'BF8.2'

p249.54

762.27

[OFMT

249,54

762.27

0.00

p249.54

6.00

762.27

6.00

The B qualifier is permitted with the type I, F, E, G and Y format phrases.
4.1.5.2

C—Insert Commas

The C qualifier inserts commas between each group of three digits in the
integer part of a formatted value. For example:
"Fi4.1,710"
12249.5

OFMT

"'CRAIWL
L, T10OFMT

12,249.,5

734214

734,214

p12249.,49

91142452.0

p12249,49

91,142,452.0

734214

91142452,15

2150

91142452,15

2150

734214

The C qualifier is permitted with the type I and F format phrases.

VAX APL Users Guide

4-21

The Report Formatter
4.1 Format Phrases
4.1.5.3

Kn—Scale Factor

The Kn qualifier multiplies the target value by the scale factor 10 n before the
value is formatted. The n must be an integer that is positive, zero, or gegative
(you can use a minus or a high minus sign to make it negative). For example:
"F10.2,710"
249.49

OFMT 1 4 p249.49 29 762,27 881124
881124
762.27
29

"K3F10.2,K27110" OFMT 1 4 p2u49.49 29 762.27 881124
88112400
2900 762270.00

249490.00

'K-4F10.2,K-3I10"
0.02

'K 50F4,2,I10'

OFMT 1 4 p249.49 29 762.27 881124
0.08

881

OFMT 20

0.00

The Kn qualifier is permitted with the type LE
F, and G format phrases. 1t 1s
particularly useful with type G, which rounds to integers.

If a value of n is too large, it may cause the scaled value to be too large to
represent:
"K50F10,2'

OFMT 20

27 LIMIT ERROR (FLOATING OVERFLOW)
'K50F10.2'

OFMT 20

4.1.5.4

L—Left-Justify

The L qualifier places the target value left-justified in its output field. For
example:
0OFMT 1 u4p249.49 29 762.27 881124
881124
762.27
29
"LF10.2,L110"' OFMT 1 4p249.49 29 762.27 881124
881124
762.27
29
249,149
'F10.2,I10'

249.49

A, and Y format phrases.
The L qualifier is permitted with the type LF,E
4.1.5.5

S—Standard Symbol Substitution

The S qualifier replaces, in the formatted value, certain occurrences of the first
character in a specified symbol pair with the second character in the pair. The
symbol pairs are placed in the format phrase immediately following the S. The
first character in each symbol pair—that is, the character to be replaced—must
be a star (+ ), decimal point ( . ), comma, (, ) or zero (0 ). The first characters
are replaced in the formatted value by the second character in each symbol
pair as follows:

4-22

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases

Replaced if it occurs as an overflow indicator for a value formatted by a type

Y,LF,G, or E format phrase.

Replaced if it is a decimal point that occurs in a value formatted by a type E or
F format phrase.
,

Replaced if it occurs in a value formatted by a type I or F format phrase that
had a C qualifier.

Replaced if it occurs as a fill character in a value formatted by a type I, Y, or
F format phrase that had a Z qualifier, or a type G format phrase that had a
9-pattern character.

For example:
"CI5'

UOFMT 1

p1234

12345

1,23U*x*xx%

'S<,.*x->CI5"

[FMT 1

'ZFg.2'

OFMT

2 p1234

2p555.66

12345

29.88

00555.6600029.88

'S<.,0x>7ZF8.,2"'"
x%*555

[OJFMT 1

2p555.66

29.88

6b*%x%x29,88

The S qualifier may also be used with the type G format phrase to substitute

an alternate character for the 9, Z, or @ pattern character. For details, see
Section 4.1.3.4.
4.1.5.6

Wn—Exponent Digits

The Wn qualifier changes the default width of the exponent digit of an
exponential value from 2 to the value specified by n. The n must be an integer
in the range 1 through 3. For example:
'E12.4"
2.495EF2

[OFMT 1 4 p249.49 267E
5 .23 99
2.670F 3
2.300F 1
9.900F1

'"W1E12.4'
2.495EF72

[JFMT 1 4 p2u49.49

267E
5 .23 99
2.300F 1
9.900F1

2.670F 3

'"W3E12.u4' [OFMT 1 4 p249.49 267E
5 .23 99
2.495E2
2.670F 3
2.300F 1
9.900F1

The Wn qualifier is permitted with type E format phrases only.
4.1.5.7

Z—Zero Fill

The 7Z qualifier inserts zeros into unused leading positions of values formatted

by a type I, F, or Y format phrase. For example:
'I8,F8.2"
777

[JFMT 1

2p777

88.8

88.80

"ZI8,ZF8.2"'
oy
el 4
W

[UFMT 1

2p777

88.8

0000077700088.80

VAX APL Users Guide

4-23

The Report Formatter

4.1 Format Phrases
4.1.5.8

M and N—Negative Left and Right Decorators

The M and N decorators insert text beside negative values formatted by a type
I, F, or G format phrase. If the M decorator is used, the text is placed to the
left of the value and it replaces the negative sign. If the N decorator is used,
the text is placed to the right of the value and the negative sign still appears
to the left of the value. For example:
'M<CREDIT>F13.2'
29.99

[OFMT 1 2p29.99 249,54

CREDIT249.,54
REMPTY

'M<>F13.2'

VALUE FOR M ELIMINATES SIGN

OFMT 1 2p29.99 249,54

29.99

249,54

'"N<CREDIT>F1iu4.,2' [OFMT 1 2p29.99 249,54
29,99 "2u49,54CREDIT

The maximum length of the inserted text is 255 characters. Note that the field
width you specify must be large enough to accommodate both the value and
the inserted text. An empty text string is permitted.
4.1.5.9

P and Q—Positive Left and Right Decorators

The P and Q decorators insert text beside positive values formatted by a type
I, F, or G format phrase. If the P decorator is used, the text is placed to the left
of the value. If the Q decorator is used, the text is placed to the right of the
value. For example:
'P<DEBIT>F13.2"' OFMT 1 2p29.99 249.54
DEBIT29.99
219,54

'Q<DEBIT>F13.2"' QOFMT 1 2p29.99 2u49.54

29.99DEBIT

249,54

O—Zero Decorator

The O decorator inserts text in place of data that has been formatted as a zero
value. The text is right-justified in the output field. For example:

2.5

'20<ZERO>F6.1,2 0<NO VALUE>I9'
ZERO
598 NO VALUE

OFMT 1 u4p

2.5

,01445

598

,499

The O decorator is permitted with type I, F, G, and Y format phrases. The
maximum length of the inserted text is 255 characters. Note that the field
width you specify must be large enough to accommodate the inserted text.

4-24

VAX APL Users Guide

The Report Formatter
4.1 Format Phrases
4.1.5.11

R—Background Decorator

The R decorator inserts text into unused portions of a formatted value’s output
field. Starting at the left, the text is repeated as many times as necessary to
fill the field. For example:
"R<-/%>I10" [JFMT 1 3p 22
~[*x=[*=-[22-/%-[/%x-333-/%-/*xUllY

333

uuiuy

The R decorator does not replace zeros inserted by the Z qualifier, nor does it
replace blanks inserted by other decorators. However, the R decorator does

replace blanks inserted by the B qualifier.
The R decorator is permitted with type I, F, E, A, G, and Y format phrases.
The maximum length of the inserted text is 255 characters.

4.2 Right Argument
The right argument is a list of simple homogeneous arrays of any type or rank.
The list must be surrounded by parentheses (unless there is only one array in
the list), and the arrays must be separated by semicolons. Missing elements

in the list do not affect the result. For example, (4;;B) is the same as (4;B).
Alternatively, the right argument may be an enclosed vector of depth 2. In
other words, the argument is in the vector domain and its items are simple
homogeneous arrays. Each item of the vector is treated in the same manner as
an element of a list type argument.

Before formatting the right argument to produce the result matrix, OFMT
combines the arrays in the list and arranges them as an intermediate matrix
1n canonical form. The successive columns (target columns) of the intermediate

matrix are formatted for the result array according to specifications in

successive format phrases in the left argument. Vectors and enclosed scalars,
for example, are treated as 1-column matrices:
TOTALS<+ 479,59

'Fg8.2"

29.99

12799.50

1uuL,09

325.88

[JFMT TOTALS

479.59

29,99
12799.50
444,09

325.88

In this example, the items in the vector TOTALS were treated as one target
column of values, that is, as a matrix with the shape 5 1. Then, the values
were output as specified by the format phrase Fs.

VAX APL Users Guide

4-25

The Report Formatter
4.2 Right Argument

Arrays with ranks greater than 2 are treated as matrices. The matrices look
the same as the original arrays would look if they were displayed without
blank lines between planes. For example:

aSTANDARD DISPLAY OF ARRAY NUMS
4 5p

O«NUMS«2
2

5
10

140

aNUMS AS RIGHT ARGUMENT

'I13,I4,1I5,I6'

UFMT NUMS

Note that each of the five columns of data in the right argument to OFMT 1s
a target column, so the left argument has five format phrases, one for each
column.

After the arrays in the list are reshaped, they are placed side by side in the
intermediate matrix.

For example, if both NUMS and TOTALS were included in the right argument to
OFMT, they would first be converted to matrices as described, and then placed
side by side to be treated as a single matrix by OFMT, as follows:

4-26

col 1

col 2

col 3

col 4

col 5

6
col

479.59

29.99

12799.50

1444.09

325.88

VAX APL Users Guide

The Report Formatter

4.2 Right Argument

col 1

col 2

col 3

col 4

col 5

col 6

Six target columns result, so the left argument to JFMT would need six format
phrases:
|
TOTALS« 479.59
NUMS«2

29.99

'13,13,13,13,13,F9.2"
1

12799,50

14u44,09

325.88

5p140

OFMT

(NUMS;TOTALS)

479.59

29.99

12799.50

1444,09

325.88

4.3 Resulit Array
The result array is a character matrix formed according to the specifications
of successive format phrases from the left argument, as applied to successive
target columns from the canonical form of the right argument. When the result
array is formed, however, the nonediting format phrase types T, X, and literal
are not associated with target columns.
If there are extra target columns, the left argument is rescanned beginning
with the leftmost format phrase. If there are extra format phrases, they are
ignored, except that the format phrase types T, X, and literal will continue to
be processed until APL encounters one of the following:
e

A format phrase type other than T, X, or literal

The end of the format string

A left parenthesis

A right parenthesis with an incompletely used repetition count

The result matrix has a number of rows equal to the longest column of the
right argument’s intermediate matrix; short columns are filled with blanks.

Within each output field in the result matrix, the data values are right-justified
uniess you use the L qualifier (except that type Y floating-point data is
normally left-justified). Negative values are output with a minus sign (APL —,

VAX APL Users Guide

4-27

The Report Formatter

4.3 Result Array
APL -, or ASCII —, depending on (ONG; see the VAX APL Reference Manual)
unless you use the M qualifier. Plus signs are not included in the formatted
output unless you insert them as literal text or via decorators.

4.4 Formatting Character Data
When you format character data, note that the target columns in the
reformatted right argument always consist of exactly one character. Because

you generally want to format a string of characters rather than a single
character, you will find the repetition parameter to be particularly useful. For
example:
TEAMS<5

'5A1Y

5p'PHILABOST.N.J.

WASH.N.Y,

[FMT TEAMS

PHILA
BOST.

N.J.
WASH.

N.Y.

Here, OFMT applied the format phrase 41 to each of the five target columns in
the right argument:
col 1

col 2

col 3

col 4

col
5

You can use the width parameter to alter the spacing of the characters in the
string:
TEAMS<5 S5p'PHILABOST.N.J., WASH.,N.Y.
"A1,A2,24A1,A3" (OFMT TEAMS
P HIL

B 08T
N

.J.

W ASH

.Y.

Note that 4 format right-justifies the character value in the output field.

4-28

VAX APL Users Guide

The Report Formatter
4.4 Formatting Character Data
One way to move a character string’s position in the output field is to use a

large value for the width parameter for the first character in the string:
TEAMS<5

5p'PHILABOST
.N.J. WASH.N.Y.

'A10,441"

[JFMT

TEAMS

PHILA
BOST.

N.J.
WASH.
N.Y.

The characters in target column 1 (P, B, N, W, N) were right-justified (by

default) in a 10-character output field.
Note that because OFMT treats vectors as 1-column matrices, applying OFMT to

a vector of characters may not yield the result you expect. For example:
OFMT

'"PHILA'

e R

'5A1"

To keep the character vector on one line, convert the vector to a 1-row matrix:
'S5A1Y

[JFMT

S5p'PHILA'

PHILA

"A1'

OFMT

,[0.5]"PHILA"

PHILA

VAX APL Users Guide

4-29

O
VAX APL Input and Output
VAX APL is an interpreter; thus, its input and output (I/O) operations can be

as simple as typing a line of input and receiving APL’s immediate response
with the appropriate output.
As you become more proficient with the language and begin to extend it
by writing user-defined operations, you probably will want to perform I/0
operations that are more complex than the I/O that occurs by default. To allow

such extended I/O capability, APL provides the following:
*

I/O system variables that facilitate terminal I/0 operations from within
user-defined operations. These variables include quad input, quote quad

input, quad del input, quad output, and bare output.

File system operations that allow you to manipulate data in external files.
These include ) INPUT, )OUTPUT, and others.

All forms of I/0 can be used either in immediate mode or within user-defined
operations; however, the I/O variables are more commonly used within

user-defined operations.

5.1

Terminal Input and Output
Input and output operations not involving external files—the default terminal

I/O and the use of I/O variables—are sometimes called terminal I/0O, because
the only I/0 device involved is your terminal.
The default terminal I/O is straightforward; you enter input from your
terminal, and APL echoes your input, beginning in column 7. If the statement
you enter does not have a quiet function as the leftmost function, APL prints

the result beginning at column 1 on the next line of your terminal. If the
statement does have a quiet function as the leftmost function, specification

(+ ), for example, APL does not display a result.

VAX APL Users Guide

5-1

VAX APL Input and Output
5.1 Terminal Input and Output
J«Ad<«25

aQUAD SPECIFICATION IS NOT QUIET

B<bU4x3

aSPECIFICATION FUNCTION WITHOUT QUAD IS QUIET

17+4 ¢ B
42

262144

APL does not control wrapping of input lines. If the system setting for your
terminal allows wrapping, input lines that are too long to be echoed as one line
on your terminal are continued (wrapped) on subsequent lines. If the system
setting for your terminal inhibits wrapping, input is not echoed on more than
one line; any characters that do not fit on one line are displayed in the last
column on the line. Thus, when the input line is complete, the last column
contains the last character entered.

You can cancel an input line before entering it (before pressing the Return key)
by entering the abort input signal. (See Section 1.9.)

5.1.1

Terminal Input Variables
The quad input (0 ), quote quad input (1 ) and quad del input (B ) system
variables allow you to request input from the terminal. When one of these
system variables appears in an expression, APL displays a prompt; the result
of any expression entered in response to this prompt becomes the value of that
system variable.

Typically, these system variables are used with the specification function (<)
so that the value of the input data is assigned to a variable. However, these
system variables are legal in any context that requires a value.

While the system is waiting for your input, you can execute a system command
or you can define or edit an operation; the input request remains pending
until you supply a value. APL cancels the input request if you do any of the
following: enter Ctrl/Z; execute one of the system functions ORESET, 0BREAK,
or 0SIGNAL; or execute a system command that changes the state of the active
workspace, that is, a ) LOAD, )XLOAD, ) CLEAR, )OFF, ) CONTINUE, )MON or
)SIC command.

To escape without entering a value, either type the right-arrow (- ) character,
or enter the abort input signal. If you are inside an operation when you escape,
the operation is suspended (unless it is locked).
Note that escaping with branch (- ) is quiet; APL simply cancels the input
request. When you escape from any of the input system variables with the
abort input signal, however, APL cancels the input request and signals INPUT
ABORTED (trappable with 0TRAP; branch (- ) is not trappable).

5-2

VAX APL Users Guide

VAX APL Input and Output
5.1 Terminal Input and Output
If the input you enter contains an error, APL prints the appropriate error
message and reissues the input prompt.

5.1.1.1

Quad Input
Quad input (0 ), also known as evaluated input, allows you to request input

from the terminal. The default prompt is [0:, followed by a <CR><LF> and six
spaces. You can define your own prompt with 0SF (see the VAX APL Reference

Manual).
Note that using the 0 input system variables to request input inside of an
operation is convenient. For example:
VR<SQUARE
;A

[1]

"ENTER

[2]

A<[]

[3]

R<Ax2

VALUE TO BE SQUARED'

SQUARE
ENTER

VALUE TO BE SQUARED

O:
5

If you enter multiple statements separated by the diamond (¢ ) character, APL

evaluates them individually, beginning with the leftmost statement. APL uses
the value of the rightmost statement as the value of quad input. For example:
B+l
X<l

Y €2

7+<3

X
Y
2
Z

Multiple expressions separated by the output catenator (;) are not allowed to
quad input. For example:
A<{]

0:
1:;2:3

DOMAIN ERROR

(SEMICOLON LIST NOT ALLOWED)

1:2:3
A

VAX APL Users Guide

5-3

VAX APL Input and Output
5.1 Terminal Input and Output
If you enter character data in response to the [ input prompt, you must use
single quotation marks. For example:
NAME <« []

"JAMES CLERK MAXWELL'

APL reprompts if you enter an attention signal, an illegal overstruck character,
or an expression with no value, such as a blank line or an operation that does
not return a value.

5.1.1.2

Quote Quad Input

When quote quad input (1 ) input appears in an expression, APL accepts the
data between the current cursor position and the next carriage return as a
character value. For example:
2 + 3
IS A

ACATENATE TWO CHARACTER VECTORS

VERY SIMPLE EQUATION.

2 + 3 IS A

VERY SIMPLE EQUATION.

If you enclose the input in quotation marks, the quotation marks are taken as
part of the value:
X+
'"THAT'S AMAZING'
X

'THAT'S AMAZING'

If the input is a single character, [1 input is a character scalar. If the input
is two or more characters, [1 input is a character vector. If you enter only a
Return or an attention signal, 1 input is an empty character vector.
Because whatever you type is accepted as part of a character value, you cannot
execute system commands or invoke the function editor while [ input is
pending.

Legal overstrikes typed while [1 input is pending are accepted as one character.
Treatment of illegal overtstrikes depends on the character set being used in the
session. Terminals using the APL. COMPOSITE character set do not generate
illegal overstrikes; instead, they create the squish quad symbol. The squish
quad symbol is treated as one character. Illegal overstrikes are accepted as
three characters for all other character sets. For example:
Urr
19

X<l

5-4

VAX APL Users Guide

RSESSION USING COMPOSITE CHARACTER SET

VAX APL Input and Output
5.1 Terminal Input and Output
1+084
pX
5

‘

X[3

184

UTT+«2

ARSESSION USING TTY CHARACTER SET

X _.Q4
1+.XX.TRA
pX
7

X(3

XX.TRA

5.1.1.3

Qual Del Input
Quad del (B ) input is similar to quote quad (1 ) input for sessions using the

COMPOSITE character set. For other character sets, the enterred characters

returned remain untranslated. What is normally a legal APL overstruck
character becomes three characters.

In the following example, the session using the COMPOSITE character set
enters an illegal overstrike, which is accepted by APL as one character, squish
quad. The legal overstrike character (& ), which is entered as Ctrl/D o \,

also accepted as one character.
From the session using the TTY character set, APL accepts the illegal

overstrike character (. XX) and the legal overstrike character (. TR) as three
characters each.
Orr

ASESSION USING COMPOSITE CHARACTER SET

X<l
1+[194
pX
5

X[3

184

UTT<2

aSESSION USING TTY CHARACTER SET

X .QD

1+.XX.TRA
pX
9

X[3

456

XX.TRA

As with quote quad input, if you enter only a Return, or if you enter an
attention signal, APL treats the input as an empty character vector. If you
enter a single character, the @ input is a character scalar.

VAX APL Users Guide

5-5

VAX APL Input and Output

5.1 Terminal Input and Output

5.1.2 Terminal Output
When APL outputs a character array that fits on one line (of length 0P¥), it
begins its display in column 1 and outputs the array unchanged. When APL
outputs a numeric array that fits on one line, it begins its display in column 1
and separates each element in the array with one blank.

When APL outputs an array that cannot fit on a single line, the remainder of
the line prints on succeeding lines, indented six spaces. For example:
0PN
132

A<'THIS LINE IS LONGER THAN 35 CHARACTERS'
A

THIS LINE IS LONGER THAN 35 CHARACTERS
OPW+35
A

THIS LINE IS LONGER THAN 35 CHARACT
ERS

When displaying arrays that have three or more axes, APL inserts one blank
line between each plane and one additional blank line for each additional axis.
For example:
2

4p14o

Numeric values are broken only between single numbers; character values
may be broken between any two character elements. Note that the formatting
of numeric arrays is done independently of the current OP¥ setting. As a
result, when a wrap occurs, decimal points in wrapped lines are not necessarily
aligned.

In numeric output, APL does not display the following:

5-6

Plus signs

Trailing zeros after the decimal point

Trailing decimal points

VAX APL Users Guide

VAX APL Input and Output
5.1 Terminal Input and Output
*

Leading zeros (except for numbers between ~ 1 and 1, which are preceded

by one zero)
For example:
O«Ad«+1
19

9.0

41.

.99

0.99

In multiline numeric output, APL formats each column independently of the

other columns. Within a column, all decimal points line up, and all numbers

are right-justified. There is exactly one space between the longest element in a
column and the longest element in any adjoining column. In the first column

of elements, the element with the most digits to the left of the decimal point
begins in column 1. For example:
3

3p12.345

1.2

12,345

1.2

12.345

1.2

12.345

1.2

12.345

1.2

12,345

APL displays numbers in fixed-point rather than floating-point format, unless

one of the following is true:
*

The integer part has more than PP digits.

The fixed-point representation of the magnitude would require more than

OPP+n+3 characters (where n is the number of exponent digits, and the
constant 3 allows for a decimal point, an £, and an exponent sign). In

this case, floating-point format is used because it uses less space than
fixed-point representation.
For example:
OpP
5

[J«A«12345678
12345678

[«A«<12345678
1.23456E7

1234567890

12345678901

1.23u456F10

The following rules govern the display of floating-point numbers:

There are n+2 characters allotted for the exponent, where n is the number
of exponent digits, and the constant 2 allows for an £ and an exponent
sign.

Within a column, the £ lines up. As a result, trailing zeros may appear in
the fraction field so that the decimal points are aligned.

The exponent field is left-justified.

VAX APL Users Guide

5-7

VAX APL Input and Output

5.1 Terminal input and Output
e

The decimal point (if any) is positioned to the right of the leftmost digit.

The exponent of 0 is O.

For example:
3

5.1.2.1

253

7F35

2.53E2

TE35

1.23E9

5E0

65.3

0.00£0

1K1

1,23F9

65.3

Output Catenator
The output catenator, the semicolon (; ), prints data from more than one

expression on the same line. The expressions can mix both character and
numeric simple data, but may not contain heterogeneous or enclosed values.

To use the output catenator, enter a series of expressions, separated by

semicolons, in the order in which they are to appear. The expressions in a
semicolon list must be separated by exactly one semicolon, and there may not
be any leading or trailing semicolons. Incorrect uses of semicolons will result
in system messages, as explained in the VAX APL Reference Manual.

Although APL evaluates expressions from right to left, it displays values
separated by semicolons from left to right. For example:
1+1:'CHAR'"
; 3+3
2CHARG
1331914

312

4512

Note that when you enter two or more expressions separated by semicolons,
APL does not add spaces between the results; you must specify a space if you
want one:
1+1:2+72

24
1413

13242

A2 B30«
234

In semicolon lists, arrays of rank 2 and greater are displayed on separate lines.
For example:

5-8

VAX APL Users Guide

VAX APL Input and Output
5.1 Terminal Input and Output
A<«2

2p14

B<3

3p19

A:B
12

1632

2p14

456

4
2

2pi1lds1b

12
3

3456

All expressions delimited by the output catenator must return a value. For
example, if a user-defined function F does not return an explicit result, the
following signals an error:
VF

[1]

"HI THERE'

[2]

V
1;F:2

HI THERE

VALUE ERROR

(FUNCTION DOES NOT RETURN A

RESULT)

1:F32
A

Note that, in the preceding example, the error occurs after the function F is

evaluated, but before APL can display the catenation of the three expressions.
ATRY AGAIN WITH A

FUNCTION

THAT DOES RETURN A

VALUE

VH<G

[1]

H«

[2]

'"HI THERE,

AGAIN

1:G:2
1HI

THERE,

AGAIN 2

Catenated output has no value, even though the individual expressions being
catenated do have values. This means you cannot use catenated output in
any context that requires a value, such as the argument to a function or an
operator. In particular, catenated output may not be used as the argument to

the execute function, and may not be surrounded with parentheses.

VAX APL Users Guide

5-9

VAX APL Input and Output
5.1 Terminal Input and Output
Catenated output may be mixed with the statement separator symbol (¢ ):
A<1 ¢ B<2

'THESE ARE THE NUMBERS 1 AND 2:

o A;

';B

THESE ARE THE NUMBERS 1 AND 2:
1

5.1.2.2

Quad Output

The result of quad output (0+«) prints on the terminal. For example:
A<25

O<A
25

Note that using quad output has the same effect as merely typing the variable
name (in this case, 4). Quad output is helpful when an APL statement
contains multiple specification operations. For example:
B«3+[«5x4
20

This statement displays the result of the intermediate computation 5x 4, then
adds 3 and assigns the result to B. The use of [ output is more efficient than
the following:
A<5xl
A
20

B<+3+4

5.1.2.3

Bare Output

Bare output (either N« or @+«) works the same way as quad output (0+), except
that bare output does not print <CR><LF> (not even closing ones) that are not
entered by the user. Thus, bare output provides a convenient way to request
input on the same line as an output string. Note the difference in the following
examples:
aQUAD OUTPUT FOLLOWED BY INPUT

O<'ENTER YOUR NAME ' ¢ A<

ENTER YOUR NAME

5-10

VAX APL Users Guide

(Quad output inserts <CR><LF>)

VAX APL Input and Output
5.1 Terminal Input and Output
ITRENE
A

IRENE
pA
aBARE

OQUTPUT WITH INPUT

L«p[l«'"ENTER YOUR NAME:
ENTER YOUR NAME:

'¢o A<l

IRENFE

(APL

waits on same

IRENE

(Bare output

line)

became part

of A)

pA
22

IRENE

Note also that the input value is preceded by a number of spaces equal to the

length of the M output. If you do not want the spaces, you can use the JARBOUT
function to reset the bare output buffer (see the VAX APL Reference Manual for
more information). For example:
(«'ENTER YOUR NAME'
ENTER YOUR NAME

o [ARBOUT 95

¢ A<[]

IRENE

A
IRENE

5.1.3

Diverting Input and Output to Another Device
)INPUT and )OUTPUT allow you to change the source of APL input or the

destination of APL output from your terminal to another device. Typically you
would select a file (or another terminal) to be the new device by enterring the
command and the name of the VMS file to be used. For example:
)INPUT EMPLOYEE

(User enters the attention signal)
YINPUT/REVERT

Optionally, you can specify that the file should be read or written in a
characterset other than the terminal’s current characterset. In the following
example, the output is written to a file using the TTY characterset.
YJOUTPUT OUTFILE/TTY

VAX APL Users Guide

5-11

VAX APL Input and Output
5.1 Terminal Input and Output
Table 5—1 describes the possible values for the /character-set qualifier. Note
how the meaning of the values varies depending on the terminal designator,
which you specify when you invoke APL.

Table 5-1

Character Set for )

78vPUT and )oUTPUT Files
Qualifier Value

Terminal

Designator

/APL

IKEY

/BIT

TTY

/COMPOSITE

BIT

bit-paired

key-paired

bit-paired

tty

composite

COMPOSITE

composite

key-paired

bit-paired

TTY

composite

VT220

composite

key-paired

bit-paired

TTY

composite

VT240

composite

key-paired

bit-paired

TTY

composite

VT320

composite

key-paired

bit-paired

TTY

composite

VT330

composite

key-paired

bit-paired

TTY

composite

VT340

composite

key-paired

bit-paired

TTY

composite

key-paired

bit-paired

TTY

composite

DECTERM

composite

key-paired

bit-paired

TTY

composite

HDSAVT

key-paired

bit-paired

TTY

composite

HDS201

key-paired

bit-paired

TTY

composite

HDS221

key-paired

bit-paired

TTY

composite

KEY

key-paired

bit-paired

TTY

composite

key-paired

bit-paired

TTY

composite

APL

key-paired

bit-paired

TTY

composite

GIGI

key-paired

bit-paired

TTY

composite

4013

key-paired

bit-paired

TTY

composite

4015

key-paired

bit-paired

TTY

composite

VT102

key-paired

bit-paired

TTY

composite

TTY

key-paired

bit-paired

TTY

composite

TTY/alternate

alternate

key-paired

bit-paired

TTY

composite

The ) INPUT command may be nested to a depth of 10; the )0UTPUT command
may not be nested.

5-12

VAX APL Users Guide

VAX APL Input and Output
5.1 Terminal Input and Output

If you enter either the weak or strong attention signal while input is being
diverted from your terminal, APL stops processing the current ) INPUT file and
puts SYS$INPUT at the top of the nested input list (even if the list already has
10 input sources). Thus, your terminal becomes the default source of input,

and none of the diverted input streams are deleted. The new SYS$INPUT

input stream added to the top of the list will have the same /character-set
qualifier value as the SYS$INPUT stream at the bottom of the list.
If you enter either a weak or a strong attention signal while output is being
diverted from your terminal, APL responds by displaying output on your
terminal as well as in the diverted stream. If output is already being shadowed
on your terminal, the attention signal does not affect the output file.
The VAX APL Reference Manual has additional information about these
commands.

5.2 File Input and Output
APL provides an extensive file system that allows you to process external data
files with the five types of file organization that are supported by VAX Record
Management Services (VAX RMS), the file processing system used by the VMS
operating system. APL supports the following types of file organization:
e

ASCII sequential organization—standard ASCII files in which each record
(except the last) is logically adjacent to the next record.

Internal sequential organization—files stored in internal APL format. Such
files can be accessed faster than ASCII files. Each record (except the last)
is logically adjacent to the next record.

Direct-access organization—shareable, random-access files containing
records, called components, that are identified by a unique index called
a component number. The VAX RMS name for these files is single-key
indexed files; APL uses the component number as the key value.

Relative organization—shareable, random-access files containing records
identified by a relative record number.

Keyed organization—shareable, random-access files containing records
identified by primary and/or secondary keys.

Using the APL file system to process data files is essentially a 3-step process:

Associate a file specification and related file information with a channel
number. The file can be an existing file or one you want to create.

Open the file and read, write, or modify records until there are no more
records to be processed.

VAX APL Users Guide

5-13

VAX APL Input and Output
5.2 File Input and Output
3.

Close the file and disassociate it from the channel to which it was assigned.

The basic file system functions provide the capabilities needed for typical
file-processing applications. For some applications, however, you may need
to use some advanced I/0O techniques. Thus, APL offers some extensions to
the arguments for the basic file system functions as well as some additional

file system functions. Advanced file I/O techniques are discussed later in this
chapter.

5.2.1

Basic File Concepts
For ASCII sequential files written by APL, a record is a line of APL output;
thus, if the value of the output spans more than one line (if it is a matrix,
for example), it is written as more than one record. For files written in APL
with other than ASCII sequential organization, a record consists of all the

data written in a single output operation (for example, all of the elements of a
matrix), and the shape information is built into the record.

For all types of file organization, APL writes variable-length records by

default. If you want APL to write fixed-length records, you can specify the
/RECORDTYPE switch with the 0455 system function (see the VAX APL

Reference Manual). Direct-access and relative files may seem to be the same
to APL users because the syntax used to process them is identical. Both use
an integer index to retrieve specific records in the file: for direct-access files,
the index is called a component number; for relative files, the index is called a
relative record number.

Your choice of which type of file organization to use depends on the records
you want the file to contain. Generally, relative files provide faster access than

direct-access files because each record in a direct-access file is preceded by
VAX RMS retrieval information.
You should not use relative files in two cases:

When you need to write records that are very long. For direct-access
files, components may be segmented; that is, one component may consist
internally of more than one VAX RMS record. Relative files, however,
cannot contain segmented records; thus, the length of the largest record

possible in relative files is smaller than in direct-access files.
°*

When there is a large difference between the length of the largest and

smallest records in the file. The variable-length records in relative files are
stored in fixed-length cells, so each record uses the same amount of storage
as the largest record in the file.

5-14

VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output

In a keyed file organization, each record contains one or more fields known
as keys of reference. When you create a keyed file, you specify the locations,
lengths, and number of keys of reference. Once specified, this structure does
not change.

The first key of reference is the primary key, and subsequent keys of reference
are alternate keys. The contents of any key of reference field is known as a key
value.

When you write data to a keyed file, each record contains the key values
that determine the location of the record inside the file. You do not specify a
component or record number, since the indexing information is embedded in
the record. Also, the length of the components that you write must be shorter
than the maximum record length for the file. This behavior is unlike that of
/DA files which segment components that are too long.

When you retrieve a record from a keyed file, you can specify a key of reference
for sequential access, or a specific key value within a key of reference for
random access.

Note that the term keyed is synonymous with indexed.

For more details on these file organizations and their associated access
methods, see the Introduction to VMS System Routines and VMS Record
Management Services Manual documentation and Section 5.2.
5.2.1.1

File Access Methods

There are two types of file access: sequential and random. Sequential access
means that the records are accessed in a serial order; random access means
that particular records can be accessed directly at any point in the file.
The type of access you can use for a particular file depends on the file’s
organization.

For files with ASCII sequential or internal sequential organization, only
sequential access is possible.

For files with direct-access, relative, or keyed organization, both sequential
and random access are possible. When you specify a component number,
record number, or key value in the argument to a read or write function, you
access the file randomly; when you do not specify a component number, record
number, or key value in the argument, you access the file sequentially.
When you use the sequential access method, you access the file’s records in a
predetermined order. Each record (except the first and last) is said to have a
predecessor and a successor. Once you access a record, that record’s successor
is the only record you can access next.

VAX APL Users Guide

5-15

VAX APL Input and Output
5.2 File Input and Output
For files that have ASCII sequential or internal sequential organization,
sequential access means that records are accessed in the order of their
insertion into the file. Once you read or write a record, you must reposition the

file at its beginning before you can access any earlier records.

APL positions ASCII sequential and internal sequential files at their
beginning when the files are opened (unless you specify a star () after the

file organization switch). You must then do sequential read operations to

get to the particular record you want. If you execute a write function at the
beginning of the file, you create a new version of the file. If you execute a read
function when you are at the end of a sequentially organized file, APL returns

an end-of-file indicator (see the VAX APL Reference Manual).

For direct-access, relative, and keyed files, sequential access means that
records are accessed in ascending order according to component number

(for direct-access), record number (for relative), or key value (for keyed).
A sequential write to a direct-access or relative file finds the next record

by adding one to the value of the component or record number used in the
previous 1/O operation. A sequential read from a direct-access, relative,

or keyed file retrieves the next available record (it skips empty records) as
determined by the value of the file system’s internal next-record pointer (see

Section 5.2.1.2 for details).

Random access allows you to control the order of record access; you can

access records or components in any order at any point in the file; thus,
the predecessor-successor relationship is not relevant. To access a particular
record, you simply execute an input or output function that specifies an index
representing a component number, record number, or key value; APL accesses

the component or record identified by the index. If the referenced record does
not exist, APL returns an end-of-file indicator (see the VAX APL Reference
Manual).
5.2.1.2

The Next-Record Pointer

The file system uses an internal mechanism called a next-record pointer to
keep track of the next record to be processed by a sequential input function.

When sequential files are opened, the next-record pointer points to the
beginning of the file. As each record is processed, the next-record pointer
1s incremented by one.

When direct-access, relative, or keyed files are opened by a sequential read or
write function, a random write function, or by a OFLS, ODVC, OMBX , OWAIT, or
OREWIND function, the next-record pointer points to the beginning of the file.

When the same files are opened by a random read function, the next-record

pointer is set to the value of the component number, record number, or key
value specified in the input function’s argument.

5-16

VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output

While a direct-access, relative, or keyed file is being processed, the value of the
next-record pointer changes only when an input function is executed; it never
changes when an output function is executed. Thus, if you open a file, write
records 1, 2, and 3, and then do a sequential read, APL retrieves record 1. If
you then write more records and do another sequential read, APL retrieves
record 2. You can always retrieve any record you want in these files by reading
it randomly.

5.2.1.3 Record Handling and Sequential Operations

Because direct-access, relative, keyed, and sequential files can be opened for
both read and write functions, you can perform a mixture of input and ouput
operations. The following rules apply to these situations:

A sequential delete deletes the record just read or written (regardless of

A sequential write rewrites the record just read or deleted. Any number
of repetitions of a sequential write followed by a sequential delete (or vice

whether the previous read or write was sequential or random).

versa) will affect the same record over and over.

The location of the next-record pointer is affected only by sequential read,

random read, OCLS, and OREWIND. Random write or random delete never
affects or modifies the next-record pointer.

Sequential files are generally opened for either read or write operations, but

not for both. The four exceptions to this rule are listed below.

When the file specification you used with 0ASS represents a terminal
device.

When the file is a mailbox.

When the file is assigned with the /UPDATE qualifier.

When you invoke OREWIND on a file initially opened for write operations.

5.2.2 Associating Files with Channels

The APL system functions that read and write records take channel numbers,
not file specifications, as arguments. Thus, before you can read or write to
a file, you must use the 045s function to associate the file and its related
information with a channel number using the following form:
([ variable< T10145S ' [L channel filespectl ffileorganization] (L /qualifiersT] '

VAX APL Users Guide

5-17

VAX APL Input and Output
5.2 File Input and Output
variable

1s an optional variable
channel

1s an optional integer scalar whose absolute value represents a channel
number in the range 1 through 999. If you do not specify a channel number,
APL assigns one for you. APL picks the first available channel number,
beginning at 12 and counting down to 1; then APL begins at 13 and counts up

to 999.

filespec
is the VMS file specification associated with the specified channel. If you do
not include the file extension, APL uses the default file extension for the file
organization qualifier specified. (See Table 5-2.)

/fileorganization

is the qualifier identifying the file organization of the file specified by filespec.
The possible values of the /fileorganization qualifier are listed in Table 5-2.
The default value is /DA.

/qualifiers
are the other optional qualifiers listed in the VAX APL Reference Manual.
These qualifiers can specify the blocksize, buffercount, whether the file can be
shared or updated.

Table 5-2

File Organization Qualifiers

ffileorganization

Default File

Qualifier

Extension

Type of File

/AS

LAAS

ASCII sequential; can open for either read or

write, or both (when you specify /UPDATE).
/AS*

LAAS

ASCII sequential; file is positioned at end-of-file

JAIS

Internal sequential; can open for either read or

to allow appending.
/IS

write, or both (when you specify /UPDATE).
/IS*

LAIS

Internal sequential; file is positioned at end-of-

file to allow appending.
(continued on next page)

5-18

VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output

Table 5-2 (Cont.) File Organization Qualifiers
[ffileorganization

Default File

Extension

Type of File

/DA

ATX

Direct-access; can do both read and write (this 1s

/RF

.ARF

Relative; can do both read and write.

/KY

JAKY

Keyed; can do both read and write.

Qualifier

the default).

For example:
aASSIGN THE ASCII SEQUENTIAL FILE TO CHANNEL 6
JASS

'6 FOO/AS'

aAPPEND RECORDS TO TEST.AAS
0ASS '5 TEST.AAS/AS+/OPEN:

aAPL ASSIGNS THE DIRECT-ACCESS FILE TO CHANNEL 12

A«[QASS '"PROJECTIONS/OPEN:

OLD'

A
12

Associating a file with a channel does not open or create the file (unless
you specify the /0PEN qualifier on 04SS); it merely establishes a connection
between a channel number and a file specification. Using the /0OPEN qualifier
allows you to detect errors related to the opening or creating of a file at the
time of assignment instead of at the time of the first I/O operation. This is
particularly important when you share files with others, and their current
assignments to a file invalidate the assignment you are making.

Some of the related file information you can specify with 0ASS, like the file’s
type of organization, is fixed when the file is created; other file information,
like the file’s shareability, can be changed each time you use JASS. Refer to the
VAX APL Reference Manual for more information about the optional qualifiers.
The argument to 04SS must be specified according to the following rules:

If you use the /fileorganization qualifier, it must immediately follow the
file specification. The other parameters may follow the file specification
and organization in any order.

You may not repeat a qualifier, even with a different value.

VAX APL Users Guide

5-19

VAX APL Input and Output
5.2 File Input and Output
*

If you use a qualifier that takes an argument, APL looks for a qualifier
delimiter (: or =). If it does not find a delimiter, APL assigns the default
value to the qualifier. If APL does find a delimiter, the argument value
must follow.

White space (spaces and tabs) is permitted between any two qualifiers.

When you assign a keyed file to a channel, use the 0455 system function with

the /kY switch. When you are creating the file, you must include a value for at

least the primary key of reference (other key of reference values are optional).
When the file already exists, the key specifications are optional; if you choose
to specify them, APL assumes your specifications are consistent with the file’s
key structure and allows you to successfully assign the channel. However, if

there is an inconsistency, APL signals

70 ERROR (FILE KEY STRUCTURE DOES

NOT AGREE WITH USER ASSIGNMENT) when you attempt any I/O operations.

Each key specification identifies the location of the first byte of the key,
the length, in bytes, and the data type of the key, either INW, INL, INQ or
CHARACTER.

The following expression shows 4SS with the /kY qualifier. In this example,
there are two key specifications: the primary key begins at the first byte of the

record, has a length of 10 bytes, and is of type character; the first alternate
key begins at the 12th byte of the record, has a length of 4 bytes, and is of type
character.
OASS

'1 BANGKOK/KY:1:10:CHAR,12:4:CHAR'

Like other APL functions, JASS returns a result. The value of the result
depends on what channel you assigned and whether that assignment was

successful:
*

If you specify a channel number channel, 0ASS returns that number as the

result.

If you do not specify a channel number, APL assigns one, and 04SS returns
that as the result.

If you assign a channel number that has already been assigned, APL

deassigns the channel from its original file and reassigns it to the new file.
0ASS returns the channel number of the new file as the result.
*

If APL encounters an error in the JASS function, it returns a result of
0, indicating that your assignment failed. This is also the case if the
argument you specify is empty, and if you do not specify a channel when
no unassigned channels are available. After a failed assignment, 0ERROR
contains an error message that describes the reason for failure.

5-20 VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output

Note that if you are superseding an assigned channel number, and the new
assignment fails because of the /OPEN qualifier, the specified channel number
becomes deassigned. For example:
UASS

'"GOMJABBER/DA'

OASS

'12 PLANEX/DA/OPEN=0LD'

OERROR
33 I0 ERROR (FILE NOT FOUND)
HASS

'"12 PLANEX/DA/OPEN=0LD'
A

HASS 12

OCHANS

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

Table 5—2 describes the possible values for the /fileorganization qualifier,
the default file extensions implied by the values, and the meaning of the
various file organizations. (Section 5.2 has more information on file types and
organization.)

5.2.2.1

Querying File Assignments

The query form of 4SS returns the current value of assignments made
previously with the action form. The result of 04SS identifies the parameters
you associated with the channels specified. For example, the following line
displays the assignment made for channel 1:
JASS '1 PLANS.AAS/AS*/PROT=(S:RWED,0:RWNED)"
1

O0ASS 1
PLANS.AAS/ASx/PROTECTION:(S:RWED,0:RWED,G:
,W:)

Note that when the result is a matrix, the shape of the matrix is n by L, where
n is the number of channels, and L is the length of the longest line in the
display.

If the argument is a singleton and the channel you specify is currently
unassigned, APL returns a character vector of length 4 with the channel
number left-justified with trailing blanks. If the argument is a vector, elements
representing an unassigned channel are identified by the number and enough
blanks to make the line the appropriate length. If the argument is 1 0 APL
returns a character matrix with the shape 0 0. In the following example,
channels 2 and 4 are not assigned:

VAX APL Users Guide

5-21

VAX APL Input and Output

5.2 File Input and Output
UASS

'1 PLAN.AAS/AS*/PROT=(S:RWED,OQ:RWED)"'

UASS

'3 APLREL/RF/DISPOSE:DELETE'

OASS

'S5 APLSEQ/AS/SHARE/READONLY'

OJASS 2
2

OJASS 15
1

PLAN.AAS/AS*/PROTECTION: (S:RWED,0:RWED,G: ,W:)

APLREL/RF/DISPOSE:DELETE

5.2.2.2

APLSEQ/AS/SHARE/READONLY

Returning Channel Numbers

OCHANS displays all of the channel numbers currently associated with file
specifications. The result is a vector. In the following example, channels 1, 3,
and 5 are each associated with a file:
UASS

"1 PLAN/AS'

HASS

OASS

'5 ANALYSIS/AS!

BUDGET/AS'

3
5

OCHANS
1

JCLEAR
CLEAR WS

UCHANS

(APL outputs a blank line)

To list the parameters associated with all files assigned to channels, use
OCHANS as the argument:
JASS

PLAN/AS'

HASS

'3 BUDGET/AS'

HASS

'S5 ANALYSIS/AS!

HASS [JCHANS
1

PLAN/AS

BUDGET/AS

ANALYSIS/AS

If no channels are assigned, JCHANS returns an empty numeric vector.

5-22

VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output

5.2.3 Opening Files and Reading and Writing Records
You use the APL input quad (d) and output quad (B) functions to read and

write records. They are similar to the terminal I/O system variables (see
Section 5.1), except that the input and output is to and from external files
rather than to and from your terminal.
If the first reference to a file (by means of a channel) is an output function,
APL opens the file—or creates and opens it if it does not exist—and then writes
the record. If the first reference is an input function, APL opens the file and
reads the record, or returns an error if the file does not exist.
5.2.3.1

Writing and Reading ASCII Sequential Files
You can write or read ASCII sequential file records in any of four character
sets: KEY, BIT, TTY, or APL COMPOSITE. The mode parameter indicates the
following:

The character set you want to use to read the file

Whether to use evaluated (0), quote quad ([1), or quad del (@) input to read
the next record

The APL character set refers to the character set you specified as your terminal

designator (see Section 1.5). The default character set is the one specified by
your terminal designator; the default output type is 0 mode. Be sure to enclose

the mode specification in brackets. Table 5—3 shows the possible values for the
mode parameter and the meanings associated with each value.
Table 5-3
Type

/45 Input and Output Modes
Character Set

Mode

TTY

APL

KEY

[

KEY

(continued on next page)

VAX APL Users Guide

5-23

VAX APL Input and Output

5.2 File Iinput and Output

Table 5-3 (Cont.)
Type

/45 Input and Output Modes
Character Set

Mode

BIT

[

BIT

COMPOSITE

]

COMPOSITE

In the following example, the ASCII file OUTPUT.4AS is created, and records
are written using the key-paired character set. Then the file is closed and the

newly created file is read.
JASS

OUTPUT/AS'

'FIRST RECORD'

"SECOND RECORD'

[7]2

(2 4p18) B [7]2
OCLS 2
M [8]2

FIRST RECORD

M (812

SECOND RECORD
12

¢4

b [7]12
B [7]2

A<Hd [7]2
p

(EOF encountered)

When you use file input (B ) with mode 1, 4, 7, 10, or 13, records are processed
until APL gets a value to return as the result. Blank lines and comments in
the file are ignored, system commands are executed (and their output, if any, is

displayed on the terminal), and function editing sequences continue until the
operation is closed. Thus, these modes allow you to write files that are fully

documented with comments and that can define operations to be used later in
expressions within the file. For example:

5-24

VAX APL Users Guide

VAX APL Input and Output

5.2 File Input and Output
HASS "1 TEST/AS!
(1+1)

AEXPRESSION GETS EVALUATED BEFORE WRITING

aNEXT
E

IB(_2I

Ty!

LINES WILL

ASYSTEM COMMAND

'Ft

ACALL

(2+2)

1 READ

COMMAND

REND FUNCTION DEFINITION

"YWIDTH'
R

BE PROCESSED BY

!A.(_ll

ARFUNCTION DEFINITION

NO RESULT WHEN EXECUTED

aFINALLY A

OCLS 1

VALUE,

READ

WILL

STOP HERE

ACLOSE CHANNEL ASSIGNMENT
aSHOW NO FUNCTIONS IN WORKSPACE

JENS
ASHOW NO

VARIABLES IN WORKSPACE

)VARS

WAS 80

B 1

AREAD FIRST RECORD

M 1

AREAD UNTIL NEXT VALUE-RETURNING RECORD

(1+1)
(2+2)

aSHOW THAT F WAS DEFINED DURING LAST RFAD
JENS
ASHOW THAT F WAS EXECUTED T0O
A

) VARS
B

Note that if the abort signal is read with file input (B ) in mode 1, 4, 7, 10, or
13, APL cancels the input and signals

TNPUT ABORTED. If @ is executing in one

of these modes, and the end of the file is reached while the v editor is being
executed, the effect is the same as if @ read the abort signal: the editing is
aborted and the value returned by the § function is 0 75p 0.

5.2.3.2

Writing and Reading an Internal Sequential File
When you use § and B (see Section 5.2.3) with internal sequential files, you do

not have to specify an input mode as you do with ASCII sequential files. Data
in internal sequential files is stored in the internal format of APL.
In the following example, three records are written to an internal sequential
file and the file is closed; then, the three records are read:
JASS

'"1 INT/IS'!

'RECORD 1'H1
"RECORD 2'H1
(2

4p:8)

OCLS 1

VAX APL Users Guide

5-25

VAX APL Input and Output

5.2 File Input and Output
M1
RECORD 1

M1
RECORD

M
12

A
4

(APL outputs a blank line)
0

(EOF encountered)

As with ASCII sequential files, the end-of-file indicator indicates that you are

at the end of the file. Blank records in internal sequential files return blanks.
5.2.3.3

Writing and Reading a Direct-Access or Relative File
The components or records in direct-access or relative files are associated with
indexes called component numbers (for direct-access files) or record numbers

(for relative files).
To randomly read or write a direct-access or relative file, you specify, in the

argument to the file input (M) or file output (8) function, an index representing
a component or record number in the following form.
data @ [[record-number]] channel
When you sequentially access a direct-access file, that is, when you use the d

or B function and do not specify a component or record number, APL retrieves

records as follows:
*

For input, APL retrieves the record referenced by the value of the nextrecord pointer (see Section 5.2.1.2).

For output, APL writes the record referenced by 0FLS[2]+1, that is, one
plus the component or record number used in the previous I/O operation.

If you execute a file output (B) function that accesses an existing record or
component, APL replaces the old value of the record or component with the
new value you specified.

There is no end-of-file in direct-access or relative files; however, they may have
empty components or records scattered throughout the file. If you try to read a
component or record that is empty, APL returns the end-of-file indicator.

You can delete records from direct-access and relative files by using the
monadic form of file output (B ).

5-26

VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output
The following example shows records 20 and 21, and 50 and 51 being written

to the file REL . ARF: Note that when no record number was specified for output,
APL used the record number used in the previous I/O operation plus one.
JASS

'"1 REL/RF®

"RECORD 20"

[20]1

"RECORD 21'

"RECORD 50'

[50]1

(v4) Bt
H

[20]1

RECORD 20

[5171

3 U4
12

'NEW VALUE FOR 20'

[20]1

NEW VALUE FOR

You can access components or records in any order—for instance, you can write

component or record 10 before 9—but it is more efficient to access them in
ascending order of their component or record numbers. It is also more efficient,
when updating a file, to make deletions first and then make replacements and

additions.

5.2.3.4

Writing and Reading a Keyed File

When you write records to a keyed file, use the file output () function in the
following form:
data B channel [data-typel]|

If you are writing APL objects and plan to read them back into the APL
environment, do not specify data-type, or specify a value of 0; APL will add

header information to the beginning of the record. When you do specify the

data type, you imply that you want to write the record in a pure data mode
and that you do not want APL to add descriptive information to the beginning
of each record. For more information on pure data types, see Section 5.3.4.
In the following example, one record is written to a keyed file.
OASS

'1 BANKGKOK/KY:1:11:CHAR,13:4:CHAR'

"TRANSFERRED EEUU
505617374

$1050

EFFECTIVE JULY 8,

273924509

1990'

To read records randomly from a /XY file, use the @ function in the following
form:

B [[value [;key-num [[;tech[;key-type]llll chan [data-type]

VAX APL Users Guide

5-27

VAX APL Input and Output
5.2 File Input and Output

value
Specifies the key value for the record you want to read. It can be in either the

near-integer singleton or the character vector domain. With a character vector
key, you can specify a key value that is shorter than the field length of the key

of reference. In this case, APL interprets the value as a prefix and searches
for any keys (within the specified key of reference) that begin with the prefix

value. If the defined length of the key is known to the APL environment, value
1s padded to that length with trailing NUL bytes (hex 00). Note that if value
belongs to the character domain, and the file you want to process is not in APL
character set (it was written out in pure data type 6, 11, 12, 13, 14, or 15), you

must specify that external data type number (see Table 5-6 in Section 5.3.4) for

data-type or key-type in order to convert the key to the appropriate character
set.

key-num
Is a near-integer singleton that specifies which key of reference you want to

read. Use O for the primary key, 1 for the first alternate key, and so on. The
default is the primary key.
tech
Specifies the search technique that APL uses to retrieve the record you want to
read. It belongs to the character vector domain and has three possible values:

'EQL', 'GTR', and 'GEQ'. 'EQL"' 1is the default value. It means that APL

searches for the record with a key that matches exactly the key value that you

specify.

GTR' means that APL searches for the first record with a key that is

greater than the key value that you specify.

'GEQ' means that APL searches

for the first record with a key that is either greater than or equal to the key
value that you specify.
key-type

Specifies the external data type of the key of the record you want to read.
Do not specify this parameter unless you are reading “pure” data. (See

Section 5.3.4 for more information on pure data records.) It is not necessary to

specify key-type when the data type of your key is the same as the rest of the
data in the record. The possible values are 0, 1, 5, 6, 11, 12, 13, 14, or 15.

chan
Specifies the channel number currently assigned to the /

5-28

VAX APL Users Guide

kY file.

VAX APL Input and Output

5.2 File Input and Output
data-type

Specifies the data type of the record you want to read. Do not specify this
parameter unless you are reading “pure” data. When you include a value for

data-type, you imply that the record contains pure data; that is, the beginning
of the record contains no header information. If you do not specify data-type, or

if you specify a value of 0, APL assumes that there is a header at the beginning
of the record (see Section 5.3.4). The possible values are 0, 1, 5, 6, 11, 12, 13,
14, or 15.

The following example opens a keyed file, writes a record to the file and then

performs a random read of that record by specifiying a prefix of the key value
of the primary key of reference:
HASS

'1 BANKGKOK/KY:1:11:CHAR,13:4:CHAR'

"TRANSFERRED EEUU
505617374

$1050

FFFECTIVE JULY 8,

273924509

1990'

1 5

M ['"TRAN';0]

TRANSFERRED EEUU
505617374

$1050

FFFECTIVE JULY

273924509

1990

To read records sequentially from a /XY file, use the file input (§) function in
the following form:
@ channel [data-type]
Keyed files use the next-record pointer mechanism described in Section 5.2.1.2.
When you perform a sequential read operation on a /KY file, APL finds the

next record in the key of reference specified in the previous I/O operation.
When you create a keyed file with APL, the primary key does not allow
duplicate values and alternate keys do allow duplicate values. Duplicate
values refers to two records with the same key value in the same key of
reference. When you write a record that has a duplicate key to a file that does

not allow duplicates, the record you are writing replaces the existing record.
For example:
HASS

'1 MOVASI/KY:1:1:CHAR'

"AEMPIRE'

VX « B

[TA']11

RPRIMARY KEY INDEX GETS A

EMPIRE

"AFOUNDATION'
WX « 4
FOUNDATION

[TA']1

ARREPLACE EMPIRE WITH FOUNDATION

VAX APL Users Guide

5-29

VAX APL Input and Output
5.2 File Input and Output
When you write a record that has a duplicate key to a file that does allow

duplicates, the corresponding index is updated with the duplicate entry. If you
randomly specify the duplicate key, APL retrieves the first occurrence of the
duplicate. Subsequent sequential reads will retrieve duplicate key values.
The only way to randomly read records that have duplicate keys is by using a

different key of reference.
OASS

'1 HOGAN/KY:1:2:CHAR,3:5:CHAR'

nPRIMARY KEY INDEX GETS AA,

"AALUNARVISAR'

APRIMARY KEY INDEX GETS ZZ,
A

ALTERNATE KEY GETS LUNAR

5
ALTERNATE KEY GETS

DUPLICATE LUNAR

"ZZLUNARANYMEDE'

ARETRIEVE FIRST DUPLICATE-KEY RECORD

O«X<«Md ['LUNAR';1]
AALUNARVISAR

ASEQUENTIAL READ RETRIEVES SECOND

DUPLICATE-KEY RECORD

O«X«l 1 5
LLLUNARANYMEDE
RDEFAULT IS PRIMARY KEY AND EQL

7K « B
ANYMEDE

['22']

TECHNIQUE

If you want a keyed file to have a structure different from those that APL
provides, you can create the file with a VMS File Definition Language (FDL)

Utility. For example, with the FDL$CREATE command you can create a key
structure that permits duplicate primary keys. Once you create the structure,

you can then use APL to write and read records to the existing file. For more
information, see the VMS File Definition Language Facility Manual.

To delete records from a /KXY file, use the file output (B) function in the same
form used to read random records:

B [value [;key-num [;tech[;key-typel]ll] chan [data-type]

- 5.2.4

Resetting Next-Record Pointer to Start of File
OREWIND allows you to reposition the next record pointer to the first record of
a file without closing the file. When you want to return to the beginning of a
sequential file you could also use ICLS. (See Section 5.2.5.)
With the monadic form of JREWIND, you can specify a vector of channel
numbers in the right argument. This will rewind each of the files associated

with the specified channel numbers. If any of the files have a keyed
organization, APL performs the rewind on the primary key of reference.

5-30

VAX APL Users Guide

VAX APL Input and Output
5.2 File Input and Output
Use the dyadic form for keyed files when you want APL to perform the rewind

on a key of reference other than the primary key. The right argument specifies
the channel number associated with the keyed file. The left argument specifies

the key of reference: 0 indicates the primary key, a 1 indicates the secondary
key, and so on. You can specify only one file at a time when you invoke dyadic
OREWIND.

In the following example, APL rewinds each of the files associated with the
channel numbers 10, 9, 8, and 7. Any subsequent sequential read operation

on one of these files will select the first record. (If any of the files has a keyed
organization, a read operation selects the first record by the primary key of
reference.)
B«

OREWIND B

"B GETS

VECTOR OF CHANNEL NUMBERS

AMONADIC FORM

The next example shows the dyadic form of OREWVIND:
A10

3 UREWIND 10

CHANNEL NUMBER OF A

KEYED FILE

a3 IS FOURTH KEY OF REFERENCE

If an /A4S or /IS file is opened for read operations when you invoke OREWIND, it
will remain open for read operations. If the file is opened for write operations
initially, it will be open for both read and write operations afterward. Because
write operations can occur only at the end of a sequential file, you must read

through to the end before attempting a write operation. Otherwise, APL
signals 70 FRROR ($PUT NOT AT END OF FILE).
OREWIND does not release locked records on the specified channels.
For sequential files, the second value returned by the OFLS system function

indicates the number of read and write operations that have taken place since
the file was opened or since OREWIND was last executed on the file.

5.2.5 Closing Files and Disassociating Files from Channels
When you have finished processing a file’s records, you can use the O0DAS
function to close the file and end its association with the channel number. If
you want to close the file but keep its association with the channel, you can use

the OCLS function. OCLS is useful when you want to return to the beginning of
a sequential file. (You can also use the JREVIND system function, which does
not close files.)
APL automatically closes and deassigns all open files when you type Ctrl/Z or
execute a )LOAD, )CLEAR, )OFF, or )CONTINUE system command (the )MON

and ) PUSH system commands do not have this effect).

VAX APL Users Guide

5-31

VAX APL Input and Output
5.2 File Input and Output
If you access a file after you close a channel, a read function would open the
file and read the first record, and a write function would create a new version
of the file (except for direct-access, relative and keyed files for which a new file

is created only if no version currently exists).
OCLS is a quiet function; it does not return a result if it is the leftmost function

in a statement. When [JCLS is not the leftmost function, it returns an empty
numeric vector.

Any unassigned channels in the argument are ignored.

The following example closes files:
UASS [OCHANS

BANGKOK/KY=1:11:CH,13:4:CH

MINTMP/AS

NIN/AS

TEST/AS

OCLS 1
UASS [CHANS

BANGKOK/KY=1:11:CH,13:4:CH

MINTMP/AS

NIN/AS

TEST/AS

X<[JCLS112
X

(APL outputs a blank line)

ODAS disassociates file specifications from channel numbers. If any files
associated with the specified channel numbers have not been closed (by OCLS),
[O0DAS closes them and then deassigns them.
In general, IDAS reverses the actions performed by the 045S system function.

Any unassigned channels in the argument are ignored.
[ODAS i1s a quiet function; it does not return a result if it 1s the leftmost function
in a statement. When (O0DAS is not the leftmost function, it returns an empty
numeric vector.

The following example deassigns the files associated with channels 1, 3, and 5:

0ASS [OCHANS
BANGKOK/KY=1:11:CH,13:4:CH

MINTMP/AS

NIN/AS

TEST/AS

ODAS 1 9 10 12
0ASS OCHANS

5-32

VAX APL Users Guide

(APL outputs a blank line)

VAX APL Input and Output

5.2 File Input and Output

5.2.6 Determining Information about Files and Devices
It would be helpful to know something about how a file was written before you
read it. The 0CHS and OFLS functions return information about the file. ODVC

displays the characteristics of where files are stored.
Returning File Organization and Open Status
Use [1CHS to determine the file organization and status of the file associated
with the channel you specify. If the argument is a singleton, [1CAS returns a
2-element vector: the first element identifies the file’s organization, and the
second element identifies the file’s open status. If the argument is a vector of n
elements, the result is an array of shape n by 2.
In the example, the file associated with channel 1 is an ASCII sequential file

and is open for input. The second expression returns a 3-by-2 array:
[ICHS 1
1

13
7

O«FILS«[JCHS13

pFILS

Table 5—4 gives the meanings of the possible values.
Table 5—4

Possible JcHAs Codes

Code

File Organization

=W
N = O

First Element

Not applicable

5.2.6.1

Not applicable

/AS
/IS

Not applicable
/DA

(continued on next page)

VAX APL Users Guide

5-33

VAX APL Input and Output

5.2 File Input and Output

Table 5-4 (Cont.)

Possible cis Codes
First Element

Code

File Organization
Not applicable
/RF

/KY

5.2.6.2

Code

Open Status

Channel free

W
DN

Second Element

Assigned but not open

Open for output

Open for input
Open for input and output

Returning File Information

Use JFLS to determine information about files. The result contains one row of
five values for each channel specified in the argument. The meanings of the
values can differ according to each file’s organization.
The first value is a 1 if you specified /SHARE in the argument for the associated
JASS function; 0 means that you did not.
For sequential files, the second value is the number of records read and written

since the file was opened or since JREWIND was last executed on the file. For

direct-access and relative files, it is the value of the last record or component
number used for a successful read or write operation. For keyed files, it is the
value of the last key of reference used for a successful read, write, or rewind.

The third value indicates the maximum record length of the file.

0 means

there is no user limit on record size.
The fourth value indicates the

/BLOCKSIZE setting for the file.

The type of the most recent I/0O operation is indicated by the fifth value. You
can use this information in determining the location of the next record pointer.
There are six possible I/O operations:

5-34

VAX APL Users Guide

VAX APL Input and Output

5.2 File Input and Output

o
=
N

Random read
Sequential write
Random write

Sequential read

Sequential delete

None

I/0 Operation

Value Returned

Random delete

OFLS returns a 5-element vector if a single channel number is specified. If the

argument specifies more than one channel, the result is an array of shape n by

5, where n is the length of the argument.
If its argument is empty, (0FLS returns a result of 0 5p 0. If any of the integers
in the argument refers to an unassigned channel, [IFLS returns a row of 5
zeros. For example:
OFLS 1
0

20u4u4

512

Note that to return a value for OFLS, APL must open files that have been

associated with channels but have not yet been opened. (For a list of
commands that open files, see Section 5.2.3.) Thus, unopened files associated
with channels identified by positive integers in the JFLS argument are opened
for input; unopened files associated with channels identified in the argument by

negative integers are opened for output. Note that when you open a sequential
file for output, APL makes a new copy of the file with a version number that is

one higher than that of the previous copy.
5.2.6.3

Returning Device Characteristics

O0pvc displays the characteristics of the devices where files are stored.
For each channel specified in the argument, ODVC returns one row containing
two values: the first value is the VMS device-characteristics longword, and the
second value is always 0. For unassigned channels, 0DV returns 0 0.
ODVC returns a 2-element vector if a single channel is specified. If more than

one channel is specified, the result is a matrix of shape n by 2, where n is the
length of the argument.
If its argument is empty, O0DVC returns a result of 0 2p 0.

VAX APL Users Guide

5-35

VAX APL Input and Output

5.2 File Input and Output
Note that to return a value for 0DvC, APL must open files that have been
associated with channels but have not yet been opened.

(For a list of

commands that open files, see Section 5.2.3.) Thus, unopened files associated
with channels identified by positive integers in the [1DVC argument are opened

for input; unopened files associated with channels identified in the argument by
negative integers are opened for output. Note that when you open a sequential
file for output, APL makes a new copy of the file with a version number that is

one higher than that of the previous copy.

It is usually helpful to convert the device-characteristics longword to binary
format before examining it. For example:
UPW<50
4«0DVC 1
A
474824968

(32p2)7 A[1]
0001110001001

101010000010

0001000

You can compare the binary value of the longword with the device charac-

teristics in Table 5-5. The first element in the table is associated with the
rightmost bit in the longword, the second element is associated with the next
rightmost bit, and so forth. Thus, in the previous example, the three rightmost
0 s indicate that the device is not record-oriented, is not a carriage-control

device, and is not a terminal; the 1 in the fourth position from the right
indicates that the device is directory-structured.

Table 5-5

Record-oriented

Carriage-control

Terminal

Directory-structured

Single directory-structured

Sequential, block-oriented

Type or Condition of Device

Being spooled

Bit

Device Characteristics Longword

Open console
(continued on next page)

5-36

VAX APL Users Guide

VAX APL Input and Output

5.2 File Input and Output

Table 5-5 (Cont.)
Bit
8

Device Characteristics Longword

Type or Condition of Device
RA50,RA81,RA82,RH60

9 - 12

(Bits reserved)

Network

File-oriented

(Bit reserved)

Shareable

Generic

Available for use

Mounted

Mailbox

Marked for dismount

Error logging enabled

Allocated

Non-file-structured

Software write-locked

Capable of providing input

Capable of providing output

Allows random access

Real-time

Read-checking enabled

Write-checking enabled

5.3 Advanced I/O Techniques
The preceding sections explain how to use the file system for typical fileprocessing applications; however, you may have some applications that are
not typical. For those, APL provides facilities such as shared files, event flags,

mailboxes, and untranslated data records. These advanced I/O facilities are

explained in the following sections.

VAX APL Users Guide

5-37

VAX APL Input and Output
5.3 Advanced I/O Techniques

5.3.1

Sharing Files
The APL file system provides a way to make files shareable, that is, to make
files available for access by more than one user simultaneously.

5.3.1.1

Sharing Sequential Files

ASCII sequential and internal sequential files are shareable unless the first
channel assigned to a file specifies the /NOWRITERS switch. You do not need
to do anything special to share sequential files (the /SHARE switch is not
necessary when you assign the file); APL provides this facility automatically.
In all cases, there can be only one writer to a shared sequential file, though
there can be more than one reader.

There are four optional switches (on 0ASS) that determine the share
characteristics of a file: /NOWRITERS (no other channels can write to the
file), /READONLY (the assigned channel can only read the file), /UPDATE (the
assigned channel can read and append to the file), and /WRITEONLY (the
assigned channel can only write to the file).

When no switches are specified, the rules for sharing are as follows:

If the first operation is a write, a new file is created and no other channels
can share the file.

If the first operation is a read, any other channel (that did not specify
a switch) can also read the file, but none of these channels can perform
writes.

In all situations, any channel can specify OREVIND, move to the beginning of
the file, and then continue reading.

When a channel assigns to a sequential file and uses /UPDATE, the channel
can read and write to the file. The channel can use OREWIND to move to the
beginning of the file, read through the file, and then append new records.
Previous assignments can continue reading from the file, and subsequent
assignments can also gain read access. If the first operation of the /UPDATE
channel is a write, a new file is created. (If the assignment specified
/OPEN:0LD, a new file is not created. However, the channel can only write
to an existing file if the file is empty or if /7S was specified for appending.)
No other channels can assign to this file with /UPDATE.

When the first assignment uses /WRITEONLY, a new file is created when the
channel writes to the file. (If the assignment specified /OPEN:0LD, a new file
is not created. However, the channel can only write to an existing file if the file
is empty or if /1S* was specified for appending.) Subsequent assignments can
gain read access to the file.

5-38

VAX APL Users Guide

VAX APL Input and Output

5.3 Advanced l/O Techniques
When the first assignment uses

/READONLY, other channels can also read

the file and one other channel has the opportunity to gain write access (with
/UPDATE).

The following list describes the rules for sharing sequential files. In each case,
the list assumes that Chanl performs the first operation.

Qualifiers

First Operation

Chan1i

Other Users

none

read

none

write

read, write

none

/READONLY

n/a

read

read, 1 writer

/WRITEONLY

n/a

write

read

/UPDATE

n/a

read, write

read

In the following example, the same file is associated with two different

channels. Note that when the file is opened for output on channel 1, it cannot
be read from channel 2. However, after the file is closed on channel 1, it is

opened successfully for input on both channels.
JASS

'1 FOO/AS'

(JASS

'2 FOO/AS!

56 B

57 B 1
58 B

1
aFILE IS LOCKED BY

CHAN1

B 2
32 INVALID SIMULTANEOUS ACCESS

(FILE CURRENTLY LOCKED BY ANOTHER

2
A

OCLS 1
H 2

aCHAN1 UNLOCKS FILE
aCHAN2 PERFORMS READ, DOES NOT LOCK FILE

g2
57

aCHAN1 CAN SHARE FILE

M1
57

Note that it is possible for two (or more) users to appear to have the same
sequential file open for output at the same time.

VAX APL Users Guide

5-39

VAX APL Input and Output
5.3 Advanced I/O Techniques
In the following example, the users are creating two new files: each user
makes a new copy of MYFILE.AAS, and the copy made on channel 2 has a
version number that is one higher than the copy made on channel 1.
Note that if the user on channel 1 closes the file and then tries to reopen it
with an B function, APL signals an error because it tries to open the latest
version of MYFILE.AAS and that version is locked (still open) by the user on
channel 2.

Once the user on channel 2 closes the file, it is no longer locked. When both
users reopen the file for input, both get the latest version of the file—the
version created on channel 2.
aTWO CHANNELS ASSIGN,

HASS

'"1 MYFILE/AS!

UASS

"2 MYFILE/AS!

FILES ARE NOT OPENED YET

1 B1

aCHAN1

CREATES NEW VERSION OF MYFILE.AAS

10 H2

aCHAN2

CREATES NEW VERSION OF MYFILE.AAS

OCLS 1
4 1
32 INVALID SIMULTANEQOUS ACCESS (FILE CURRENTLY LOCKED BY ANOTHER USER

B 1
A

NCLS

g 1
10

You may encounter locked records as you perform read operations. APL waits
indefinitely for locked records (unless you set OWAIT), and you must use the
attention signal to regain control. Note that using ORELEFASE to unlock locked
records is one way of avoiding delays while waiting for records. The following
example describes such a situation:
0ASS

"1 REX/IS/OPEN:NEW'

4550
1 ¢

AASSIGN FILE REX

aPOPULATE FILE AND DEASSIGN

355H
1 o

[DAS
1

aOPEN REX FOR READ AND WRITE OPERATIONS

[ASS

g 1

5-40

'"1 REX/IS/OPEN:OLD/UPDATE/SIGNAL'

aREAD AND LOCK RECORD 1

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
ROPEN

HASS

REX

FOR READ

CHAN

'2 REX/IS/OPEN:0OLD/SIGNAL'

H 2

RnATTEMPT READ OF LOCKED RECORD

18 ATTENTION SIGNALED

M 2

(WAITING FOR RECORD LOCK)

RnATTEMPT READ OF LOCKED RECORD

OWAIT 2

ASET WAIT FOR 2

H 2
33

SECONDS

RATTEMPT READ AGAIN

I0 ERROR

(TIMEOUT PERIOD EXPIRED)

K 2

nATTEMPT READ AGAIN

ORELEASE 1
g

ARELEASE RECORD LOCKED BY CHAN 1

aNOW RECORD IS AVAILABLE TO

CHAN 2

455

Note that it is possible to use combinations of JASS switches that are
contradictory. The contradiction might cause the first I/O operation to fail.
For example:
HASS

'"1 REX/IS/OPEN:NEW'

4558

AASSIGN FILE REX

APOPULATE FILE AND DEFASSIGN

3550

[JDAS 1

a0PEN REX FOR READ AND WRITE

HASS
4

OPERATIONS

"1 REX/IS/OPEN:OLD/UPDATE/SIGNAL'

AREAD AND LOCK RECORD

ROPEN REX FOR READ

CHAN

455

OASS

'2 REX/IS/OPEN:0LD/SIGNAL'

H 2
18

nATTEMPT READ OF LOCKED RECORD

ATTENTION SIGNALED

M 2

(WAITING FOR RECORD LOCK)

AATTEMPT READ OF LOCKED RECORD

OWAIT 2

M 2
33

I0 ERROR

ASET WAIT FOR

2 SECONDS

AATTEMPT READ AGAIN
(TIMEOUT PERIOD EXPIRED)

K 2

RATTEMPT READ AGAIN

ORELEASE 1

ARELEASE RECORD LOCKED BY CHAN 1

ANOW RECORD IS AVAILABLE TO

CHAN 2

455

VAX APL Users Guide

5-41

VAX APL Input and Output

5.3 Advanced I/O Techniques
5.3.1.2

Sharing Direct-Access, Relative, and Keyed Files
APL does not provide any automatic sharing for direct-access and relative files.
They are not shareable for input or output unless you specifically make them
shareable by using the /SHARE switch with the 045S function.

Each user that wants to share the file must use the /SHARE switch with the
0A4SS function that associates the file with a channel. If one user opens a file
and has not specified /SHARE, other users may not share the file, even if they

do specify /SHARE. If a file is open for sharing, and a user who did not specify
/ SHARE tries to open it, APL signals FILE CURRENTLY LOCKED BY ANOTHER
USER.

Another [14SS switch, /NOWRITERS, gives you some control over file sharing. If

you specify /NOWRITERS with /SHARE (/NOWRITERS

has no meaning without

/SHARE), only you can modify the file, but all users are permitted to read it (by
specifying /SHARE/READONLY).
When files are shared, the file system locks any record as it is retrieved by a

user; the record remains locked until that user executes another file input (8)
or file output (8) function on the same channel. You can unlock records sooner

by using the ORELEASE system function (see Section 5.3.1.3).
5.3.1.3

Unlocking Shared Records
ORELEASE unlocks any locked records in files associated with the channel

numbers specified in the argument.
If you read a record that you do not intend to rewrite, it is a good idea to

unlock the record as soon as possible because other users that try to retrieve
the record are put in a wait state until the record becomes available.
In the following example, a file is shared on channels 1 and 2. Records 1, 2,

and 3 are written from channel 1, and records 4, 5, and 6 are written from
channel 2. Then, channel 1 reads record 1, and channel 2 tries to read the
same record before it is released by channel 1.

5-42

HASS

COUNT/RF/SHARE'

OASS

COUNT/RF/SHARE'

VAX APL Users Guide

"RECORD 6'

G
3

"RECORD 5'

'"RECORD

"RECORD

"RECORD 2!

VAX APL Input and Output
5.3 Advanced I/O Techniques

g1
RECORD

1
aUSER WILL ENTER WAIT STATE

2
(User enters the attention signal)

18 ATTENTION SIGNALED
H

(WAITING FOR RECORD LOCK)

ORELEASE 1
H
RECORD

2
1

In this example, the user escaped from the wait state on channel 2 by entering
the attention signal. The value of the OWAIT system function determines
APL'’s response to a locked record. Depending on the current value of OWAIT,
APL will wait indefinitely for a locked record to become available, wait for a

specified amount of time, or escape from the wait state immediately. For more
details on OWAIT, see Section 5.3.1.4.
5.3.1.4

Limiting Time on Read Functions

Dyadic OWAIT specifies the amount of time you want APL to wait when it tries
to read a shared record that is locked by another user.

When you set a waiting period, APL will wait even if you specified the
/READONLY : NOLOCKS switch when you assigned the file to a channel with
0ASS (NOLOCKS normally causes a read operation without waiting).

The left argument (¢imelimit) determines the time limit; it has the following
meanings:

Value of timelimit
!

Meaning
Don’t wait, return immediately.

Wait indefinitely (this is the default).
n

Wait for n seconds.

The OWAIT function opens the file if it is not already open. (For a list of
commands that open files, see Section 5.2.3.) Thus, unopened files associated

with channels identified by positive integers in the OWAIT argument are opened
for input; unopened files associated with channels identified in the argument by
negative integers are opened for output. Note that when you open a sequential

VAX APL Users Guide

5-43

VAX APL Input and Output
5.3 Advanced I/O Techniques
file for output, APL creates a new copy of the file with a version number that
is one higher than that of the previous copy.
OWAIT is a quiet function; if your program requires a result, APL returns 1 0.

If you deassign a channel, or if you close a file, the time limit is set to 0, the
default value. OWAIT affects the reading of shared files or sequential files
opened with the /UPDATE switch and does not influence output operations.

When a time limit has been set on a channel and the record does not become
unlocked within the time limit period, APL signals 70 ERROR (TIMEOUT
PERIOD EXPIRED).

Monadic OWVAIT queries the system for the current time limits associated with
individual channel numbers.

For each channel number in the argument, monadic OWAIT returns a value
between ~ 1 and 255 that can have the following meanings:
Value Returned
1

Current Time Limit
Don’t wait
Wait indefinitely

Wait for n seconds

If the argument is empty, the result is an empty matrix with a shape of 0 1;

if the argument is a singleton, the result is a one element vector; and if the
argument is an n element vector, the result is a matrix with a shape of n by 1.
If the channel is unassigned, OWAIT returns 0.

5.3.2

Event Flags
An event flag is a switch that is shared by all users who are in the same group

(the system manager generally is responsible for assigning users to groups; for

details see the VMS System Manager’s Manual). Event flags are particularly
useful for synchronizing access to mailboxes (see Section 5.3.3.4) or shared
files.

5.3.2.1

Associating Events Flags with Channels
Event flags, like files, must be associated with a channel number, and, as with

files, you use the JASS function to make that association. The 0455 switch
that sets up event flags has the form:
/EFN :

n, the event flag number, is an integer from 64 through 95 inclusive. You must
specify a value for n.

5-44

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
For example, the following associates event flag number 77 with channel 1:
UASS

'1 MYFILE/RF/SHARE/EFN:77"

The file specification and other information in the 4SS argument, in this case
MYFILE/RF/SHARE, are not specifically related to the event flag, except that

both are associated with the same channel. However, if you plan to use the
event flag to synchronize access to the shared file, it is convenient to associate
the file and the event flag with the same channel, thus establishing a logical
connection between the two.

If you want to set up an event flag without associating a file with a channel

at the same time, use a dummy file name for the file specification in the J4SsS
argument. As long as you do not try to open the file, the dummy specification

will not generate an error.

Each user in the group who wants access to a specific event flag must associate
the event flag number with a channel. Then, any of the users may read, set, or

clear the event flag by using the event flag system functions.
VAX APL associates the cluster name APL$_CHANNL_EFC using $ASCEFC
with the common event flag cluster given by the /EFN=n switch to .bxASS.

It does the $ASCEFC the first time any one of OEFC, OEFR, or OEFS is used
with the event flag. Since APL only allows the event flag on /EFN to be in the
interval [64..95], APL only allows access to common event flags and only one

event flag cluster. The access is allowed inside cooperating processes in the
same group so all processes in that group using /EFN have to agree on what

each event flag means.
Event Flag System Functions

There are three event flag system functions: JEFR to read event flag values,
OEFS to set event flags (make them equal 1), and OEFC to clear event flags

(make them equal 0).
The OFFR function returns the values of the event flags associated with the
channel numbers in its argument. For channels not associated with an event
flag, OEFR returns ~ 1. For example:

OEFR 15

5.3.2.2

VAX APL Users Guide

5-45

VAX APL Input and Output
5.3 Advanced I/O Techniques
The result is a matrix (or vector, if the argument is a singleton) of shape n 1,
where n is the shape of the argument. In the example, the result indicates
that the event flags associated with channels 1, 3, and 5 are set, the event flag
associated with channel 2 is clear, and no event flag is associated with channel
4,

The OEFS and OEFC functions set and clear, respectively, the event flags
associated with the channel numbers in their arguments. They return a
matrix of shape n by 1, where n is the shape of the argument, and the values
are the previous values of the event flags. For channel numbers not associated
with event flags, EFS and OEFC return ~ 1.

If the argument to OEFR, OEFS, or JEFC is empty, APL returns 0 1p 0 as the
result.

5.3.3

Mailboxes
Mailboxes allow you to communicate easily with other users. A mailbox is an
area in memory from which you can send and receive messages. In APL, the
way you access mailboxes is similar to the way you access files. The difference
is that when you send a message to a mailbox, APL prevents you from doing
further processing until another user reads the message. In addition, if you
read a mailbox that does not contain a message, APL puts you in a suspended
state until a message becomes available.
For some applications, you may want to suspend processing when you access
a mailbox; for others, you may want to be careful to read from a mailbox only
when it contains a message, or to write to a mailbox only when another user is
ready to read. Section 5.3.3.4 shows how you can use event flags to synchronize
access to mailboxes.

5.3.3.1

Associating Mailboxes with Channels
You use the 145S function with the /¥BX switch to associate a mailbox with a
channel. For example:
0ASS '1 MBOX/AS/MBX/SHARE/DISPOSE:KEEP/MAXLEN:80
/PROTECTION=(S:RWED,0:RWED,G:RWED)"'
1

A file specification (in this case ¥B0X) and the /MBX switch are required.
Mailboxes are sequential devices, so the file organization switch must be /45
or /IS.

5-46

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
The /DISPOSE : KEEP parameter makes the mailbox a permanent mailbox. If
you use /DISPOSE:DELETE, the mailbox is a temporary mailbox that is deleted
when no user has a channel associated with it. Note that

/DISPOSE:DELETE

is the default for mailboxes (/DISPOSE: KEEP is the default when /MBX is not

specified). A permanent mailbox is deleted whenever the system is rebooted.
If you use /SHARE, the mailbox is called a public mailbox and its name is

included (after the mailbox is opened) in the group logical name table (you
can use the command ) PUSH SHOW LOGICAL/GROUP to see the contents of the

group logical name table). All users in the group can find the name in the table
and access the mailbox by associating the name with achannel.

If you do not use /SHARE, the mailbox is called a private mailbox. Other users
in the group can still access the mailbox if they know its name, but the name
1s not included in the group logical name table. Thus, you can restrict access to

the mailbox.
When the mailbox is temporary, and you specify /SHARE, the logical name is

associated with a mailbox device and is inserted into the logical name table

LNM$TEMPORARY_MAILBOX. (Note that logical names of mailboxes are
case-sensitive.) By default, LNM$TEMPORARY_MAILBOX is associated with
the logical name table LNM$JOB. This logical name table is accessible only to
processes within the current job.

When the mailbox is temporary, and you do not specify /SHARE, the logical
name 1s not defined, and the mailbox can only be accessed by its device name

(the physical device number from OMBX). However, 0ASS does not allow access
to mailboxes via device names. For more information about using mailboxes,

see the VMS System Services Reference Manual.
When the mailbox is permanent, and you specify /SHARE, the logical name is
associated with
a mailbox device and is inserted into the logical name table

LNM$PERMANENT_MAILBOX. (Note that logical names of mailboxes are
case-sensitive.) By default, LNM$PERMANENT MAILBOX is associated with
the logical name table LNM$SYSTEM; this logical name table is accessible on
a system-wide basis.
When the mailbox is permanent, and you do not specify /SHARE, the logical
name is not defined, and the mailbox can only be accessed by its device name.

However, (AS5S does not allow access to mailboxes by means of device names.
The /MAXLEN parameter establishes the maximum message length for a new
mailbox. It is ignored for existing mailboxes.

The /PROTECTION switch works as described in the VAX APL Reference

Manual.

VAX APL Users Guide

5-47

VAX APL Input and Output
5.3 Advanced I/O Techniques
5.3.3.2

Sending and Receiving Messages

You use the file output (F) and file input (d) functions to send messages to and
receive messages from mailboxes. You must access mailboxes sequentially. For
examples of mailbox I/O, see Section 5.3.3.4.

5.3.3.3

[#Bx—Mailbox System Function
[OMBX returns information on the status of mailboxes. The absolute values

of chans represent the channel numbers associated with the event flags you
want to manipulate. For each channel specified, OMBX returns a row of three
elements denoting the following (from left to right):
e

The physical device number assigned to the mailbox (or 0 if the mailbox is

remote, and ~ 1 if the channel is not associated with a mailbox).
*

The process identification number (PID, returned by 0UL) of the last user

to receive a message you sent to the mailbox (or ~ 1 if no messages have
been sent).

The PID of the last user from which you received a message in the mailbox

(or ~ 1 if no messages have been received).

The result is a matrix (or a vector if the argument is a singleton) with the
shape n by 3, where n is the length of the argument.
To return a value for [J¥BX, APL must open the mailbox if it is not already

open. (For a list of commands that open files, see Section 5.2.3.) For channel
numbers represented in the argument by positive integers, APL opens the

mailbox for input; for channel numbers represented by negative integers, APL
opens the mailbox for output. Note that whether a mailbox is opened for input
or output is not significant because APL treats mailboxes like terminals; it
allows both input and output at the same time, even in sequential modes.
5.3.3.4

Sample Functions That Use Mailboxes
This section describes five groups of functions that use mailboxes. The first
three groups include functions that associate a mailbox with a channel, read
from a mailbox, and write to a mailbox. Each group is distinguished by the
way it synchronizes mailbox processing:
»

The first group does not use event flags to synchronize mailbox processing.

The second group uses one event flag.

The third group uses two event flags.

The fourth group uses mailboxes for communication between a parent
process and a subprocess.

5-48

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
The fifth group shows the effects of the /SHARE and /DISPOSE switches on

the logical name definitions of APL mailboxes.
In the first group of mailbox examples, event flags are not used to synchronize

access. Comments within each function explain what the function does.
V

[1]
[2]
[3]

CHAN«EFOASSIGN

aTHIS FUNCTION RETURNS

THE CHANNEL

NUMBER THAT

aTHE MAILBOX IS ASSOCIATED WITH.

CHAN<[JASS

'"MAILBOX/AS/MBX/SHARE'

[4]

[1]
[2]
[3]

aWHEN YOU USE THIS FUNCTION TO WRITE TO

DATA

EF00UT CHAN

aMAILBOX,

RUSER

[u]
[5]

DATA

[1]
[2]
[3]
[4]
[5]

aWHEN

SESSION IS SUSPENDED

THE

UNTIL ANOTHER

TAKES THE MESSAGE OUT OF THE MAILBOX.

B({4]

CHAN

INPUT<EFOIN CHAN
YOU

aMAILBOX,

USE THIS FUNCTION TO READ FROM A
SESSION IS SUSPENDED

UNTIL A MESSAGE

nIS AVAILABLE IN THE MAILBOX.

INPUT«W[4]1CHAN
v

In the second group of mailbox examples, one event flag is used to synchronize
access to a mailbox. These examples use the convention that if the event flag

associated with the mailbox’s channel is 0, the mailbox is empty; if the event
flag is 1, a message is available.
V

CHAN<EF1ASSIGN

[1]

ATHIS FUNCTION RETURNS

[2]

ATHE MAILBOX IS ASSOCIATED ON.

[3]

CHAN«[ASS

(4]

[1]

THE CHANNEL

'MAILBOX/AS/MBX/SHARE/EFN=6U4'

BUSY«DATA EF10UT CHAN

alF THE MAILBOX ALREADY HAS A MESSAGE IN IT,

[2]

ATHIS FUNCTION RETURNS

[3]

[5]

ADATA

[6]

AYOUR SESSION IS SUSPENDED

[7]

AREADS YOUR MESSAGE.

[81]

DATA H[u]

[101

[4]

NUMBER THAT

AIF MAILBOX IS EMPTH,
INTO

1 AND DOES NOTHING.

THIS FUNCITON WRITES

THE MAILBOX AND RETURNS

(BUSY<«[JEFS CHAN)p

UNTIL ANOHER

NOTE THAT

USER

CHAN

VAX APL Users Guide

5-49

VAX APL Input and Output
5.3 Advanced I/0O Techniques
V

[1]
[2]
[3]

[u]

INPUT«EF1IN CHAN

alF THE MAILBOX IS EMPTY,
nOTHERWISE RETURNS

(0={EFC CHAN)p

EMPTY:

[6]

INPUT«0

EMPTY

INPUT<KH[41CHAN ¢ >

[5]

RETURNS 0

THE CONTENTS OF THE MAILBOX.

In the third group of mailbox examples, two event flags are used to synchronize
access to a mailbox. These examples use the convention that event flag 81 is

set by the receiver to announce that it is searching for a sender and is cleared
by the sender when the sender recognizes the receiver. Event flag 82 is set by

the sender to announce that it is searching for a receiver and is cleared by the
receiver when it recognizes the sender.
V

[1]

[2]

@CONTAINING THE CHANNEL

2-FELEMENT

VECTOR

THAT THE MAILBOX AND

[3]

REVENT FLAG 81 ARE ASSIGNED ON

[4]

aFOLLONED BY THE CHANNEL THAT EVENT FLAG 82

[5]
[6]

CHANVECTOR<«0

[7]
[8]
[9]
[10]

5-50

CHANVECTOR«EF2ASSIGN;
PRICHAN ; SECCHAN

aTHIS FUNCTION RETURNS A

nlS ASSIGNED ON

(PRICHAN),

(SECCHAN).

+(0=PRICHAN<[JASS'MAILBOX/AS/MBX/SHARE/EFN=81")p0
+(0=SECCHAN<[JASS'DUMMY$DEVICES$: /AS/EFN=82")p0
CHANVECTOR«PRICHAN,SECCHAN
v

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
V

NOTSENT<DATA EF20UT CHANVECTORWAIT

[1]

ACHANVECTORWAIT IS A

[2]
[3]

nOF PRICHAN AND SECCHAN FROM FUNCTION EF2ASSIGN,

[4]

AWAIT BEFORE RETRYING THIS FUNCION IF

aFOLLOWED BY

3-FELEMENT

THE NUMBER OF SECONDS YOU WANT TO

[5]

aMESSAGE CANNOT BE SENT.

[6]

EVENT FLAG

[7]
[8]
[9]

SET BY RECKFIVER,

[10]
[11]
[12]
[13]
[14]
[15]
[16]
[17]
[18]
[19]
[20]
[21]
[22]
[23]
[24]
[25]
[26]
[27]
[28]
[29]
[30]
[31]
[32]
[33]
[34]
[35]
[36]
[37]
[38]

VECTOR CONSISTING

THE

81
CLEARED BY SENDER

EVENT FLAG

SET BY SENDER,

CLEARED BY RECEIVER

aTHIS FUNCTION CHECKS EVENT FLAG 81

TO SEE IF

RANYONE IS READY TO RECEIVE.

THIS

RFUNCTION RECOGNIZES
aEVENT FLAG
AnNTOTDRLITCLR

MULHOOAW
L UL,

IF SO

THE RECEIVER

(BY

CLEARING)

81 AND SENDS THE MESSAGE.
mgrc

1HL0

TIINAMTAN

CUIVGL

LUV

RTMOLDD

flnMDLPmPO

Di10odN

UMD

LDl

AAND RETURNS 1 INDICATING NO MESSAGE WAS SENT,
rOR WAITS THE NUMBER OF SECONDS SPECIFIED BY
RTHE THIRD ELEMENT IN CHANVECTORWAIT AND TRIES
RAGAIN,

aTHE SENDER LOOKING FOR RECEIVER FLAG
aNOT CLEARED IF WE RETURN

SO A

REITHER CLEAR THE FLAG OR CALL
RAGAIN LATEFR,

(82)

CALLER SHOULD

THIS FUNCTION

THE RIGHT THING TO DO IS TO

CALL

aTHE FUNCTION AGAIN BECAUSE CLEARING THE FLAG
aCOULD CAUSE A RACE CONDITION.
aNOTSENT«1

LOOP:

aINITIALIZE RESULT'

SET EVENT FLAG

alF NO RECEIVERS READY,

RETURNS

ABRANCH TO DELAY,

AND TRY AGAIN.

[OSINK+[(EFS ~1+2+CHANVECTORWAIT
WAIT,

1 AND

EXIT OR

(0=0FFC 14+CHANVECTORWAIT)p DELAY

alF

THERE IS A RECEIVER,

SEND MESSAGE AND EXIT.

DATA B[4]1+CHANVECTORWAIT ¢ » NOTSENT+0
o

nlF WAIT IS OT 0,

DELAY:

RETURN AND

OSINK<ODL ~1+CHANVECTORWAIT
+ LOOP

TRY AGAIN.

(0= 1+CHANVECTORWAIT)p

aWAIT

aTRY AGAIN

VAX APL Users Guide

5-51

VAX APL Input and Output

5.3 Advanced I/O Techniques
INPUT«WAIT EF2IN CHANVECTOR

[1]

[2]
[3]

(4]
(5]
(6]
[7]

EVENT FLAG 81

SET BY RECEIVER,

CLEARED BY SENDER

EVENT FLAG 82

SET BY SENDER,

CLEARED BY RECEIVER

A
A THIS

FUNCTION CHECKS EVENT FLAG 82

(8]

anANY SENDERS HAVE MESSAGES TO SEND.

[9]

A THE

[10]
[11]
[12]
[13]
[14]
[15]
[16]
[17]
[18]
[19]
[20]
[21]
[22]
[23]
[24]
[25]
[26]
[27]

IF YES,

FUNCTION RECOGNIZES THE SENDER AND READS

aTHE MESSAGE.
a0

TO SEE IF

OTHERWISE,

IF WAIT=0,

IF WAIT IS NOT 0,

WAITS

RETURNS

THE NUMBER

aOF SECONDS INDICATED BY WAIT AND TRIES AGAIN,
A

aTHE RECEFIVER LOOKING FOR SENDER FLAG

(81)

aNOT CLEARED IF FUNCTION RETURNS 0

nCALLER SHOULD FITHER CLEAR THE FLAG OR CALL
aFUNCTION AGAIN LATER.

nIS TO

CALL

THE RIGHT THING

THE FUNCTION LATER,

TO DO

BECAUSE CLEARING

aTHE FLAG COULD CAUSE A RACE CONDITION.
A

INPUT«<0
LOOP:

AINITIALIZE RESULT

[USINK<[JEFS 14CHANVECTOR

aANNOUNCE READY

ABRANCH IF NO SENDERS READY

(0=0FFC 1+CHANVECTOR)p DELAY

INPUT<H[4]114CHANVECTOR ¢ - 0

aGET MESSAGE.

AIF WAIT NOT O,

[28]

DELAY:

[29]

»(WAIT=0)

RETURN,
p

¢o

ELSE DELAY,

TRY AGAIN.

[SINK<«[IDL WAIT o

~LOOP

The fourth group of mailbox examples demonstrates the assignment of a

channel to a mailbox; the creation of a function that performs some simple 1/0O
through a parent process that spawns a child subprocess; and the running of

the function.

5-52

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
APARENT PROCESS
ATHROUGH A

COMMUNICATING WITH ITS CHILD PROCESS

TEMPORARY MAILBOX.

AaBUILD CHILD FUNCTION

[1]
[2]

[3]
[4]

AASSIGN CHANNEL FOR A

[5]

CH « [JASS MAILBOXNAME,'AS/MBX/SHARE/DISPOSE=DELETE!

[6]

[7]
[8]
[9]
[10]
[11]
[12]
[13]
[14]
[15]
[16]
[17]
[18]
[19]
[20]
[21]

CHILD MAILBOXNAME

;CH;DATA

J/AS MAILBOX

ADO MAILBOX I/0
A

RREAD MAILBOX MESSAGE FROM PARENT

LOOP:

DATA <« H[2]

AlF FOF RETRY

2 (A/0

75=24p

DATA)/'+ LOOP'

AECHO MESSAGE OVER MAILBOX AND BACK TO PARENT

('"++ RECEIVED

->,'DATA,'<- END')

ACONTINUE UNTIL

H[2]

QUIT RECEIVED

>(A/'QUIT
24+ ,DATA)/LOOP
A

ACLEANUP AND QUIT
A

DONE:

[DASOCHANS ¢¢')OFF!

v
A

[1]

[2]
[3]
[u]
[5]
[6]
[7]
[8]
[9]

[10]
[11]
[12]
[13]
[14]
[15]
[16]
[17]
[18]
[19]
[20]
[21]
[22]
[23]
[24]

ITERATIONS PARENT MAILBOXNAME

:CH

ASPAWN SUBPROCESS
A

" )PUSH/NOWAIT APL/TERM=TTY/SILENT=ALL MAILBOX'
A

RASSIGN CHANNEL

FOR AN /AS MAILBOX

CH « [JASS MAILBOXNAME,'/AS/MBX/SHARE/DISPOSE=DELETE"'
A

ADO MAILBOX I/0
Q

C «0
ADO ITERATIONS

LOOP:

»(ITERATIONS <

C+«C+1)/DONE

aSEND DATA

OVER MAILBOX TO

(v C) Bl[2]

CHILD

AREAD AND ECHO RESPONSE FROM CHILD

0 «

"«x MESSAGE

',(s

+ LOOP

C),'

',B[2]

AaCONTINUE

pALL DONE
g

DONE:

'"QUIT'

H[2]CH

AaSEND QUIT MESSAGE

VAX APL Users Guide

5-53

VAX APL Input and Output
5.3 Advanced I/O Techniques
aVERIFY QUIT MESSAGE RECEIVED
', (v C)," ',BH[2]) CH
ADEASSIGN
0ODAS [CHANS
¢')DROP MAILBOXSL;*'

[25]

0O « 'xx MESSAGE

[26]

[27]
[28]

[29]
A

aSAVE WORKSPACE FOR SUBPROCESS
A

OLX «

'"CHILD

''TEMPBOX'''

YWSID MAILBOX
WAS CLEAR WS

)SAVE

MONDAY

21-JAN-1991

12:01: 56.73

17 BLKS MAILBOX

aSTART MAILBOX 1I/0
o

5 PARENT

'TEMPBOXa

x* MESSAGE 1 ++ RECEIVED ->1<- END
xx MESSAGE 2 ++ RECEIVED ->1 2<- END
x+ MESSAGE

RECEIVED

->1 2

3<- END

*x MESSAGE 4 ++ RECEFIVED ->1 2 3 U<~ END
xx* MESSAGE 5 ++ RECEIVED ->QUIT<- END
APLD$: [APLIMAILBOX.APL;1 deleted (36 Blocks)

The fifth group of mailbox examples demonstrates the effects of the /SHARE
and /DISPOSE switches on the logical name definitions of APL mailboxes.
aNOTE: APL DOES NOT ALLOW ASSIGNING CHANNEL NUMBERS TO
A

MAILBOXES WITH DEVICE NAMES.

AnASSIGN AND OPEN CHANNELS TO MAILBOXES
A

0ASS 'TEMPNOSHARE/AS/MBX/DISPOSE=DELETE/OPEN=NEW'
12
11

04SS 'TEMPSHARE/AS/MBX/SHARE/DISPOSE=DELETE/OPEN=NEW'
0ASS 'PERMNOSHARE/AS/MBX/OPEN=NEW'
OASS

'"PERMSHARE/AS/MBX/SHARE/OPEN=NEW'

aVIEWN THE MAILBOX DEVICE NUMBERS THAT HAVE BEEN ASSIGNED

0 + MBX « (MBX [CHANS

5-54

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/0 Techniques

ZEXAMINE THE LOGICAL NAMES THAT HAVE BEEN DEFIINED
?DO SHOWN LOGICAL *SHARE
(LNM$PROCESS<«TABLE)
(LNM$JOB«80412D10)
APERMSHAREnR

AMBA179:n

AaTEMPSHAREn

AMBA177
:n

(LNM$GROUP+«000011)
(LNM$SYSTEM<«TABLE)
ASYSSSHARER

aSYS$SYSROOT:[SYSLIB]n

(DECWN$LOGICAL+NAMES)

2EXAMINE THE DEVICE INFORMATION ON EACH
Z+')D0 SHOW DEVICE/FULL MBA'
¢ A,
(%

14,14[1IMBX),":"

Device MBA179:

is online,

Error count
Owner process
Owner process ID
Reference count

0
AR
00000000
1

¢ A,
(v 14,14[1IMBX),":"
Device MBA178:

is online,

Error count
Owner process
Owner process ID
Reference count

UDAS [CHANS

5.3.4

o MBX<1y[1]MBX

record-oriented device,

shareable,

mailbox device.

Operations completed

Owner UIC
CUSERS, APLUSER]
Dev Prot
S:RWLP,0:RWLP,G:RWLP
,W:RWLP
Default buffer size
2044

o MBX«1{[1]1MBX

record—oriented device,

0
AA
00000000
1

shareable,

Operations completed
Owner UIC

mailbox device.

0
[USERS, APLUSER]

Dev Prot
S:RWLP,0:RWLP,G:RWN
,W:RWLP
LP
Default buffer size
2044

ADEASSIGN THE OPENED CHANNELS

Pure Data Records
The data records you write (to other than /45 files) using the B function are
APL objects. They include more than the data itself: in internal sequential,

direct-access, relative, and keyed files, APL also includes other information
within each record, such as the object’s rank, shape, and data type. APL uses

the information to format the data when you read the record using file input
(8 ). The format of this additional information is shown in Section 5.3.4.1.

Having APL internal information within records is acceptable if you are
working in an APL-only environment. You never see the internal information

and when you read a record from an internal sequential, direct-access, relative,
or keyed file, APL displays it in APL format.

VAX APL Users Guide

5-55

VAX APL Input and Output
5.3 Advanced I/O Techniques

However, if you want to create files for use by programs written in other
languages, you may want to write records containing “pure” data, that is,
records that are vectors of values with no embedded format information.
Similarly, if you want to read files created by non-APL programs, you must
instruct APL not to look for the internal formatting information that would be
in records written by APL.

APL interprets a data record as a vector of pure data if you use the data-type
option with the file input (@ ) or file output (B ) function. The forms are as
follows:

data B (I [index]1] channel [T data-typeTll @ [ [index] T channel [T data-typel]

data-type specifies the data type to be used to interpret the data. The values
and meanings for the data-type parameter are listed in Table 5—-6. The
data-type parameter is invalid with ASCII sequential files.
The other parameters have the same meanings as described in Section 5.2.3.

For file input (8 ), the data-type parameter has the same effect for internal
sequential, direct-access, relative, and keyed files. It instructs APL to assume
that the record is a vector of pure data, and to assign the indicated data type
to it.

For file output (B ), the data-type parameter instructs APL to reformat the
data in the specified data type and to write it as a single, unsegmented vector
of values. If the values cannot be reformatted into the specified data type (for
example, floating-point to Boolean), APL signals DOMATN ERROR. If the record
cannot fit into a single segment, APL signals MAXIMUM BLOCK SIZE EXCEEDED.
Data type conversion Tables 5—7 and 5-8, in Section 5.3.4.3), summarize the
effects of using the data-type parameter with all possible combinations of data
types.

The effects of using the data-type parameter with § are the same for all four
types of file organization, with one exception: records in direct-access files
have headers consisting of two longwords that contain a record number and
a segment number. (The count of record and segment numbers begins at 0,
not 1. The segment number is always 0, because pure data records cannot be
segmented.)

If you do not use the data-type parameter and you try to read a record that
is not an APL object (was not written by APL or was written by APL as pure
data), APL signals COMPONENT ERROR (RECORD NOT A COMPONENT).

5-56

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5—6
Value

Data-Type Parameter Values
External Data Type

No conversion, use type of data

32-bit integer

1-bit Boolean

F_floating single-precision floating point

D_floating double-precision floating-point

8-bit APL 04V characters

8-bit ASCII characters

8-bit numeric bytes

G_floating double-precision floating-point

H_floating floating-point

16-bit integer

8-bit Digital multinational characters

8-bit APL 04V characters in TTY mnemonics

8-bit APL D4V characters in KEY-paired APL

8-bit APL 004V characters in BIT-paired APL

8-bit APL 04V characters in COMPOSITE APL

Note that when you specity the key-type or data-type parameters for /kY files,
you can use only the external data type value O, 1, 5, 6, 11, 12, 13, 14, or 15.

These external data types allow APL to compare the length of the key value
with the key size defined for the file.
You may want to read /KY records that use different data types for the key

values and the actual data. The following example mixes character key values
and integer data. Note the form for reading /XY records randomly:
[[value [;key-num [[;tech[; key-type]llll chan [data-type]

In the example, both the key-type and the data-type parameters are specified.
This is necessary because the data types for the key values and for the actual

data are different. If they were the same, APL would use the value for
data-type as the default for key-type. (You could still specify key-type explicitly.)

VAX APL Users Guide

5-57

VAX APL Input and Output
5.3 Advanced I/O Techniques
RASSIGN NEW [KY FILE,
0ASS

PRIMARY KEY = 8

CHARACTERS

'1 TEST/KY=1:8:CHARACTER/SIGNAL'

ACREATE 3

VARIABLES FOR WRITING,

X1«(VAAAAAAAAY

[JC0Q

X2« ('"BBBBBBBB'

[JC0Q 0

15),1100+110

X3«(rccccececect

gcog 0

15),1200+110

X1 B1

X2 H1

X3 BH1

AWRITE RECORDS TO CHAN

AKEY-TYPE IS

15;

DATA-TYPE IS

Yi<M[ 444444 ;0;"EQL"';15]1

X1 =

CHARS,

10 INT

15),110

AFOUND AAAAAAAL

1 AS INTEGERS

...

aFOUND CCCCCCCC 210

202

Y3«g['CcCcCcccccc
;05 'EQL 1511 1
X3

5.3.4.1

Reading Pure Data Files Sequentially
You can use the B function with the data-type parameter to read VAX RMS
disk files sequentially. You can successfully read any such file by assigning any
of types 2, 5, 7, or 11 to the records.
If the file was not created by APL, neither the type of file organization the
file has nor the type you used when you associated the file with a channel is

important; APL reads each record as a vector of values that have the specified
data type.

Note that if the language that created the file includes internal formatting
information in its records (as APL does), the internal data is returned as part
of the record. Thus, if you want to read a file created by another language,
you may need to know something about how that language formats records.
Figure 5—-1 shows the format of an APL record on disk.

5-58

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/0O Techniques
Figure 5-1

APL Internal Record Format

component number for /DA: ignore

for /IS, /RF, and /KY
component number for /DA: ignore
for /IS, /RF, and /KY

8 bits
ignore

4 bits
lype

4 bits
ignore

16 bits
rank

0
0

x/pDATA
(pdata)1]
(pdata)2]

(pDATA) rank]
(,data)[1]
(,data)[2]

(,data)[ length]
NU-2231A-RA

rank

Is the rank of the data contained in the record.
type

Is one of the four APL internal data types described in Table 5-7. The possible

values are 0, for floating-point; 1, for integer; 2, for Boolean; and 3, for APL
character.

VAX APL Users Guide

5-59

VAX APL Input and Output
5.3 Advanced I/O Techniques
length

Is the number of items in the array.

In the following example, two records with the value 1 10 are written to
an internal sequential file: the first record is an APL object (the data-type
parameter is not used); the second record is a record of pure data (the data-type
parameter is used).
NASS

'1 TESTIS/IS!

(110)H1
(110)H1 1

ARRECORD 1 IS AN APL OBJECT
aRECORD 2 IS INTEGER PURE DATA

OCLS 1

C<«H1 7
AREAD APL OBJECT AS NUMERIC BYTES
APUT IN INTERNAL RECORD FORMAT
d(((pC)+u),4)pC
0

5.3.4.2

4
00

00
6

Reading Pure Data Files Randomly

Relative and keyed files created outside APL can be read randomly. You
must know the structure of the records written to a keyed file and the

location, length, and data type of each key. Like other languages, APL assigns
relative record numbers to /RF files, so you can use the [index] and data-type
parameters with file input (d) to randomly retrieve a particular record in a
relative file and read it as pure data.

You cannot randomly read records in an APL direct-access file as pure data,
unless the file was created by APL, or unless the file’s records were given a key
structure consistent with that used by APL.

5-60

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
5.3.4.3

Data Type Conversion Tables

APL stores all data internally as one of four possible data types:
APL character— stored as 8-bit values that are indexes (from 0 to 255) of
HAV.

Boolean—stored as 1 bit per value.
Integer—stored as 32 bits per value.

Floating-point—stored in VAX D_floating format (64 bits per value).
Table 5—7 summarizes the effects of converting (using B or 1C0Q; see

Section 5.2.3 and the VAX APL Reference Manual, respectively) an internal
APL data type to one of the external data types listed in Table 5—6 in

Section 5.3.4.
Table 5—7

Converting APL Internal Values to External Values
Floating-Point

External

Boolean

Integer

(D_floating format;

Character

Data Type

(1 bit per value)

(32 bits per values)

64 bits per value)

(8 bits per value)

type=1

Each 1 or 0 is

Each integer is

If each D_floating

APL signals DOMAIN

(integer)

written as a

written as a 32-bit

value is equal to

FRROR

integer value

a near-integer, all

. 32-bit integer
value

are written as 32-

bit integer values

otherwise, APL
signals DOMAIN
ERROR

type=2

Each 1 or 0 is

If each integer is

If each D_floating

APL signals DOMAIN

(Boolean)

written as a

equal to 0 or 1 (near-

value is equal to O or

ERROR

1-bit value

integer), all are

1 (near-integer), all

written as 1-bit

are written as 1-bit

values; otherwise,

APL signals DOMAIN

ERKROR

ERROR

type=3

Each 1 or 0 is

Each integer is

Each D_floating

(F_floating)

written as a

rounded as necessary

value is written as

32-bit F_floating

and is written as

a 32-bit F_floating

value

a 32-bit F_floating

value

APL signals DOMAIN
- ERROR

value

(continued on next page)

VAX APL Users Guide

5-61

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-7 (Cont.)

Converting APL Internal Values to External Values
Floating-Point

External

Boolean

Integer

(D_floating format;

Character

Data Type

(1 bit per value)

(32 bits per values)

64 bits per value)

(8 bits per value)

type=4
(D_floating)

Each 1 or 0

Each integer is

Each D_floating

is written

written as a 64-bit

value is written as

APL signals DOMAIN
ERROR

as a 64-bit

D_floating value

characters)

a 64-bit D_floating
value

D_floating value
APL signals

APL signals DOMAIN

Each APL character

DOMAIN FRROR

ERROR

value is written as an

8-bit APL character
value
type=6

APL signals

APL signals DOMAIN

(ASCII

DOMAIN ERROR

ERROR

See Table 5-9

characters)
type=7

Each 1 or 0 1s

If each integer is in

If each D_floating

APL signals DOMAIN

(numeric

written as an

the range 0 through

value is equal to a

ERROR

byte)

8-bit integer

255 inclusive, all

near-integer in the

value

are written as 8-

range O through 255

bit integer values

inclusive, all are

otherwise, APL

written as 8-bit

signals DOMAIN

integer values;

ERROR

otherwise APL
signals DOMAIN
EFRROR

type=8

Each 1 or 0

Each integer is

Each D_floating

APL signals DOMAIN

(G_floating)

1s written

written as a 64-bit

value is written as

ERROR

as a 64-bit

G_floating value

a 64-bit G_floating
value

G_floating value
type=9

Each 1 or O

Each integer is

Each D_floating

APL signals DOMAIN

(H_floating)

18 written

written as a 128-bit

value 1s written as

ERROR

as a 128-bit

H_floating value

a 128-bit H_floating

H_floating value

value

(continued on next page)

5-62

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-7 (Cont.)

Converting APL Internal Values to External Values
Floating-Point

External

Boolean

Integer

(D_floating format;

Character

Data Type

(1 bit per value)

(32 bits per values)

64 bits per value)

(8 bits per value)

type=10

Each 1 or O is

If each integer is in

If each D_floating

APL signals DOMAIN

the range ~ 32768

value is equal to

ERROR

16-bit integer

through 32768

a near-integer in

value

incluseive, all are

the range ~ 32768

(16-bit integer) written as a

written as 16-bit

through 32768

integer values;

inclusive, all are

otherwise, APL

written as 16-bit

signals DOMAIN

integer values’

ERROR

otherwise, APL
signals DOMAIN
ERROR

type=11

APL signals

APL signals DOMAIN

(DEC

DOMAIN ERROR

ERROR

type=12

APL signals

APL signals DOMAIN

Each character is

(TTY

DOMAIN FRROR

FRROR

ERROR

translated to the 04V

See Table 5-10

Multinational
characters)

mnemonic

characters that are its

characters)

TTY mnemonic (see

Table 1-15)

type=13
(KEY-paired

APL signals
=~ DOMAIN ERROR

APL signals DOMAIN

Each character is

FRROR

EFRROR

translated to the J0AV

characters that are

characters)

its KEY-paired APL

representation (see
Table 1-13)

type=14

APL signals

APL signals DOMAIN

Each character is

(BIT-paired

DOMAIN ERROR

EFRROR

translated to the 04V
characters that are

characthers)

its BIT-paired APL
representation (see

Table 1-14)

type=15

APL signals

APL signals DOMAIN

Each character is

(COMPOSITE

DOMAIN ERROR

FRROR

ERROR

translated to the JAV

characters)

characters that are
its APL. COMPOSITE

representation (see
Table 1-16)

VAX APL Users Guide

5-63

VAX APL Input and Output
5.3 Advanced I/O Techniques
Table 5-8 summarizes the effects of converting (using @ or [JCIQ; see

Section 5.2.3 and the VAX APL Reference Manual, respectively) external data
types to one of APL internal data types listed in Table 5-6.
Table 5-8

Converting External Data Types to APL Values

Data Types

Type Specification APL’s Action

type=1 (integer)

Interprets 32 bits at a time; returns the integer value of
each 32 bits in the record or variable.

type=2 (Boolean)

Interprets 1 bit at a time; returns a Boolean vector whose
length is equal to the length of the record or variable (in

bits).
type=3 (F_floating)

type=4 (D_floating)

Interprets 32 bits at a time; returns the F_floating value of
each 32 bits in the record or variable. APL stores F_floating
values in D_floating format.
Interprets 64 bits at a time; returns the D_floating value of

each 64 bits in the record or variable.
type=5 (APL character)

Interprets 8 bits at a time; returns the APL character value
(an element of JAV) of each 8 bits in the record or variable.

type=6 (ASCII text)

Interprets 8 bits at a time; returns the APL character
that would result from using del quad input with the TTY
character set on each 8 bits in the record or variable.

type=7 (numeric byte)

Interprets 8 bits at a time; returns the integer value of each
8 bits in the record or variable. APL stores numeric byte
values in 32-bit integer format.

type=8 (G_floating)

Interprets 64 bits at a time; returns the G_floating value of
each 64 bits in the record or variable. APL stores G_floating
values in D_floating format. If the G_floating magnitude is
outside the range (approximately) 0.26E~ 38 to 1.7E38, APL
signals DOMAIN ERROR.

type=9 (H_floating)

Interprets 128 bits at a time; returns the H_floating value
of each 128 bits in the record or variable. APL stores
H_floating values in D_floating format. If the H_floating
magnitude is outside the range (approximately) 0.26ETM 38 to
1.7E38, APL signals DOMAIN ERROR.

type=10 (16-bit integer)

Interprets 16 bits at a time; returns the integer value of
each 16 bits in the record or variable. APL stores 16-bit

integer values in 32-bit integer format.
(continued on next page)

5-64

VAX APL User,s Guide

VAX APL Input and Output
5.3 Advanced /O Techniques

Table 5-8 (Cont.)

Converting External Data Types to APL Values

Data Types

Type Specification APL’s Action

type=11 (DEC Multinational Characters)

Interprets 8 bits at a time; returns the APL character (or
characters) that would result from the translation specified
in Table 5-12 on each 8 bits in the record or variable.

type=12 (TTY mnemonic

Interprets 8 bits at a time; returns the APL character (or

character)

characters) that would result from using quote-quad input
with TTY character set on each 8 bits in the record or

variable.

type=13 (KEY-paired
APL character)

Interprets 8 bits at a time; returns the APL character (or
characters) that would result from using quote-quad input
with the KEY character set on each 8 bits in the record or
variable.

type=14 (BIT-paired

Interprets 8 bits at a time; returns the APL character (or

APL character)

characters) that would result from using quote-quad input

with the BIT character set on each 8 bits in the record or
variable.
type=15 (APL

COMPOSITE character)

Interprets 8 bits at a time; returns the APL character (or
characters) that would result from using quote-quad input
with the APL. COMPOSITE character set on each 8 bits in
the record or variable.

Table 5—9 summarizes the effect of converting APL characters to ASCII.

In addition, the following APL characters translate to ASCII as follows:

[CTRL translates into the ASCII characters with hexadecimal codes 00
through 1F, and 7F (for Delete).

[JNUM translates into the ASCII characters 0123456789.

14+ DALPHA translates into the ASCII characters A — Z.

[JALPHAL translates into the ASCII characters a — z.

All other APL characters will signal DOMAIN ERROR if you attempt to convert
them to ASCII.

VAX APL Users Guide

5-65

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-9

Converting APL Characters to ASCIl (0 10 <~ 0)

0A4v
Index

APL
Character

Equivalent
ASCII

space

OAvV
Index

APL
Character

Equivalent
ASCII

’

)

]

123

{

125

}

126

128

‘

155

(

156

[

157

;

158

159

187

188

212

Note that you cannot translate some APL characters to ASCII, and then back
to APL, when using pure data mode 6. The following transformations occur.
APL Character
Written Out

ASCII Character
External to APL

5-66

APL Character When
Read Back In

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques

APL Character
Written Out

APL Character When
Read Back In

ASCII Character
External to APL

The combination of Table 5-10 and Table 5—11 provide information for the

conversion from APL to the Digital Multinational Character Set (MCS) for all
256 characters of the multinational set.

Table 5-10

Converting from APL to Digital Multinational Characters (010+-0)

0AvV

APL

Equivalent

space

Index

Character

MCS

0Av

Index

APL

Equivalent

Character

MCS

)

]

123

{

125

}

126

128

‘

46
47

155

(

156

[

157

;

158

159

187

212

’

In addition, the following APL characters translate to the Digital Multinational
Character Set characters as follows:
e

[cTRL translates into the MCS characters with hexadecimal codes 00

through 1F, and 7F (for Delete).

VAX APL Users Guide

5-67

VAX APL Input and Output

5.3 Advanced I/O Techniques
o

[NUM translates into the MCS characters 0123456789.

1y0ALPHA translates into the MCS characters A — Z.

[JALPHAL translates into the MCS characters a — z.

Note that the preceding translation is slightly different from the translation of

APL characters to ASCII (data type = 6) in Table 5-9.
For more information about the Digital Multinational Character Set, see

Table 5-10.

Certain sequences of APL characters of the form charl Backspace char2
translate into single MCS characters, as described in Table 5-11 (070 <+ 0)
and MCS index in decimal where NUL <~ 0).
Table 5-11

Converting from APL to Digital Multinational Characters

(010 <~ 0)
char1

chari

char2

DEC

Equivalent

OAvV
Index

APL
Char

OAV
Index

APL
Char

MCS
Index

DEC MCS
Char

NUL

127

DEL

128

unused

SOH

127

DEL

129

unused

STX

127

DEL

130

unused

ETX

127

DEL

131

unused

EOT

127

DEL

132

IND

ENQ

127

DEL

133

NEL

ACK

127

DEL

134

SSA

BEL

127

DEL

135

ESA

127

DEL

136

HTS

127

DEL

137

HTJ

127

DEL

138

VTS

127

DEL

139

PLD

127

DEL

140

PLU

127

DEL

141

127

DEL

142

SS2

127

DEL

143

SS3
(continued on next page)

568

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/0O Techniques

Table 5-11 (Cont.)

Converting from APL to Digital Multinational Characters

(010 <~0)
char1

chari

char2

DEC

Equivalent

OAV
Index

APL
Char

OAV
Index

APL
Char

MCS
Index

DEC MCS
Char

DLE

127

DEL

144

DCS

DC1

127

DEL

145

PU1

DC2

127

DEL

146

PU2

DC3

127

DEL

147

STS

DC4

127

DEL

148

CCH

NAK

127

DEL

149

SYN

127

DEL

150

SPA

ETB

127

DEL

151

EPA

CAN

127

DEL

152

unused

127

DEL

153

unused

SUB

127

DEL

154

ESC

127

DEL

155

CSI

127

DEL

156

127

DEL

157

OSC

127

DEL

158

127

DEL

159

APC

space

127

DEL

160

187

161

unused

unused
i

inverted !

162

cent sign

108

163

pound sign

126

127

DEL

164

unused

121

165

yen sign

127

DEL

159

166

unused

111

115

167

section sign

111

120

168

currency sign

111

169

VAX APL Users Guide

5-69

VAX APL Input and Ourtput

5.3 Advanced I/O Techniques

Table 5—11 (Cont.)

Converting from APL to Digital Multinational Characters

(010 «~0)
char1

char1

char2

DEC

Equivalent

04V

APL

O4v

APL

MCS

DEC MCS

Index

Char

Index

Char

Index

Char

170

female ordinal

indicator
35

171

angle quotation

mark left
44

127

DEL

172

unused

127

DEL

173

unused

127

DEL

174

unused

DEL

175

unused

127

212

176

degree sign

177

plus/minus sign

212

178

superscript 2

212

179

superscript 3

127

DEL

180

’

unused

117

181

micro sign

112

187

182

paragraph sign

212

183

46
56

middle dot

127

DEL

184

212

185

unused

111

186

superscript 1

masculine ordinal

indicator
38

187

angle quotation

mark right
52

188

fraction one-quarter

49
1

189

fraction one-half

127

DEL

190

unused

191

inverted ?

128

‘

192

A grave

193

A acute
(continued on next page)

5-70

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/0 Techniques

Table 5-11 (Cont.)

Converting from APL to Digital Multinational Characters

(010 «~0)
charl

chari

char2

DEC

Equivalent

OAV
Index

APL
Char

04V
Index

APL
Char

MCS
Index

DEC MCS
Char

212

194

A circumflex

195

A tilde

156

196

A umlaut

197

A ring

101

198

A E ligature

199

C cedilla

101

128

;

200

E grave

101

201

E acute

101

212

202

E circumflex

101

156

203

E umlaut

105

128

‘

204

I grave

105

205

I acute

105

212

206

I circumflex

105

156

207

I umlaut

112

127

DEL

208

unused

110

209

N tilde

111

128

‘

210

O grave

111

211

O acute

111

212

O circumflex

111

213

O tilde

111

156

214

O umlaut

101

111

215

O E ligature

111

216

O slash

117

128

‘

217

U grave

117

218

U acute

117

212

219

U circumflex
(continued on next page)

VAX APL Users Guide

5-71

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-11 (Cont.)

Converting from APL to Digital Multinational Characters

(010 «~0)
chari

char1

char2

DEC

Equivalent

OAV

APL

OAv

APL

MCS

DEC MCS

Index

Char

Index

Char

Index

Char

117

156

220

U umlaut

121

156

221

Y umlaut

127

DEL

212

222

unused

147

223

German small sharp
S

128

129

224

a grave

129

225

a acute

129

212

226

a circumflex

129

227

a tilde

129

156

228

a umlaut

129

229

a ring

129

133

230

a e ligature

131

231

c cedilla

128

133

232

e grave

’

133

233

e acute

133

212

234

e circumflex

133

156

235

e umlaut

128

‘

137

236

i grave

’

137

237

1 acute

137

212

238

1 circumflex

137

156

239

1 umlaut

127

DEL

144

240

unused

142

241

n tilde

128

‘

143

242

0 grave

143

243

o acute

143

212

244

)

o circumflex

143

245

o tilde

(continued on next page)

5-72

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-11 (Cont.)

Converting from APL to Digital Multinational Characters

(010 «~>0)
char1

chari

char2

DEC

DAV

APL

DAV

APL

MCS

Index

Char

143

156

246

)

o umlaut

133

143

247

o e ligature

143

248

o slash

128

‘

149

249

u grave

Index

Char

Index

Char

Equivalent

DEC MCS

149

250

u acute

149

212

251

u circumflex

149

156

252

u umlaut

153

156

253

y umlaut

127

DEL

254

unused

127

DEL

127

DEL

255

unused

The order of charl and char2 is immaterial. For example, 4 Backspace '

and

' Backspace 4 both translate to “A acute”, MCS character 193.

Every MCS character has a unique translation into APL characters in

data type = 11. MCS has 256 characters. The translation for the first
128 characters is shown in Table 5-12. The translation for the second 128
characters is shown in Table 5—11. (Each MCS character whose index is

greater than 127 is translated into a 3-character sequence, charl Backspace
char2 of APL characters.)

Table 5-12

Converting from Digital Multinational Character Set to APL Characters
(010+~>0)

DEC MCS

Index

Char

APL Char

DEC MCS

Index

Char

APL Char

[AV Index

NUL

155

SOH

2
3

STX

ETX

[4V Index

(continued on next page)

VAX APL Users Guide

5-73

VAX APL Input and Output
5.3 Advanced I/0 Techniques

Table 5-12 (Cont.)

Converting from Digital Multinational Character Set to APL
Characters (0 10+« 0)

DEC MCS

Index

Char

APL Char

DEC MCS

Index

Char

APL Char

[04V Index

EOT

100

ENQ

101

ACK

102

[JAV Index

BEL

103

104

105

106

107

108

109

110

111

DLE

112

DC1

113

DC2

DC?2

114

DC3

115

DC4

DCu

116

NAK

117

SYN

118

ETB

119

CAN

120

121

SUB

122

ESC

[

]

212

(continued on next page)

5-74

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-12 (Cont.)

Converting from Digital Multinational Character Set to APL

Characters (010+«~0)

DEC MCS

Index

Char

APL Char

DEC MCS

Index

Char

APL Char

UsS

space

’

‘

128

187

129

[AV Index

[04V Index

156

130

157

131

126

100

132

158

101

133

159

102

134

’

103

135

(

104

136

)

105

137

106

;

138

107

139

108

140

—

109

141

110

142

111

143

112

144

113

145

114

146

115

147

116

148

117

149

118

150

119

151

120

152

121

153

(continued on next page)

VAX APL Users Guide

5-75

VAX APL Input and Output
5.3 Advanced I/O Techniques

Table 5-12 (Cont.)

Converting from Digital Multinational Character Set to APL
Characters (0 10+~ 0)

DEC MCS

Index

Char

APL Char

DEC MCS

[A4V Index

Index

Char

APL Char

[JAV Index

122

154

123

{

123

;

124

125

}

125

126

127

DEL

127

In the following example, the user attempts to write the integer value 60 as

each of the external data types. APL signals DOMAIN ERROR when the user
tries to write 60 as a Boolean or character value.
Reading the records back in as Boolean values indicates how they were stored

(note that all records must be at least 8 bits, so type 2 may have to be padded
with 0s).

Then, the example shows what happens when the records are using each of the
external data types.

5-76

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced I/O Techniques
HASS

60M[1]1
60H1

TEST/RF!
1

15 DOMAIN ERROR

6001
A

60H1

6081
60H1
15

DOMAIN

(ILLEGAL DATA

I'YPE CONVERSION)

(ILLEGAL DATA

TYPE CONVERSION)

(ILLEGAL DATA

I'YPE CONVERSION)

(ILLEGAL DATA

T'YPE CONVERSION)

(ILLEGAL DATA

T'YPE CONVERSION)

(ILLEGAL DATA

T'YPE CONVERSION)

(ILLEGAL DATA

TYPE CONVERSION)

60B1
A

601
15

DOMAIN

601
A

60R1

60B1

60H1
60H1
601
15

DOMAIN ERROR
6081

60H1
15

DOMAIN ERROR

60p1

60H1
15

DOMAIN ERROR

60p1

60H1
15

DOMAIN FRROR

60H1

6081
15

DOMAIN ERROR

60H1

60R1
15

DOMAIN ERROR

60R1

(INVALID EXTERNAL DATA

TYPF)

VAX APL Users Guide

577

VAX APL Input and Output
5.3 Advanced I/O Techniques
Ri<d[111

aWRITTEN AS TYPE 1

(INTEGER)

aWRITTEN AS TYPE 3

(F<FLOATING)

aWRITTEN AS TYPE 4

(D<FLOATING)

aWRITTEN AS TYPE 7

(NUMERIC BYTE)

pR1
32

R2«<M[2]1
pK2
32

R3«H[3]1
pK3
bl

Ruy<@d[4]11
pRUu
8

R5<@[5]1 2

aWRITTEN AS TYPE 8 G+<FLOATING)

oR5
64

Re<«K[6]1

eWRITTEN AS TYPE 9

(H<«FLOATING)

o Kb
128

R7«H(7]1 2

AWRITTEN AS TYPE 10

(16-BIT INTEGER)

OR7
16

R8«@[8]1

pK8
0

YWIDTH 52
WAS 132

¢ R2

¢ K3

¢ K4

o R5

¢ Ro

¢ R7

0001110110000100000000000
00O0O0TO0T
O

0000111011

0000100000000000

0000000000000 O0O0O0O0O0O0O0O0O00O
0

000O0O0OO0O0O0OO0OCOOOQCDO

00111100

011101100000001000000O0O0000O0
0

00000O0O0O0CO0O0OCOO0OOCOOOOOOOODQO

0O 000O0O0O0O0COO0OOOO0ODPO

01100000000OO0DO0O01O0O0OO0OO0OOO0OO0CCOO0OO0OO0OTGO
0

00111000000O0O0O0O0O0O0COO0OO0OO0DQO0

000000O00DOOODOOOOODOODOOOOOW
0

00000O00O0O0O0COO0OO0OOO0OOOOCODO

0O 0

000ODO0OO0DO0ODOO0OOOOOOOOOOOOOO

000O0O0OOCOOOO
001111000000O0O0O00

5-78

VAX APL Users Guide

VAX APL Input and Output
5.3 Advanced |/O Techniques
Mi1]1
1
60

RBOOLEAN

111 2

00111100000000O00DO0OO0DO0O0COO0OO0COO0OO
000

0O0O0

Mg{1J1 3

ANOT IN F<«FLOATING FORMAT

{111 4
10 LENGTH ERROR

(DATA TYPE EXCEFEDS DATA LENGTH)

4
Bl111
A

Mi111

AAPL

CHARACTERS

(Ends with

3 NUL

characters)

OAVIOIO+60]

M{1]1

aASCII

VALUE

(Ends with 3 NUL characters)

ARETURNS 4 8-BIT VALUES

mLil11 7
60
0 0 O

aONLY

Ml1]1

BITS;

10 LENGTH FRROR

TYPE

NEEDS

(DATA TYPE EXCFEDS DATA LENGTH)

M{1]1 8
A

AONLY

BITS;

TYPE

NEEDS

128

9
M{1]1
10 LENGTH FRKOR

(DATA TYPE FXCFKFEDS DATA LENGTH)

Wl1J1 9
A

l1Jl1

0
60

Mi1]1 11
<

ARETURNS 2

16-BIT

VALUES

rDigital MCS CHARACTERS
(Fnds with 3 NUL characters)

Ml1]1 12
<

M{111 13
:

Mi1]1

nTTY APL CHARACTER

(Fnds with

3 NUL characters)

(Fnds with

3 NUL

aKEY APL CHARACTER

characters)

nBIT APL CHARACTER
(Ends with 3 NUL characters)

Mi1J1 15
:

aCOMPOSITE APL CHARACTER

(Fnds with 3 NUL characters)
M{111

15 DOMAIN ERKOR

(INVALID EXTERNAL DATA TYPE)

16
M[1]1
A

VAX APL Users Guide

5-79

VAX APL Input and Output
5.3 Advanced I/O Techniques
Numeric byte data is stored as 8-bit values, so you can read it back as

characters. For example:
HASS

"1 TEST/RF!

68H[11]1

Ml11]1 7
65

M[1111

ndS APL

VALUES

alnl

M [11]1 6

aAS ASCII VALUES

ABCD

Ml11]11 2

ABOOLEAN VECTOR EQUIVALENT IS:

1000001001

00001011000010002100010

Ml11]1 1

AaINTEGER INTERPRETS AS ONE VALUE

1145258561

When you read ASCII values (type 6) as APL characters (type 5), you get the
character produced in the equivalent position on the ASCII and APL (keypaired) keyboards. For example, when the keyboard is shifted and you type 3,
the ASCII keyboard produces the number sign (#), and the APL (key-paired)
keyboard produces the less-than symbol (<).
OASS

'x $ +

TEST/RF!

M[21]1 6
x

5-80

<=2

[21]1

RASCIT

Mg[21]1 5
<

x'H

VAX APL Users Guide

RAPL FQUIVALENTS

6
Calling External Routines
VAX APL allows you to call external routines (not written in APL) from within
the APL environment. You can call library routines and routines written in
FORTRAN, C, BLISS, PL/I, PASCAL, and other languages that support the
VAX Procedure Calling and Condition Handling Standard. You cannot call

VMS system service routines directly since they do not reside in a shared
image.

You cannot call external routines that have extensive environments other than

VMS. Routines written in APL, LISP, and interpreted BASIC are examples of
such routines. To communicate with routines of this type, you can use a VMS
subprocess and the mailbox facility.
Note that you cannot call VAX APL routines from programs written in other

VMS software languages.
Calling external routines from APL requires three steps:
1.

Write a routine and link it into a VMS shared image (see Section 6.1).

Define the external routine to APL (within APL) with dyadic OMAP (see
Section 6.2.1). After using dyadic OMAP, you can use monadic OMAP to
query for a summary of the definitions that have been associated between

the external routine and APL (see Section 6.2.2).
3.

From APL, call the external routine (see Section 6.3).

The VAX MACRO and Instruction Set Reference Manual, the Introduction

to VMS System Routines, and the VMS Run-Time Library Routines Volume
contain details about calling external routines and passing parameters. You

should be familiar with these subjects before you use the VAX APL call-out
facility. Note that the term procedure is synonymous with the phrase external
routine.

VAX APL Users Guide

6-1

Calling External Routines

6.1 Linking a Routine into a VMS Shared Image

6.1

Linking a Routine into a VMS Shared Image
Write an external routine and compile the routine with debugging information

so the symbol names and source lines will be available. Note that the /DEBUG
and /INOOPTIMIZE qualifiers used only during development.

In the following example, the file named F.FOR contains FORTRAN source
code. The function F in F.FOR takes an integer vector and its length as
arguments. It adds 1 to each element of the vector that is less than 100. The
value returned by F is the number of elements that were not incremented.
$ type f.for
FUNCTION F

(LEN,

INTEGER F,

LEN,

ARRAY)

ARRAY

(LEN),

F =20

DO 100 I = 1,
IF

(ARRAY

ARRAY

LEN

(I)

.LT.

100)

THEN

= ARRAY

(I)

+ 1

ELSE

F=F+1
ENDIF

100

CONTINUE
RETURN

END)

The FORTRAN function is compiled with debugging information so the symbol

names and source lines will be available during debugging. It is compiled
without optimizations since FORTRAN optimizations invalidate certain

debugging information.
$ fortran/debug/nooptimize f

The preceding compilation creates the file named F.OBJ.

Link the object module into a shareable image. Use the UNIVERSAL linker
option to specify the entry points that will be available to the APL call-out
facility.
Continuing the example, the FORTRAN function is linked into a shared image

with debug support.
$

link/sharable=fshr/debug f,sysSinput:/options universal=f

The preceding LINK command creates the file named FSHR.EXE.
Define a logical name that refers to the shared image.
$ define f image user$:[user]fshr

The default file extension for external routine images is .EXE.

6—2

VAX APL Users Guide

Calling External Routines
6.2 Mapping the Routine into APL

6.2 Mapping the Routine into APL
Use the dyadic [IMAP system function to define an external routine to APL.

Once a routine is defined in a workspace, the workspace can be saved, loaded,
or copied, and the definition for the routine remains intact. Each time you
) LOAD or ) COPY a workspace and then invoke an external routine, the shared
image that contains the external routine is loaded (providing the shared image

exists), arguments (if any) are passed, and the routine is executed. After the
first call to an external routine, subsequent calls do not require a reloading

of the shared image (thus reducing the amount of time required to invoke the
external routine).

The monadic OMAP system function returns an operation header that provides
information on the current definition associated with an external routine.

6.2.1

Dyadic Map
Use the following form:

func-res< [ext-rout-res/attrib]func-name]arg/attrib]OMAP image-def

func-res

is the result of dyadic [I¥AP, and specifies the name of the function that has
just been defined.

ext-rout-res/attrib

if included, specifies that the external function returns a result. Note that the
result must be a scalar. The result attributes specify the type of the result in
the from of /TYPE:vms-data-type and must be one of the external data types
listed in Table 6—1 (excluding /TYPE: 7).
Do not specify the /MECHANISM attribute for the result of an external routine.
APL determines the mechanism by the value specified for /TYPE.

func-name

specifies the name you want APL to associate with the shared image entry
point The function-name, used to call the external routine as if it were a userdefined operation has a name class value of 3. Dyadic IMAP signals DOMAIN
ERROR (NAME IN USE) if the function-name is the same name as an existing

label, variable, or group, or if it is the same name as an existing operation that
1s pendent or suspended. If an operation already exists in your workspace with

the same name, and it is not pendent or suspended, IMAP replaces it.

VAX APL Users Guide

6-3

Calling External Routines
6.2 Mapping the Routine into APL
arg/attrib
specifies the names of the function’s formal parameters. These names are

similar to the dummy arguments of a user-defined operation; they are
placeholders only, and you specify the actual values for these parameters
when you invoke the function.

The attributes for each of the arguments specify the kind of access that the
external routine has to the parameter (either read, write or both), the data
type of the parameter, and the passing mechanism used to send the parameter
between APL and the external routine.
The possible forms for the attributes are as follows:

JACCESS: [IN

INOUT

OoUT
]

/TYPE: vms-data-type

/MECHANISM: [IMMEDIATE

REFERENCE

DESCRIPTOR
]

image-definition

specifies the name of the VMS shared image. Use either the VMS logical name,

or specify a file name, not the complete file specification.
Optional qualifiers include the following:
e

/ENTRY to specify the name of the starting address of the executable code
in the shared image. The default entry point is the same as function-name.

/VALUE to specify the name of a global constant, a 32-bit signed longword)

in the shared image. When you specify /VALUE, then the function-header
must specify a niladic function that returns a value with a return type of L
(for example, 'Z/TYP:L«F'). If

/VALUE 1is specified without a value, APL

assumes that the name of the global constant is the same as function-name.
In the following example, the external routine result is Z, and the functionname, F has two arguments for passing the routine parameters, A and
B.
Sapl/silent/t=d
X<'"ZJTYP:L<F A/TYP:L/MECH:REF'
X<X,'B/TYP:L/MECH:REF/ACC:INOUT'
X [OMAP

6—-4

'F_IMAGE'

VAX APL Users Guide

Calling External Routines
6.2 Mapping the Routine into APL

6.2.2 Monadic Map
The monadic form of [IMAP returns information on the current definition
associated with an external routine when used in the following form.
[MAP func-name

If func-name is empty, the result is an empty character vector. If the value
of func-name does not name an external routine, APL signals DOMAIN ERROR
(NOT AN EXTERNAL FUNCTION).

APL returns an operation header (ext-rout-def). This is the same header that
dyadic OMAP uses when you successfully define the external routine to APL.
Table 6-1

Characteristics of External Data Types

External
Type

Type
Name

DEFAULT result
/MECHANISM

Unspecified

N/S

Byte Logical

IMM

Word Logical

IMM

Longword Logical

IMM

Quadword Logical

N/S

Oou

Octaword Logical

N/S

Byte Integer

IMM

Word Integer

IMM

Longword Integer

IMM

Quadword Integer

N/S

Octaword Integer

N/S

F_floating

IMM

D_floating

IMM

G_floating

IMM

H_floating

REF

Key to Default result

Length
in Bytes

/MECHANISM

N/S—not supported
IMM—by value
REF-—by reference
DES—by description

(continued on next page)

VAX APL Users Guide

6-5

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—1 (Cont.)

Characteristics of External Data Types

External
Type

Type
Name

DEFAULT result
/MECHANISM

F complex

IMM

D complex

REF

G complex

REF

H complex

REF

CIT

COBOL Temp

N/S

8-bit Text

DES

Varying Text

REF

Numeric String

DES

Left Sign String

DES

NLO

Left Overpunch String

DES

Right Sign String

DES

NRO

Right Overpunch String

DES

Zoned Sign String

DES

Packed Decimal

N/S

Bit

IMM

Bit Unaligned

N/S

Instructions

N/S

ZEM

Entry Mask

N/S

DSC

Descriptor

N/S

BPV

Bound Procedure

N/S

BLV

Bound Label

N/S

ADT

Date/Time

N/S

other

DEC or user reserved

N/S

Key to Default result /MECHANISM

N/S—not supported
IMM—by value
REF—by reference
DES—by description

6—6

VAX APL Users Guide

Length
in Bytes

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—2

Converting Internal Data to External Data Types

External

Type

Boolean

Integer

D_Floating

No conversion

Each 1 or 0 is
passed as an
8-bit unsigned
byte

If each integer
is in the range
0 through 255
inclusive, all are

If each D_floating
value is equal to a
near-interger in the
range 0 through 255

APL signalsDOMAIN
ERROR

passed as 8-bit

inclusive, all are

wuU

Character

unsigned byptes;

passed as unsigned

otherwise, APL

bytes; otherwise,

signals DOMAIN

APL signals DOMAIN

EFRROR

FRROR

Each 1 or

If each integer

If each D_floating

APL signals DOMAIN

0 is passed

is in the range 0

value is equal to a

ERROR

as a 16-bit

through 65535

near-integer in the

unsigned word

inclusive, all are
passed as 16-bit

range 0 through
65535 inclusive,

unsigned words;

all are passed as

otherwise, APL

16-bit unsigned

signals DOMAIN

words; otherwise

ERROR

APL signals DOMAIN
FRROR

Each 1 or

If each integer is

If each D_floating

APL signals DOMAIN

0 is passed

>, all are passed

value is equal to

ERROR

as a 32-bit

as 32-bit unsigned

a near interger =,

unsigned

longwords;

all are passed as

longword

otherwise, APL

32-bit unsigned

signals DOMATIN

longwords; otherwise,

ERROR

APL signals DOMAIN
FRROR

Not supported

Not supported
(continued on next page)

VAX APL Users Guide

6-7

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—2 (Cont.)

Converting Internal Data to External Data Types

External
Type
B

Boolean

Integer

D_Floating

Character

Each 1 or 0 is

If each integer

If each D_floating

APL signals DOMAIN

passed as an

is in the range

value is equal to a

ERROR

8-bit signed

~ 128 through

near-integer in the

127 inclusive,

range ~ 128 through

byte

all are passed as

127 inclusive, all

8-bit signed bytes;

are passed as

otherwise, APL

8-bit signed bytes;

signals DOMAIN

otherwise, APL

ERROR

signals DOMAIN
EFRROR

Each 1 or o

If each integer

If each D_floating

APL signals DOMAIN

is passed as a

is in the range

value is equal to

ERROR

16-bit signed

~ 32767 through

a near-integer in

word

32767 inclusive,

the range ~ 32767

all are passed

through 32767

as 16-bit signed

inclusive, all are

words; otherwise,

passed as 16-bit

APL signals

signed words;

DOMAIN ERROR

otherwise, APL

signals DOMAIN
ERROR

Each 1 or o

Each integer is

If each D_floating

APL signals DOMAIN

is passed as a

passed as a 32-bit

value is equal to

ERROR

32-bit signed

signed longword

a near-integer, all

longword

are passed as 32-bit
signed longwords;
otherwise, APL
signals DOMAIN
ERROR

Not supported

Each 1 or

Each integer

Each D_floating

APL signals DOMAIN

0 1is passed

is rounded as

value is passed as

ERROR

as a 32-bit

necessary and

a 32-bit F_floating

F_floating

passed as a 32-bit

value

F_floating value

(continued on next page)

6—-8

VAX APL Users Guide

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—2 (Cont.)

Converting internal Data to External Data Types

External

Type

Boolean

integer

D_Floating

Character

Each 1 or
0 is passed

Each integer is

Each D_floating

APL signals DOMAIN

passed as a 64-bit

value is passed as

as a 64-bit

ERROR

D_floating value

a 64-bit D_floating

D_floating

value

Each 1 or

Each integer is

Each D_floating

APL signals DOMAIN

0 is passed

passed as a 64-bit

value is passed as

ERROR

as a 64-bit

G_floating value

a 64-bit G_floating

G_floating

value

Each 1 or o
is passed as

Each integer
is passed as a

Each D_floating
value is passed as

APL signals DOMAIN
ERROR

a 128-bit H_

128-bit H_floating

a 128-bit H_floating

floating value

value

Each pair

Each pair of

Each pair of values

of values is

values is treated

is treated as the real

APL signals DOMAIN

treated as the
real and the
imaginary

as the real and
the imaginary

and the imaginary
part of a complex

part of a complex

number; each

part of a

number; each

D_floating value

complex

integer is passed

is passed as a 32-bit

number;

as a 32-bit

F_floating value

each 1 or

F_floating value

= ERROR

0 1s passed

as a 32-bit
F_floating

value

Each pair

Each pair of

Each pair of values

APL signals DOMAIN

of values is

values is treated

is treated as the real

ERROR

treated as the

as the real and

and the imaginary

real and the

the imaginary

part of a complex

imaginary

part of a complex

number; each

part of a

number; each

D_floating value

complex

integer is passed

is passed as a 64-bit

number;

as a 64-bit

D_floating value

each 1 or

D_floating value

0 is passed

as a 64-bit
D_floating

value

(continued on next page)

VAX APL Users Guide

6-9

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—2 (Cont.)

Converting Internal Data to External Data Types

External

Type

Boolean

Integer

D_Floating

Each pair

Each pair of

Each pair of values

of values is

values is treated

is treated as the real

treated as the

as the real and

and the imaginary

real and the

the imaginary

part of a complex

1maginary

part of a complex

number; each

part of a

number; each

G_floating value

complex

integer is passed

is passed as a 64-bit

number;

as a 64-bit

G_floating value

each 1 or

G_floating value

Character
APL signals DOMAIN
= ERROR

0 is passed

as a 64-bit

G_floating
value
HC

Each pair

Each pair of

Each pair of values

of values is

values is treated

is treated as the real

treated as the

as the real and

and the imaginary

real and the

the imaginary

part of a complex

imaginary

part of a complex

number; each

part of a

number; each

D_floating value

complex

integer is passed

is passed as a 128-bit

number;

as a 128-bit

H_floating value

each 1 or

H_floating value

APL signals DOMAIN
@ ERROR

0 is passed

as a 128-bit
H_floating
value
CIT

Not supported

APL signals

APL signals DOMAIN

Each APL character

DOMAIN FRROR

DOMAIN EFRROR

ERROR

is translated to its

ASCII equivalent if
possible (see Table 5-9);

otherwise, APL signals
DOMAIN FRROR

(continued on next page)

6—-10

VAX APL Users Guide

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—-2 (Cont.)

Converting Internal Data to External Data Types

External
Type

Boolean

Integer

D_Floating

Character

APL signals

APL signals DOMAIN

Each APL character is

DOMAIN ERROR

ERROR

translated to its ASCII

equivalent if possible
(see Table 5-9) with

a 16-bit length field
preceding the string;

otherwise, APL signals
DOMAIN ERROR

APL signals

APL signals DOMAIN

DOMAIN ERROR

EFRROR

APL signals

APL signals DOMAIN

DOMAIN FRROR

DOMAIN ERROR

ERROR

APL signals

APL signals DOMAIN

DOMAIN ERROR

EFRROR

APL signals

APL signals DOMAIN

DOMAIN FRROR

DOMAIN ERROR

ERROR

APL signals

APL signals DOMAIN

DOMAIN ERROR

ERROR

APL signals

APL signals DOMAIN

DOMAIN EFRROR

ERROR

Not supported

VvV

Each 1 or o

If each integer

If each D_floating

APL signals DOMAIN

is passed as a

is equal to 0 or

value is equal to 0 or

ERROR

1-bit value

1 (near-integer),

1 (near-integer), all

NLO

NRO

all are passed

are passed as 1-bit

as 1-bit values;

values; otherwise

otherwise APL

APL signals DOMAIN

signals DOMAIN

ERROR

No conversion

FRROR

Not supported

ZEM

Not supported

DSC

Not supported

BPV

Not supported

(continued on next page)

VAX APL Users Guide

6-11

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—2 (Cont.)

Converting Internal Data to External Data Types

External

Type

Boolean

Integer

D_Floating

Character

BLV

Not supported

ADT

Not supported

any

Not supported

other

Note that external data types passed to external routines are the same as pure

data types used for input and output:
External Type
BU

<HZQU
A s

LUor LL

Table 6—-3

Pure Data Type

Converting External Data Types to Internal Data

External
Type

Internal
Type

Not supported

Integer

\\'48)

Integer

Entering
Workspace

Converts each 8-bit unsigned byte to 32-bit integer
format

Converts each 16-bit unsigned word to 32-bit integer
format

Interger

Treats each 32-bit longword as 32-bit integer format

(signed)
(continued on next page)

6-12

VAX APL Users Guide

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—3 (Cont.)

Converting External Data Types to Internal Data

External
Type

Internal
Type

Not supported

Oou

Not supported

Integer

Entering
Workspace

Converts each 8-bit signed byte to 32-bit integer
format

Integer

Converts each 16-bit signed word to 32-bit integer
format

Integer

Not supported

D_floating

Treats each 32-bit signed longword as 32-bit integer
format (signed)

Converts each 32-bit F_floating value to 64-bit
D_floating format

D_floating

Treats each 64-bit quadword as 64-bit D_floating
format (reserved operand checking is performed to
detect illegal floating point format)

D_floating

Converts each 64-bit G_floating value to 64-bit
D_floating format (overflow may occur)

D_floating

Converts each 128-bit H_floating value to 64-bit
D_floating format (overflow may occur)

D_floating

Treats each complex number as 2 values; converts
each 32-bit F_floating value to 64-bit D_floating
format

D_floating

Treats each complex number as 2 values; treats
each 64-bit quadword as 64-bit D_floating format
(reserved operand checking is performed to detect
illegal floating-point format)

D_floating

Treats each complex number as 2 values; converts
each 64-bit G_floating value to 64-bit D_floating

format (overflow may occur)

D_floating

Treats each complex number as 2 values; converts
each 128-bit H_floating value to 64-bit D_floating
format (overflow may occur)

CIT

Not supported
(continued on next page)

VAX APL Users Guide

6-13

Calling External Routines
6.2 Mapping the Routine into APL

Table 6-3 (Cont.)

Converting External Data Types to Internal Data

External

Internal

Entering

Type

Workspace

APL characters

Converts each 8-bit character to the APL character
that would result from using quad del input with
the TTY character set

APL characters

Converts each 8-bit character to the APL character
that would result from using quad del input with
the TTY character set, skipping the 16-bit length
field that precedes the string

APL characters

No conversion

APL characters

No conversion

NLO

APL characters

No conversion

APL characters

No conversion

NRO

APL characters

No conversion

APL characters

No conversion

Not supported

\Y%

Boolean

\%4 8

Not supported

/Al

Not supported

ZEM

Not supported

DSC

Not supported

BPV

Not supported

BLV

Not supported

ADT

Not supported

any

Not supported

Treats each bit as 1-bit Boolean format

other

The VMS documentation set introduces VMS data usages. Table 6-4 shows the

relationship between data usages and the APL /TYPE attribute. (Note that NA
indicates Not Applicable.)

6—-14

VAX APL Users Guide

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—4

VMS Data Structures

Data Usage

APL Attribute

Data Usage

APL Attribute

access_bit_names

logical_name

access_mode

longword_signed

address

longword_unsigned

address_range

mask_byte

arg_list

mask_longword

ast_procedure

mask_quadword

Boolean

mask_word

wuU

byte_signed

null_arg

byte_unsigned

octaword_signed

channel

octaword_unsigned

char_string

page_protection

complex_number

procedure

process_id

process_name

quadword_signed

cond_value

quadword_unsigned

context

rights_holder

date_time

rights_id

device_name

rab

ef cluster name

section_id

ef number

section_name

exit_handler_block

system_access_id

fab

time_name

file_protection

wuU

uic

floating_point

user_arg

varying_arg

vector_byte_signed

vector_byte unsigned

vector_longword_signed

function_code

(continued on next page)

VAX APL Users Guide

6-15

Calling External Routines
6.2 Mapping the Routine into APL

Table 6—4 (Cont.)

VMS Data Structures

Data Usage

APL Attribute

Data Usage

APL Attribute

io_status_block

vector_longword_unsigned

item_list 1

vector_quadword_signed

item_list_2

vector_quadword_unsigned

item_list 3

vector_word_signed

item_quota_list

vector_word_unsigned

wuU

lock_id

word_signed

lock_status_block

word_unsigned

lock value block

6.3 Invoking External Routines
Once an external routine is defined to APL using dyadic OMAP, you can invoke
the routine as if it were a user-defined operation: specify the function name (as
defined in the left argument of dyadic [I¥4P) and any argument in the following
form:
function-name [arg]|

Unlike a user-defined function, the right argument of the external routine may

take an argument list. In this case, use the following form:
function-name (argi; arg2; . .. ; argn)
The argument list is delimited by semicolons and must be surrounded by
parentheses. Each element of the list must be a simple, homogeneous array.

Alternatively, the right argument can be specified as a strand of values. In this
case, each item of the strand must be a simple, homogeneous array.
function-name arg1 arg?2 . . . argn

When you specify a semicolon list, you do not have to specify an argument
for each of the formal parameters. However, you must delimit the locations
of any missing arguments. (Because it is not possible to delimit the locations

of missing arguments with a strand right argument, the strand form cannot

be used unless all arguments are specified.) For example, if there are three
arguments, and you want to leave the second argument empty, use the
following form:
function-name (arg1 ; ; arg3)

6-16

VAX APL Users Guide

Calling External Routines
6.3 Invoking External Routines
Empty lists are also allowed:

function-name () function-name (;)

The argument list can contain only missing arguments when the access defined
for the corresponding formal parameters is IN; you must supply a value for

each parameter that is defined as OUT or INOUT. In all cases where you supply

a value, the value must already be defined to APL; you cannot supply an
undefined variable.
If, for parameters defined as OUT or INOUT, you specify a variable that does
not currently have a value, APL assumes that it will have a scalar value after

it is modified by the external routine; APL then determines the appropriate
passing mechanism based on the value you specified for /TYPE. If you specify a

variable that currently has a value, APL passes the address of the value.
When the argument list contains missing arguments, the passing mechanism
defined for the corresponding formal parameters must be either REFERENCE

or DESCRIPTOR. This is necessary because APL passes a value of 0 when it
encounters an empty argument; if you specify

/MECHANISM:

IMMEDIATE, the

external routine cannot determine whether 0O is the value of the argument or
the indicator of a missing argument.

When the argument list contains a nonscalar value whose corresponding
formal parameter is defined as

/MECHANISM:REFERENCE, APL does not have

control of the length of the value because it is passing the address and not the
value itself. In this case, the external routine must expect the length of the
value contained in the address.
Note that for any arguments to be passed from an external routine to APL, the
access defined for the corresponding formal parameters must be either 0UT or
INOUT.

APL treats external routines as locked operations. However, you can erase an
external function with the ) ERASE system command, and you can replace an

external routine definition with an APL function definition by using the OFX
system function.

Note that any changes made to your terminal characteristics by the external
function remain in effect when the function completes execution. (For example,

these terminal characteristics include the print width, broadcast, or line
editing.)
When an external routine signals an error to APL, APL signals SIGNAL FROM
EXTERNAL ROUTINE xxx, where xxx is the message sent from the external
routine.

VAX APL Users Guide

6-17

Calling External Routines
6.4 Debugging External Routines

6.4 Debugging External Routines
VAX APL features include support for the VMS Debugger.

Also, you can use [ITRACE, 0STOP, and OMONITOR with external routines (with
line numbers 0, 1, and 0, respectively).

The following is an example of debugging an external routine called from APL.
The example uses the following system functions:
e

[1STOP to invoke the VMS Debugger

[JTRACE to trace the value returned by the external routine

[IMONITOR to time the execution of the external routine

For more information on [JTRACE, 0STOP, and OMONITOR, see the VAX APL
Reference Manual.

Continuing the example from the previous sections, debug F from inside APL.
1 JSTOP

'F!

aSET BREAKPOINT ON FIRST LINE OF F

X<15

Fo(5;'X")

VALUE EKRKOR
F(5:'X")
A

Setting module F
break at routine F
1:

FUNCTION F

DBG>

set

language

DBG>

step

stepped to F\%LINE 2
2
INTEGER F,
DBG>

step

stepped to F\%LINE 4
4.
F =0
DBG>

examine len

F\LEN:
DBG>

examine array

F\ARRAY

(1)

(2):

(3):

DBG>

6—-18

(4) :

(5)

VAX APL Users Guide

(LEN,

ARRAY)

LEN,

ARRAY

fortran

(LEN),

Calling External Routines
6.4 Debugging External Routines
Trace the result of F:
VFF N

L: XN
X{OOM 2[X]1+200

[1]
[2]
[3]

OSINK<F

[4]

>(0<N<N-1)/L

(N;'X'")

[5]

[OTRACE

'F!

FF u

F[0]

FL{oJl

F{o]

Flol

1
't

[JTRACE

'F!

Time the execution of F':
0

OMONITOR

1000

OMONITOR
0

1000

'F!

'F'

840

6.5 Examples of Calls to External Routines
The following subsections describe possible uses of calls to external routines.

6.5.1

Example 1: Calling RTL MTH$DACOSD
The VMS Run-time Library (RTL) routine MTH$DACOSD takes a
D_FLOATING point number as the cosine of an angle and returns the angle,

in degrees, as a D_FLOATING point value. (See the VMS Run-Time Library
Routines Volume for more information.) This routine can be called from
VAX APL with the following statements:
A<

'7JTYP:D <« DACOSD A/TYP:D/MECH:REF'

B«

"MTHRTL/ENTRY:MTH$DACOSD'

4 [IMAP B
DACOSD

UMAP

'"DACOSD'

Z/TYPE:D/MECHANISM: IMMEDIATE+

DACOSD/IMAGE :MTHRTL/ENTRY :MTH$DACOSD
A/ACCESS:IN/TYPE:D/MECHANISM:
REFERENCE
DACOSD

0.33333

70.52898194

VAX APL Users Guide

6-19

Calling External Routines
6.5 Examples of Calls to External Routines

6.5.2 Example 2: Calling RTL LIBSERASE_PAGE
The VMS RTL routine LIBSERASE_PAGE erases a video screen from the
current cursor position to the end of the screen. It takes two optional 16-bit
integer parameters that specify the line number and the column number at
which to position the cursor before doing the erase. By positioning the cursor
at line number 1 and column number 1, the entire screen can be erased. The
routine returns a status value as an integer result. This routine can be called
from VAX APL with the following statements:
A«

'7/TYP:I <ERASE PAGE L/TYP:W/MECH:REF'

B«

'SCRSHR/ENTRY:LIB$ERASE
PAGE'

A [OMAP B

ERASE PAGE

OMAP 'ERASE_PAGE'
7/TYPE:L/MECHANISM: IMMEDIATE«

ERASE PAGE/IMAGE:SCRSHR/ENTRY:LIB$ERASE
PAGE
L/ACCESS:IN/TYPE:W/MECHANISM:
REFERENCE
aCLEAR THE ENTIRE SCREEN
STATUS< ERASE PAGE

6.5.3 Example 3: Calling LIBSPUT_SCREEN
The VMS RTL routine LIB$PUT_SCREEN displays text at a specified cursor
location on the video screen. The routine takes up to 4 arguments:

TEXT—a read-only character string, passed by descriptor, that is the string
to display. No carriage return or line feed control characters are inserted.

LINE-NO—an optional read-only 16-bit integer (word), passed by reference,
that specifies the video screen line number at which to display the text. If
omitted, the default is the current line number.

COL-NO— an optional read-only 16-bit integer (word), passed by reference,
that specifies the video screen column number at which to display the text.
If omitted, the default is the current column number.

FLAGS—a read-only longword, passed by reference, that specifies terminal
characteristics as bits:

6-20

—

Bit 0 on means bold

—

Bit 1 on means reverse video

—

Bit 2 on means blinking

—

Bit 3 on means underscored

VAX APL Users Guide

Calling External Routines
6.5 Examples of Calls to External Routines
The routine returns a status value as an integer. The following example shows

various calls to LIB§PUT_SCREEN from VAX APL:
A«

'"7/TYP:L < PUT SCREEN C/TYP:T/MECH:DESC

A« A,

"L/TYP:W/MECH:REF C/TYP:W/MECH:REF

A« A,

'"F/TYP:W/MECH:REF"'

B«

'"SCRSHR/ENTRY:LIB$PUT
SCREEN'

A OMAP B
PUT_SCREEN

OMAP 'PUT_SCREEN'
Z/TYPE:L/MECHANISM: IMMEDIATE<
PUT SCREEN/IMAGE:SCRSHR/ENTRY:LIB$PUT_SCREEN
C/ACCESS:IN/TYPE:T/MECHANISM:DESCRIPTOR
L/ACCESS:IN/TYPE:W/MECHANISM:REFERENCE

C/ACCESS:IN/TYPE:N/MECHANISM:
REFERENCE
F/ACCESS:IN/TYPE:N/MECHANISM:
REFERENCE

STRING <«

'SOME TEXT'

aPUT STRING AT

UCTRL

[14

CURRENT CURSOR

11]

POSITION

STATUS« PUT SCREEN STRING
aPUT STRING AT LINE 5

STATUS« PUT SCREEN
aPUT STRING AT LINE
a

IN REVERSE

COLUMN

(STRING
6

;

COLUMN

;

10)

;

VIDEO

STATUS« PUT SCREEN

(STRING

;

6.5.4 Example 4: Calling RTL LIBSGET_SCREEN
The VMS RTL routine LIB$GET_SCREEN reads an input string from the
terminal. The routine takes up to 3 arguments:
e

INPUT-TEXT—a write-only character string, passed by descriptor, that

contains the text read from the terminal.
e

PROMPT-STR—an optional read-only character string, passed by
descriptor, that contains a prompt to display on the terminal before
doing the read.

OUT-LEN—an optional read-write 16-bit integer (word), passed by
reference, that contains the length
of the string put into the INPUT-TEXT
argument.

The following example shows various calls to LIB$PUT_SCREEN from
VAX APL:

VAX APL Users Guide

6-21

Calling External Routines
6.5 Examples of Calls to External Routines
A< '7/TYP:L <« GET SCREEN I/TYP:T/MECH:DESC/ACC:INOUT
A< 4 , "PJTYP:T/MECH:DESC L/TYP:WU/MECH:REF/ACC:INOUT'
4 [MAP

'"SCRSHR/ENTRY:LIB$GET
SCREEN'

GET SCREEN

OMAP

'GET SCREEN'

7/TYPE:L/MECHANISHM: IMMEDIATE<

GET SCREEN/IMAGE:SCRSHR/ENTRY:LIB$GET
SCREEN

I/ACCESS: INOUT/TYPE:T/MECHANISM:
DESCRIPTOR
P/ACCESS:IN/TYPE:T/MECHANISM:
DESCRIPTOR
L/ACCESS:INOUT/TYPE:WU/MECHANISM:
REFERENCE
TEXTLEN < 80
INTEXT « 80

PROMPT <«

'ENTER YOU DATA:

o TEXT WILL BE READ INTO

VARIABLE INTEXT

aPROMPT WILL APPEAR
oTHE LENGTH OF THE TEXT READ INTO
o

INTEXT WILL BE PUT INTO

STATUS < GET SCREEN
ENTER YOUR DATA: HI THERE
o

TEXTLEN

('INTEXT'

;

PROMPT;

'TEXTLEN')

O « INTEXT

HI THERE
8

TEXTLEN
g

6.5.5 Example 5: Calling VMS SORT
The following example shows VAX APL calling the VMS SORT Utility. For
details on this utility, see the VMS Sort/Merge Utility Manual or the VMS
Utility Routines Manual.
I«

'"X/TYP:L <« FILES

I« 7,

"A/TYP:T/MECH:DESC

I« Z,

'"B/TYP:T/MECH:DESC"

Z [OMAP

aINPUT FILE

aQUTPUT FILE

'"SORTSHR/ENTRY:SOR$PASS<FILES'

FILES

[<'X/TYP:L« INIT

< 7,

"A/TYP:W/MECH:REF

oaKEY COUNT,

< 7,

'"B/TYP:N/MECH:REF

aLONGEST REC LEN

ASC,

2« 7,

'"C/TYP:W/MECH:REF

aOPTION FLAGS

I« 7,

'"D/TYP:W/MECH:REF

aNUMBER OF WORK FILES

I« 7,

"E/TYP:W/MECH:REF'

Z [OMAP

aSORT TYPE

'SORTSHR/ENTRY:SOR$INIT<SORT'

INIT

I+~

"X/TYPE:L « VMSSORT'

Z [OMAP

'SORTSHR/ENTRY:SOR$SORT<«MERGE"

VMSSORT

L«

'"X/TYPE:L « END'

Z [OMAP

'SORTSHR/ENTRY:SOR$END<SORT'

END

6-22

TYPE,

VAX APL Users Guide

START,

LEN

Calling External Routines
6.5 Examples of Calls to External Routines
'"FILES'

OMAP

X/TYPE:L/MECHANISM: IMMEDIATE+«
FILES/IMAGE:SORTSHR/ENTRY
: SOR$PASS FILES
AJACCESS:IN/TYPE:T/MECHANISM:DESCRIPTOK

B/ACCESS:IN/TYPE:T/MECHANISM:DESCRIPTOR
UMAP

'INIT'

X/TYPE:L/MECHANISM
: IMMEDIATE+«
INIT/IMAGE :SORTSHR/ENTRY :SOR$INIT SORT

A/ACCESS:IN/TYPE:W/MECHANISM
: REFERENCE
B/ACCESS:IN/TYPE:W/MECHANISM
: REFERENCE

C/ACCESS:IN/TYPE:N/MECHANISM:REFERENCE
D/ACCESS:IN/TYPE:W/MECHANISM:REFERENCE
E/ACCESS:IN/TYPE:W/MECHANISM
: REFERENCE

'"VMSSORT'

[IMAP

X/TYPE:L/MECHANISM
: IMMEDIATE«
VMSSORT/IMAGE
: SORTSHR/ENTRY : SOR$SORT MEKGE

'"END'

UMAP

X/TYPE:L/MECHANISM
: IMMEDIATE+«
END/IMAGE : SORTSHR/ENTRY
: SOR$END SORT
V

CREATE FILE

[1]

OSINK « [JASS

[2]

1«27

[3]

L:(80pUALPHATI])

[4]
[5]
[6]

> (2 < T«I-1)/L
ODAS 1
v

[1]
[2]

OTRAP <« '» EQF!
OSINK«<[ASS '1 ' ,FILE,'/AS/SIGNAL/OPEN:OLD'

[3]

L:M[2]1

' ,FILE,'/AS/OPEN:NEW!
H

[211

DISPLAY FILE

[4]

> T

[5]
[6]
[7]

EOF :[JEKKOR
ODAS 1
V
CREATE

'"DESCEND.AAS'

DISPLAY

'"DESCEND.AAS'

L2ZL2222ZZ222222222222222Z222222Z2202Z2Z00822Z02222222222222217 . .

YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY. . .

KXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX . . .

DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD .
ccecececeeeeecceeccceceeoccececcceceececceeecececcecceececcccececec o

BBBBBBBBBBBBBBBBBBBBBEBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBAE . . .
AAAAAAAAAAAAAAAAALAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAL

END OF FILE ENCOUNTERED

DISPLAY[3]

L:Md[2]1
A

FTT?,"("

FRENY YY)

MATIAT T

VOO UCLIVL

AAC!

HA D

1T ACQATTIAT T

HOoVLIWL
s HA U

VAX APL Users Guide

6-23

Calling External Routines

6.5 Examples of Calls to External Routines
aONE SORT KEY:

CHARACTER ASCENDING

ASTARTING AT CHAR 1 FOR 80

CHARS

ANO MAXIMUM RECORD LENGTH
ANO OPTIONS
aUSE 3 WORK FILES
ASTABLE TYPE SORT

INIT (5p1 120180

;

VMSSORT
1

END
1

DISPLAY

TASCEND.AAS'

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALL | . .

BBBBBBBBBBBBBBBBBBBBBBEBBBBBBBBBBBBEBBBBBBBBBBBBBBBBBBBBBBAB . .

ccceeeeeeeceeeeceeeeeeecceeeceeeceececececeeeccececccecececececececeeeece . . .

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX . . .
YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY | . .
Z7Z7727727222222222222222270020202Z2Z2Z2Z22Z222222Z222222272222222 . . .
68 END OF FILE ENCOUNTERED
L:H[2]1

DISPLAY[3]

6.5.6 Example 6: Calling VAX FORTRAN
The following example shows VAX APL calling a VAX FORTRAN function.
The FORTRAN function RHYME expects a character argument, which it
modifies. Then, the function returns the length of the new character value as
the function value. Assume the function is contained in a file named T.FOR:
Stype t.for

FUNCTION RHYME

(C)

INTEGER RHYME

(*) C
CHARACTER*
INTEGER L

L = LEN

(C)

(L .GE. 22

.AND. C(1:9)

.EQ.

'.RO.RO.RO")THEN

C = 'GENTLY DOWN THE STREAM’
RHYME = 22

ELSEIF
C =

(L .GE.

RHYME = 19
ELSE

C = 'WHAT ?'
RHYME = 6
ENDIF

6-24

.AND. C(1:4)

'LIFE IS BUT A DREAM'

VAX APL Users Guide

.EQ.

"4.RO")

THEN

Calling External Routines
6.5 Examples of Calls to External Routines
RETURN

END

The following commands create a shared image containing the FORTRAN
function RHYME:

$ fortran t.for/object=t.obj/optimize

$ link/shar=shrt t.obj,sys$Sinput:/options universal=rhyme

The APL function F sets up and calls the FORTRAN function RHYME. Note
that a job-wide logical name must be used to point to the shared image
DEVDIR:SHRT containing RHYME.
V

:L1:;L2:X:7Z

[1]

USINK < JX@

[2]

0xqQ

')DO DEFINE/JOB XX DEVDIKR:SHRT'

[3]
[4]
[5]
[6]
[7]
[8]
[9]
[10]
[11]
[12]
[13]

VZ/TYP:L « RHYME A/TYP:T/MECH:DESC/ACC:INOUT"' [JMAP 'XX'
Li< ('ppp YOUR BOAT' [JC0Q 0 12) [CIQ 0 11
L1 [QOOM 34=2QCTRL 1+ L1] <« ' !

'DO SHOW LOGICAL/JOB XX')

L2« ('3p'"'MERILY,''' [0C0Q 0
L2« [[0OM 3uz[JCTRL 1 L2] <« '
L1
X<+22 S L1 ¢ Z<RHYME 'X'
)ZSX
)L?
)X <« 10SL2 o Z<«RHYME 'X!

12)

QOCIQ 0

)ZSX

[14]

)V
F

aXXa

aDEVDIR:SHRTa

(LNM$JOB<«80E14CBO)

RHYME

.RO.RO.RO YOUR BOAT
GENTLY DOWN THE STREAM

3.RO'MERRILY,'
LIFE IS BUT A DREAM

6.5.7 Example 7: Calling VAX DATATRIEVE
The following examples establish definitions in VAX DATATRIEVE, use OMAP
to define the DATATRIEVE external routines to APL, create user-defined
functions that interact with the DATATRIEVE routines, and then show APL
calling DATATRIEVE.
Prior to executing APL, the following must be established in DATATRIEVE:

The following DATATRIEVE commands define the record structure that is
used for both the PARTS files and the communications port:

VAX APL Users Guide

6-25

Calling External Routines
6.5 Examples of Calls to External Routines
DTR>

define record parts rec using

DFN>

01 parts

rec.

DFN>

03 partno

pic

9(5)

DFN>

03 desc

pic

x(20)
.

comp.

DFN>

03 value

pic

9(6)

v99

comp—2.

DEN>
;

The following commands define the domain for the PARTS file and
establish an empty ISAM file with a single index key, the part number,
represented by PARTNO:
DTR>

define domaln parts using parts rec on parts.dat;

DTR>

define

file

for parts

key = partno;

The following command defines the communications port that is used to
pass data records between APL and DATATRIEVE:
DTR>

define port tport using parts rec;

Before executing APL, you should define the logical name CDD$DEFAULT
to be the DATATRIEVE directory that contains the domains and record
definitions that you have just created. This can be done as follows:
S

define cddS$default cddStop.subdirectorypath

Where subdirectorypath represents the subdirectory path names that
identify where the definitions reside. For example:
S

define cdd$default cddStop.apl

You can now execute APL and use the callable interface detailed below to
read and write records using DATATRIEVE.
The following example describes the external functions that must be defined to
APL in order to use DATATRIEVE.:

DTR$INIT—initializes the interface to callable DATATRIEVE.:
[OMAP 'DIRAINIT!
STATUS/TYPE:L/MECHANISM: IMMEDIATE+

DTRAINIT/IMAGE:DTRSHR/ENTRY
:DTR$INIT
DAB/ACCESS:INOUT/TYPE:WU/MECHANISM:
REFERENCE
SIZE/ACCESS:IN/TYPE:L/MECHANISM:REFERENCE

MSGBUF /ACCESS:IN/TYPE:T/MECHANISM:DESCRIPTOR
AUXBUF/ACCESS:IN/TYPE:T/MECHANISM:DESCRIPTOR
OPTION/ACCESS:IN/TYPE:L/MECHANISM:
REFERENCE

6—26

VAX APL Users Guide

Calling External Routines
6.5 Examples of Calls to External Routines
DTR$COMMAND—passes a command to DATATRIEVE:
UMAP

'"DTRACOMMAND'

STATUS/TYPE:L/MECHANISM: IMMEDIATE<«
DTRACOMMAND
/| IMAGE : DTRSHR/ENTRY : DTR$COMMAND

DAB/ACCESS:INOUT/TYPE:WU/MECHANISM:
REFERENCE
CMD/ACCESS:IN/TYPE:WU/MECHANISM:DESCRIPTOR

DTR$GET PORT—reads a record from the communications port:
UMAP

'"DTRAGET PORT'

STATUS/TYPE:L/MECHANISM: IMMEDIATE<

DTRAGET PORT/IMAGE:DTRSHR/ENTRY:DTR$GET
PORT
DAB/ACCESS:INOUT/TYPE:WU/MECHANISM:
REFERENCE

RECORD/ACCESS:IN/TYPE:NU/MECHANISM:
REFERENCE

DTR$PUT PORT—writes a record to the communications port:
OMAP

'"DTRAPUT_PORT'

STATUS/TYPE:L/MECHANISM: IMMEDIATE<

DTRAPUT PORT/IMAGE:DTRSHR/ENTRY:DTR$PUT_PORT
DAB/ACCESS:INOUT/TYPE:NU/MECHANISM:
REFERENCE
RECORD/ACCESS:IN/TYPE:NU/MECHANISM:
REFERENCE

DTR$PORT_EOF—terminates a sequence of records written to the
communications port:
(MAP

'DTRAPORT EOF'

STATUS/TYPE:L/MECHANISM: IMMEDIATE<

DTRAPORT EOF/IMAGE:DTRSHR/ENTRY
:DTR$PORT EOF
DAB/ACCESS:INOUT/TYPE :WU/MECHANISM: REFERENCE

DTR$CONTINUE—scans error codes returned by DATATRIEVE:
OMAP

'"DTRACONTINUE'!

STATUS/TYPE:L/MECHANISM
:: IMMEDIATE<

DTRACONTINUE/IMAGE:DTRSHR/ENTRY :DTR$CONTINUE
DAB/ACCESS: INOUT/TYPE :WU/MECHANISM:
REFERENCE

DTR$FINISH—terminates callable DATATRIEVE:
OMAP

'"DTRAFINISH'

STATUS/TYPE:L/MECHANISM: IMMEDIATE+

DTRAFINISH/IMAGE :DTRSHR/ENTRY :DTR$FINISH
DAB/ACCESS:INOUT/TYPE:WNU/MECHANISM:
REFERENCE

VAX APL Users Guide

6-27

Calling External Routines
6.5 Examples of Calls to External Routines
DTR$UNWIND-—cancels unused commands:
[MAP

'DTRAUNWIND'

STATUS/TYPE:L/MECHANISM: IMMEDIATE+

DTRAUNWIND/IMAGE :DTRSHR/ENTRY : DTR$UNWIND
DAB/ACCESS:INOUT/TYPE:NU/MECHANISM:
REFERENCE

LIB$SYS _GETMSG—gets a system error message:
[IMAP '"ERRORAMESSAGE'
STATUS/TYPE:L/MECHANISM: IMMEDIATE<«

ERRORAMMESSAGEE/IMAGE
: LIBRTL/ENTRY :LIB$SYS_GETMSG
ERRNO/ACCESS:INOUT/TYPE:L/MECHANISM:REFERENCE

LENGTH/ACCESS:INOUT/TYPE :WU/MECHANISM : REFERENCE
ERRORATEXT/ACCESS:INOUT/TYPE:T/MECHANISM:DESCRIPTOR
FLAGS/ACCESS:INOUT/TYPE:L/MECHANISM:REFERENCE
QUTBUF/ACCESS:INOUT/TYPE:T/MECHANISM:
REFERENCE

The following examples describe the APL functions used to invoke the external
DATATRIEVE functions:

I1NIT—establishes communications with DATATRIEVE and establishes the
domains to be used. In the example that follows, PARTS is a file domain
that contains the data to be manipulated. TPORT is a port domain used
for passing records between APL: and DATATRIEVE.
DAB is a control block used to pass status and other control information
between APL and callable DATATRIEVE. It is used as a vector of
UNSIGNED WORD values because this allows easy access to the two
fields that are important. DAB[2 3] holds the two halves of the condition
value and DAB[13] holds the current state of the call interface. The size of
the DAB control block is 100 bytes; thus, DAB is defined to be a vector of
50 integers that will be mapped into 50 UNSIGNED WORDS.

The third and subsequent arguments to DTR$INIT are optional and
are not used in this example. The size (in pages) to be allocated for the
DATATRIEVE stack is 100.
VINIT

6-28

;17

(1]

DAB « 50 p 0

[2]

Z< DTRAINIT

[3]
READY
[4]
[5]

< DTRACOMMAND ('DAB':;'READY PARTS WRITE;
TPORT WRITE;')
CONT
¥

VAX APL Users Guide

('DAB';10043)

)

Calling External Routines
6.5 Examples of Calls to External Routines
CcoPYV IN—instructs DATATRIEVE to send all records of PARTS to the
port.
VCOPYAIN
L<DTRACOMMAND

'Z
('DAB';'FOR PARTS STORE

TPORT

USING PARTS REC

)

PARTS REC;'
V

READV ALL—reads the records sequentially from the port:

The DATATRIEVE record definition for the PARTS file specifies that the
VALUE field has 2 decimal places. DATATRIEVE will scale the data stored
into VALUE by 2 decimal places when the record is put into the file by
DATATRIEVE. The data is not scaled down again when the record is read
back through the callable interface, so this function divides the VALUE
field passed by DATATRIEVE by 100.
VREADAALL ;2 ;RECORD ; PARTNO ; DESC; VALUE

[1]

RECORD+8p0

[2]

LO:Z « DTRAGET PORT

(31

=~ (1# Z)

[4]

('DAB';'RECORD'")

/ L1

[5]

DESC < 1

PARTNO«RECORD[
1]
20 p RECORD

[1+.5]

[6]

VALUE <

(RECORD

[CIQ

[7]

'I5,

20A1,

4X,

[8]

+~ L0

[9]

L1:CONT

[10]

F8.,2"'

[CIQ

[JFMT

(PARTNO;DESC;VALUFE)

coPYV 0UT—instructs DATATRIEVE to store records from the port into the

PARTS file:
VWRITE A;7Z

[1]

Z< DTRAPUT PORT

[2]

v
VWRITEAEOF

('DAB';4)

[1]

L<DTRAPORT
EOF

[2]

CONT

[3]

Z«DTRACOMMAND

(4]

CONT

[5]

('DAB')
('DAB':':")

WRITE—writes a record to the port:
VWRITE A7

[1]

Z+ DTRAPUT PORT

[2]

('DAB';4)

WRITEA EOF—terminates a sequence of records written to the port:

VAX APL Users Guide

6-29

Calling External Routines

6.5 Examples of Calls to External Routines
The semicolon (;) is required to terminate the command sequence that
writes the records to the port.
VWRITEANEOF

[1]
[2]
[3]
(4]
[5]

Z«DTRAPORT_EOF ('DAB')
CONT
Z<«DTRACOMMAND ('DAB';';")
CONT
V

FINISH—terminates communications with DATATRIEVE:
VFINISH

[1]

(2]

Z<DTRVFINISH ('DAB')
¥

DABI[2 3] hold the two halves (in reverse order) of the condition value. This

function calculates the condition value from the two DAB elements.
V

[1]
[2]

I < ERROR

Z«DAB[2] + DAB[3] x 65536
¥

cONT—reads error conditions returned from DATATRIEVE.
After a command has been sent to DATATRIEVE, the function returns
the value of 1, with the state being returned in the DAB. The state field
in the DAB is element 13 (DAB[13]). If this has the value 4, the success
or failure of the function is indicated in the condition value in the DAB,

elements 2 and 3. We must successively execute DTR$CONTINUE until
the state field becomes 1, which indicates that DATATRIEVE is waiting for
another command. The condition value of 9274723 is DTR$_SUCCESS,
that 1s, successful command execution.
VCONT

1]
(21

~» (4 = DAB[13]) /L1
L0: Z <« DTRACONTINUE ('DAB') o » (1 = DAB[13])/ 0

[3]

- (9274723

(4]

(5]

= Z + ERROR)
DISPLAYAERROR 7 o » LO

/L0

Li: -+ (1 = DAB[131) /0

(6]

DAB[13]

[71

DISPLAYV ERROR—displays the error message corresponding to the error
condition returned from DATATRIEVE:

6-30

VAX APL Users Guide

Calling External Routines
6.5 Examples of Calls to External Routines
VDISPLAYNERROR ERRNO;

[1]

LENGTH « 0

[2]

L<ERRORAMESSAGE

(3]

ERRORATEXT

[4]

ERRORAMTEXT;LENGTH;Z

o ERRORATEXT <« 256p
(ERRNO;

'"LENGTH';'ERRORATEXT';;)

[WLENGTH]

10. FORMATV RECORD—formats a record from its constituent fields.
The VALUE field must be scaled up by 2 decimal places before being
written to DATATRIEVE because DATATRIEVE stores VALUE 1n the file
1n a scaled format.
VA

FORMATARECORD X;TEMP

[1]

TEMP« 8

[2]

TEMP

[1]<e,X[1:]

[3]

TEMP

[1+15]

[u]

TEMP

[5]

¢ A,

'«TEMP!

[6]

<«
<«

(e,X[2:])

0C0Q

(100xe,X[3:1])

0
0C0Q

11. FTELDS—the fields that make up a record:
FIELDS

PARTNO
DESC
VALUE

The following series of APL functions initialize the communications channel to
DATATRIEVE and display all of the records therein.

Notice that record number 3 is missing; we will add it in the second half of the
example. The individual fields are set to the appropriate values and formatted
into the record, which is then written to the PARTS file. The example then
rereads all of the records from the PARTS file to check that the insertion
worked. Finally, the communications channel is closed.

VAX APL Users Guide

6-31

Calling External Routines
6.5 Examples of Calls to External Routines
INIT

COPYAIN
READAMALL
1

PART NUMBER

12.34

PART NUMBER 2

J4.56

PART NUMBER 4

32.69

PART NUMBER 5

1234.56

PARTNO+ 3
DESC <« 20

'PART NUMBER

VALUE< 987.65

"RECORD'

FORMATARECORD FIELDS

COPYAOUT
WRITE RECORD

WRITEAEOF
COPYAIN
READAALL

PART NUMBER 1

PART NUMBER 2

PART NUMBER

12.34
34.56
987.69

PART NUMBER

32.69

PART NUMBER 5

1234.56

FINISH

6.5.8 Example 8: Using JMAP with /VALUE
The following example shows the use of the / VALUE switch with OMAP.
The DATATRIEVE error message "%DTR-E-ERROR, Statement abandoned

due to error" is associated with the DATATRIEVE symbol DTR$ ERROR. This
symbol is defined in SYS$SHARE:DTRSHR.EXE, the DATATRIEVE shared
image, as a global constant. The value of this global constant can be brought
into an APL workspace using the /VALUE switch to JMAP:
A«

'"Z/TYPE:L<« DTRA

B«

'"DITRSHR/VALUE:DTR$_ERROR'

ERROR'

A [MAP B
DTRA_ERROR

OMAP 'DTRA_ERROR!
Z/TYPE:L/MECHANISM: IMMEDIATE+«
DTRAN _ERROR/IMAGE:DITRSHR/VALUE:DTR$
FRROR

DTRA_ERROR
9273530

You can use the APL identifier DTRV _ERROR to check the status returned by
various DATATRIEVE functions to see if "statement abandoned due to error"
has occurred.

6—32

VAX APL Users Guide

Calling External Routines
6.5 Examples of Calls to External Routines

Example 9: Calling a VMS System Service
OMAP cannot be used to call VMS system services directly because the VMS
system services do not reside in a shared image. To call a system service, write
a routine in a compiled VMS programming language that calls the system
service, link that routine into a shared image, and invoke that routine from

inside APL.
The following BLISS program in the file TERMINAL.BLI contains the routine

TOGGLE_ECHO, which toggles the NOECHO flag on the terminal assigned to

SYS$INPUT:..
Stype terminal.bli
MODULE

TERMINAL =

BEGIN

LIBRARY ’SYSSLIBRARY:STARLET’;
!+
!

The following

.BXMAP expression is

TOGGLE ECHO as

an external

required to define

function:

"STATUS/TYP:L _ T.USECHO'

.BXMAP ’TERMSHR/ENTRY:TOGGLE.USECHO’

|
!

GLOBAL ROUTINE

TOGGLE ECHO =

!
!

This routine toggles the NOECHO bit in the terminal

assigned to SYSSINPUT:.

not echoed to the terminal but output

When NOECHO is set,

input is

is displayed.

| —

BEGIN

LOCAL
STATUS,
TERMINAL CHAN,

TERMINAL
DSC
DEVICE BLOCK

: VECTOR [2],
: BLOCK
[12, BYTE]

;

BIND

TT1

DEVICE BLOCK

[4,0,0,0]

TERMINAL
DSC

[0]

SCHARCOUNT

TERMINAL
DSC

[1]

UPLIT

SASSIGN

6.5.9

BLOCK

[,BYTE];

(' SYSSINPUT:’);

(’SYSSINPUT:');

(DEVNAM=TERMINAL
DSC,

CHAN=TERMINAL CHAN);

VAX APL Users Guide

6-33

Calling External Routines

6.5 Examples of Calls to External Routines

= DEVICE BLOCK,

= 12;)

[TT$V NOECHO]

STATUS = $QIOW

= NOT .TT1

(CHAN = .TERMINAL CHAN,)
FUNC = (I0$ SETMODE),
P1

P2
RETURN

[TTSV_NOECHO];

TT1

(CHAN = .TERMINAL CHAN,)
FUNC = (IOS SENSEMODE),

STATUS = SQIOW

DEVICE BLOCK,

12;)

.STATUS;

! End of TOGGLE ECHO routine

END;
'

END

End of TERMINAL module

ELUDOM

Compile the BLISS program called TERMINAL.BLI to create
TERMINAL.OBJ:
$ bliss terminal.bli

Create a shared image called TERMINAL.EXE from TERMINAL.BLI:
$ link/shareable=terminal terminal,sysS$input:/options
echo
universal=toggle

Define the logical name TERMSHR to point to the shared image on the
device and directory where TERMINAL.EXE resides:
$ define termshr device: [directory]terminal.exe

Invoke APL and use TOGGLE_ECHO:
$ apl/terminal=key/silent
'"STATUS/TYPE:L « T_ECHO'
B« '"TERMSHR/ENTRY:TOGGLE_ECHO'

A«

A [JMAP B

TOGGLE_ECHO

eNOECHO IS CURRENTLY OFF SINCE INPUT IS BEING ECHOED
TOGGLE _ECHO

6-34

(1 1 is the input but only the answer is displayed)

(TOGGLE ECHO is the input; only its result is displayed)

VAX APL Users Guide

Calling External Routines
6.5 Examples of Calls to External Routines

6.5.10

Example 10: Calling SMG$ Routines
The following example invokes four external SMG$ routines. The example
creates a pasteboard and a virtual display, and writes some text on the board.

SMG$CREATE_PASTEBOARD
R "STATUS/TYP:L CREATEPB

RR,'PBID/TYP:L/ACCESS:OUT/MECH:
REFERENCE '

R R, "OUTPUT/TYP:T/ACCESS:IN/MECH:DESC '

RR,’ROWS/TYP:L/ACCESS:0OUT/MECH:REFERENCE '
RR,’COLS/TYP:L/ACCESS:0UT/MECH:REFERENCE '
RR,’FLAG/TYP:L/ACCESS:
IN/MECH: REFERENCE’
R.BXMAP ’SMGSHR/ENTRY
: SMGSCREATE .PASTEBOARD’

SMG$CREATE_VIRTUAL_DISPLAY
R "STATUS/TYP:L CREATEVD

RR,’ROWS/TYP:L/ACCESS:IN/MECH:REFERENCE '
RR,’COLS/TYP:L/ACCESS:IN/MECH:REFERENCE '
RR,’DISPID/TYP:L/ACCESS:0UT/MECH:
REFERENCE '
R R,’'DISATT/TYP:L/ACCESS:IN/MECH:REFERENCE '

R R,’VIDATT/TYP:L/ACCESS: IN/MECH:REFERENCE’
R.BXMAP ’SMGSHR/ENTRY:SMGSCREATE .USVIRTUAL.USDISPLAY’

SMG$PASTE_VIRTUAL_DISPLAY
R ’STATUS/TYP:L PASTEVD '

RR,’DISPID/TYP:L/ACCESS:IN/MECH:
REFERENCE '
RR,'PBID/TYP:L/ACCESS:IN/MECH:REFERENCE '
R:R,’PBROW/TYP:L/ACCESS:IN/MECH:REFERENCE ’
R R,’PBCOL/TYP:L/ACCESS:IN/MECH:REFERENCE '

R.BXMAP ’SMGSHR/ENTRY:SMGSPASTE.USVIRTUAL.USDISPLAY’

SMG$PUT_CHARS
R "STATUS/TYP:L PUTCH '

R R,’DISPID/TYP:L/ACCESS:IN/MECH:REFERENCE ’
RR,’TEXT/TYP:T/ACCESS:IN/MECH:DESC ’
RR,’STARTROW/TYP:L/ACCESS:IN/MECH:REFERENCE ’
R R,’STARTCOL/TYP:L/ACCESS:IN/MECH:REFERENCE ’

RR,’ERASEFG/TYP:L/ACCESS:IN/MECH:REFERENCE '
RR,’RENDSET/TYP:L/ACCESS:IN/MECH:
REFERENCE ’
R R,’RENDCMP/TYP:L/ACCESS:IN/MECH:REFERENCE’

R.BXMAP ’SMGSHR/ENTRY:SMGSPUT
CHARS’

The four SMG$ routines are now defined in the APL workspace. The example
continues by defining the text that will be written to the pasteboard, setting
the attributes for the virtual display, and calling the external routines.

VAX APL Users Guide

6-35

Calling External Routines

6.5 Examples of Calls to External Routines
TEXT<'THIS IS THE DEMO FOR USING SM$ ROUTINES'
TEXT1«<'TO SHOW HOW TO CREATE A WINDOW ON THE'
TEXT2<'TERMINAL SCREEN, SMG$PUTCHAR PUT DATA HERE.'
ONSINK<«CREATEPB('PBID';;:33)

ROWS<7 ¢ COLUMNS<«50
BORDER<«1 ¢ BOLD+1
o DISPLAY AND

nSIZE OF VIRTUAL DISPLAY
aSPECIFY THE DEFAULT RENDITION FOR

VIDEO ATTRIBUTES

OSINK<CREATEVD(ROWS:COLUMNS;
'DISPID1' ;BORDER;BOLD)
OSINK«PUTCH(DISPID1;TEXT;231;::;)
NSINK<PUTCH(DISPID1sTEXT1451:;;)
OSINK«PUTCH(DISPID1:;TEXT2:651;;)

OSINK«PASTEVD(DISPID1;PDID;u4;15)

| THIS IS THE DEMO FOR USING SMG$ ROUTINES
| TO SHOW HOW TO CREATE A WINDOW ON THE
| TERMINAL SCREEN, SMG$PUTCHAR PUT DATA HERE.

6-36

VAX APL Users Guide

|
|
|

A
VAX APL Workspace Interchange Standard
The VAX APL Workspace Interchange Standard (WSIS) describes a method for
transferring workspaces from one APL implementation to another. The WSIS
allows a workspace to be transferred regardless of its internal APL format

or the size and content of the particular implementation. (Note that you
cannot transfer nested arrays.)
The WSIS has been agreed to by implementors of APL and documented in the
article “Workspace Interchange Convention,” APL Quote-Quad, Vol. 9, No. 3,
March 1979.

A workspace to be transferred is converted into a standard format and written
to a magnetic tape (or, optionally, to a disk file). Then, the workspace can be
read from the tape and converted from the standard format to a particular

implementation’s format.
If you want to use the WSIS, you must install the optional WSIS software
when you install VAX APL (for details, see the VAX APL Installation Guide.)

The optional WSIS software consists of the following:
APLTAP.EXE

A VMS program that copies WSIS-formatted files from disk to tape and

WSOUT.APL

A VAX APL workspace that contains the function QQwsouT, which
converts VAX APL workspaces to WSIS-formatted workspaces.

WSIN.APL

A VAX APL workspace that contains the function QQw¥SIN, which

from tape to disk.

converts WSIS-formatted workspaces to VAX APL workspaces.

A.1

Converting VAX APL Workspaces to WSIS-Formatted
Workspaces
To create a tape file containing VAX APL workspaces that are to be transferred
to a different APL implementation, follow these steps:

VAX APL Users Guide

A-1

VAX APL Workspace Interchange Standard
A.1 Converting VAX APL Workspaces to WSIS-Formatted Workspaces
1.

Invoke VAX APL, load the workspace that is to be transferred, copy the

VAX APL workspace WSOUT from SYS$LIBRARY, and execute the APL
function Q@WSOoUT. For example:
$ apl/term=dec/silent
YLOAD WSNAME

)COPY SYS$LIBRARY:WNSOUT
QOWSOUT

'FILENAME'

This writes the workspace identified by wsname as a disk file with the
name file-name. (The default file type of file-name is . AIS.) The disk file
includes the workspace’s functions, operators, and variables, except for
those whose names begin with @@ Certain VAX APL system variables are
also copied. The WSIS software does not provide a way to copy the state
indicator stack, groups, or channel assignments.

Repeat step 1 for each workspace to be transferred. Use a different file
name for each workspace written to disk.

Execute APLTAP.EXE (from SYS$LIBRARY) to write the disk files to a
tape (note that you can put multiple workspaces on a single tape). You will
need to use the following APLTAP commands:
INITIALIZE

Opens a tape file and writes initial interchange information, which
prepares the tape to receive the workspace named by the WRITE
command. You will be prompted for the name of the tape file. The
default file type of the tape file is .AXF.

WRITE

Copies a disk file to tape (the tape must have been initialized). You
will be prompted for the name of the disk file that contains the
WSIS-formatted workspace. Records in the disk file may contain a
maximum of 512 bytes. The default file type of the disk file is .AIS.

TERMINATE

Closes the tape file.

EXIT

Exits from the APLTAP program. Closes any tape files that were
initialized but not terminated.

Ctri/Z>

A-2

VAX APL Users Guide

Closes the tape file and exits from the APLTAP program (just as if
you had executed the TERMINATE and EXIT commands).

VAX APL Workspace Interchange Standard
A.1 Converting VAX APL Workspaces to WSIS-Formatted Workspaces
For example:
S run sysSlibrary:apltap
APLTAP!initialize

Enter tape file specification:tape
APLTAP!lwrite

Enter file name:file-name-1
APLTAP!write

Enter file name:file-name-2

APLTAP !'terminate
APLTAP'exit

Note that APLTAP prompts for commands with APLTAP!. You may enter

APLTAP commands in either uppercase or lowercase, and you may abbreviate
them to the shortest unique spelling.

APLTAP requires that the tape have a standard ANSI label. APLTAP writes
fixed-length 1892-byte (8-bit bytes) records (it pads the last record with spaces).

Other characteristics of the tape, such as density and parity, are not specified

by the WSIS; APLTAP will execute successfully only if the sender and receiver
have agreed on these characteristics.

You can use APLTAP to copy a WSIS-formatted file to a device other than tape
(such as a disk file). If you respond to the tape file specification prompt with
a disk file specification, APLTAP prints a warning but continues processing.
Thus, although APLTAP will not write to an unlabeled tape, you could copy
the WSIS-formatted files to an unlabeled tape by first using APLTAP to create

a disk file, and then using some other mechanism to write the disk file to an
unlabeled tape.

A.2 Converting WSIS-Formatted Workspaces to VAX APL
Workspaces
To convert workspaces from WSIS format to VAX APL format, follow these

steps:

Execute APLTAPEXE (from SYS$LIBRARY) to copy the WSIS-formatted
tape files to disk and to create a command file that will be used to convert
the disk files to workspaces.

VAX APL Users Guide

A-3

VAX APL Workspace Interchange Standard
A.2 Converting WSIS-Formatted Workspaces to VAX APL Workspaces
You will need to use the following APLTAP commands:
READ

Reads one or more tape files and creates disk files for input to
the APL function Q@wSIN. The default file type for these tape
files is .AXF. Also creates a command file that contains the APL

statements needed to execute QQWSIN. The default file type for
the command file is .AAS. If you choose a different file type, then
you will have to specify it when you use the ) INPUT command
(see step 2).

EXIT or Ctrl/Z

Exits from the APLTAP program.

For example:
$ run sysSlibrary:apltap
APLTAP!read

Enter name of command file:

Enter next tape file name

command-file
(DONE to exit):

tape-file-1

(DONE to exit):

tape-file-2

(DONE to exit):

done

Total number of errors =

Enter next tape file name
Total number of errors =

Enter next tape file name
APLTAP!exit

APLTAP first prompts for the name of the command file to be created, and

then it successively prompts for tape files to process until you enter DONE.
Note that APLTAP prompts for commands with APLTAP!. You may
enter APLTAP commands in either uppercase or lowercase, and you may
abbreviate them to the shortest unique spelling.
APLTAP creates a disk file named WSINnnnn.AIS for each tape file

entered (nnnn is a 4-digit decimal number; the first file is assigned 0000).
The names will be used by the command file created for step 2.
A tape record may not exceed 4096 8-bit bytes in length. If the specification

you supply as the tape file is not actually a tape device, APLTAP prints a
warning but continues processing. Thus, although APLTAP will read only
labeled tapes, you can copy a WSIS-formatted workspace from an unlabeled
tape by first using some other mechanism to create a disk file from the
unlabeled tape, and by then using APLTAP to process the disk file.
2.

Invoke VAX APL and use the ) INPUT command to execute the command
file created in step 1. For example:
$ apl/term=dec/silent
JINPUT command-file/TTY

Note that the command file is created in TTY character set.

A-4

VAX APL Users Guide

VAX APL Workspace Interchange Standard
A.2 Converting WSIS-Formatted Workspaces to VAX APL Workspaces
This procedure creates workspaces with file names taken from the WSIS

tape; each workspace has a file type of .APL. If the name of any of the
new workspaces is already in use in your default directory, WSIN changes

the file type of the new workspace to .Wnn, where nn is a 2-digit decimal
number.

WSIN lists the function, operator, and variable names on the terminal as it
copies them to the new workspace. When WSIN has processed the entire

file, it deletes the WSINnnnn.AIS file produced by APLTAP, but does not
delete the command file.

A.3 Sample WSIS Session
In the following sample session, a VAX APL workspace (TEST.APL) is written
to tape in WSIS format. The file is read and the WSIS-formatted workspaces

are recreated as VAX APL workspaces.
$ apl/term=dec/silent
YLOAD

TEST

SAVED WEDNESDAY

17-APR-1991

09:40:01.77

BLKS

yCOPY SYS$LIBRARY:WSOUT
SAVED WEDNESDAY
QQWSOUT

13-MAR-1991

13:19:08.56

27 BLKS

' TEST!

CREATING QUTPUT FILE:

TEST/IS

OPERATIONS:

FN
FN1
VARIABLES:

B
A

OQvVPC
arr

OTLE
OTIMEOUT
OTIMELIMIT
(OTERSE
OSINK
OSF
ORL
OR
OPW

ONG
OLX

0I0
0GAG
OERROR
O0DML

VAX APL Users Guide

A-5

VAX APL Workspace Interchange Standard
A.3 Sample WSIS Session
VARIABLE'S VALUE IS NESTED OR HETEROGENEOUS:
ODC

[(DC

OcT
OAUS

[TRAP
OpP
QQWSOUT IS DONE
)OFF

Run APLTAP.EXE to copy the WSIS-formatted file (TEST.AIS) to tape.
$ run sysSlibrary:apltap

APLTAP!initialize
Enter tape file specification:
APLTAPlwrite
enter file name:

mkad00:tranx

test

APLTAP!terminate
APLTAPlexit

The WSIS-formatted file has been copied to the tape. Now APLTAP.EXE is
used to read the file and restore the workspace.
S run sysSlibrary:apltap
APLTAP !'read

conv
Enter name of command file:
Enter next tape file name (DONE to exit):

mkab00:tranx

Total number of errors =

Enter next tape file name

(DONE to exit):

done

APLTAP'ex1t

APLTAPEXE copied the file to the default disk area and named the file
WSINO0000.AIS. APLTAP.EXE also created a command file, CONV.AAS, to
be executed inside of APL using the ) INPUT command. The contents of that
command file are as follows:
S type conv.aas
) CLEAR

) COPY SYSSLIBRARY:WSIN
.2Q.ZQWSIN ’SUSERS: [APLUSER]WSINOOOOQ'

Invoke APL and use )

A-6

VAX APL Users Guide

INPUT to execute the command file, CONV.AAS.

VAX APL Workspace Interchange Standard
A.3 Sample WSIS Session
yINPUT CONV/TTY

)CLEAR

CLEAR WS
)COPY SYS$LIBRARY:WSIN
SAVED WEDNESDAY

13-MAR-1991

QQWSIN

13:19:07.48

41 BLKS

' $USERS : LAPLUSERINSINOOOO!

READING FROM $USERS:[APLUSERIWSIN0000
OLD WSID WAS TEST
SUPERSEDING

TEST.WO00

SUPERSEDING

TEST.WO1

NEW WSID IS

TEST.WO01

NOTE:

CREATED ON WEDNESDAY

LUSERS,APLUSER]
CREATED OPERATION:

CREATED OPERATION:

FN1

17-APR-1991

AT TWA4:

CREATED NUMERIC VARIABLE:

09:40:01.77 BY

WITH T4.0-875

gvec
OrT
CREATED NUMERIC VARIABLE: OTLE
CREATED NUMERIC VARIABLE:

CREATED NUMERIC VARIABLE:

CREATED NUMERIC VARIABLE:
CREATED NUMERIC VARIABLE:

CREATED NUMERIC VARIABLE:

UTIMEOUT
OTIMELIMIT
OTERSE
USINK

CREATED CHARACTER VARIABLE:

[SF

CREATED NUMERIC VARIABLE:

[RL

CREATED NUMERIC

VARIABLE:

CREATED NUMERIC VARIABLE:

[PW

CREATED NUMERIC

[NG

VARIABLE:

CREATED CHARACTER

VARIABLE:

[OLX

CREATED NUMERIC VARIABLE:

CREATED NUMERIC

QIO

VARIABLE:

CREATED NUMERIC VARIABLE:
CREATED

[GAG

CHARACTER VARIABLE:

[ERROR

CREATED NUMERIC VARIABLE:

[DML

CREATED NUMERIC VARIABLE:

[CT

CREATED NUMERIC VARIABLE:

[AUS

CREATED CHARACTER

VARIABLE:

CREATED NUMERIC VARIABLE:

[JTRAP

[IPP

DONE WITH INPUT FILE $USERS:[APLUSERIWSINO0O0O
+DELETE-I-FILDEL,

)LOAD

$USERS:[APLUSER]JWSIN0000.4IS;1

deleted

blocks)

TEST.HO1

)ERASE QQWSIN
)SAVE
WEDNESDAY

17-APR-1991

10:01:31.38

22 BLKS TEST.WO01

JDROP $USERS:[APLUSERIWSIN0000.,AAS;0
+DELETE-I-FILDEL,

$USERS:[APLUSERJWSIN0000.AAS;1

deleted

VAX APL Users Guide

A-7

VAX APL Workspace Interchange Standard
A.3 Sample WSIS Session
The @@wsoUT and QQIN functions can also be used to transfer files. To convert

a file to WSIS output form, load the WSOUT workspace from SYS$LIBRARY:
and execute the QQWsSOUT function with a left argument which is the file

specification of the file to be converted. (The default file type is .AIX; for other
file types include the appropiate switch; For instance, /AS for ASCII sequential,

AAS types.) The right argument is the output tape specification, the same as
when transferring workspaces. The following example illustrates transferring

an ASCII file called FOO.AAS. Because the file is transferred to a disk instead
of tape, APLTAP outputs a warning message.
$ apl/term=dec/silent
JLOAD SYS$LIBRARY :WSOUT

SAVED WEDNESDAY 13-MAR-1991
"FOQO/AS'

QQWSOUT

CREATING OUTPUT FILE:

13:19:08.56

25 BLKS

'"OUTFILE!

QUTFILE/IS

REC0000
REC0000
QAWSOUT IS DONE
)OFF

$ run sysS$Slibrary:apltap
APLTAP'initialize

Enter tape file specification: Susers:[apluser]tranx
Target device 1s not tape.

WARNING:

APLTAP!'WRITE
Enter file name:

outfile

APLTAP!terminate
APLTAP!exit

Now input the transferred file.
$ run sysSlibrary:apltap
APLTAP!'read

Enter name of command file:

doit
Enter next tape file name (DONE to exit):
WARNING:
Target device is not Tape.
Total number of errors

Susers:[apluser]tranx

Enter next tape file name

(DONE to exit):

done

APLTAP'exit

$ apl/term=dec/silent
YINPUT DOIT/TTY
)CLEAR
CLEAR WS
)COPY SYS$LIBRARY:WSIN
SAVED WEDNESDAY

13-MAR-1991

QQWSIN

13:19:07.48

u1 BLKS

"$USERS
: [APLUSERIWSINOO0O2'!

READING FROM $USERS:[APLUSERIWSIN0002
OLD FILEID WAS F00/AS
NEW FILEID IS F00.X00

DONE WITH INPUT FILE $USERS:[APLUSER]WSIN0O0O2
+DELETE-I-FILDEL,

A-8

VAX APL Users Guide

$USERS:[APLUSERIJNSIN0002.AIS;1

deleted

Dlocks)

VAX APL Workspace Interchange Standard
A_.3 Sample WSIS Session
JDROP $USERS:[APLUSERJNSIN0O002.4AS;0
*DELETE-I-FILDEL,

$USERS:[APLUSERIJWSIN0002.AAS;1

deleted

blocks)

JOFF

A.4 Error Messages and Warnings Generated by WSIS

Software
When you use the WSIS software, some error and warning messages may be
displayed. This section identifies those messages and explains (if necessary)
what they mean. In the messages, xx is a hexadecimal number, typically the
error code from VMS Record Management Services.

A.4.1

WSOUT Messages
QAWSOUT IS5 DONE

Explanation: OOWSOUT has completed processing.
UNABLE TO ASSIGN THE OUTPUT FILE

Explanation: QQQQWSOUT was unable to assign the output file to channel
1.
CREATING OUTPUT FILE:filespec

Explanation: Informational.
OPERATION LOCKED:

name

Explanation: wSOUT cannot transfer locked function or operator.
UNABLFE TO ASSIGN INPUT FILFE

Explanation: It is not possible to open the file to be transferred.
INVALID WORKSPACE IDENTIFIFER

Explanation: The workspace to be transferred has an invalid identifier.

A.4.2

WSIN Messages
INPUT FILE file NOT FOUND
Explanation: QQWSIN was unable to find the specified input file.
FILE IN INCORRECT FORMAT

Explanation: The specified input file is not in the expected format.
UNKNOWN PSEUDOVARIABLE name IGNORED

RANK:

r SHAPE:

Explanation: The named pseudovariable is unknown.

VAX APL Users Guide

A-9

VAX APL Workspace Interchange Standard
A.4 Error Messages and Warnings Generated by WSIS Software
UNEXPECTED END OF FILE
WS FULL. YOU MUST START OVER.
UNEXPECTED ERROR NUMBER

WARNING, IDENTIFIER:

xxxx BEING TRUNCATED TO: xxx

Explanation: If an incoming identifier has more than 31 characters, it is
truncated to the first 31 characters.
WARNING, IDENTIFIER SAME AS PREVIOUS ONE

Explanation: A truncated identifier matches some previously converted
identifier.
FIX OF OPERATION name FAILED AT LINE

Explanation: The function or operator could not be created for some
reason. The operation is left as an operation with all its lines turned into
comments.

UNABLE TO FIX OPERATION name AT LINE

Explanation: A function or operator with all its lines commented out
cannot be fixed. The operation is left as a character array.
UNABLE TO ASSIGN THE OUTPUT FILE

Explanation: A file that is being transferred cannot be created.
EXECUTABLE EXPRESSION: expression
SIGNALED THE FOLLOWING ERROR.

Explanation: An executable expression received an error.
SCALARS OF TYPE type ARE NOT ALLOWED. IGNORED.

Explanation: An invalid pseudovariable was found.
TOO MANY VERSIONS OF THE SAME NAME-~-RAN OUT OF SUFFIXES

Explanation: There are more than 99 files with the same name.
x*x*x*xKRROR, BAD RANK IN name

Explanation: The rank information for a transferred object is invalid.
***x*xx*ERROR, BAD SHAPFE IN name

Explanation: The shape information for a transferred object is invalid or
inconsistent with the rank information.

A-10

VAX APL Users Guide

VAX APL Workspace Interchange Standard
A.4 Error Messages and Warnings Generated by WSIS Software
x**x%x** FRROR CREATING NUMERIC VARIABLE name

Explanation: An attempt was made to create an invalid numeric array.
The variable is left in character form for possible repair. Too large an
exponent is a possible cause of this message.
**xxx* FRROR CREATING NUMERIC COMPONENT:

name

Explanation: An invalid numeric array was found when transferring a
file.
CREATED CHARACTER VARIABLE: name

Explanation: Successful transfer of a variable.
CREATED NUMERIC VARIABLE: name

Explanation: Successful transfer of a variable.
CREATED OPERATION: name

Explanation: Successful transfer of a function or operator.
EXECUTED EXECUTABLE EXPRESSION: expression

Explanation: Performed the execution of the expression passed in the
executable expression pseudovariable.
DONE WITH INPUT FILE filespec

Explanation: A file has been successfully transferred and created.

A.4.3 APLTAP Messages
Command Syntax Errors
Illegal command: Not one of READ, WRITE, INIT, TERM, or EXIT.

Tape has already been initialized.

Explanation: An INITIALIZE command was entered for a tape that was
initialized for writing.
Tape initialized for writing.

Explanation: A READ command was entered for a tape that was

initialized for writing.

VAX APL Users Guide

A-11

VAX APL Workspace Interchange Standard

A.4 Error Messages and Warnings Generated by WSIS Software
Tape not initialized.

Explanation:

A WRITE or TERMINATE command was entered for a tape

that has not been initialized.
I/0 Errors

Unable to open <SYS$INPUT | tape-file | source-file> (xx).

Explanation: An error occurred when APLTAP tried to open the indicated
file.

Unable to create <tape-file | wsin-file | log-file> (xx).

Explanation: An error occurred when APLTAP tried to create the
indicated file (log-file refers to the command file).

Unable to connect to <SYS$INPUT | log-file | tape-file | wsin-file | sourcefile> (xx).

Explanation: An error occurred when APLTAP tried to connect to the
indicated file (log-file refers to the command file).
Error closing <input-file | tape-file>.

Explanation: An error occurred when APLTAP tried to close the indicated
file.

Unable to write out prologue (xx).

Explanation: An error occurred when APLTAP tried to write the WSIS
prologue to the tape. The initialization is aborted.
Unable to write END pseudovariable (xx).

Explanation: An error occurred when APLTAP tried to write the END
pseudovariable to the tape. The tape file is closed.
Unable to write to log file (xx).

Explanation: An error occurred while APLTAP was writing to the
command file. READ processing is terminated.
Error writing to tape file (xx).

Explanation: An error occurred while APLTAP was writing a data block
to the tape. Writing of this file is terminated.

A-12

VAX APL Users Guide

VAX APL Workspace Interchange Standard
A .4 Error Messages and Warnings Generated by WSIS Software
Cannot write to WSIN file (xx).
Explanation: An error occurred while APLTAP was writing to the

WSINnnnn file. READING of that tape file is stopped, but READ
processing continues.

Error reading from <input-file

SYS$INPUT

| tape-file> (xx).

Explanation: An error occurred while APLTAP was reading from the
specified file. Processing of that file is stopped.
Unexpected end of file reading from tape.

Explanation: End of file occurred while APLTAP was reading the WSIS
or TRANSLATE pseudovariables.
Unexpected error reading from tape (xx).
Explanation: An error occurred while APLTAP was reading from the tape
file. READING of that file is stopped, but READ processing continues.
Tape Format Errors

Number in tape input too large.
Explanation: The WSIS or TRANSLATE pseudovariable contained a
numeric string that was too long to translate to a 32-bit integer.
No WSINnnnn name available for use (nnnn is a 4-digit decimal number).

Explanation: All names of the form WSINnnnn are in use.
Second vector is not TRANSLATE pseudovariable.

Explanation: TRANSLATE pseudovariable is not a matrix.
TRANSLATE contains too many rows.
TRANSLATE contains too few columns.
First vector is not WSIS pseudovariable.
Format on tape is not convention 0.

Explanation: The WSIS software supports version 0 of the workspace
convention.

Warnings from APLTAP

VAX APL Users Guide

A-13

VAX APL Workspace Interchange Standard
A.4 Error Messages and Warnings Generated by WSIS Software
Target device is not tape.

Explanation: The file specification given for the tape file does not
correspond to a magnetic tape device.

Incorrect length for WSIS pseudovariable.
Nonblank padding at end of WSIS.
Nonblank padding at end of TRANSLATE.

TRANSLATE contains a character with more than two overstrikes at entry
(xx).

TRANSLATE contains character not found in AV at entry (xx).
Illegal reference to undefined character (xxx).
Total number of errors = (nn).

Explanation: Note that if no errors occur, nn in this message is blank.

A-14

VAX APL Users Guide

Index
Arguments (cont’d)

shape of function,

Abort input signal,

definition of,

3-24, 3-36

axes of,

1-33

Absolute tab format phrase,

4-15

Access methods

file,

empty,

1-30
3-2
5-23

Ambivalent derived functions,

3-3

Ambivalent functions,

3-2, 3—-39e

APL character set,

1-2 to 1-5, 5-23

APL command line,

1-11

shareable,

1-1

APL interpreter output,

APL keyboards,
APL names,

1-27

1-27, 3—1

APL session
interrupting,

1-33

starting,

dummy,

output precision of,

2—2

2-3, 2-7

2-6

shape of,

2-4

spaces in,

2-3

2-2
2-13

2-1

ASCII
character set,
graphics,

1-2, 1-45t
1-5, 1-28

1-5, 1-8t

keyword mnemonics,

1-2, 1-37

Arguments

actual,

3-1

2-3

2-2

control characters,

1-11

APL terminals,

numeric,

types of,

5-6

2-25

2-34, 2-35

maximum axes,

type if empty,

APL operations and programs,
1-35

indexing,

structure of,

1-5t

APL operating modes,

formation rules,

reshaping,

1-2

exiting from,

2-12

rank of,

APL interpreter
1-1

2-3

2-8

format for displaying,

Alternate character set, TTY,

reentrant,

2-8

displaying,

Active workspace

Actual arguments,

2-3

2-1

dimensions of,

5-15

definition of,

2-2

coordinates of,
depth of,

5-16, 5-26

sequential,

2-3

character,

definition of,

5-15

random,

2-9

Arrays

Attention signal,

1-4, 1-5

1-28, 1-29t, 1-33

Axis argument in functions,

3-39e

3-2
3-2

extending singletons,

2-10

Index—1

Character set,
alternate,

Background format phrase decorator,
Backspace,

1-29t

Banner line,

1-20

4-25

APL,

1-36
5-23

1-2 to 1-5, 5-23

ASCII,

1-2, 1-45t

atomic vector,

Bare branch,

344

Bare output,

5-10

resetting buffer,

5-11

1-2, 1-24t, 1-37, 5-23

composite,

1-2, 1-42t, 5-23

key-paired,

1-2, 1-24t, 1-37, 5-23

multinational,

Bit-paired character set,

1-2, 1-24t, 1-37,

5-23

Blank when zero format phrase qualifier,
4-21

TTY,

1-44t, 567t

1-7t

overstruck,

1-4, 1-38, 1-39t, 5-23

typewriter-paired,

1-2

Character-Cell interface

Boolean number,

2-2

Branch function,

3-10, 3—13e

Break system function,

1-46t

bit-paired,

buffer
editing operations,

Buffer

resetting bare output,

5-11

Byte data format phrase,

4-13

1-17

definition of,

3-49

3—-20

initialization stream,
starting,

1-17

windows,

1-18

1-17

Characters

allowable, in names,

C
Calls to external routines,

arrays of,

6-1

fill,

Carriage return

as quote quad input,

Channels
assigning files to,
listing active,

5-33

status of,

5-33

definition of,

5-22

2-—2

errors,

1-39

5-45

1-30

5-31

Command level, returning to,

1-29t

Comments,

2-19

1-5, 1-36

2-32

Closing files system function,
Command line, APL,

editing,

1-11

2-25, 3-14

Composite character set,

Conditional branching,

1-2, 1-42t, 5-23

3-11

Constants

Character data
4-28

mixing with numeric,

Character editing,

3-32

escaping from,

3-36

Character format phrase,

Index-2

1-5

Clear event flag system function,

Character

formatting,

single-strike,

Character_Cell Interface

Clear workspace

Channels system function,
arrays,

2-42

1-28

1-4, 1-24t, 1-25t

editing variables,

5-17

5-22

numbers,

constants,

overstruck,

5—10

suppressing,

Changing selected items in arrays,

2-13

keyboard editing,

2-17

2-2

4-10

character,

2-19

indexing,

2-39

numeric,

2-18

CONTINUE workspace,

4-5

Control characters,

1-30, 1-32

1-9t

ASCII,

1-5, 1-28

Ctrl/C,

1-22, 1-29t, 1-33

Control characters (cont’d)

DECwindows Interface (cont’d)

Ctrl/D,

1-4, 1-33, 1-35

Ctrl/O,

1-29t

editing variables,

CtrI/R,

1-29t

of index origin,

Ctrl/'T,

129t

workspace name,

Ctrl/U,

1-29t

2-35
1-31t

Del Quad input

CtrI/X,

1-29t

Ctrl/Y,

1-29t, 1-33

Ctrl/Z,

1-22, 1-36

See Quad Del input

Del, protected,

editing lines containing,
CtrVZ,

2-30

Defaults

3-14

Deleting input character,

3-36

1-29t

Delimiters in operation header,

1-22

Depth of arrays,

3—4

2-8

Derived functions

types of
amibivalent,

Data

converting,

5-56, 5-61

external types of,

terminal,

5-64

internal representation, outputting,

internal types of,

5-61

outputting literal,

4-18

reformatting,

4-13

changing for input,
mailbox number of,

4-1, 5-56

Diamond character,

6-25e

state indicator,
stop vector,

trace vector,

3—44

output,

3-48

3-42

3—46

in pattern data with TTY,

4-11

4-24

zero,

Decorators, format phrase,

4-19

DECwindows interface

window,

1-16

transcript area,

Dyadic functions,
definition of,

1-4

2-9

3-2

3-2, 3—-38e

2-10
3-3, 3—41e

1-16

DECwindows Interface

editing operations,

Echoing input lines,

/EDIT Qualifier,

5-2

1-15

YEDIT system command,

1-16

initialization stream,
starting,

Domains of arguments,

4-24

command line,

5-6

Dyadic operators,

4-25

positive,

5-26

Dollar sign representation,
Dummy arguments,

Decorators
negative,

5-26

Display format

Decimal point

background,

2-24

reading and writing,

6-18

suspended operations,

5-35

548

deleting records from,
end-of-file,

3—49

external routines,

5-11

Direct-access files

Debugging

error trapping,

1-21

Device

displaying characteristics of,

DATATRIEVE

calling from APL,

3-3

Designators

3-18

3—22

Editing
See DECwindows interface
character,

1-5, 1-36, 3-32

commands for,

3-24t

deleting lines,

3-27

displaying lines,

3-28

Index—-3

Editing (cont’d)
immediate mode,
inserting lines,

Execution functions

1-28, 3-36

pending,

3-26

1-28

keyboard,

locking operations,

3-14

operation headers,

3-31

search and replace,

4-23

3-20

Expressions

definition of,

3-17

indexing,

2-34

order of evaluating,

4—4

to report formatter,

External data types,

Empty components

in direct-access files,

External routines,

5—26

calling,

5-26

Empty user-defined operation,
typing beyond,

invoking,

2-25

linking,

End-of-file
direct access,
relative,

5-26

methods for,

2-43

3-49

Errors
1-39

in user-defined operations,
order of checking,

2-43

2-44

5-23

File organization qualifiers,

5-18

File output system function,

5-23

File specification

VMS,

1-31

3-49

File status,

trapping,

3-49

Files

1-28

544, 5-49e

Execution

changing order of,

stopping,

index—4

3-11

5-32

1-15

3-10

initialization,

keyed,

5-15

2-24

locked,

5-40

1-28

order of statement,

5-23

deassigning,
HI,

5-17

5-31, 5-32

creating,

See Quad input

interrupting,

5-33

assigning to channels,
closing,

Evaluated input

Event flags,

5-44

File input system function,

signaling,
typing,

5-15

synchronizing,

Error system variable,
character,

6-5

6—2

File access

2-43

secondary,

6-2

2-42

Error messages

primary,

6-3

6-16

writing,

5-26

Error handling,

6-6t

querying APL definition,

5-26

internal sequential,

6-19e

defining to APL,

End of line

2-10

5-64

6-1

data types,

3-24

1-28

2-22

Extension of singletons,

2-12

in relative files,

2-16

2-39

interrupting evaluation of,

Empty arguments
Empty arrays,

1-29t, 1-33, 1-35

Exponent digits format phrase qualifier,

3-29

)EDITsystem command,

1-27

Exit from APL session,

See Character-Cell interface,
Editing Operations,

345

Execution mode,

3-23

operations,

3—-45

suspended,

opening,

1-12

5-23, 5-35, 548

organization of,

5-33

Files (cont’d)
reading,

Forming arrays,

5-23

direct-access,

5-26

internal sequential,
keyed,

calling from APL,

5-25

characteristics,

5-56, 5-58

relative,

kinds of,

5-26

returning to the beginning of,
sharing,

5-34, 5-38, 5-42

writing,

5-23

Fill character,

arguments, shape of,

localizing,

2-15

APL specification,

defining,

2-15

Floating-point numbers,

4-6

amibivalent,

dyadic,

5-7

niladic,

Format
5-60

of terminal output,

5-6

Global symbols,

decorators, See Decorators, format phrase
qualifiers, See Qualifiers, format phrase

character,

3-6

3—6

Graphics

1-5, 1-8t

4-13

Group logical name table,

4-5

Group names,

fixed-point,
integer,

4-12

literal,

4-18

4-6

Headers

of an operation,

matching with target columns,
parameters to,

pattern data,

4-18

4-3

4-16

repetition parameter,

4-2

syntax summary,

type parameter,

4-3

of functions,

of records,

3-2

3-1

5-56

Hexadecimal output

4-9

qualifiers parameter,
relative tab,

5-47

1-32, 2-16

4-3

4-8

floating-point,

types of,

naming,

ASCII,

4-15

digits parameter,

syntax,

3-2

4-2

absolute tab,

3-2

monadic,

1-26

byte data,

3-3

types of

2-2

of internal records,

2-42

3-1

results of,

4-8

Floating-point format phrase,

Format phrases,

1-27

Functions

Fixed-point format phrase,

display of,

3-6

Function-definition mode,

Fill item

Font files,

2-9

Function names

Fill element

definition of,

2-21

parts

5-31

2—13

definition of,

6-24e

Function

5-27

non-APL,

2-25

FORTRAN

4-3

of internal data representation,
HI file,

4-13

1-15

/HI Qualifier,

1-15

High minus sign,

2-18

4-5

4-3

4-5

width parameter,

4-3

Index-5

Input lines (cont’d)

I/0
file,

5-1

variables,

5-1

5-2

1-16

)INPUT system command,

Identifier

5-11

Insert commas format phrase qualifier,

definition of,

2-16

Illegal overstrike,

1-5, 2—19

in quote quad input,
in TTY mode,

1-39

1-27

editing in,
Index origin,

4-12

/INTERFACE qualifier,

1-16

5-61

Internal record format,

5-60

Internal sequential files

1-30

reading and writing,

2-35

5-25

Items

Indexed files

definition of,

See Keyed files
Indexing arrays

Key-paired character set,

1-11, 1-12

order of processing,
parameters,

1-20

Keyboard editing,

1-12

definition of,

Keyboards, APL,

1-11

Keyed files,

Input

abort input signal,

1-33

escaping from quad,

5-2

5-5

Input device
changing default,
Input lines
5-2

correcting,

writing,

5-27

names of,

requesting inside an operation,

canceling,

5-27

5-20

Labels

5-5

untranslated,

reading,

1-27

quote quad 1,

5-15

/KY file organization switch,

5-11

1-28t

1-2

assigning channels,

1-12

quad del,

1-28

Keyboard editing characters,

Initialization file

diverting,

1-2, 1-24t, 1-37,

5-23

streams

creation,

2-1

See Arrays
Initialization

prompt,

4-21

3-46

Internal data types,

1-28, 3-36

Inactive workspace,

Integer format phrase,

Intermediate results of operation execution,

Immediate mode,

1-29t

deleting,

1-29t

echoing,

5-2

Index—6

2-25

wrapping,

/INPUT qualifier,

terminal,

quad,

2-25

Input prompt system variable,

5-23

file,

entering,

length of,

5-11

5-3

2—-16

operation-line,

3-6

Lamp character,

3-14

Latent expression system variable,

1-21

Left-justify format phrase qualifier,

4-22

Length
of input lines,

of names,

2-25

2-17

of operations,

3-5

LIBSERASE_PAGE
calling from APL,

6-20e

Messages (cont’d)

LIB$GET_SCREEN
calling from APL,

secondary,

6-21e

calling from APL,

Minus sign,

6-20e

ASCII keyword,

2-3

superedit,

canceling input,

5-2

correcting input,

1-29t
1-29t

echoing input,

5-2

edit characteristics,

output,

2-25

length of input,

2-25

typing beyond end of,
wrapping input,

APL operating,

superedit,

3-44

6-2

4-18

3-6

Local operators,

3—6

Local symbols,

3-4, 3-6

Monadic functions,

3-2, 3—38e

Monadic operators,

3-3

MTH$DACOSD
calling from APL,
See Keyed files

3-8

error in,

2-24

3-14

5-42

Logical names

Names

5-47

APL,

1-5t

characters allowed in,

Mailbox system function,
Mailboxes,

5-48

5—46

Map system function,

6-3, 6-5

Matrix

1-32, 2-16

labels,

2-16

length of,

2-17

localizing,

3-6

domain definition,

symbolic,

2-9

MCS

translation,

5-73t
547

2-17

3-5
2-17

2-16

workspaces,
Near-integer,

length of mailbox,

2-17

user-defined operations,
variables,

Messages
primary,

groups,

rules for forming,

definition of,

1-44t, 5-67t

Multistatement line

5—40

table of group,

6-19e

Multinational Character Set,

Local variables, value of,

Locked records,

3-1

332

Multikey

3-6, 3—7

Locked operations,

1-27, 3—1

1-27, 3-1

operator-definition,

5-2

Local functions,

3-1

1-27

function-definition,

2-25

Linking external routines,

Locked files,

execution,

immediate,

Line counter system function,
Literal format phrase,

5-23

Modes

1-25

entering input,

1-36

Mode parameter

2-16, 2-25

deleting input,

naming,

5-5

Mode

1-20

definition of,

1-4, 1-5

in quote quad input,

Line

banner,

5-46, 5-48

2-18

Mnemonics

Limit
of axes in arrays,

2—42

to and from other users,

LIB$PUT_SCREEN

1-31
2-2

Negative format phrase decorators,

4-24

2-42

Index—7

Operations (cont’d)

Negative numbers
representing,

Negative sign,

replacing,

pendent,

2-18

5-12

Next-record pointer,
Niladic functions,

5-16, 5-26, 5-30

3-2, 3-37e

/NOEDIT Qualifier,
/NOHI Qualifier,

1-16

1-2, 1-38

1-19

errors in,

/NOTERMINAL qualifier,

/NOVECTOR qualifier,

1-19

1-20

channel,

5-33

2-18

4-10

header,

3-1, 3-2

result,

3-3

3—4

requesting input inside,

5-3

using system commands,

3-5

Operators,

2-21

defining,

3-1

adding lines,

1-27

suspended,

Operating system

returning to command level,

1-29t

dyadic,
local,

3-10

intermediate results of,

3-3

3-6

monadic,

3-46

3-11, 3—42
3-17

See Character-Cell interface

See DECwindows interface
See VAXTPU editor

3-3

Operators, types of
user-defined,

Operations

3-25

3-42

types of

Operation execution

Index—8

3-1

parts

Operating modes

editing,

2-17

delimiters for header,

Numeric data

changing order of,

3—2

body,

2-18

mixing with character,

3-6

3-5

parts

2-2

Numeric constants,

stopping,

3-6

3-28

naming rules,

representing negative,

APL,

3-26

naming,

output precision of,
Numeric arrays,

inserting lines,
labels for lines,

maximum lines,
2-2

3-31

2-44

localizing names,

Numbers

3-42

3-23

listing lines,

1-32

floating-point,

3-28

editing the header,

2-2

3-27

displaying operands,
editing,

/NOSILENT qualifier,

342

displaying lines,

5-56, 5-58

Boolean,

3-4, 3-5

3-24

deleting lines,

Non-APL files

Null password,

3-14

nested,

debugging,

1-16

/NOINTERFACE qualifier,

definition of,

3-24

user-defined

1-15

Non-APL terminals,

empty,

locked,
stub,

1-15

/NOINPUT qualifier,

reading,

1-32

types of

4-24

Nested input list,

1-32

suspended,

3-1

Optional character set with TTY,
Origin

default index,

2-35

5-23

Private mailbox,

Output
APL interpreter,

displaying,
file,

Process, suspended,

5-10

bare,

order of,

quotation marks,

input,

1-29t

Output mode parameter,

3-14

Prototype

5-23

definition of,

2-14

Public mailbox,

5-47

1-4, 1-7t, 1-24t,

1-25t

Pure data records,

1-5, 2—19

in quote quad input,
in TTY mode,

1-27

Protected del,

2-25, 5-3, 5-8

Overstruck characters,

1-39

1-5

Quad Del input,
Quad input,

5-5

5-2

escaping from,
pending,

1-29t, 1-33

1-11

initialization,

1-12

5-10

Qualifiers
APL,

Parameters, format phrases,

4-18

1-11

blank when zero,
definition of,

Parentheses
use in expressions,

5-2

3-45

Quad output,

Parameters

definition of,

5-55

with tab character,

Panic exit,

2—22

exponent digits,

4-23

file organization,

null,

insert commas,

1-32

1-31

left-justify,

Pattern data format phrase,
Pendent operations,

editing,

4-9

priority,

5-47

Pervasive functions

2-10
5—48

values,

1-14

zero fill,

4-23

/EDIT,
/HI,

Pointer

5-16, 5-26, 5-30

Positive format phrase decorators,

Precedence of local symbols,

1-15

3-54

1-16

/INTERFACE,
/NOEDIT,

/NOHI,

4-15, 4-16
3-16

1-16

1-15

/NOINPUT,

Print column pointer

Printing Operations,

4-22

1-15

/INPUT,

4-24

3-8

Primitive functions, optimized,
altering,

4-22

Qualifiers, APL

Physical device number mailbox,
next-record,

4-22

standard symbol substitution,

Permanent mailbox,

definition of,

5-18
4-21

1-13

scale factor,

1-32, 3-45

3-43

4-21

1-11

Password

workspace,

3-54

Prompts

2-19

suppressing terminal,

illegal,

1-20

Programming considerations,

5-10

Output catenator,

5-48

5—46

Processing

5-6

5-23

quad,

5-47

Process identification number,

1-27

1-16

/NOINTERFACE,

/NOSILENT,

1-16

1-19

/NOTERMINAL,

1-19

Index-9

Qualifiers, APL (cont’d)
/NOVECTOR,
/SILENT,

1-20

1-19

/TERMINAL,
/VECTOR,

1-19

Saved workspace,

1-20

1-30

Scalar

Qualifiers, format phrase,

4-19

definition of,

2-3

Question mark,

1-22

domain definition,

Quiet functions,

5-1

extension, definition of,

Quotation marks,
output,

2-2

2-9

product, definition of,

2-19

Scale factor format phrase qualifier,

Quote quad input,

Segmented records,

5-14

Selective assignment,
Semicolon,

R
Random access method,
Rank of arrays,

use of,

5-16, 5-26

Read event flag system function,

5-45

Records

index for,

segmented,

5-58

Shared images,

5-42

Signal system function,
1-1

abort input,

5-56

deleting records from,

attention,

Release system function,

Singleton,

4-16

2-42

2-10

2-5

4-1

calling from APL,

6-35e

SORT, calling from APL,

4-27

6-22

Spaces

Representation

as quote quad input,

1-4

Reset system function,

Results of functions,

3-46

3-3

Rewind system function,

Index-10

2-10

extension definition of,

SMG$ routines

see Format phrases

5-15

2-3

extending arguments,

shape,

Report formatter system function,

RMS,

1-5

2-9

definition of,

Report formatter

of dollar sign,

3-24, 3-36

1-19

Single-strike characters,

5-42

Replacing selected items in arrays,

1-33

/SILENT qualifier,

5-26

Relative tab format phrase,

3-49

1-28, 1-29t, 1-33

Signals, abort input,

5-26

526

reading and writing,

1-1

6—2

Signals

Relative files

result array,

2-9

2-40

Shareable APL interpreter,

Reentrant APL interpreter,

end-of-file for,

5-45

3-8

2-2,2-4

indexing result,

5-14

Reformatting data,

Shadowing symbols,

function argument,

5-55

releasing locked,

5-15

Set event flag system function,

array,

5-26

5-42

pure data,

5-8

Shape

5-56

internal format of,

locked,

2-42

2-25

Sequential access method,

2-3, 2-7

headers for,

2-10

5-30

in arrays,

2-3

use in APL,

2-22

whitespace,

2-22

Specification function,

2-42

4-22

Standard symbol substitution format phrase
qualifier,

State indicator,
clearing,

2—24
2-24

Status
channel,

5-33

Stop system function,
Stop vector,

348

3-48

STOPSET error,

3-48

Structure of arrays,

3—44

5-46

3-5

3-6

local,

34, 3-6

1n operations,

3-5

5-45

3-48

trace,

3—46

wait,

543

5-43
4-1

5-44

System services
calling from APL,

3—49
5-33

5-22

error message,

clear event flag,

5-10

3—49

5-2

quad del input

quad output #,

5-10

trap,

5-5

3-49

System variables, APL
latent expression,

OCHANS, 5-22
OCHS, 5-33
closing files,

6-33e

System variables in APL

mput prompt 0,

channel status,

gcrs,

5-30

bare output [1 or @,

5-11

System functions in APL

channels,

5-30

report formatter,

2-34, 3-22

break,

rewind,

System manager,

System commands in APL

5-23

542

3—46

OWAIT,

System commands

5-23

5-45

5-42

ORELEASE,
reset,

stop,

6-3, 6-5

5-48

System functions, APL

global,

6-3, 6-5

set event flag,

Symbols

3-44

5-48

OREWIND,

Suspended process,

yINPUT,

2-—42

1-32, 3—42, 3-45

343

Symbol table,

5-34

OrFLs, 5-34
line counter,

release,

1-36, 3-32

3-43

terminating,

5-23

file sharing,

read event flag,

2-2

3-24

Suspended operations,
restarting,

5-45

OMBX,

1-33

Substituting selected items in arrays,

editing,

OEFS,

OMAP,

Strong attention signal,

Superedit mode,

545

map external routine,

2--20

Stub operations,

545

OEFR,

mailbox,

Strand notation
definition of,

OEFC,

file /O,

5-33

5-35

Opve,

definition of,

5-32

device characteristics,

3-46

order of executing,

edit,

5-32

deassigning files,

1-32, 3—44

Statement

file,

System functions in APL (cont’d)

ODAS,

4-22

1-21

5-45

5-31

index-11

TPU editor,

2-34

Trace system function,

Trace vector,

Tab character,

1-29t

overstriking,

1-5

use in APL,

2-22

Trap system variable,

4-15

relative,

4-16

character set,

in quote quad input,
1-36

overstruck characters,

547

1-21

1-26

1-29t

overstruck characters,

Unconditional branching,
1-4, 1-25t

Untranslated input,

1-19

errors in,

APL,

1-2, 1-22t, 1-37

names,

BIT,

1-22t

2-44

2-17

User-defined operators,
1-23t

1-22t

HDS201,

1-22t

HDSAVT,

1-22t

Variables

HSD221,

1-22t

LA,

2—-32

editing with the DECwindows interface,

1-22t

2-30

1-2, 1-4, 1-23t, 1-38

5-1

Tektronix 4013,

1-22t

I/0,

Tektronix 4015,

1-22t

names of,

VS,

5-6

editing with the Character-Cell interface,

1-22t

non-APL,

1-23t

2-16

VAXTPU

VT102,

1-22t

APL interface,

VT220,

1-22t

buffer,

VT240,

1-22t

VT320,

1-23t

editing variables,

VT330,

1-23t

syntax form,

VT340,

1-23t

TPU

See VAXTPU editor

Index-12

3-1

1-22t

Value display,

KEY,

3-1

User-defined operations

Terminals

DECTERM,

3-10

5-5

User-defined functions,

1-19

/TERMINAL qualifier,

1-2

5-6

displaying,
suppressing,

COMPOSITE,

5-56

Typewriter-paired character set,

output

GIGI,

5-56

with output function,

5-1

type,

5-23

1-39

Type parameter

with input function,

font files,

5-5

optional character set with,

Terminal
designators,

4-11

mnemonics

Temporary mailbox,

/O,

14, 1-38, 1-39t, 5-23

decimal point, in patterns,

Telephone

disconnecting,

3-49

TTY

Tab position
absolute,

3-46

3—46

1-17

VAXTPU editor
2-27

2-34, 3-22

Vector

definition of,

2-3

domain definition,

2-9

Vector (cont’d)

clearing,

stop,

3-48

trace,

3—46

Vector notation

definition of,

1-30

definition of,

1-29

inactive,

2-20

/VECTOR qualifier,

names,

1-20

subprocess,

format of,

1-31

password,

3-58

saved,

VMS SORT

calling from APL,

1-31

1-30

1-33
3-57

1-30

Writing external routines,
5-43

Weak attention signal,

1-33

2-22

Wildcards
in identifiers,
Workspace

1-31t

1-31

space considerations,
types,

Wait system function,
White space,

size,

6-22e

1-30
1-31

defaults for,

VMS

file specification,

1-30

CONTINUE,

2-17

WSPRINT.APL,
WSAPRINT,

6-2

3-16

Z
Zero fill format phrase qualifier,

Zero format phrase decorator,

4-23

4-24

Index-13

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040

before placing your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using
a 1200- or 2400-baud modem.

If you need assistance using the Electronic Store,

call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KAO2/2

Nashua, New Hampshire 03061

P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
International

Internal’

Local Digital subsidiary or
approved distributor
USASSB Order Processing - WMO/E15
or

U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

1For internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader’s Comments

VAX APL
User’s Guide
AA-P142E-TE

Please use this postage-paid form to comment on this manual. If you require a written

reply to a software problem and are eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR form.
Thank you for your assistance.

I rate this manual’s:

Excellent,

Good

Fair

Poor

Accuracy (software works as manual says)

[]

Completeness (enough information)

[]

Clarity (easy to understand)

Organization (structure of subject matter)

[]

]

[]

Figures (useful)

[]

Examples (useful)

[]

Index (ability to find topic)

]

Page layout (easy to find information)

]

[]

]

I would like to see more/less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version

Name/Title

of the software this manual describes.

Dept.

Company

Date

Mailing Address

Phone

Do Not Tear - Fold Here and Tape

—-———————""""—"""""
""" ""—-—-———-—————————

No Postage
Necessary
f Mailed

in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
Corporate User Information Products
PKO03-1/D30
129 PARKER STREET
MAYNARD, MA 01754-9975

Do Not Tear — Fold Hexre

———————————
e
e e e e e e
— — — —