Digital PDFs

AA-Y921B-TE

May 1986

432 pages

Original

98MB

view download

OCR Version

53MB

view download

Document:	VAXLISP/VMS User''s Guide
Order Number:	AA-Y921B-TE
Revision:	000
Pages:	432
Original Filename:

OCR Text

VAX LISP/VMS
User’s Guide
Order Number: AA-Y921B-TE

May 1986

This document contains information required by a LISP language
programmer to interpret, compile, and debug VAX LISP programs.

Operating System and Version:

VAX/VMS Version 4.2

Software Version:

VAX LISP/VMS Version 2.0

digital equipment corporation
maynard, massachusetts

First

Printing,

June

1984

May

1986

Revised,

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

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.
©

Digital

Equipment Corporation 1984,
All

Rights

Printed

1986.

Reserved.

in U.S.A.

A postage-paid READER’S COMMENTS form is included on the last page
of
this
document.
Your
comments
will
assist
wus in preparing future
documentation.

The

following are

trademarks of Digital

Equipment Corporation:

DEC

UNIBUS

PDP

DECUS

VAX

VMS

MicroVAX
VAXstation

MicroVAX I1I
VAXstation II

MicroVMS
AI VAXstation

DECnet

ULTRIX

ULTRIX-11

ULTRIX-32

ULTRIX-32m

dlilgliltall8

CONTENTS

X111

PREFACE

Part

Interpreter

Compiler

Editor

Handler

Call-Out Facility
Alien Structure Facility
Function

Facility

Graphics

VAX LISP/VMS

B B

Interrupt
VAXstation

Interface

Function,

Macro,

and Variable
it
i

DCL

INVOKING

COMMANDS

LISP
LISP

LISP

ENTERING

INPUT

DELETING AND

EDITING

ENTERING

DEBUGGER

USING

THE

CONTROL

CREATING
LOADING

KEY

INPUT

CHARACTERS

PROGRAMS
FILES

COMPILING

PROGRAMS

Compiling

Individual

Functions

Compiling Files
Advantages of Compiling
COMMAND

Five Ways
/COMPILE

/ERROR_ACTION

/[NO]INITIALIZE

LISP

Compiling

Expressions

LISP

Expressions

QUALIFIERS

Use

LISP

DCL

of Not

and Macros

the

DCL

LISP

Command

NS (O

Advantage

W OOWWOWOWOOJOUH
W
=

ENTERING

VAX

SPECIFICATIONS

NAMES

FILE

LOGICAL

EXITING

ol eNoNoRol
W

HELP

VAX/VMS

USING

HELP

LISP

S I |
|
|
PN
DNDNNDNNDNDDNDDDNDNDDNDDND
=
|
i
(I
D
D
T
W R WWWI~IO0UTU
S W
NN

FACILITIES

DCL

SENENESECESENESH
SN SR SESE SN SN SN SN SN

CHAPTER

R RRRR

Descriptions
HELP

Facilities

Pretty Printer

Error

Debugging

LISP

VAX

Command

DWW
W

LISP

UTUTOT U

LISP

VAX

FACILITIES

RRRRRRRRRRRRD

Y
e
e
e

O 00 -JOUTd
WNE
P

N
R

W NN

DCL

e
R
e
e

OVERVIEW

AND

INTRODUCTION

CONCEPTS

SYSTEM

= -

CHAPTER

LISP/VMS

OO~~~
IO

VAX

iii

/INSTALL

.10.

/[NO]JLIST

2-17

.10.

/[NOJMACHINE_CODE

2-18

.10.

/MEMORY

2-19

.10.

/[NO]OPTIMIZE

2-20

.10.

/[NO])OUTPUT_FILE

2-21

.10.

/REMOVE

2-22

.10.

/RESUME

2-22

.10.

/[NO]JVERBOSE

2-23

.10.

/[ NO]JWARNINGS

2-24

NN
DN DN

.10.

2-17
2-17

.11

USING

SUSPENDED

11.

Creating a Suspended System

c11.

Resuming a

Suspended System

2-26

Inserting Nongraphic

the

Characters

Cursor

LISP

Code

=
N
W

Case

Jdoywwio
WO

3-18
3-19

3-19
3-20
3-21

3-20

(VAXstation Only)
|

Changing

Oy U

o
o

Moving with the Pointer
Modifying Text

o
o
o
o

3-18

Undeleting Text
Cutting and Pasting Text

Oy U

Moving

Deleting Text

Moving with the Keypad and Arrow Keys

Moving

Inserting and Formatting Text
Inserting Ordinary Text
Typing and Formatting LISP Code

OPERATIONS

Interpreter

the LISP
Commands

Keypad

W wwwidhdhidhoN
e

(NG

U
O

W wwio
-

Cycle

the Editor
Interacting with the Editor
Getting Help
Input Completion and Alternatives
Errors and Other Problems
Moving Work Back to LISP

EDITING

EDITOR

Invoking

Summary of

Editing

Returning

NDRNDNDRDNDNDNNDNDNNDDN
NN N R
R b
b
s b

(98
&

wwwwkwwwwwwwwww
Ww

&
&
€

ww
i

&
&
S
e

wwwlw
W
w

&
&
&

W
W
W

&
e

INTRODUCTION TO THE

W W Wwwwwwwww
I
T
T
|
ol
wwwwwww
e N
e
J

EDITOR

LISP

THE VAX

USING

2-25

SYSTEMS

2-25

CHAPTER

JINTERACTIVE

.10.

Substituting Text
Inserting a File or Buffer

3-22

Repeating an Operation
Summary of Commands
USING MULTIPLE BUFFERS AND WINDOWS

3-23

3-23
3-24

3-30

Introduction to Buffers and Windows
Creating New Buffers from Within the Editor

3-33

Working with Buffers
Saving Buffer Contents

3-34

3-30
3-33

SO\

Conflicts

3-34

3-35

Between Buffers

3-36
3-36

Commands
PROBLEMS

3-37

EDITOR

3-38

Binding Keys to Commands
Binding Within the Editor
Binding from the LISP Interpreter

3-39

FROM

CUSTOMIZING

THE

RECOVERING

Selecting

Summary of

Key Binding Context
Keyboard

Moving Text

Key

3-38
3-40

3-43

Sequence

and

Shadowing

3-44
3-45

Macros

Summary of Commands
USING THE EDITOR ON A VAXSTATION
Screen Appearance and Behavior
Editing with the Pointer
Pointer

The

(NS

(NI SO

3-34

Buffers

Name

Manipulating Windows

O U

W W

SO OYONOYOYUTOTUTOUOTUTUYTOYTUT
DWW W WwW

Wwwwwwwwwwwwwwwww
ww
W

Deleting

Buffer

3-46

3-46
3-47
3-47

3-47

Cursor

Selecting and Removing Windows
Moving the Text Insertion Cursor

3-48

and Marking

Cutting and Pasting
Invoking the DESCRIBE

Function And Matching
3-49

STACK

Exiting

Using

the
the

the

Break

o N AY
-

UTUTD
o

OOt

Loop

Break Loop
Break Loop

FRAME

LOOP

Invoking
TMo

STACK

BREAK

FACILITIES

ACTIVE

*UNIVERSAL-ERROR-HANDLER¥* Variable

(S S

Binding the

CONTROL

Function

Error-Signaling
Arguments

VARIABLES

DWW

o N o S

Name

(NS

Function

CONTROL

HANDLER

Defining an Error Handler

ERROR

CREATING AN
R
e

Errors

s S

Continuable
Warnings

TYPES

[

ERROR

Errors

Fatal

o
wWwwwwwwibdhhidhdo
N e

HANDLER

LISP

3-49

W
w
o

SO U
U
[

U
L]

S
®

U
2

O
[-]
-]
[

ERROR

VAX

SO SO G

HANDLING

T OOy
O U1 U

]

ERROR

DEBUGGING

CHAPTER

Information About Pointer Effects
Binding Pointer Buttons to Commands

~J ~J OO

Parentheses

Oy UT U

finN

O
o

W
w

Text

[

Break

Loop

Variables

]

DEBUGGER

Using

the
the

Debugger
Debugger

Debugger

Commands

Arguments

Debugger

Using

e
L4
Ul

@
@
W W

[

L2
[}
Wik

Invoking
Exiting

the

Sample

Commands

DEBUG-CALL

Debugging

Function

Sessions

@
¢

the

Stepper

Output

Using
—

Using

]

Commands

Stepper

Variables

*STEP-FORM*
N

SCUT UMY

Stepper

@
L]

*STEP-ENVIRONMENT
*

Example

Sample

Stepper

Use

Stepper

Tracer

Options

Invoking
Adding

Tracer

the

Debugger

Information

Invoking

Ut b

&
@

Tracer

the

Output

the

Removing

Information

Defining

When

]
[

@
®

VIR
O

WWWWwWwwioN
NN P

[]

WITH

Explicitly
Limiting

Macro

Output
Is

USING

Traced

Conserving

CONTROL

Pretty

VARIABLES

Printing

Lines

Using

Producing

Space

with

THE

FORMAT

FUNCTION

WRITE

FORMAT

Directive

the

Controlling
Controlling

Miser

the Arrangement

Controlling Where

New Lines

Mode

Using Tabs

and

Output

Begin

Indentation

Prefixes

FORMAT

DEFAULTS

USING

Enabling

Output

EXTENSIONS

Controlling Margins

[:]
@
[
[-]

EXTENSIONS

EDITOR

PRINTING

from Tracer

*TRACE-CALL*

PRETTY-PRINT

Output

Variables

PRETTY

Tracer

Function

HOW

Stepper

*TRACE-VALUES*
THE

the

Tracer

U
UTUT

]
[

]

L2
8

e
DD

@
DD

®
[
WP

Enabling

Disabling

Suffixes

O
OY O©
i
|
I
OYOYOYOYOY
OY OY OY OO
e
;
I
U
W
00~ U U DWW

TRACER

AND

]

Variables

Sessions

PRINTING

DO OO
OOy Oy O

the

Arguments

[

]

Exiting

PRETTY

CHAPTER

Invoking

STEPPER

FUNCTIONS

LISTS

6-19

FUNCTIONS

6-21

FOR

PRINTED

6-16

6-18

6-23

OUTPUT

Abbreviating Output

Length

6-24

Abbreviating

Output

Depth

6-24

Abbreviating

Output

USING

MISER

HANDLING

6-25

Lines

6-26

MODE

IMPROPERLY

LISP/VMS

DATA

FORMED

ARGUMENT

IMPLEMENTATION

LISTS

6-28

NOTES

REPRESENTATION

foacd

Numbers
Integers

Floating-Point

Lists
DIRECTIVES

Numbers

Characters
Arrays

Strings
PATHNAMES

Fields

OO -JO0yUul &

Names

to Use

Pathnames

COMMON LISP

Pathname

Field Values of a VAX LISP Pathname
Three Ways to Create Pathnames

Comparing Similar Pathnames
Converting Pathnames into Namestrings
Functions That Use Pathnames
Using the *DEFAULT-PATHNAME-DEFAULTS* Variable
COLLECTOR

GARBAGE
N

Frequency

LISP

Available

Collection

Space

Collection Failure

AND

OUTPUT

Character

Newline
Terminal

Input

End-of-File
Record
File

Garbage

Processing

Garbage
INPUT

Space

Oy U

Static

Messages

Operations

Length

Organization

Functions
N

Function

FILE-POSITION

FILE-LENGTH

OPEN Function
WRITE-CHAR Function

O OYOYOYOY
Ul o
W DN

and

Pathnames

INTERRUPT
COMPILER

Function

FUNCTIONS AND

vil

KEYBOARD

FUNCTIONS

Logical
When

Wik

Namestrings

U
I
B
B
B
VAt B B
B
BN
ol 00 R
R
R
B
R
R
N = WO 0000 JJOOYO
U
DN

(NS
e

OV OV OO
OY OY O

OWOOJd~Jd~Jd~JO0O
Ut b W

Oy OY OO

GENERALIZED

ABBREVIATING

DWW WWwWwWwWwWNDNDNDNNDNDNDDNDNDN
R R
S e
DD
D
D
D
D
D
D
D

FORMAT

DEFINING

VAX

NN SNSNSN—~-NNNSN-NNN-NNNN-NNN-NN-N-N-NNNN-N
NN
NN
NN
N

Handling

OWN

DEFINING

UT
~N N

for

YOUR

CHAPTER

Directives
DEFINING

Restrictions

COMPILE

FUNCTIONS

7-25

Function

COMPILE-FILE
Compiler

~] ~J ~J ~1 ~J

Compiler

7-25

Function

AND

LISP/VMS

FUNCTION,

APROPOS

Function

APROPOS-LIST
ATTACH

7-29

MACRO,

AND

VARIABLE

Function
Function

Function

CANCEL-CHARACTER-TAG

CHAR-NAME-TABLE

COMPILEDP

Function

*COMPILE-VERBOSE*

Variable

*COMPILE-WARNINGS*
CONTINUE
DEBUG

Tag

Function

COMPILE-FILE

Variable

Function

DEBUG-CALL

Function

*DEBUG-PRINT-LENGTH*
*DEBUG-PRINT-LEVEL*
DEFAULT-DIRECTORY

Variable
Variable

Function

DEFINE-FORMAT-DIRECTIVE

Macro

DEFINE-GENERALIZED-PRINT-FUNCTION
DEFINE-LIST-PRINT-FUNCTION

DELETE-PACKAGE

DESCRIBE

Function

*ERROR-ACTION*
EXIT

Variable

Function

Format
GC

Macro

Function

DIRECTORY

DRIBBLE
ED

DESCRIPTIONS

Function

BIND-KEYBOARD-FUNCTION

BREAK

7-26

MACROS

Part

VAX

7-26

Optimizations

Directives

Provided with VAX

LISP

Function

*GC-VERBOSE* Variable
GENERALIZED-PRINT-FUNCTION-ENABLED-P

GET-DEVICE-INFORMATION
GET-FILE-INFORMATION
GET-GC-REAL-TIME

GET-GC-RUN-TIME

Function

GET-INTERNAL-RUN-TIME

Function

GET-KEYBOARD-FUNCTION

Function

GET-PROCESS-INFORMATION
GET-TERMINAL-MODES
GET-VMS-MESSAGE

Function

HASH-TABLE-REHASH-SIZE

Function

HASH-TABLE-REHASH-THRESHOLD

viil

Function

HASH-TABLE-SIZE

Function

HASH-TABLE-TEST

Function

LOAD

Function

_ONG-SITE-NAME

Function

MACHINE-INSTANCE
MACHINE-VERSION
MAKE-ARRAY

Function

*MODULE-DIRECTORY* Variable

*POST-GC-MESSAGE*

Variable

PPRINT-DEFINITION

Function

PPRINT-PLIST

Function

*PRE-GC-MESSAGE*

*PRINT-LINES*

Variable

*PRINT-MISER-WIDTH*

*PRINT-RIGHT-MARGIN*

Variable

PRINT-SIGNALED-ERROR

Function

100

*PRINT-SLOT-NAMES-AS-KEYWORDS*
REQUIRE

ROOM

Function

105

SHORT-SITE-NAME

Function

108

Function

111

Function

112

STEP Macro

115

*STEP-ENVIRONMENT* Variable

116

*STEP-FORM*

117

Variable

SUSPEND Function
THROW-TO-COMMAND-LEVEL
TIME

Function

Macro

122

123

TRACE Macro

124
Variable

135

*TRACE-VALUES* Variable
TRANSLATE-LOGICAL-NAME

136
Function

UNBIND-KEYBOARD-FUNCTION
UNCOMPILE

Function

UNIVERSAL-ERROR-HANDLER

A.l

137

139
140

UNDEFINE-LIST-PRINT-FUNCTION Macro

118
121

*TOP-LEVEL-PROMPT* Variable
*TRACE-CALL*

APPENDIX

102
103

SET-TERMINAL-MODES
SPAWN

Variable

Function

141

142

*UNIVERSAL-ERROR-HANDLER* Variable
WARN Function

143
144

WITH-GENERALIZED-PRINT-FUNCTION Macro

145

PERFORMANCE

DATA

HINTS

STRUCTURES

A-1

A.1.1

Integers

A-2

A.l1.2

Floating-Point Numbers

A-2

A.1.3

Ratios

A-2

A.1.4

Characters

A-3

A.1.5

Symbols

A-3

A.1.6

Lists and Vectors

A.1.7

Strings,

General Vectors,

A-4

and Bit Vectors

A-5

COMPILER

REQUIREMENTS

"EMACS"

INTRODUCTION

ACTIVATING THE
|-

STRUCTURE

USING THE

Activating
Making

EDITOR

THE

EDITOR

"EMACS"

the

STYLE

a Minor

Major

Style

STYLE

EDITOR

COMMANDS

c.1

EDITOR

COMMAND

C.2

EDITOR

KEY

3-1

Numeric Keypad
Variables Governing Miser Mode

KEY

STYLE

"EMACS"

APPENDIX

BINDINGS

AND

KEY

BINDINGS

DESCRIPTIONS

BINDINGS

INDEX

FIGURES

6-1

L WNDDERFRPODD
WNE S WN
WivEFEEFE

UTOUTUTUTE

TABLES

File

Specification Defaults
In Line Editing
Control Characters
DCL LISP Command Qualifiers
DCL LISP Command Qualifier Modes
Keys

Used

General-Purpose Commands and Key Bindings
Editing Commands And Key Bindings
Commands For Manipulating Buffers And Windows
Characters Generated by Keys
Commands For Customizing The Editor
Error-Signaling Functions
Debugging Functions and Macros
Debugger Commands
Debugger

Command Modifiers

Stepper Commands
Format Directives

VAX LISP

el
N O OVOoOY
Oy

PROGRAM

DECLARATIONS

B
Womwow

APPENDIX

Tables

Functions

Hash

Provided by VAX LISP

Floating-Point Numbers

Floating-Point

Constants

VAX LISP Pathname

Fields

C-1

C-14

Implementation-Dependent

Functions

7-29

Provided with VAX LISP

GET-DEVICE-INFORMATION Keywords

GET-FILE-INFORMATION Keywords

GET-PROCESS-INFORMATION Keywords

TRACE

(NG
e N

106
125

Options

Differences

Keywords

Between

"EMACS"

Key

Bindings

"EMACS"

Style

Editor

Commands

Key Bindings

Editor

Key Bindings

And

Key Bindings

Bindings

and
QYo
o

GET-TERMINAL-MODES
Data Type Headings

Ul b

W N

Format Directives

Default
QN
w

and

BN
D DO

Summary of
Macros

PREFACE

Manual

Objectives

The VAX LISP/VMS User’s Guide is intended for use
in
developing
and
debugging
LISP
programs
and for use in compiling and executing LISP
programs on VAX/VMS systems.
The
VAX
LISP
1language
elements
are
described

in COMMON LISP:

The Language.*

Intended Audience |
This manual is designed for programmers who have a
working
knowledge
of
LISP.
Detailed knowledge of VAX/VMS is helpful but not essential;
familiarity with the Introduction to VAX/VMS is recommended.
However,

some
sections
of this manual require more extensive understanding of
the operating system.
In such
sections,
you
are
directed
to
the

appropriate manual(s)

Structure

for additional

information.

of This Document

An outline of the organization and

chapter

content

this

manual

follows:
ART

Part I

VAX LISP/VMS

SYSTEM CONCEPTS

consists of seven chapters,

describe

the VAX LISP

FACILITIES

which explain VAX LISP concepts and

facilities.

overview of
Chapter 1, Introduction to VAX LISP, provides an
VAX
LISP,
explains how to use the help facilities, describes
VAX/VMS file specifications and the
logical
name
mechanism,
and
provides
hints on entering DCL commands.
Chapter 1 also
find
can
you
documentation
describes where in the VAX LISP
information on each of

* Guy L.

AND

Steele Jr.,

Burlington,

the VAX LISP

COMMON LISP:

features.

The Language, Digital Press

Massachusetts.

Xxiiil

(1984),

PREFACE

Chapter 2,
from
VAX
input;

Using VAX LISP, explains how
to
1invoke
LISP;
use
control key sequences; enter

create

and

compile

suspended
systems.
command and its

LISP

programs;

addition,

load

Chapter

and
and

files;

exit
delete

and

describes

the

wuse

DCL

qualifiers.

Chapter 3, Using the VAX LISP Editor, describes how to use the
Editor provided with VAX LISP to create and edit LISP code.

Chapter

Error

error-handling

Chapter
LISP

LISP

PART

II:

Part

LISP

characteristics
the

explains

Facilities,

Pretty Printer,

LISP/VMS

any

VAX

LISP

explains

how to use

the

VAX

explains how

wuse

the

VAX

7,
VAX
LISP
Implementation
Notes,
describes
of
LISP that are defined by or are dependent on

describes

and

the

printer.

implementation

VAX

describes

facilities.

The

pretty

Chapter
features
VAX

Debugging

debugging

Chapter

Handling,

facility.

COMMON

FUNCTION,

functions,

LISP.

MACRO,

AND

VARIABLE

macros,

and

variables

objects

that

have

COMMON

LISP

in VAX

LISP.
or

function’s

Each

the
the

specific

function
or
wuse
and

macro’s

DESCRIPTIONS

macro
shows

VAX

implementation

description
format,

1ts

applicable
arguments,
return
value,
and
examples
of
use.
Each
description explains the variable’s use and provides examples

variable
of

1its

use.

Associated
The

Documents

following

documents

are

relevant

VAX LISP/VMS

VAX LISP/VMS Installation Guide

COMMON LISP:

VAX LISP/VMS Editor Programming Guide

VAX LISP/VMS System Access Programming Guide

VAX LISP/VMS Graphics Programming Guide

Introduction

VAX/VMS DCL Dictionary

The Language

to VAX/VMS

Xiv

programming:

PREFACE

VAX/VMS

System

VAX/VMS

I,/0

Services

User’s

Reference

Manual

Manual:

VAX/VMS Run-Time Library Routines
VAX Architecture

For

complete

Information

list

directory

which

can

the

angle

For

the

cataloged.

The

directory name

with

brackets

directory

level.

file

delimit

names

»>).

where

each

name

example:

[SMITH.EXAMPLES]

the

preceding

directory

specification,

EXAMPLES

represents

subdirectory.

filename

The name‘of the file.
filetype
An

abbreviation

that

usually

describes

the

type

the

file

one

each

data

1in

the

file.

version
An

integer

The

that

version

new version
period
The

punctuation

file

each

of
to

the

not

time

suspended

marks

the

have

you

file.

You

the

(colons,

file

version

can use

file

type

brackets,

are

either
and

time

desired.

you

create

(;)

semicolon

version.

period,

required.

and

The

semicolon)

marks

the

separate

the

specification.

supply

The

which

incremented

format

compile

system.

separate

specification

components

You

(.)

specifies

number

all

file,

only

the

components

load

component

1-8

file

initialization

you must

specification

file,

specify

1is

resume

the

file

INTRODUCTION TO VAX LISP

name;
the operating system supplies default values for the components
that you do not specify.
Table 1-1
summarizes
the
default
wvalues.
The
special variable *DEFAULT-PATHNAME-DEFAULTS* contains the default
values for the node, device, and directory elements.

Table 1-1:

File Specification Defaults

Optional Element

Default Value

node

Local

device

User’s

current default device

~directory

User'’s

current default directory

filename

Input

network node

Output

filetype

Depends

FAS
LIS
*LSC
LSP

None

Same as input file;

if no input file

specified,

there

no default

on usage:

-- Fast-loading file (output from compiler)
-- Error listing (output from compiler)
-- Editor checkpointing file
-- Source file (input to LISP reader or
compiler)

SUS

version

Suspended

system

Input -- Highest existing version number

Output

If no existing version, 1
If existing version, highest version

number

plus

The way the system fills in default values depends
on
the
operation
being
performed.
For
example, if you specify only a file name, the
compiler processes the source program if it
finds
a
file
with
the
specified file name that is stored on the default device, is cataloged
under the default directory name, and has an LSP file type.
If
more
than
one file meets these conditions, the compiler processes
the file
with the highest version number.
Suppose you pass the following
file
specification to

the

$ LISP/COMPILE

compiler:
DBA1:[SMITH]CIRCLE.LSP

The compiler searches directory SMITH
on
device
DBAl,
seeking
the
highest
version of CIRCLE.LSP.
1If you do not specify an output file,
the compiler generates the file CIRCLE.FAS,
stores
it
in
directory
SMITH
on
device
DBAl,
and
assigns it a version number that is one
higher than any version of CIRCLE.FAS cataloged in directory SMITH
on
&&.Lj

device

' & B

DBAl.

1-9

INTRODUCTION TO VAX LISP

1.4

LOGICAL NAMES

The

VAX/VMS

operating

allows

programs

have

specify

file

that

provide
with

For

the

device
or

device

another

complete

information on

logical

file
a

you

because

logical

and

on which

data

flexibility,

Command Procedures

1.5

contains

great

directory

system provides

file
wuse

you

resides

logical

can

file

name

mechanism

independent.
or

Programs
the

names.

associate

name

Logical
them

specification

that

but

not

not
the

names
only

also with

name.

logical

names,

see

the

Guide

to Using DCL

and

VAX/VMS.

ENTERING DCL COMMANDS

This section lists hints for entering DCL commands.
@

You
can
abbreviate
command
and
qualifier
names
to
four
characters.
You
can
use
fewer than four characters if the
abbreviation

unambiguous.

You must precede

each qualifier name with a

If
you
omit
a
specification),

required
the
DCL

the

slash

(/).

parameter
(for
example,
command interpreter prompts

a
file
you for

parameter.

You can enter a command on more than one
continued line with a hyphen (-).

You must press

the RETURN

pressing

RETURN

the

key

key passes

line

if you end

after

you

enter

the

command

the

each

command;
system for

processing.

You can delete

the

current

command

line

by typing CTRL/U.

You can interrupt command execution by typing CTRL/Y.
If
vyou
do
not
enter
a command that executes another image, you can
resume the interrupted command by entering
the
DCL
CONTINUE
command.
To
stop processing completely after typing CTRL/Y,
enter the DCL STOP command.

CHAPTER 2

USING VAX LISP

This

chapter

explains

the

describes

the

DCL

LISP

command

and

its

qualifiers

and

following:

Invoking

LISP

Exiting LISP
Entering

input

Deleting

input

Entering

the

Using

control

Creating
Loading

files

INVOKING LISP

You

invoke

When

appears,

and

programs

suspended

2.1

LISP.

key characters

programs

Compiling

Using

debugger

systems

interactive VAX
it

then

executed,

the

LISP
a

session by

message

LISP prompt

(Lisp>)

$ LISP

Welcome
Lisp>

to VAX LISP,

Version V2.0

typing

identifying

the

DCL

command

VAX LISP system
For example:
displayed.

USING VAX LISP
See

Section 2.10

the

LISP

2.2

EXITING

for descriptions of the qualifiers you can

wuse

with

command.

LISP

You can exit from LISP by using the LISP EXIT function.
Lisp>

For example:

(EXIT)

When you exit the LISP system, you are returned to the
DCL
level
of
operation.
If
you
have
wused
the Editor, modified buffers are not
saved on exiting LISP.
See Chapter 3 for information on how
to
save
modified buffers

before

exiting LISP.

You cannot exit the LISP system by typing CTRL/Z,
other

2.3

interactive

programs

that

as you can with many

run on VMS.

ENTERING INPUT

You enter input into the VAX LISP system a line at a time.
Once
you
move to a new line, you cannot go back to the previous line.
However,
you can recover an input expression or an output value
by
wusing
the
following

unique

variables:

//
///

* %
* % %

++
+++

These variables are
described
in
COMMON
LISP: The
Language.
The
following
example
illustrates
the use of the plus sign (+) variable
that is bound to the expression most recently evaluated:
Lisp>

(B C)

(CDR

Lisp>

(CDR

(QUOTE

"(A

C))

C)))

Lisp>

2.4

DELETING AND EDITING INPUT

The DELETE key deletes characters to the left of
the
<cursor
on
current line of input.
CTRL/U deletes the current line of input.
If you are using a video terminal, you
can
wuse
control
charac
function keys, and arrow keys on the terminal to edit the current
of

input.
2-2

the

USING VAX LISP

Table

2-1

lists

the

keys

you

can

use

delete

and

edit

input.

NOTE
You

can

bind

use

2-1

this

LISP
way

character

Table 2-1:

the

most

BIND-KEYBOARD-FUNCTION
the

control

function.

Binding

cancels

the

Table

2-1.

Keys Used

Line

characters

effect

function

listed

control

listed

for

Table

character

that

control

Editing

aitone

Key

Effect

CTRL/A

and

Switches

F14%*
CTRL/B
Up

and

between

current

line.

Recalls

the

last

overstrike

and

line

entered.

character

insert

modes

the

Arrow

CTRL/D
Left

and

Moves

the

cursor

one

Moves

the

cursor

Moves

the

cursor

one

Moves

the

cursor

the

beginning

the

left

from

the

left.

Arrow

CTRL/E

CTRL/F

and

Right

Arrow

CTRL/H

and

BACKSPACE

the

end

character

the

line.

the

right.

the

line.

and

F12*

CTRL/J

and

LINEFEED

Deletes

the

word

Deletes

characters

the

cursor.

and

F13*

CTRL,/U

the
*

2.5
If

This

key

you

(Lisp>)
to

available

ENTERING THE
make

automatically
use

with
the

error

the

only

during

the

debugger

LISP

of
the

the

cursor

position back

line.

LK201

keyboard.

DEBUGGER

1invokes

VAX

beginning

interactive

debugger,

prompt

debugger,

see

(Debug

VAX

LISP

session,

which

replaces

1>).

For

Chapter

the

LISP

information

error

prompt
on

how

USING VAX LISP

Typing CTRL/C is a quick way to recover from an error without using
If you want to recover from an error by
the VAX VLISP debugger.
CTRL/C.
type
over,
typed and starting
you
discarding the expression
the
displays
which
loop,
nt
read-eval-pri
the
returns vyou to
CTRL/C
LISP

prompt

(Lisp>).

2.6

USING CONTROL KEY CHARACTERS
characters

Table 2-2 lists the control

you

1in

use

can

VAX

CTRL/C is the only one whose listed function is specific to LISP.
other control characters perform standard VMS functions.

LISP.

The

NOTE

to
function
BIND-KEYBOARD-FUNCTION
the
You can use
Table
in
listed
characters
the control
of
bind most
character
control
Binding a
2-2 to a LISP function.
in this way cancels the effect listed for that control
character

2-2.

in Table

These control characters do not work in the

VAX

LISP

Editor.

Table 2-2:
Control

Control Characters

Character

Function

CTRL/C

Returns you to the top-level loop from
command

level.

LISP,

CLEAR-INPUT function on the

then

performs

CTRL/C

any

invokes

other
the

*TERMINAL-IO*

stream,

If you want to

recover

a throw to the catcher established

for CANCEL-CHARACTER-TAG.

by discarding the expression you
error
an
from
(See
CTRL/C.
type
over,
starting
and
typed
of
example
an
for
II
Part
in
ACTER-TAG
CANCEL-CHAR
changing the behavior of CTRL/C.)

CTRL/0O
CTRL/Q

terminal

until

Resumes terminal output that had been halted

with

Discards output being sent to the
you

type

another

CTRL/O.

CTRL/S.

CTRL/R

Redisplays what is on a line.

USING VAX LISP

Table

2-2

Control

(cont.)

Character

CTRL/S

Function

Stops output to the terminal

wuntil

CTRL/Q

typed.

CTRL/T

Displays
during

CTRL/U

Deletes
echoed

CTRL/X

CTRL/Y

the

2.7

CREATING

The

most

editor.
loaded

into

this way,
the

Although you
LISP
Editor

current

to watch
input

This

the

line.

1is

useful

resources used.
The

prompt

is not

LISP.

all

input

you

type-ahead

that

has

not

yet

been

read

from

buffer.

the

DCL

level

control

and purges

buffer.

PROGRAMS

common way

the

type-ahead

Returns

information.

computation

Deletes
the

process

LISP

create

the

LISP

program

program exists

environment

the

in a

LISP

1is

source

LOAD

wusing

file

that

text

can be

function.

can compose source programs with any text editor, the VAX
provides
facilities
that
help you enter and edit LISP

source code.
For example, the Editor helps
you
balance
parentheses
and
maintain
proper
1indentation.
Furthermore,
this editor, being
integrated into the LISP environment, can be
extended
with
features
that
fit
vyour own style of editing.
See Chapter 3 for a description
of

how

use

the

Editor.

Another way to create LISP
programs
is
to
define
them
wusing
the
interpreter
in
an interactive LISP session.
If you define functions
with
the
DEFUN
macro
or
macros
with
the
DEFMACRO
macro,
the
definitions
become
a
part of the interpreted LISP environment.
You
can then invoke your defined functions
and
macros.
However,
since
these
definitions
are
not
in
a
permanent text file, your work is
stored only
temporarily
and
disappears
when
you
exit
VAX
LISP.
Entering
programs
by typing to the interpreter is really useful only
for experimenting with small functions and macros.

2.8

LOADING FILES

Before you can use a file
into
the
LISP
system.

in interactive LISP, you must load the
file
The
file
can
be compiled or interpreted;

2-5

USING VAX LISP

compiled files load more quickly.
system

You can load a file

into

the

LISP

ways:

three

Load the file by specifying the DCL LISP INITIALIZE qualifier.
For

example:
S

LISP/INITIALIZE=MYINIT.LSP

Welcome

Version V2.0

to VAX LISP,

Lisp>

The LISP prompt
indicates
the
file
has
been
successfully
loaded.
If
the
file
1is
not successfully loaded, an error
message indicating the reason appears on your terminal screen.
Include the /VERBOSE qualifier to cause the names of functions
loaded in an initialization file to be listed at the terminal.
on the /VERBOSE qualifier, see Section
information
more
For
2.10.14.

Load the file by using the
interactive LISP session.

'
b e =e

wes

Lisp>

(LOAD

LISP

LOAD

when

function

1in

For example:

"TESTPROG.LSP")

Loading contents of

file DBAl:[JONES]TESTPROG.LSP;1

FACTORIAL

FACTORS -OF

Finished loading DBA1l: [ JONES ]TESTPROG.LSP;1

isp>

The file name ("TESTPROG.LSP" in the example) can be a string,
symbol, stream, or pathname.
FACTORIAL and FACTORS-OF are the
functions contained in the file
TESTPROG.LSP.
The
final
T
For
has been successfully loaded.
file
the
that
indicates
more

information on the LOAD function,

see Part

II.

that
when
Editor
the
in
Evaluate the contents of a buffer
See Chapter 3 for more information on
buffer contains a file.
this

topic.

With the /INITIALIZE qualifier, you can load more than one file
at
a
time.
With the LOAD function, however, you can specify only one file
at

2.9

time.

COMPILING PROGRAMS

You compile LISP programs by compiling the LISP expressions that make
up
the
programs.
You
can
compile
LISP
expressions 1n two ways:
individually, by using the LISP COMPILE function; or
1in
a
file,
by

2-6

USING VAX LISP

using

either

the

LISP

COMPILE-FILE

function

the

DCL

LISP

/COMPILE

qualifier.

2.9.1
In

Compiling

LISP,

macro.
LISP

the

unit

You

can

compile

wusing

session

described

You

the

Individual

compilation

call

LISP

function works.

compiled

COMMON LISP:

normally

COMPILE

Functions and

form without
function

for

normally

function

the

COMPILE

The

Language.

function

Once

to write

either

macro

function.

first

it works

having
this

Macros

function

currently
This

interpreted

interpreted,
the

function

form

you
a

can

see

test

file.

running

Use

1is

1if

1in
the

purpose.

When you

compile a function or a macro that is
not
1in
a
file,
the
consequent
compiled
definition
exists only in the current LISP; the
definition is not in a file.
However,
you
can
use
the
VAX
LISP
UNCOMPILE
function
to
retrieve
the
1interpreted
definition.
This
function, described in Part II, is
wuseful
when
debugging
programs.
Because
the
interpreted
code
shows
vyou
more
of
your function’s

evaluation than the compiled code, you can find the error more easily.
You
can
modify
the function definition in the Editor to correct the

error and also save your corrected version of the function in a
file.
See
Chapter
3
for
further information on using the Editor to write
interpreted

2.9.2

functions

Compiling

files.

Files

Any collection of LISP expressions can make up a program
and
can
be
stored in a file.
The compiler processes such a file by compiling the
LISP expressions in the file and writing each compiled
result
to
an
output

file.

You can compile VAX LISP files either
command and the /COMPILE qualifier or
LISP

COMPILE-FILE

at
DCL
level
with
the
LISP
in interactive VAX LISP with the

function.

The
/COMPILE
qualifier
1is
described
1in
Section
2.10.2.
The
COMPILE-FILE
function is described in Part II.
The following example
shows
how
the
/COMPILE
qualifier
is
wused
to
compile
the
file
MYPROG.LSP

the

DCL

level:

LISP/COMPILE MYPROG.LSP

S
This

example

produces

output

file

named MYPROG.FAS.

USING VAX LISP

The

compile

example
the

Lisp>

shows

file

how

(COMPILE-FILE

compilation

FACTORIAL

compiled.

Finished

compilation

Errors,

COMPILE-FILE

from within

function

the

LISP

can

wused

system:

"MYPROG.LSP")

Starting

the

MYPROG.LSP

file

DBAl:[JONES]MYPROG.LSP;1

file

DBA1l:[JONES]MYPROG.LSP;1

Warnings

"DBAl: [ JONES ]JMYPROG.FAS;1"
Lisp>

Both

methods

defaults.

each

function

does

not.

compiling

The
it

Both

quickly

compiles
methods

than

first

method

has

step.

example:

For

compile

The

the

second method

are

has

the

compilation

using

leave

the

the
LISP

compiling

correct

except
lists

but

fast-loading
files.

directory

files,

(type

can

their
name

FAS)

that

run

files

are

files.

LISP

several

qualifier

source

the

compile

/COMPILE

files

one

FILE3.LSP

function,

vyou

/COMPILE

files

wusing

can

1in
the

Fast-loading

FILE2.LSP,

since

the

containing your

that you

COMPILE-FILE

only

takes

several

compile

single

that

have

COMPILE-FILE

output

file

COMPILE-FILE

Editor

to
The

function

leaving
on

function

one

steps

file

you

method

some

each

returns

can

follows:

Lisp>

(LOAD

2-8

LISP

both

you

file

and you do

not

also

convenient

quickly

method

made

the

convenient

check

1is
to

changed

namestring

Therefore,

load

COMPILE-FILE

stay

you have
macros

LISP

The

the

vyou

method

create

and want

generates.

function,

This

LISP.

changes

defined

wusing

enabling

afterwards.

environment.

them without
you

files,

LISP

depends

is,

compiling

advantage

and

compilation

The

equivalent

automatically

terminal,

compiling

files,

are

COMPILE-FILE.

function,

during

the

FILEl1.LSP,

LISP

several

advantage

LISP/COMPILE

When you use
call

the

produce

qualifier,

files

function

uncompiled

automatically placed
The

LISP

COMPILE-FILE

LISP

you

are

errors

and

necessary

the
a

for

want

1if

the

environment;

package.

corresponding

1immediately

resulting

the

after

using

the

output

file

USING VAX LISP

2.9.3

Advantages of Compiling LISP Expressions

You can use both
compiled
and
wuncompiled
(interpreted)
files
and
functions
during
a
LISP session.
Both compiled and uncompiled LISP
expressions have their advantages.
The
advantages
of
compiling
a
file,

a macro,

function

follow:

debugging
initial
good
Compiling a function or a macro is a
tool,
since
the compilation does static error checking, such

as checking the number of arguments to a function or a
macro.
For example, consider the following function definition:
(DEFUN

(IF

TEST

(X)

(TEST

(TRY

X)))

In
the
definition
of
the
function
TEST,
the
alternate
consequent
(the
false part) of the IF condition invokes TEST
with
two
arguments,
(TRY
X)
and
X,
while the
function
definition
of TEST calls for only one argument.
Despite this
error,
TEST
might
work
correctly
as
an
interpreted
(uncompiled)
function
if
the
argument
given is a positive
number, since it uses only
the
first
consequent
(the
true

part);
so
you may not detect the error.
the function, the compiler
would
detect
second consequent and issue a warning.

compiled
the
A compiled file not only loads much faster, but
the corresponding
than
faster
significantly
executes
code
interpreted

2.9.4

But if you compiled
the
error
in
the

code.

Advantage of Not Compiling LISP Expressions

You can debug run-time errors in an interpreted function
more
easily
than vyou can debug them in a compiled file or function.
For example,
if the debugger is invoked because an error occurred in an
uncompiled
function,
vyou
can
wuse the debugger to find out what code caused the
error.
If the debugger is invoked because
an
error
occurred
in
a
function, the code surrounding the form that caused an error
compiled
to be signaled may not be accessible.
The stepper
facility
1is
also
more
informative
with interpreted than with compiled functions.
See
Chapter 5 for information on the debugger and the stepper.

2.10

DCL LISP COMMAND QUALIFIERS

The LISP command can be specified with several qualifiers according to
The format of the LISP command with
conventions.
standard VMS
the

2-9

USING VAX LISP

qualifiers

follows:

LISP[/qualifier...]
Some

qualifiers

have

which

negates

the

specify

equal

sign

qualifier

(=)

corresponding

specified

and

the

negative

action.

Other

value,

type

qualifier

value.

For

the

form,

/NOgualifier,

qualifiers
name

values.

followed

vyou

choose

example:

/INITIALIZE=MYPROG.LSP

Qualifier

only

one

values

value

are

from

surrounded

list.

/ERROR_ACTION={EXIT
To

specify

parentheses.

1list

For

by braces

({

})

when

can

example:

DEBUG}

qualifier

wvalues,

enclose

the

wvalues

1in

lines

that

you

example:

/INITIALIZE=(MYPROG1.LSP,MYPROG2.LSP)
You

can

use

frequently.
$

define

BIGLISP

Following
prompt,

Table

this

results

2-3

Sections

Table 2-3:

DCL

symbols

For
:==

the

DCL

execution

summarizes
2.10.2

represent

LISP

the

through

symbol
the

Qualifier

BIGLISP,

LISP

qualifiers
2.10.15

DCL LISP Command

you

when

command

can

describe

use

each

typed

line

with

the

DCL

shown.

the

qualifier

LISP
in

command.

detail.

Qualifiers
Function

/COMPILE

Invokes

the VAX

compile
(input

the
/ERROR_ACTION={EXIT

command

LISP/INITIALIZE=SYSSLOGIN:LISPINIT/MEMORY=10000

command,
in

example:

DEBUG}

one

arguments

that

type

causes

your

when

the

default

compile

mode

DEBUG
@

e o oan e oy e o ow o om

lnceracttive

the
T

Lior

mode

(with

when

occurs.

batch

DEBUG

debugger

files

default

program

error

qualifier).

source

LSP).

LISP

compiler

file

EXIT

LISP

EXIT

jobs

the

invokes
an

error

default
P
-

sSession.

exit

and

/COMPILE

the

VAX

occurs.
in

USING VAX LISP

Table

2-3

(cont.)

Qualifier

Function

/[NO]JINITIALIZE=(file-spec,...)

Causes

the LISP
initialization

default

system

to
load
an
file(s).
The

file

type

initialization

NOINITIALIZE
of
/INTERACTIVE

file

suppresses

the

/INSTALL=suspended-system-spec

the

LISP

suspended

for

that

created

during

listing

consists

and

/INO]OPTIMIZE=(SPEED:n,SPACE:n,
SAFETY:n,COMPILATION SPEED:n)

except

jobs,

/LIST

the

file

(if

messages.

for

the

mode.
default.

LISP

file.

1listing

listing

suppresses

1is

Includes VAX

the

specified),

batch

the

name,

names of the

error

the

SUS.

type

and

file

/NOLIST

file

type

compilation.

compiled

and

the

file

1listing

file

LIS.

listing

/MEMORY=number

qualifier

warning

1in
to

file

compilation,

default

file

<code

system

expressions

/VERBOSE

The

default

command.

default

Specifies

LISP

session.

the

LISP

read-only
The

LISP

suspended-system

date

/[ NO]JMACHINE_CODE

the

Causes

shareable.

/I[NO]JLIST=[file-spec]

for

FAS.

files.

interactive

/INTERACTIVE

qualifier

LSP

initialization

Starts

for

1is

machine

default
such

code

1in

/NOMACHINE_CODE

suppresses a listing of the
code and is the default.

machine

Specifies

dynamic

the

amount

virtual

memory

LISP

512-byte

pages.

Tells

the

quality

compiler

has

the

allocates

that

each

corresponding

value.
SPEED is the speed at which
the object code runs, SPACE is
the
space
SAFETY

occupied or
1s
the

used by the
run-time

code,
error

checking
of
the
code,
and
of
COMPILATION_SPEED is the
sp eed
n is an
the
compilation
process.
The
integer in the range 0 to
3 .
LN 2%

2-11

gy e,

USING

Table

2-3

VAX LISP

(cont.)

Function

Qualifier

value

value;

the

The

the

value

default

Chapter

value

for

optimization
/[NOJOUTPUT_FILE=[file~-spec]

Causes
file

the

default

lowest
3

the

for

the

o0f

the

specified

output

/OUTPUT _FILE
Deletes
with

file

Resumes

/RESUME=file

The

global

the

Section

See

The

FAS.

compiled
to
a

file.

code

default.

sections

installed

qualifier.
LISP

file

LISP

compiled
1s

suspended

default

suspended

name.

type

the

/INSTALL
a

highest.
is

description

/NOOUTPUT
prevents
from
being
written

/REMOVE=suépended»system-spec

priority

declarations.

name

system

2.11

the

output

system.

type

for

SUS.

Using

See

Suspended

Systems.

Lists

/[NO]VERBOSE

listing

file,

functions
file.

listing

macros

function

and

the

defined

suppresses

and macro

file.

the

names

/NOVERBOSE

1is

default.

Specifies

/[NO]WARNINGS

device

any,

/NOVERBOSE

defined
the

and

that

produce

/NOWARNINGS
messages.

the

compiler

warning

1is

messages.

suppresses
/WARNINGS

warning
is
the

default.

2.10.1

Five Ways to Use the DCL LISP Command

Depending on the qualifier modifying it, you
<can
wuse
command in one of the following five ways called modes:

INTERACTIVE --

1invoke

interactive LISP

default)

COMPILE

compile

LISP

files

the

DCL

LISP

session

(the

USING VAX LISP

RESUME

resume

INSTALL

create

REMOVE

code

LISP

suspended

system

the

read-only

created

with the

for
global section
in a LISP suspended system

to delete

a global
/INSTALL qualifier

section

mode.
each
Table 2-4 lists the LISP command qualifiers that apply to
qualifier, the DCL LISP command puts you 1in an interactive
Without
a

(the

session

Table 2-4:

default).

DCL LISP Command Qualifier Modes

Qualifier

Mode

/COMPILE

COMPILE

/ERROR_ACTION

INTERACTIVE or

/INO]JINITIALIZE

INTERACTIVE

/INTERACTIVE

INTERACTIVE

/INSTALL

INSTALL

/INO]JLIST

COMPILE

/[NO]MACHINE_CODE

COMPILE

/MEMORY

INTERACTIVE

/[NO]OPTIMIZE

COMPILE

/[NO]OUTPUT_FILE

COMPILE

/REMOVE

REMOVE

/RESUME

RESUME

/[ NO]VERBOSE

INTERACTIVE

/ [NO]JWARNINGS

COMPILE

2.10.2

COMPILE

RESUME

/COMPILE

th e
e
The /COMPILE qualifier invokes
more

COMPILE or

source

files.

from each source file.

The

V £X
A

compiler

Unlike ot her

2-13

LISP compiler

to compile one or

creates a fast-loading (FAS) file
for
those
as
such
compilers,

USING VAX LISP

BASIC

and

modules.

type.

COBOL,

the

Consequently,

FAS

the

qualifier

compiler

compiles

the

file.

That

check

the

/[NO]JOUTPUT_FILE

default,

vyour

source

the

aid

the

file

See

for

generate

not

have

LISP

does

your

Section

not

put

purpose
2.10.11

compiled

/NOOUTPUT_FILE

but

does

not

object

file.

file

1If

the

compilation

compiling

the

file

for

information

compiled

file

the

qualifier.
gives

with

your

FAS

newly

file

type,

new

vyou

1If you want to compile files with

initialization
For

files,

use

functions
must

the

1information

load

when

the

listed

on your

the

/VERBOSE

specify

/INITIALIZE
how

level

in your

2.10.14).

are

command

file

compiled,

they

DCL

the

want

puts

you

name

finished.

Section

returns

same

and

2.10.4).

qualifier

files,

see

(see

Section

you

prompts

not
you

specify

for

file

/[NOJMACHINE_CODE,

/[NO]JWARNINGS

the

object

qualifier,

2.8.
If

VMS

directory,

(see

with

errors.

does

compiler

type

helpful

file

device

Section

source

qualifier

LISP

source

compiler

1is

compiler

file

used

the

file’s

compiler
output

method
for

the

default

/COMPILE

LISP

files

be
If

qualifier,

but

apply

only

qualifiers
particular
particular

the

with
1If

the

you

qualifier

compiled,

the

qualifiers

the

preceding

you

wuse

specify

the

all

file,

them

after

immediately

the
the

files

LISP

/COMPILE

use

the

and

system uses

you

apply

specify

all

qualifiers

file

the
with

name,

them

files
the

the

file.

conflicting
the

DCL

/[NO]JLIST,

/[ NO]VERBOSE,

and

preceding

qualifier,

qualifiers

/[NO]OUTPUT,

/COMPILE

you

for

name

name.

/OPTIMIZE,

with

compiled.

file

and

before

/COMPILE

qualifiers
you

specify

qualifier

specified

EXIT

DEBUG.

for
for

a
the

file.

Format

LISP/COMPILE

file-spec[,...]

Example

LISP/COMPILE

FACTORIAL.LSP

$
Mode

Compile

2.10.3
The

/ERROR_ACTION

EXIT
LISP

qualifier

causes
1f

the
fatal

has

two

values:

evaluation of your
or

continuable

2-14

and

program to
error

occurs

stop
(for

and
a

exits

complete

USING VAX LISP

description of errors and warnings, see Chapter 4).
EXIT
1is
the default
in batch mode and in compile mode, that is, with
the /COMPILE

qualifier.

Once
occurs.
error
DEBUG calls the VAX LISP debugger if an
error,
your
at
look
are in the VAX LISP debugger, you can
you
inspect the control stack, and continue your program from
the

point
at
which
it
interactive session.
the

stopped.
DEBUG
See Chapter 5 for

is
the
default in an
more
information
on

debugger.

You can use the /ERROR_ACTION qualifier when invoking
an
interactive
LISP session or when compiling files with the /COMPILE qualifier.
The
/ERROR_ACTION qualifier is
mainly
wuseful
for
batch
Jobs.
It
1is
equivalent to the VAX LISP *ERROR-ACTION* variable (see Part II).
Format

LISP/ERROR_ACTION=value
Example

LISP/COMPILE/ERRORMACTION::DEBUG MYPROG.LSP

Mode

Interactive,

2.10.4

Compile,

Resume

/[NO]INITIALIZE

The /INITIALIZE qualifier causes the LISP system to load one
or
more
initialization files containing LISP source code or compiled code.
An
initialization file’s purpose is to predefine functions you might want

wuse

a LISP session.

The default is to have no initialization

file.

If the initialization files contain calls to exiting functions
or
1if
these
files
contain errors and the /ERROR_ACTION qualifier is set to
EXIT (/ERROR_ACTION=EXIT), the LISP system returns to
the
DCL
level
without
prompting for interactive input.
If the initialization files
contain errors
and
the
/ERROR_ACTION
qualifier
1s
set
to
DEBUG
(/ERROR_ACTION=DEBUG),
the
LISP
system
puts you into the debugger.
See
Section
2.10.3
for
more
information
on
the
/ERROR_ACTION
qualifier.

The /INITIALIZE qualifier uses the LISP LOAD function to
default
the
proper
type, directory, and other parts of a file specification.
For
example,
vyou
do
not have
to
specify
the
file
type
if
initialization
file
has a FAS or a LSP file type.
If your directory
contains a file name with both a FAS and a LSP
file
type,
the
LISP
LFL LI

I\JUL

2-15

USING VAX LISP

system
file.

and

selects
1If

the

only a

directory

LSP

most
type

exists,

recently
file

the

created

only

LISP

file

FAS

system

type

the

file

selects

1initialization
of

the

given name

type

file

that

exists.

Use

the /VERBOSE qualifier

terminal

screen

initialization

You
LISP

can use

the

(see

names

any

2.10.14)

functions

display

the

macros

the

file.

the /INITIALIZE

session

Section
of

when

qualifier

compiling

files

when

1invoking

with

the

/COMPILE

qualifier with

the

/RESUME

cannot

use

the /INITIALIZE

you do

so,

the /INITIALIZE qualifier

interactive

qualifier.

You

qualifier;

1if

disregarded.

Format

LISP/INITIALIZE=(file-spec,...)
or

LISP/COMPILE/INITIALIZE=(file-spec,...)

file-spec

Example

LISP/INITIALIZE=MYINIT/VERBOSE

LISP,

contents

file

DBAl:[JONES]JMYINIT.LSP;1

FACTORS-OF

Finished

the

LISP

DBA1l:[JONES]MYINIT.LSP;1

preceding

FACTORIAL

and

system

described

example,

from Jones’s

the

FACTORS-OF are

*TOP-LEVEL-PROMPT*
Lisp> prompt to an
is

Version V2.0

FACTORIAL

ws
¥ wme

to VAX

Welcome

initialization

"*")
in
the
asterisk (*).

Part

file

functions

type

defaults

that are
file.

loaded
The

LSP.

into

form

the

(SETF

initialization file changes the
The *TOP-LEVEL-PROMPT* variable

II.

The SETF form and the prompt variable are not listed on an output
device
when
the
file is loaded, because the /VERBOSE qualifier
lists only functions and macros defined in the file.
Mode

Interactive

Compile

2-16

USING VAX LISP

2.10.5

/INTERACTIVE

The /INTERACTIVE qualifier,

the default,

starts

interactive

LISP

session.
Mode

Interactive

2.10.6

/INSTALL

The /INSTALL qualifier causes the read-only code in a LISP suspended
system to be shareable, reducing the physical memory requirements in a
Making the code shareable enables several people to
multiuser system.
You need the SYSGBL
read-only code.
same
the
simultaneously use
section)
global
(permanent
PRMGBL
and the
(system global pages)
generally
manager
system
A
privileges to use the /INSTALL qualifier.
installing VAX LISP on a multiuser
uses this qualifier once when
For
type for a suspended system is SUS.
file
default
The
system.
more information on this qualifier, see the VAX LISP/VMS Installation
Guide.
Format

LISP/INSTALL=suspended-system-spec
Example

S LISP/INSTALL=LISP$SSYSTEM:LISPSUS.SUS
Mode

Install

2.10.7

/[NOJLIST

The /LIST qualifier is meaningful only if it is specified with the
The /LIST qualifier specifies that the compiler
/COMPILE qualifier.
You must specify this
generate a listing file during compilation.
qualifier if you want a listing file. A listing includes the name of
the file compiled,

the date it was compiled, warning or error messages

summary of warning and error
and a
produced during compilation,
specify the /VERBOSE qualifier with the /LIST
If you
messages.
the 1listing also includes the names of the functions
qualifier,
compiled.

Specify the /LIST qualifier with a file name value only when you want
to be different from the name of the source
file name
1listing
the
2-17

USING VAX LISP

file.

1If

LISP

you

system

name

the

The

/NOLIST

batch

specify
produces

source

the
a

/LIST

listing

qualifier

without

file

with

LIS

file

type

name,
and

the

same

file.

qualifier

mode.

suppresses

The

/LIST

listing

qualifier

and

the

default

for

except

batch mode

operations.
Format

LISP/COMPILE/LIST[=file-spec]

file-spec

Example

$
Sample

LISP/COMPILE/LIST=FACTORIAL.LIS/VERBOSE MYPROG.LSP
Listing

Listing

output

Compiled
Lisp

File

for

file

10:33:30

Version

compilation

FACTORIAL

compiled.

Finished

compilation

Errors,

Friday,

December

1985

JONES

file

"DBAl:[JONES.LIS]MYPROG.LSP;1".

file

"DBAl1:[JONES.LIS]JMYPROG.LSP;1".

V2.0

Starting

DBAl:[JONES.LIS]MYPROG.LSP;1

Warnings

Mode

Compile

2.10.8
The

/[NOJMACHINE_CODE

/MACHINE_CODE

the

/COMPILE

compiler

separate
puts

VAX

put

from

anything

Section

listing

the

FAS

usually

2.10.7

LISP

qualifier

for

machine

code

However,

<compiling

that

The

must

the

qualifier

file

the
the

included

only

/MACHINE_CODE
VAX

LISP

compiler
in

description
is

similar

LISP

source

qualifier

machine-code

meaningful

The

machine

generates.

listing

file

listing

code

specified with

qualifier

1in

requests

<code
The

compiler

this

the
file
also

file

(see

code.

file).

standard

assembly

language

does

generate

object

not

modules

linked.

/MACHINE_CODE

code;

qualifier.

listing

has

the

has

produces
file
same

effect

only

generated when
name

your

2-18

the

production

machine-code

listing

vyou

wuse

the

source

file

and

machine

file.

The

/MACHINE_CODE
has

LIS

file

USING VAX LISP

type

(unless you also used

the /LIST

qualifier

specify a

different

name).

The /NOMACHINE_CODE qualifier,
LISP

machine

the

default,

suppresses

listing

code.

Format

LISP/COMPILE/MACHINE_CODE

file-spec

Example

LISP/COMPILE/MACHINE_CODE MYPROG.LSP

Mode

Compile

2.10.9

/MEMORY

The /MEMORY qualifier lets you specify the amount of
dynamic
virtual
memory
the
LISP
system
allocates
1in
512-byte pages.
This system
requires a
minimum
of
6000
pages
of
dynamic
wvirtual
memory
to
function.
This
memory
is
1in
addition to the read-only and static
memory.
Consequently, the default page size for the
dynamic
wvirtual
memory
is
6000 pages.
If you specify fewer than 6000 pages with the
/MEMORY qualifier, the system disregards the requested page
size
and
uses
the default page size.
You do not need the /MEMORY qualifier 1if
you intend to use no more than 6000 pages of dynamic memory.

To see how many pages of memory are available at any point
while
you
are
in
LISP,
wuse
the LISP ROOM function.
If you discover that you
need more memory, save your work by creating a suspended
system,
and
exit
LISP.
Then
reenter
LISP
with
the
/RESUME
and the /MEMORY
qualifiers.
Use the /MEMORY qualifier to specify a larger
number
of
pages
than you had previously specified.
For information on creating

a suspended system,

/RESUME
II,

see

Section

2.11.1;

qualifier and the ROOM function,

for

see

descriptions

Section 2.10.13

respectively.

Format

LISP/MEMORY=number-of-pages
or

LISP/COMPILE/MEMORY=number-of-pages

file-spec

the

and Part

USING VAX LISP

Example
$

LISP/MEMORY=15000

Welcome

VAX

LISP,

Version

V2.0

Lisp>
Mode
Interactive

2.10.10
The

Compile

Resume

/[NO]JOPTIMIZE

/OPTIMIZE

your

qualifier

program

lets

according

SPEED

(execution

SPACE

(space

SAFETY

you

optimize

the

following

speed

occupied

(run-time

of
by

error

the
the

the

results

compilation

qualities:

code)
code)

checking

the

code)

@ COMPILATION_SPEED (speed of the cdmpilation process)
You

can

optimize

quality.
value

the

That
means

other

your

program

value

must

the

quality

qualities;

priority

relationship

specify

the

/OPTIMIZE

value

this
The

suppress

has

the

setting

integer

the

lowest

wvalue

the

/OPTIMIZE

compiler,

qualifier,

other

VAX

LISP:

The

qualifier
does

LISP

priority

the

priority

means

the

optimization,

for

When

the

each

take

use

/NOOPTIMIZE

The
to

highest

vyou

qualities
the

each

relationship

quality has

qualities.

the

value

range

the

not

default
form

qualifier.
and

other

qualifier.

/COMPILE

meaningful

The

nothing

facility.

Language

for

only

/OPTIMIZE
the

See

interpreter,

Chapter

information

qualifier

the

specified

affects

Appendix

declarations.
Format

2-20

file-spec

the

any

debugger,

specifying

LISP/COMPILE/OPTIMIZE=(quality:value[,...])

with

only
and

COMMON

optimization

USING VAX LISP

Example

LISP/COMPILE/OPTIMIZE=(SPEED:3,SAFETY:2)

MYPROG.LSP

LISP/COMPILE/QPTEMEZEmSPEED:3

MYPROG.LSP

Mode

Compile

2.10.11

/[NOJOUTPUT_FILE

The /OUTPUT_FILE qualifier is meaningful only when
it
1is
specified
with
the
/COMPILE
qualifier.
The /OUTPUT_FILE qualifier tells the
compiler to write the compiled
code
to
a
specific
file.
If
vyou
specify
the
/OUTPUT_FILE qualifier with a file name, the LISP system
puts the compiled code in a file with that specified
name.
Use
the
/OUTPUT_FILE
qualifier
only
when you want to change the name of the
compiled file so that the source
file
and
the
compiled
file
have
different

names.

The /OUTPUT_FILE qualifier does not specify a
compiled
file.
See
the
/LIST
qualifier
explanation of

listing

1listing
(Section

file,
only
a
2.10.7) for an

file.

If this qualifier is not specified, the compiler produces a
the same name as the source file and a type of FAS.

file

with

The /NOOUTPUT_FILE qualifier prevents compiled code from being written
to
a
file.
If
you
want only to check a file for errors, use this
qualifier with the /COMPILE qualifier.
Format

LISP/COMPILE/OUTPUT_FILE[=file-spec]

file-spec

Example

LISP/COMPILE/OUTPUT_FILE=TEST.FAS

FACTORIAL.LSP

Format

LISP/COMPILE/NOOUTPUT_FILE file-spec
Example

LISP/COMPILE/NOOUTPUT_FILE MYPROG.LSP

2-21

USING VAX LISP

Mode

Compile

2.10.12
The

/REMOVE

/INSTALL

qualifier

qualifier.

outdated

code

need

SYSGBL

the

section)

when

deletes
You

you

add

(system

privileges

use
pages)

/REMOVE

sections

the

new version

global

use

global

can

installed

/REMOVE
of

and

LISP

the

because

qualifier

PRMGBL

the

by
to

the

remove

system.

You

(permanent

global

removes

key

1installed

and

system

resources.

NOTE
If

new version

you
want
file), be
with

the

of VAX

LISP

to remove the old
sure to specify an
/REMOVE

has

been

suspended system (the SUS
explicit
version
number

qualifier.

Format

LISP/REMOVE=suspended-system-spec
Example

S LISP/REMOVE=LISPSSYSTEM:LISPSUS.SUS;1
Mode
Remove

2.10.13
The

/RESUME

suspension
systems.

qualifier

resumes

suspended

occurred.

See

Section

The /RESUME

and

the /INITIALIZE

together.
Format

LISP/RESUME=file-spec

2.11

for

LISP

system

an explanation
qualifiers

where

cannot

the

suspended
be

wused

USING VAX LISP

Example
S

LISP/RESUME=MYPROG.SUS

Lisp>

Mode
Resume

2.10.14

/[NO]JVERBOSE

1listing
the
The /VERBOSE qualifier lists on the output device and in
initialization
an
in
loaded
or
defined
functions
the
of
file the names
The
file, and the names of functions in a file as they are compiled.

/VERBOSE

qualifier

applies

only

files

loaded with /INITIALIZE

qualifier or compiled with the /COMPILE qualifier.

The /NOVERBOSE qualifier (the default) prevents the names of functions
/COMPILE qualifier or loaded with the /INITIALIZE
the
compiled with
qualifier from being listed in a file or at the terminal.
Format

LISP/VERBOSE/INITIALIZE=file-spec
or

LISP/COMPILE/VERBOSE file-spec
Examples

S LISP/VERBOSE/INITIALIZE=MYINIT.LSP

t-'“

Welcome to VAX LISP,

Version V2.0

Loading contents of file DBAl:[JONES]MYINIT.LSP;1
FACTORIAL

FACTORS-0OF

Finished loading DBAl:[JONES]MYINIT.LSP;1

1sp>

1loaded
FACTORIAL and FACTORS-OF are functions that are
file.
the LISP system from Jones’s initialization
$ LISP/VERBOSE/COMPILE MYPROG.LSP
Starting compi

ation of
8

file DBAl1:[JONES]MYPROG.LSP;1
o

b ¥a% %i

BERF
T
Y

into

USING VAX LISP

MULT

compiled.

SUB

compiled.

DIV

compiled.

Finished
0

compilation

Errors,

file

DBAl:[JONES]MYPROG.LSP;1

Warnings

S
MULT,

SUB,

and

MYPROG.LSP.

DIV
The

are

functions

compiled

written

the

file,

Interactive

Compile

compiled

definitions

1in

these

the

file,

functions

are

MYPROG.FAS.

Mode

2.10.15
The

/[NOJWARNINGS

/WARNINGS qualifier specifies that the LISP system is
to
produce
messages.
Warning messages are the default when you use the

warning

/COMPILE

qualifier.

warning

message

indicates

likely

that

the

something

that

to be wrong.

a file is
variable

being

wvalue

the

compiled and
the
NIL
(the
default),

LISP

system

1If warnings
of
the
compilation

are

has

*BREAK-ON-WARNINGS%*
continues.
But, 1if

errors are signaled, compilation of the expression causing
is not continued though the rest of the file is compiled.
4 for more information on the differences between warnings
The

/NOWARNINGS

The

following

displays
$

for

qualifier

example
the

TEST

LISP/COMPILE

Warning

TEST

suppresses

warning

a warning message

function defined

the

Section

message
2.9.3.

TEST

earlier

called with

args,

wants

Format

LISP/COMPILE/NOWARNINGS

file-spec

Example

LISP/COMPILE/NOWARNINGS

MYPROG.LSP

the
error
See Chapter
and errors.

messages.

TEST.LSP

detected

signaled while

at most

the

compiler

USING VAX LISP

Mode

Compile

2.11

USING SUSPENDED SYSTEMS

A suspended system is a binary file that is a copy of the LISP

memory

in use during an interactive LISP session up to the point at which you
to
The purpose of a suspended system is
create the suspended system.
do
to
want
might
You
session.
LISP
interactive
an
of
state
the
save
this if your work is incomplete.
By resuming LISP
from a
suspended
system,
you
can
continue
your work
from
the
point at which you
stopped.

Creating a Suspended System

2.11.1

The VAX LISP SUSPEND function puts in a file the LISP memory
1in
use
LISP session, enabling you to resume the same
interactive
an
during
the
The SUSPEND function does not stop
LISP session at a later time.
after
session; you can continue to use the LISP session
LISP
current
The
file.
into a
copy of memory
the SUSPEND function has put a
function also automatically invokes a garbage collection of
SUSPEND
garbage
information on
for
7
Chapter
See
dynamic memory space.
collections.

of
In the following example, the file FILEX.SUS is created and a copy
can
name
file
The
file.
that
the memory in a LISP session is put into
See Chapter 7 and COMMON LISP: The
be a string, symbol, or pathname.
Language for a description of pathnames.
Lisp>

:
;
;
;

(SUSPEND

Starting
Finished
Starting
Finished

"FILEX.SUS")

garbage
garbage
garbage
garbage

collection
collection
collection
collection

due
due
due
due

to
to
to
to

GC function.
GC function.
SUSPEND function.
SUSPEND function.

NIL

Lisp>

interactive
to your
returns
After your file is created, the system
Your
You can exit LISP when you see the LISP prompt.
session.
LISP
suspended system file is placed either in your default directory or in
The file 1is
the directory you specified in the file specification.
usable only in an interactive LISP session.

Editor
SUSPEND function,
the
Editor before wusing
If you use the
resumed
the
in
buffers that are associated with files are deleted
Consequently, if you want to save any material in a buffer,
system.
a description of the VAX LISP
For
file.
in a
put that material
2-25

USING VAX LISP

Editor,
Part

Chapter

Resuming

resume

qualifier
Program

For

description

suspended

and

the

execution

function.
qualifier.

After

creates

execution

system,

name

continues

SUSPEND

See

use

the

file

from

the

Section

suspended

continues

2.10.13

the

LISP

function,

the

call

SUSPEND.

However,

when

using

the

/RESUME

qualifier,

the

program

execution

1is

can

use

resuming

the

action

necessary.

See

description

the

effects

return

the

result

vyou

see

function

system.

resumes

SUSPEND

the

returns

function

/RESUME

system.

<called

exactly

execution

the

/RESUME

explanation

function

SUSPEND

value

SUSPEND

suspending

for

the

suspended

which

SUSPEND

Therefore,

with

the

environment

result

take

SUSPEND

command

containing
point

system,

with

LISP

before

1if

the

a Suspended System

/RESUME

and

I1I.

2.11.2
To

see

NIL

it was
as

returns

determine

qualifier,

Part

the

for

and

CHAPTER 3

USING THE VAX LISP EDITOR

This chapter describes how to use the VAX LISP
objects

and

files

containing

information

you

learn

about

the

1in

this

not

covered

Programming

need

to edit

LISP

code.

LISP

and

wish

Editor,

chapter,

This

general
to

refer

Editor
chapter
text.

customize
to

the

edit

provides
If

VAX

LISP

all

the

vyou

want

ways

that

are

LISP/VMS

Editor

Guide.

NOTE
This

chapter

you

LISP

form

is,

Editor’s

the

its

minor

wish

see

3.1

it,

how

the

LISP

Section

3.3

file

Section

3.4

using

Section

style

"EMACS"

style

this

the
or

Editor

LISP

"EDT

LISP".

files.

1its
That

Emulation"

1If

you

are

©provided

and

using
with

or
the

manual.

follows:

work

the

Editor

into

explains

how

editing

LISP

shows

how you

available

among

your

get

using

objects

"VAX

introduces

for

switch

are

and

out

edit

explains
it,

and

how
how

start

return

interpreter.
3.2

Section

1is

Appendix

features

major

the

chapter
.is divided

Section

edit

style

wuse

Editor,

This

assumes

default

the

3.5

can

editing

objects

explains

the

needs.

for

objects

how

text,

and

have

1including

special

code.

than

one

time

files

you

are

recover

from

one

and

LISP

object

explains

how

editing.
problems

while

vyou

suit

Editor.

shows

how you

can

customize

the

Editor

USING THE VAX LISP EDITOR

Each major section ends with a table of the commands and key
that are

bindings

section.

covered in that

on a
Editor
the
When you use
Note to VAXstation users:
is different, and you can use
behavior
screen
VAXstation,
Throughout
the pointer to perform some editing operations.
appropriate
at
noted
are
differences
these
chapter,
this
and use
Section 3.6 summarizes Editor behavior
locations.
on

3.1

a VAXstation.

INTRODUCTION TO THE EDITOR

The VAX LISP Editor
capabilities
some
For example,
code.
It can
for you.

It 1includes
is a general-purpose text editor.
that make it particularly useful for editing LISP
the Editor matches parentheses and indents lines
also evaluate a LISP function definition or symbol

value that you are editing.

You use the Editor directly from the LISP environment.
a

part

LISP

and

cannot

be used outside of LISP.

The Editor

1is

You can move

When you go from
freely between the Editor and the LISP interpreter.
the state of your
preserves
Editor
the
,
interpreter
the
to
the Editor

work until you return to

it.

The Editor is designed to work only on a video terminal or a
It maintains the screen at all times to reflect the
VAXstation.
contents of the LISP object or file. When you insert text 1in the
middle of 1lines or between lines, the Editor immediately adjusts the
screen to show your modification.

Many commands are
You communicate with the Editor by using commands.
commands, SO
useful
most
the
invoke
sequences
key
Keys or
available.
keypad
numeric
the
on
Keys
names.
command
you do not have to type the
making
editor,
keypad
EDT
the
emulate
invoke a set of commands that
the VAX LISP Editor similar to EDT.

The Editor allows you to have more than one LISP object or file
available for editing at one time. Each object or file resides in 1its
own buffer. Commands allow you to switch from one buffer to another,
and you can view more than one buffer at a time, or more than one
place

in the

same buffer.

The rest of this section describes the basics of wusing the Editor.
Section 3.1.6 <contains a table of the commands presented in this
section.

3-2

USING THE VAX LISP EDITOR

3.1.1

Editing

editing

and

you

LISP

code.

cycle

starts

want

The

cycle

start

argument

the

You

you

Editor

you

modified

You

are

use

the

interpreter

file

containing

edit

LISP

object,

replace

command

file,
to

supplying

file

specification

object

are

file.

invoked

Most

control

keypad.
you

use

function

you use

the

pause

the

modify.
the

function,

commands

numeric

out

command

definition

command

make
value.

write

the

new

vyou

the

disk.
the

Editor,

returning

interpreter,

you

can

the

object

modifications

are

required,

without

Resuming

state

the

that

can

wvalue

now

use

the

you

can

new

load

function

the

new or

file.

further

cycle

create
to

the

file

LISP

function

This

LISP

interpreter.

modified

VAX

object

version

editing

definition

the

Editor

editing

are

edited

the

LISP

calling
of

commands

you

wish

keys

using

follows:

name

used

are

modify

Editor

LISP

characters

your

you

the

frequently

the

file

use

when

create

You

of
®

Cycle

arguments

Editor

existed

occur

this

when

you

many

times

to
way

brings

paused
and

vyou

return

you

the
as

can

vyou

use

back

the

Editor.

the

Editor

Editor.

many

objects

files

time

vyou

needed.

3.1.2

Invoking the

The

function

invoke
an

argument

file
To

the

edit

symbol

can

this

the

VAX

LISP

session,

function.

The

editor.
you

argument

The
should

first
be

sure

identifies

the

supply

object

edit.

object,

the

following

give

the

object’s

form

edits

symbol

the

function

argument.

definition

For
of

the

SHIP-ACCESSOR:

(ED

also

definition,
in

the

during

LISP

Lisp>
You

invokes

Editor

you want

example,

Editor

’'SHIP-ACCESSOR)

edit

the

by using

example:

value

the

:TYPE

LISP

symbol,

keyword with

rather

the

than

its

function,

function

shown

USING THE VAX LISP EDITOR

Lisp>

(ED

’'SHIP-LIST

:TYPE

: VALUE)

To edit a file, give the file specification as the argument to the
function.

Lisp>

For

example:

(ED

"CLOCK.LSP")

Then,
screen clears.
the
The first time you use the ED function,
this:
like
looks
screen
the
appear,
messages
n
initializatio
some
after

{ Mew Function)
On a VAXstation: A new window appears; the window contains
The window is taller than a standard
the Editor display.
to
identical
24-1line screen, but otherwise the display 1is
that seen on a video terminal.

Note the following points about this screen display:

The label strip near the bottom of the screen tells

you

that

you

are editing the function definition of SHIP-ACCESSOR, you

this

point.

are using the major style called "EDT Emulation" and the minor
style called "VAX LISP", and your current movement direction
The movement direction is useful to you while you
is forward.
You need not concern yourself with styles at
are editing.

USING THE VAX

The

information

that

you

are

information
Editor

The

area

cursor

The

After you have used
return

your

editing.

simply

call

Lisp>
You
you

can

you
the

the

short

screen

definition.

informational

tells
1In

vyou

general,

messages

about

errors.

shows

Editor,

the

where

you

upper
new

want

return

without

1left

text

can pause

interpreter.

old

for
the

argument

Editor.

symbol

The

use

function

LISP

function

supply
the

the

available

the

bottom

new

positioned

you

the
a

EDITOR

Later,
the

corner

will

(see
you

the

inserted.

Section

3.1.5)

may want

resume

state

vyou

left,

Editor

arguments:

(ED)

also

Editor.

and

cursor

the

resume

replace

see

contains

operations

screen.

and

area

editing

LISP

file

symbol

editing.
ED

following

The

See

function
screen

LISP

you

file

another
symbol

were

made

Section
without

3.3

LISP
or

editing

for

arguments

Melcome to the YAY LISP Editor
Tupe PF2 (HELP) for Help

you

when

inactive,

display:

3-5

symbol

file

specify

you

although

when

does

not

paused

the

still

Editor,

you

details.
to

start

the

USING THE VAX LISP EDITOR

You
This means that the Editor is running but has nothing to edit.
you
Or,
CTRL/Z.
CTRL/X
typing
by
interpreter
to the LISP
return
can

can type CTRL/Z and enter an Editor command by name, as

described

3.1.3.

Section

NOTE

the BIND-KEYBOARD-FUNCTION function to
You can use
character (such as CTRL/E) to the ED
control
bind a
Editor
function, allowing you to invoke or resume the
If
character.
control
the
asynchronously by typing
1
than
greater
you do this, do not specify a value
a
Using
with BIND-KEYBOARD-FUNCTION’s :LEVEL keyword.
Editor’s
the
value greater than 1 may disrupt
x

operation.

Interacting with the Editor

3.1.3

You interact with

the

Editor

through

commands.

Commands

the

following:

change from
pause 1it,
Control the operation of the Editor:
and so
stics,
characteri
operating
set
another,
to
buffer
one
on.

Modify the LISP object or file that you are editing.

To enter a command to the Editor, you can type its name or type a key
or sequence of keys that causes the command to be executed. The two

ways are

equivalent.

To type a command by name, first type CTRL/Z, which
prompt to appear just below the label strip:

Function iHIP—fiECESSDR Forward

causes

EDT Emulation {"VAX LISP")

Enter command name

While vyou
Type the name of the command, then press RETURN.
1in
described
keys
editing
the
of
any
use
can
vyou
are typing,
name
full
the
supply
must
You
input.
your
Section 3.2 to edit
once you have typed part of the
(However,
of the command.
command, the Editor can complete the name for you or display a
see Section
l1ist of command names that start that way;
3.1.3.2.)

If a key or key sequence is bound to the command, you can
Most
enter the command by typing that key or key sequence.
3-6

USING THE VAX LISP

frequently

them.
which
For

example,

type

keys
to

"Pause

RETURN.

Or,

Editor"
to

the

you

type

command,

the

LISP

ready

Commands

are

cause

the

Editor

that

you

decide

CTRL/C

which

can

type

prompt,

bound

CTRL/Z,

and

press

the

pause

"Pause

and

return

cancel
stops

other

not

command

the

current

want

type

the

middle

command

and

its

makes

commands.

throughout

this chapter.
Appendix C
contains
available commands and their key bindings

the

HELP

labeled

window

"Help"

and

remove

between
the

press

the

example,
the

text

Editor

obtain

specified
example,

have.

disappear

also

prompt

The

keyboard)

any

time

get

how

this

<called

the

pressed

"VAX

how

remove

help

text

Editor
CTRL/Z

is
--

explains

from

LISP

to
from

from

the

when

vyou

have

and

"Apropos"

These

commands

"Apropos"

names.

The

command

lists

whose

screen.
type

describes

help

text.

entered

RETURN.

objects.

objects

a
prompt
-displays help

and

"Describe"

same

the

this

the

General

screen,

prompt

through

the

help

around

displaying
the Editor

the

help.
or

Editor

move

window

scroll

screen

Editor
Editor

display:

help

CTRL/V

and

the

command

the

keypad

Press

using

following

numeric

the
typed

"Apropos"

Editor

the

window

and

instructions

have

provides

functions

description

object.

kinds

PF2

key while

you

information

LISP

LK201

Typically,

the

provides different

(either

containing

HELP

you

will

response

the

windows

after

prompt.

options

Editor

key

contains

window

CTRL/R.

you

The

situation.

CTRL/X

the

you

command

methods

the

appears.

Help

Help"

the

CTRL/C.

press

current

The

the

CTRL/Z,

then

introduced

your

The

command,

to
see

commands.

CTRL/X

decide

Getting

can

key

the

but

you

descriptions

3.1.3.1

Editor"

response

type

key sequences
bound
Bindings" command to

any).

You

for

bound

"Pause

Both

CTRL/Z

type

Editor

keys or
"List Key

interpreter.

the

can

have

the

currently

enter

execution,

(1f

are

use

Editor"
you

commands

<can

command.

you

short

used

You

EDITOR

command

(by

all

names
for

"Describe"
default)

Editor

contain
the

commands
are

command
or

certain

Editor

string.

"file"

displays

other

commands

string

similar

other
For

produces

USING THE VAX LISP EDITOR

Edit File
Insert File
fiead File
iew File

eite Named Filell

Function SHIP-ACCESSOR Forward

EDT Emulation ¢"VaX LISP")

You can also obtain descriptions of LISP symbols through the Editor
when vyou are editing LISP code. The CTRL/? key invokes the LISP
DESCRIBE function on the word at the current cursor position.
On a VAXstation:

function

You can

moving

also

invoke

the

LISP

DESCRIBE

the pointer cursor to the symbol to be

described and pressing the right pointer button.

You can use the cursor movement techniques described in Section 3.2.3
to move around in the window containing help text. When you are done,
use the key sequence CTRL/X CTRL/R to remove this window and return to
editing.

3.1.3.2 Input Completion and Alternatives - The Editor can help vyou
The first way 1s input
enter responses to prompts 1in two ways.
you are typing a
while
time
completion. If you type CTRL/SPACE at any
your input
complete
to
response to a prompt, the Editor will attempt
can, and
it
as
for you. The Editor will complete as much of the input
display the status of the completion.

3-8

USING THE VAX LISP EDITOR
For

example,

1f,

string

"pau"

command

name

You

can

hand,
will

then

press

the

able

with

keypad.

The

list

have

used

PF2.

"New

Li".

make

the

list

you

command
and

use

the

and

enter

file
see

type

back

the

can

Li"

than

other

Editor
and

one

can

far

will

command

and

obtain

the

Li",

you

enter

numeric

displays

example,

commands

input

this

not

file

LISP

can

when

you

type

PF1

beginning with

enough

completion

(CTRL/SPACE)

restricted

type

can

template.

example,

but

".LSP"

are

your

then

For

command,

edit

the

file

distinguish
fills

unsure

of
then

this

your

which

point,

current

of
point

command
and

file

specifications

File"

files

You
name

"New

PF2

"New
the

you want,
use

are

out

"Edit

all

beginning

file

CTRL/SPACE

as
of

particular

the

"LSP".
the

You

list

far

list

then

existing

name.
a

as
a

command

and

fill

matching

edit

the

name.

get

alternatives

them

files

for

enough

display

unambiguous,

the

you

choose

1If,

PFl
For

PF2,

Typing

prompt,

typed

CTRL/Z

file

typing
way.

PF1

the

that

you

cursor

information

have

can

complete.

you

will

Li".

alternatives

completion

the

input

starting

also

type

far

what

You

wish

You

because

type

complete

CTRL/SPACE,

commands

Editor

all

only

vyou

will

command.

ambiguous,

the

examines

completion
can

"New

input

that

the

followed

Editor

the

input

You

execute

the

prompt,

the

Editor

input

complete

entering

name"

inform you

"new"

input

available

all

The

Input

string

when

and

complete

the

command

CTRL/SPACE,

RETURN

the

string

that

point

"Enter

Editor"

type

any

"Pause

now

report

list

the

you

starts
At

followed

input

from

the

name.

prompts

followed

other

having

by moving

rest

assume

directory

specification
in

names.

obtain

the

and

typing

file

names.

the

file

specification.

3.1.3.3

Errors

Editor

displays

error

messages

problem.
sequence

you

error

asks

the

short

Problems
error

are

usually

the

short

major
which

you wish
and

your

screen

messages

Section

these

attempt
of

the

3.4

allow

vyou

to
the

the

error,
area.

the
These

correct
CTRL/X

the

key

error.

encounters

Editor

your

contains

minor

sufficient,

the

information

Editor

save

error,

make

the

recover,

you
in

not

information

cannot

severity

work.
from

sufficient

error,
it

message

display more

from

recover

MAIL

may

make

nature

all

and Other

work.

Editor

reports

may

-internal

the

error

Depending
not

and

the

able

save

how

information

problems.

should

become

arriving

disrupted

use

the

for

CTRL/W

3-9

some
key

reason

refresh

for
the

example,
screen.

USING THE VAX LISP EDITOR

Moving Work Back to LISP

3.1.4

There are several ways to move your work back to the LISP environment.
Use one of the methods described in this section if you want your work
to be

available

LISP.

Two commands, “Write Current Buffer"
place your work back

in a

symbol or

and

file:

"Write

Modified

Buffers",

If you were editing the function definition or the value of

new function definition or
the
cause
commands
the
symbol,
value to replace the existing function definition or value.

If you were editing a file,
of

the

the commands write a

new

version

file.

The difference between the two commands is that "Write Current Buffer”
that is, the buffer whose window
current buffer;
the
only
affects
"Write Modified
command.
contained the cursor when you entered the
Buffers" affects any buffer you have worked on since the last time the
buffer was written.

Neither of these commands pauses the Editor or alters the contents of
After using either command, you can immediately return
buffers.
your
to editing, or you can use the "Pause Editor" command to return to the
editing the function definition or
you were
If
1interpreter.
LISP
value of a symbol, the new function definition or value is immediately
If you were editing a file, you will have
to you in LISP.
available
to load the file before you can use the modifications you made.
by
environment
LISP
the
You can also move a function definition to
CTRL/X
type
then
definition,
function
the
in
cursor
the
positioning
function
the
causes
procedure
This
CTRL/X CTRL/A.
CTRL/SPACE
return
now
can
You
evaluated.
containing the cursor to be
definition
definition.
function
modified
the
to the LISP interpreter and use
you must eventually include the definition in a file, or the
However,
1s
This procdure
LISP.
modification will be lost when you exit

particularly useful when you are editing a file containing a number of
definitions,

and you want to modify only one of them.

If you are editing a function definition and you want to save it in a
This command prompts for
"Write Named File" command.
the
use
file,
buffer to the file.
current
the name of a file, and then writes the

3.1.5

Returning to the LISP Interpreter

you
files,
or
When you have finished creating or modifying objects
you
whatever
test
to
interpreter
LISP
the
generally want to return to
LISP
the
to
control
returns
The "Pause Editor" command
have written.
key seguence CTRL/X CTRL/Z invokes "Pause Editor".
the
interpreter;
3-10

USING THE VAX LISP EDITOR

The "Pause Editor" command saves the state of
your
editing
session.
If
you
return
to
the
session
by
calling the ED function without
arguments,

the

Editor will

as you

left

1it.

The "Pause Editor" command does not cause any of your
buffers
to
be
written.
Before
pausing the Editor, you must use one of the methods
LISP
the
in
available
described in Section 3.1.4 to make your work
environment.
Also, if you pause the Editor without first writing your
modified files and then exit LISP, the work you did on your files will
be
lost.
(See
Section
3.4 for information on partially recovering
from

this

situation.)

On a VAXstation:
returns

the

When you

pause

the

Editor,

the

cursor

LISP window.

In contrast to the "Pause Editor" command, the
"Exit"
command
shuts
down the Editor.
If you use the "Exit" command, the Editor warns that
If you type Y,
changes will be lost and asks if you want to continue.
allows you to save modified buffers on a buffer-by-buffer
Editor
the
basis.

3.1.6

Summary of Commands

Table 3-1 provides a summary of the commands presented in this section
These commands are
the keys (if any) that invoke those commands.
and
Subsequent
Editor.
the
of
operation
the
controlling
for
useful
useful in
are
that
commands
of
tables
contain
sections in this chapter
all
of
table
alphabetic
an
provides
C
Appendix
specific situations.
the

commands.

Table 3-1:

General-Purpose Commands and Key Bindings

Name

Binding*

Description

Execute Named
Command

CTRL/Z
or
keypad PF1 7

a
of
the name
for
Prompts
the
type
execute;
to
command
name of the command, followed by
RETURN

or
DO*

List Key
Bindings

None

Pause Editor

CTRL/X CTRL/Z

a list of keys and key
Displays
to
currently bound
sequences
commands

Pauses
state,

the

Editor,

and returns to

saving 1its
the

LISP

interpreter

* Keys marked with an asterisk (*) available only on LK201 keyboard
3-11

USING THE VAX LISP EDITOR

Table

3-1

(cont.)

Name

Binding#*

Description

Write Current

None

Replaces

Buffer

buffer,
of

Write

function
with the

Modified

None

the

writes

the

modified

Select
Form

Outermost

CTRL/X

Evaluate

LISP

CTRL/X

CTRL/A

new

version

LISP

all

the

object

new

version

Evaluates
by

Region

value
current

contents

Highlights
the
form containing

CTRL/SPACE

buffers

corresponding
file

symbol’s
or
the

file

Writes

Buffers

LISP

definition
contents of

LISP

"Select

other

outermost
cursor

code

highlighted

Outermost

means,

available

LISP

the

Form"

making

the

result

the

LISP

interpreter

Write

Named

File

Window

None

CTRL/X

CTRL/N

Prompts

for

writes

the

that

file

Makes

the

file

current

name,

current

window

window;

moving

1into

then

buffer

the

useful
out

for

help

window
Remove

Current

CTRL/X

Removes

CTRL/R

the

Window

rid
Remove

OQOther

the

current

screen;

wuseful

windows

current window

Windows
keypad

Help

Displays

PF2

other

from

the

window with

your

current

CTRL/V

When

used

(only while

prompt,

for

from

getting

help window

Removes

None

window

than

the

screen
help

situation

HELP*

Prompt

Help

Scroll

Window

responding

containing

prompt)

3-12

while

responding

causes

the

help

text

window

scroll

USING THE VAX LISP EDITOR

Table

3-1

(cont.)

Name

Binding*

Prompt

Show

Keypad

Alternatives

Description

PF1

PF2

When

(only while
responding

context

so
Complete

CTRL/SPACE

String

used

input

prompt)

None

while

CTRL/?

Help

Invokes

Editor

CTRL/X

error

Redisplay Screen

3.2

CTRL/W

EDITING

OPERATIONS

This

section

describes

The

operations

is,

while

deal

This

editing

with

section

are

Section
many

one

multiple

LISP

3.2.1

operations
you

object

can

and

perform

the

how
in

Section

have

object

Editor

objects

string

you

LISP

the

supply

DESCRIBE

word

the

last

Editor

perform

then,

the

numeric

keypad

screen

single

buffer;

that

3.3

explains

how

follows:

describes

you use

perform

operations.

describes

how

insert

Section

3.2.3

explains

ways

move

3.2.4

shows

it.

you

occurred

file.

3.2.2

Section

what

Editor

other

the

help

that

Section

moving

the

available

location

buffers.

divided

editing

that

complete

list

the

Refreshes

editing

those

the
typed

description

for

Displays

Error

on
have

the

other

function

cursor

and

commands

Word

input

responding

containing
Describe

far

Displays

you

attempts

Displays

None

list

based

command
Apropos

what

alternatives

typed
Describe

and

prompt,
to

responding

far

When

(only while
responding

while

displays

alternatives

prompt)

Prompt

used

prompt,

how you

text.

the

can modify

cursor.

text

by deleting

and

USING THE VAX LISP EDITOR

Section
than

3.2.5

explains

how to

cause

an operation

occur more

once.

Section

3.2.6

summarizes

the

commands

described

1in

this

section.

3.2.1
The

Keypad

Editor incorporates a
to behave like the EDT

are bound to
keypad
keys

the
as

set of commands and key bindings that
text editor.
The keys on the numeric

EDT-like
1if
you

commands.
For the most part,
were
wusing
EDT,
although

you
there

cause
keypad

can
are

wuse
some

differences.

Figure
on it.
corner

3-1 illustrates the numeric keypad.
Each key has
three
items
Whatever appears on the actual key is shown in the lower right
of each key in Figure 3-1.
The meaning of the two names is
as

follows:

The top name
key

specifies

the action that occurs

if you press the

itself.

The bottom name specifies the action that occurs if you
press
and release the PFl1 key (sometimes called the GOLD key) before
pressing

the

key.

For example, if you press the 0 key by itself, the
Editor
moves
the
cursor
to
the
beginning of a line.
If you first press PFl and then
the 0 key, the Editor opens a new line at the cursor location.
For the rest of this section, keys will be referred to by the names of
the
actions
the
keys
1invoke.
For example, the 0 key by 1itself is
called the BEGINNING OF LINE key, while the sequence PFl1 0
1is
called
the

OPEN

3.2.2
This

LINE

Inserting and Formatting Text
section describes ways you can create new text.

Hocnw1hac

type

key.

and

wnnf1np

text
T

1ncpfif1nn

£ B

format LISP code,

nongraphic

characters

and

the

Sectio 3.

On
-

2.3

3.2.2.2

Section

3.2.2.1

describes
L

descrlbes

how

how
-

v
¥

insert

text.

3.2.2.1
1Inserting Ordinary Text - To insert text, simply
type.
All
the
keys corresponding to printing characters cause that character to
appear preceding the character at the cursor location.
1If the
cursor
is in the middle of a line, the cursor and the characters to its right
will

be displaced

further

the

right
3-14

to make

room.

USING THE VAX LISP EDITOR

GOLD
pREF

(

HELP
PF

8 PAGE
COMMAND

monecr [ oeLne|

MIALTERNATVES]]

FND

PF2

|| UNDELLNE

PRI

PRy

e [ oeLworo|

SCREEN

REPLACE

|| UNDEL WORD

FORWARD

| BACKWARD ||

BOTTOM

EoL

WORD

CHNG CASE

cHaR

" SELECT

EGINNING OF LINE

OPEN LINE

UNDEL CHAR

| SPECINSERT|

DELEOL

—

DEL CHAR

RESET

)

Note: The letters, numbers, and characters in the lower right corners

of the keys are what actually appear on the keys of a VT100
keypad.

Figure 3-1:

Numeric Keypad

You can start a new line by typing RETURN.
If you type
RETURN while
the
cursor
is
at
the
end of a line, you get a blank line with the
cursor at the beginning.
If the cursor is in the middle
of
a
line,
the

line

is broken in the middle.

The OPEN LINE key also starts a new line, but leaves the cursor at the
end of the old line instead of the beginning of the new line.

3.2.2.2
Typing and Formatting LISP Code - The Editor includes several
commands that help you to enter LISP code.
Whenever you are editing a
LISP object (either its
function
definition
or
wvalue)
or
a
file
containing LISP code, the following key bindings are in effect:
e

If you type a right parenthesis,
the
Editor
highlights
the
corresponding
left
parenthesis
for
a
moment.
If
the
line
‘corresponding left parenthesis is not on the screen, the
that contains it is displayed in the information area with the
parenthesis highlighted.

form by
outermost
the
closes
]
ESCAPE
sequence
The key
inserting
the
correct
number
of
parentheses at the cursor
position.

(Typing CTRL/[

produces an ESCAPE.)

1t
but
to RETURN,
similar
1is
The "New LISP Line" command
indents
the
new
line properly with respect to the preceding

3-15

USING THE VAX LISP EDITOR

®@

line.

CTRL/J

VT100

terminal,

The

TAB

key

cursor,

The

CTRL/X

Use

indents

key

form

that

;

When
to

the

1line

sequence

and

the

CTRL/X

;

(On

CTRL/J.)

contains

the

code.

all

the

lines

the

end

the

comment

1If

the

LISP

cursor.

space.

moves

command.

results

currently

LISP

comment

CTRL/X

Line"

key

that

the

LISP

another

LISP

indents

contains

cursor

semicolon

"New

LINEFEED

preceding

type

line,

the

start

you

move

the

TAB

CTRL/X

code.
spaces

bound

pressing

relative

outermost
®

1line

inserts

column,

then

there

cursor

Editor
is

already

the

enough
inserts

comment

beginning

the

comment.

VAXstation:

pointer

Pressing

cursor

character

the

right

positioned

highlights

the

pointer

button

when

the

<close-parenthesis

matching

open-parenthesis

character.

3.2.2.3

Inserting

characters
- #\"
X

character

character.
cases,

you

without

for

into

typing

Editor

can

use

the

Editor

Characters

your

text.

CTRL/X

provides

the

take

You

cannot

example,

you

the

two

around

ways

key

the

This

you would

For

because

CTRL/X \

will

interpretation.

example;

CTRL/X

The

sequence,

#\" X,

Nongraphic

directly

Editor

this

sequence.

would

some

insert

interprets

problem.

After

character

procedure

insert

cannot

you

1In

typing

type

and

handle

the

character

that

most
this

insert

case

type:

CTRL/X

echo

for

this

< XD
In

general,

the

Editor

representation
for

Some

characters

can

use

SPEC

INSERT,

character
key

then

the

display

the

cannot

SPEC(IAL)
you

inserts

must

key

supply

arqument

character

nongraphic

surrounded

generated
INSERT

first

prefix
the

for

character,

directly
to
the

insert

angle

from

the

such

decimal

the

keyboard.

characters.

ASCII

(see

Section

3.2.5).

the

cursor

location.

LISP

brackets.

wvalue

The

SPEC

You
To

use
the

INSERT

USING THE VAX

3.2.3
To

Moving the

insert

that

text

types.

the

Section

cursor.

within

summary

with

EDT,

FORWARD

in
can

here

should

some

sets

move

the

movements
and

how you

direction

the

current

The

keys

move

the

keypad

and

EDT.

1If

otherwise,

key

and

right,

way

right
while

line

~current

move

the

arrow
the

the

cursor

keys

the

and

can

on
be

the

current

either

direction
The

always

current

cursor
one

down

allow you

direction

forward

label

the

unit

The

BEGINNING

the

move

line

beginning

The

EOL

(End

following

with
in

the

one

arrow

keys

move

The

arrow

indicated

cursor

end

the

line
the

CTRL/H

moves

the

character
the

keys

keys.

cursor

the

current

Line)
(if

the

not

cursor

direction

key moves

the

current

the

cursor

line,

VT100,

pressing

LK201

keyboard,

WORD

direction
if

Each

direction.

The

the

left

down

depend

line

the

beginning

forward)

beginning

the

F12

the

key

direction

the

current

key

forward)

current

results
produces

key moves

1is
the

the

forward,
current

beginning

direction

the

beginning

backward.

3-17

1In

or
the

direction

current

the

CTRL/H.
same

the

current

finding

the

direction.

the

word,

the

end

(if

BACKSPACE

the

1line

regardless
the

direction

(if

CTRL/H.
)

word,

the

line:

LINE key moves

(if

backward).

The

and
bottom

regardless

backward).

backward.

forward,

strip

same,

the

column.

are

brief

direction.

move

arrow

direction.

keys

moves

move

cursor

you

direction.

simplest

various

started.

depends

backward.

cursor

arrow

can

identical

section;

you

other

keys,

get

current

For

Other

keypad

the

one

the

this

keys

window displays

left

how

direction

the

arrow

have

produce

describes

skip

The

you

keys

a way nearly

sets

current

go,

Keypad and Arrow Keys

current

key

the

you

produced
The

BACKWARD

3.2.3.2

cursor

contained

movement.

The

describes

the

action

3.2.3.1

Moving with

familiar

want

A number

code.

move

The

you

first.
Section

LISP

3.2.3.1

keys

Cursor

where

1location

LISP EDITOR

the

(On

the

action

current

previous
beginning

USING THE VAX LISP EDITOR

the

word,

the

WORD key passes over most LISP syntax characters,

and
characters,
such as parentheses, delimiters, single quote
only
EDT,
In
over.
passed
also
are
s
character
#\NEWLINE
semicolons.
spaces are passed over in finding the beginning of the next word.

The SCREEN key scrolls the text in the window. The text moves up if
the current direction is forward and down if the current direction 1is
The amount of text that scrolls 1is equal to about
backward.
two-thirds of the height of the window. The cursor moves only as much
as is necesary to stay in the window. This behavior also differs from
EDT.

The BOTTOM and TOP keys move the cursor to the end or the beginning of

whatever you are editing.

You can also move the cursor to a specified text 'string. The FIND key
prompts for a search string. You enter the string and terminate it
with RETURN; the Editor then finds the first occurrence of that string
(EDT allows you to terminate the search
'in the current direction.
string with FORWARD or BACKWARD; the VAX LISP editor requires that you
first set the current direction, then terminate the search string with
RETURN or ENTER.) The FIND NEXT key finds the next occurrence of
whatever string was last searched for.

3.2.3.2

Moving in LISP Code - Four bound commands allow you

move

key

The key sequence CTRL/X . is bound to the command
by LISP forms.
"Next LISP Form", and the key sequence CTRL/X , 1s bound to the
These commands move the cursor from
command "Previous LISP Form".
The key
es nesting level.
parenthes
current
the
form to form within
moves
Form")
t
Outermos
of
"End
command
the
sequence CTRL/X > (bound to
The
form.
LISP
t
outermos
next
or
the cursor to the end of the current
t
Outermos
of
ng
"Beginni
key sequence CTRL/X < (bound to the command
previous
or
current
Form") moves the cursor to the beginning of the
outermost LISP

form.

Four other commands allow you to move in lists.
sequences are bound to them.

They are:

default,

Backward Up List
Forward Up List
Beginning of List
End

List

See Appendix C for a brief description of these commands.

Section 3.5

explains how you can bind keys to these (and other) commands.

3.2.3.3 Moving with the Pointer (VAXstation Only) - You can move the
cursor by moving the pointer cursor to the desired spot in the text

and pressing the left mouse button.

3-18

USING THE VAX LISP EDITOR

3.2.4
In

Modifying Text

addition

inserting

deleting

1it,

moving

describes

ways

@
@

text,

1t,

modify

you

and

can

modify

substituting

existing

text

1it.

This

portions

section

text:

Section

3.2.4.1

describes

Section

3.2.4.2

shows

ways

how

delete

wundelete

text

you

text.
have

Jjust

place

deleted.

Section
by

3.2.4.4
its

describes

shows

3.2.4.6
into

text

wusing

delete

This

keypad

disappears

The

Editor

last

character,

the

how

Two

keys

the

LK201

DEL

CHAR

One

The

how

move

text

key

two

Editor

deletes
S

wee

deletes
If

you

(In

the

passes
single

the

LINEFEED

1is

modify

substitute

bound

and

word.

the

same

keys

one

The

DELETE

one

text

string

file

parts

F13

the

for

the

contents

these

key

(with

just

deletes

over

LISP

3-19

and

<X]

cursor.

The

you

are

using.

position

the

such

the

word,

parentheses,

Thus,

also

passes

DEL

over

WORD

and

line.
there

when

key

WORD

cursor

beginning

this;

Line".)

DEL

terminal

WORD
of

VT100,
the

areas

symbol

the

semicolons.

DEL

the

characters,

end

one

deleted.

cursor.

beginning

and

the

before

current

the

text,

another.

deleted
have

Text

immediately

you

the

syntax

keyboard.
not

that

the

using

LISP

areas

from

find

delete

main
1s

place

the

line

character

position

passes

way

from a

but

depending

LISP

code

three

characters,

CTRL/J

the

how

screen,

characters.

"New

describes

recover

character
LISP

text

and

character

over

cursor

keyboard,

characters

that

insert

from

the

word.

syntax

editing

from

words,

quote

and

the

word,

deletes

are

LK201

current

the

#\NEWLINE

EDT,

CTRL/J

key

deletes

the

delete

these

deletes

keys
of

keys

characters.

WORD

delimiters,
T

keyboard)

beginning

the

shows

them

delete

DEL

maintains

section

use

how

section

from

each
The

from place

work.

discarded.
for

text

commands

two ways

explains

your

Deleting Text

you

to move

case.

3.2.4.5

Section

3.2.4.1

how

1it.

another.

buffer

that

explains
pasting

changing

Section

and

Section

for

your

3.2.4.3

cutting

1is

the

current word.

editing

are

syntax

key does.

using

the

LISP,

and

that

however,

terminal

beginning

characters

key

with
the

#\NEWLINE

USING THE VAX LISP EDITOR

Three

keys

delete

lines or portions

lines:

The DEL LINE key deletes from the current cursor
position
to
the end of the current line, including the #\NEWLINE character
at the end of the line.
1If the cursor i1s
positioned
at
the
end
of
the
1line,
DEL
LINE
simply
deletes
the #\NEWLINE
character.

The DEL EOL (End-0Of-Line) key deletes from the current
cursor
position
to
the
end
of the current line, not including the
#\NEWLINE character at the end of the line.
1If the cursor
1is
positioned
at
the
end
of the line, DELETE LINE deletes the
next

line,

including

the

#\NEWLINE.

The CTRL/U key deletes from the current cursor position to the
beginning of the current line.
1If the cursor 1is positioned at
the beginning of the line, CTRL/U deletes the previous line.

3.2.4.2
Undeleting Text - Whenever you delete text, the
Editor
does
not
immediately discard it the text.
1Instead, the Editor temporarily
saves the text, allowing you to put it back if you
did
not
mean
to
delete it or to move it somewhere else.

The UNDEL(ETE)

The UNDEL(ETE) WORD key places the last word or
that was deleted at the cursor location.

word

portion

The UNDEL(ETE) LINE key places the last line or
that was deleted at the cursor location.

1line

portion

deleted at

the

CHAR key places the
cursor

location.

1last

character

that

was

Thus,
if you want to move text from one
place
to
another,
you
can
first
use
the
appropriate
key
to
delete the text in 1its original
location.
Then move the cursor to the text’s new location and use the
appropriate UNDEL key to place the text there.

Copying text -- putting it in a new location while leaving it
in
1its
original
location
-is
similar
to
moving
text, except that you
undelete it
in
its
original
1location
before
moving
to
the
new
location
You can undelete text as many times as you want.
wdes Uef Tt Wl Yo

A A

& B

3.2.4.3
Cutting and Pasting Text - Cutting and
pasting
consists
of
marking
a
block
of
text, removing ("cutting") it from its original
location, then moving the cursor
to
a
new
location
and
inserting
("pasting") the text in the new location.

3-20

USING THE VAX

Before

you

cut

text,

SELECT

key

and

the

end

one

the

text

The

the

other

between
you

select

the

are

can

the

cursor

mark

to
CUT

key

places

what

was

the

move

time

you
On

which

region,

cut.

SELECT.

cut.

The

pressed

select

1If

select

typing

region

CTRL/X
You

the

left

from

removes

can

one

the

pointer

key

appends

convenient

different

3.2.4.4
change

text

desired

paste

When

the
you

the

select

the

wish

its

the

when

you

are

CASE
It

paste

Case
of

not
key

works

containing

moving

the

pressing

and

pointer

cursor

region

from

buffer,

the

location

Use

the

has

pointer

location

holding

CUT

buffer

similar
have

been

for

the

key,

with

the

build

defined

the

screen

replacing
text,

but

PASTE

needed,

wuse

does

key

marked,

button.

not

put

until

the

you

Then

move

text

and

the

left

except

the

pointer

instead

select

paste

buffer

block

button,

the

PASTE

select

key,

except

region

and

region,

replacing

the

contents.

text

before

taking

the
you

replaces

APPEND

text

from

REPLACE

key

use

REPLACE.

with

the

buffer.

One

key

alphabetic

and

five

chararters

commands
in

your

affected.
changes

the

button.

region

want

new

the

paste

key deletes

case

form

replace

often

region

middle

and

middle

similar

mistake

cancel

paste

orginal

location.

text

select

the

pressing

select

the

buffer.

can

pressing

key

make

the

cursor.

releasing the button.

called

the

cursor

Changing
the

characters
CHNG

moving

and

the

that

REPLACE

contents

region,

locations.

REPLACE

requires

the

You

contents

point,

the

cursor

the

text.

pressing

APPEND

region

end

buffer

paste

select

text

from

VAXstation:

button,

the

cut

the

Editor

this

and

key

LISP

mark

region,

restores

cursor

cut
a

all

outermost

the

highlights

you

RESET

the

cursor

CTRL/SPACE.

pointer

the

Move

SELECT

the

use

Move

Editor

region.
use

You

text.

press

you

there.

then

The

then

select

can

versa.

mark

called

text

paste

The

cursor

the

text

The

text

PASTE

the

key

the
keys

text

there.

PASTE.

the

cut,

text

the other end of the

and

The

the

character

VAXstation:

holding

Now

mark

movement

marking

pointer

remove

must

region.

You

The

text

end

highlighted

while

you

cursor

LISP EDITOR

uppercase

follows:

3-21

letters

provide

text.

ways

Nonalphabetic

lowercase

and

vice

USING THE VAX LISP EDITOR

case

If no select region is defined, CHNG CASE changes the case

If a select region is defined, CHNG CASE changes the

all

letters in the select region.

the

character

one

character.

at the cursor position and advances the cursor

Four commands that allow you to make all the alphabetic characters in
a select region or word be of one case are "Upcase Region", "Upcase
Word", "Downcase Region", and "Downcase Word". To wuse the cemmands
that affect a region, first define the select region, then type CTRL/Z

and enter the command. To use the commands that affect a word,
position the cursor anywhere in the word, then type CTRL/Z and enter
the

command.

Finally, the "Capitalize Word" command makes the first character of a
Position the cursor anywhere in the word, then type
word uppercase.
CTRL/Z and enter the command.

for
available
are
mechanisms
3.2.4.5 Substituting Text - Two
substituting one string for another throughout text. The first 1is
the second is more powerful.

simpler;

The SUBS(TITUTE) key substitutes the contents of the paste buffer for
To use the SUBSTITUTE key, first load the paste
a search string.
buffer with the new string by typing SELECT, typing the new string,
and then typing CUT. Next, search for the string to be replaced. If
the first occurrence is in fact a string that you want to replace,
type SUBS. The Editor deletes the search string and replaces it with
the contents of the paste buffer, then automatically moves to the next
occurrence

the

string.

you

want

occurrence of the search string, type FIND NEXT to move

pass over an

the

occurrence.

The "Query Search Replace" command 1S similar to SUBS but more
The command prompts for a search string and a replacement
versatile.
string. At each occurrence of the search string, the Editor queries
You can answer as follows:

you.

SPACE -- replace this occurrence and move to the next one.

S -- replace this

allows

occurrence

and

stay

here.

Thi

option

vyou to see the results of the change before mov1ng on.

Use N to move

to the next occurrence.

. -- replace this occurrence and terminate the command.

-- replace this occurrence and

without further querying

all

remaining

occurrences

USING THE VAX LISP

not

replace

this

EDITOR

occurrence

and

find

the

occurrence.

CTRL/C

not

replace

this

occurrence

and

terminate

this

occurrence

and

terminate

the

command.

not

operation,
search

"Insert

buffer

the

cursor

input

prompt.

(Section

You

the

point

the

which

the

vyou
terminate
recursive edit

site without

losing

with

the

allows

you

your

place

1in

the

Buffer

cursor

Each

and

completion

these

contains

can

the

query.

can

the

use

the contents

the

"Insert

prompts

contents

the

for

information

the

responding

about

File"

ALTERNATIVES

CTRL/SPACE while

insert

using

commands

inserts

You

with

You

responses

location,

then

location.

3.3

possible

a
or

name

file

key

either

buffers.)

Repeating an Operation

can

cause

supplying
next

buffer

request

3.2.5

a File or

command.

edit,
which
command.
The

replacement

display help on

Buffer"
at

buffer

file

cycle.

Inserting

cursor

began.

clean

3.2.4.6

the

R -- enter a recursive
"Exit
Recursive Edit"
the

file

replace

returning

command

argument’s

press

the

Editor

numeric
to

prefix

executed

value.

perform

For

BEGINNING OF

argument.
the

action

key,

the

The

prefix

times

number

example,

LINE

the

prefix

cursor

than

argument

causes

specified

argument

will

once

the
the

and you

move

three

1lines

and

then

typing

instead
of one.
You

enter

prefix

argument

by using

the

PREFIX

key

the
number in response to the prompt, followed by RETURN.
The prefix
affects only the next command you issue.
You can
1issue
the
command
either

typing CTRL/Z

key

sequence

The

prefix

than

prefix

For

bound

and

the

command name

or by typing

the

key or

command.

arqument

also

causes

once.

For

example,

argument

some

printing

32,

then

type

commands,

you

can

supply

to
"0"

type

characters
32

zeros,

inserted

you

could

enter

once.

negative

prefix

argument.

general, the commands that are sensitive to the current direction will
accept a negative prefix arqument.
They interpret a negative argument
as
an
1instruction
to
act
in
a
direction opposite to the current

3-23

USING THE VAX LISP EDITOR
direction.

For

example,

the

current direction

forward,

a prefix

argument
of
-3
followed
by
the WORD key causes the cursor to move
three words backward.
1If the current direction is backward, a
prefix
argument of -3 causes the cursor to move three words forward.

3.2.6

Summary of Commands

Table

3-2

key

summarizes

the

commands presented in this

section and

their

bindings.

Table 3-2:

Editing Commands And Key Bindings

Name

Binding#*

Description

Text

Open Line

OPEN LINE
(keypad

Insert Close
Paren and Match

Insertion Commands

PF1

Breaks
0)

)

Inserts
a
the
cursor
matching

Close Outermost
Form

ESCAPE

1line

the

cursor

location

]

Closes
by

<close parenthesis at
and
highlights the

open

parenthesis

the
outermost LISP form
inserting
sufficient

parentheses

the

cursor

position

Indent LISP Line

TAB
or
CTRL/1I

Indents the current line to
the
appropriate
position
in
relationship to
preceding
LISP
code

New LISP Line

LINEFEED

Starts a new line,

indenting

fashion

the

proper

LISP

CTRL/J

Indent Outermost
Form

CTRL/X TAB

Indents all
the
1lines
1in
outermost
form
containing

the
the

cursor

Move

LISP

CTRL/X

;

Starts

Comment

Keys marked with an asterisk

the

(*)

available

3-24

current

moves

comment

line

only on LK201

keyboard

USING THE VAX LISP EDITOR

Table

3-2

Name

Quoted

Insert

Binding*

Description

CTRL/X

Causes

the

1inserted

without

character

the

1interpretation

typed

text
by

the

Editor
EDT

Special

SPEC

Inserts:

INSERT

(keypad

Insert

PF1

ASCII

prefix
Insert

File

None

Buffer

for

inserts

the

contents

the

buffer

EDT

(keypad

whose

the

for

then

file

the

location

buffer

the

name,

contents

the

cursor

then

the

location

Commands

Sets

FORWARD

Set

Direction

Movement

file

cursor

inserts

Cursor

specified

argument

Prompts

None

character

1is

Prompts

at
Insert

the

value

the

current

direction

current

direction

forward

Forward
EDT

Set

Direction

BACKWARD

Sets

(keypad

backward

the

Backward
Forward

Right

arrow

Character

the

Left

arrow

Character

Moves

the

Down

arrow

Moves

column

EDT

Line

Move

(keypad

Word

the

cursor

current

the

Moves

the

cursor

previous
cursor

the

current
cursor

line
to

depending

the

direction

beginning
or

line

character,

Moves

WORD

(keypad

the

column

current
Move

cursor

Moves

arrow

CHAR

Character

EDT

character

Line

cursor

character

Backward

Moves

cursor

the

next,

word,

direction
location

the

current,

depending on
and

starting

USING THE VAX LISP EDITOR

Table

3-2

(cont.)

Name

Binding*

Description

EDT Beginning of
Line

BEGINNING
OF LINE
(keypad 0)

Moves
the
cursor
beginning
of the next,

to
the
current,

current

starting

EDT End of Line

EOL

(keypad 2)

line,

direction

cursor

location

Moves

the

cursor to the end of

next,

line,

depending on

and

current,

depending

direction

and

or previous

current

starting

cursor

location

EDT Back to
Start of Line

EDT Scroll

BACKSPACE
or

Moves the cursor to the start of
the
current
1line
or
previous

or
Fl2%*

cursor

CTRL/H

line,

location

Scrolls

text

(keypad 8)

window,

Previous Screen

PREV SCREEN*

Moves

Next Screen

NEXT SCREEN*

Moves the

End

Buffer

EDT

Move

Page

buffer

PF1

current

cursor

wup

1in

the

cursor

down

1in

the

by one

I 1ffer

by one

Moves

the

Moves
the
beginning of

current

screenful

cursor

the

end of

buffer

cursor
to
the
the current buffer

Moves
the
cursor to the top of
the
next,
current, or previous
page,
depending
on
current
direction
and
starting
cursor

PAGE

(keypad

starting

wup or down in the

depending

TOP

(keypad

Buffer

direction

BOTTOM

(keypad PF1
Beginning

SCREEN

Window

depending

location

EDT Query

Prompts

for a
the
cursor
occurrence of

FIND*

current

FIND

(keypad

PF1

PF3)

3-26

string

to
that

direction

and
the
string

moves

first
in the

USING THE VAX LISP

Table

3-2

EDITOR

(cont.)

Name

Binding#*

Description

EDT Search Again

FIND NEXT
(keypad PF3)

Moves the cursor
occurrence
in

LISP

CTRL/X

beginning

LISP

form

Moves

the

beginning

LISP

Form

CTRL /X

cursor

the

nesting
of

cursor

1in

form

Outermost

CTRL/X

the

current

to beginning of
Moves the cursor
outermost form, or to
enclosing
beginning of preceding outermost

if
the
outermost
between
of

level

form

End

string

last

current or previous
the current nesting

Moves

CTRL /X

Form

Beginning

first
current

Entities

Form

Outermost

the

for

searched
Moving

the

direction

to
the

Moves

cursor

the

cursor
forms

starts

end

outermost form, or to
enclosing
of following outermost form
end
if
the
cursor
starts
between

Form

forms

outermost

Text Modification Commands
Deleting
EDT

Delete

DEL

CHAR

Character

(keypad

EDT

DELETE

Delete

,)
(

<X]

Deletes

the

cursor

location

Deletes

)

cursor

the

character

the

character before the

location

Character
EDT

Delete

Word

DEL

from cursor location to
Deletes
beginning of next word

WORD

(keypad -)
EDT

EDT

from cursor location to
Deletes
beginning of current word

F13*

Delete

Word

Delete

Line

DEL

from cursor location to
Deletes
beginning of next line

LINE

(keypad

PF4)

3-27

USING THE VAX

Table

3-2

LISP EDITOR

(cont.)
Description

Binding*

Name

EDT

Delete

End

Line

DEL

Deletes

EOL

(keypad

PF1

end
if

EDT

Delete

from

line,

cursor

Deletes

CTRL/U

location

all

end of

from

beginning

Line

cursor

of next

cursor

line

location

current

1line,

all of previous line
1if
is at beginning of line

to
or

cursor

Undeleting
EDT

Undelete

(keypad

EDT

UNDEL

Undelete

EDT

Undelete

UNDEL

PF1

Cutting,

Pasting,

Select Mark

Inserts
the
deleted at the

the

PF4)

the

Inserts

the

cursor

Inserts

LINE

(keypad PF1

Line

Set

PF1

WORD

(keypad

Word

CHAR

UNDEL

Character

character
location

last word deleted

location

the

cursor

last
cursor

last

line

deleted

location

and Substituting
SELECT

Defines

(keypad

region

. )

one

end

select

SELECT*

Unset

Select

Outermost

CTRL /X
CTRL/SPACE

Form

Cancels

RESET

(keypad PF1

Mark

Cut

CUT

(keypad
or

REMOVE*

EDT

Append

APPEND

(keypad

EDT

Paste

a select
outermost LISP

region

form

from
the
containing

cursor

Removes

the
select region from
the
text
and
replaces
the
contents
of
the
paste
buffer
with the select region

Removes
the
select region from
the text and appends the
select
region to the
contents
of
the
buffer
paste

PASTE

Inserts

(keypad

paste

location

INSERT*

select

Makes
the

EDT

the
1buffer
f

content S

the

cursor

USING THE VAX LISP

Table

3-2

(cont.)

Description

Binding*

Name

EDT

Replace

REPLACE

(keypad

PF1

Deletes

the

replaces

it with

the
EDT

EDITOR

Substitute

paste

paste
string

PF1

ENTER)

Prompts

None

and

old

region

and

contents

the

contents

the

buffer
for
the
search
and
moves
to
the
next

occurrence

Replace

the

buffer

Substitutes

SUBS

(keypad

Query

select

for

the

old

and new

string
strings,

each

occurrence

string

prompts

for

action;

versatile

the

than

"EDT

Substitute”
Exit

Recursive

Terminates

None

returns

Edit

Changing
EDT

recursive

edit

the

editing

from

which

the

recursive

was

initiated

and

1level

edit

Case

Change

Case

CHNG

Changes

CASE

(keypad

PF1

characters

the
in

case

select

region

all

of an individual character
‘Upcase

Region

None

Makes
region

Downcase

Region

None

Makes
region

Upcase Word

None

Makes
at

Downcase

Word

Capitalize

Word

None

the

all

characters

select

the word

uppercase

all

characters

lowercase

all

characters

cursor

location uppercase

Makes all characters in the word
at the cursor location lowercase
Makes

the

first

word

the

character
cursor

the

location

uppercase

General
Supply

Prefix

Argument

PREFIX

Prompts
for
a
numeric
prefix
argument,
which
may
cause the
next
command
to
repeat
1its
action

USING THE VAX LISP EDITOR

3.3

USING MULTIPLE BUFFERS AND WINDOWS

The

Editor

can

keep

track

than one

LISP

object

file

time.
The
Editor
holds
each object or file that you are currently
editing in a buffer.
Commands let you move
between
buffers,
create
new buffers, and gain access to buffers through windows on the screen.

3.3.1

Introduction to Buffers and Windows

Buffers are Editor objects that contain the text of the symbol or file
that
vyou
are
editing
and
some
information
about the text -- for
example, the position of the cursor when the text is
displayed.
The
Editor displays the contents of buffers through windows on the screen.
The Editor can keep track
of
many
buffers
at
once,
but
normally

displays
you

the

contents of no more than two buffers

time.

it has created for

On a VAXstation:
It is important to distinguish between the
VAXstation
window
that
contains the Editor and the Editor
- windows
that
display
the
contents
of
buffers.
The
VAXstation
window
1s
equivalent
to the screen of a video
terminal.
Editor windows appear in the VAXstation window.
The

first time you
use
the
ED
function,
you
supply
an
argument
specifying
the symbol or file you want to edit.
The Editor creates a
buffer having the same name as this symbol or file and a window on the
screen for this buffer.
You can then enter and modify the text in the
buffer.

If, after you return to the LISP interpreter, you use the ED
function
with a different symbol or file, the Editor creates another buffer and
window.
Both windows appear on the screen, but
the
window
for
the
buffer
most
recently
created
is
the
current window.
If you type
characters or enter Editor commands, the
buffer
viewed
through
the
current window will

For

first

example,
Lisp>

and

then,
Lisp>

the

(ED

you

affected.

’'SHIP-ACCESSOR)

after pausing
(ED

typed

the

Editor,

typed

"CLOCK.LSP")

screen might

look

this:

3-30

USING THE VAX LISP EDITOR

Function SHIP-ACCESSOR Forward
fluse-package "EDITOR")

EDT Emulation ("VAX LISP")

{define-command {clock-command :display-name "Clock")
{prefix)

(let ((buffer (find-buffer "Clock")))
{unless buffer

{setf buffer (make-buffer “{clock-buffer :display-name "Clock")
rmajor-style nil minor-styles nil

_File CLOCE. LSP Forward EDT Emulation (M4

The
Now, two label strips appear, one at the bottom of each window.
strip and the presence of the cursor in a window
label
reverse-video
show you which window

current.

To change the current window,

use

the

CTRL/X

CTRL/N

key

sequence,

When you change
the screen current in turn.
each window on
making
it
position
the
to
cursor moves
the
from one window to another,
occupied when you last edited in that window.

Wwindows that display text you are editing are called anchored windows,
Unless you
because they are fixed at a particular spot on the screen.
no
display
default
by
can
Editor
the
command,
use the "Split Window"
more
have
can
you
However,
once.
at
windows
anchored
two
than
more
each
editing at once,
than two LISP objects or files available for
list
a
The "List Buffers" command displays
its own buffer.
occupying
For example, if you had used the ED
of all the buffers in the Editor.
Buffers" might result in the following
"List
times,
three
function
display:

3-31

USING THE VAX LISP EDITOR

Huffer Name

Lines /7 Chars

ill Ring

Status

Erpty

HIP-ACCESSOR

Ckpting

Writable

Emptuy

Permanent

Writable

Yes

Function of sumbol SHIP-RCCESSOR
6 / 262
Modified
No
44 / 1660
Modified
Yes
LISPWE:
[BODGE JCLOCK.LSP:2
seneral Prompting
Empty
Modified
No
SHIP-TONNAGE
Emptuy
Weitable
No
Function of sumbol SHIP-TONNAGE
|
Listing of availableeditor buffers
(prefix)
elp
CLOCK.LSP

Yes
Mo
Yes
Mo

(let ((buffer (find-buffer "Clock")))

{unless buffer

(setf buffer (make-buffer “(clock-buffer :display-name "Clock")
»major-style nil minor-styles nil

rvariables nil))
File CLOCK, LSP Forward
EDT Emulation ("VYax LISP")

The

buffers

identified
For

holding
by

example,

symbol

the

objects

additional

the

buffer

named

SHIP-ACCESSOR."

and

line

files

that

detailing

SHIP-ACCESSOR

The

other

you

the

are

contents

contains

buffers

editing
of

the

1listed

the

are

buffer.

"Function

contain

Editor

information.
You

can

screen
name

select
with

you

not

see

list

you

Editor
are

buffer

edit.

their

there,

with

that

1is

command.
can

the

buffers

type

part

Editor

are

not

This
of

fill

currently

command
the

name,

the

available,

prompts

rest

use

the

for

the

then

the

wuse
name.

ALTERNATIVES

names.

buffer

You
that

know which

select

already

editing

Buffer"

request

displays

replaces

for

"Select

buffer

CTRL/SPACE

When

the

from

new

among

Editor

one

those

not

currently

anchored window.
removes

displaying

the

two

1least

contents

displayed,

anchored
current

the

windows
one

and

buffer

just

selected.
"Removing"

buffer.
be

window does

Removing

longer
the

CTRL/X

the

screen

and

other

delete

simply

causes

displayed,

use

windows

not

a window

CTRL/R

the
than

until
key

"Remove
the

the

sequence

Other

current

modify

time

remove

3-32

from

the

contents

corresponding

you

Windows"

window

the

select
the

it.

current

command
screen.

the

buffer

You

can

window

from

remove

all

USING THE VAX

addition

Floating

and

anchored

windows

obscuring

windows.

the

CTRL/X

the

The

purpose

CTRL/N

they

when

are

Creating

You

not

buffer.
files

The

"EA"

moves

cursor

the

current,

need

return

commands
leaving

for

function.

the
the

you

supply

want

you

supply

specification,

command

(See

the

File"

command

allows

Section

3.3.3

edit

the

turn,

Other

the

floating

windows.

overlaying

floating

window.

For

anchored windows;

CTRL/X

CTRL/R

Windows"

removes

them

Editor

interpreter
start

the

editing

create

new

starts

name,

the

LISP

you

request

1listing

Editor

string

for

"Ed"

that
a

new

objects

asks

you

the

command
to

the

specify

value

containing

file

completion

"Ed"

enter

the

file

file.
to

command

possible

The

you would

definition

editing

the

function.

that

function

from

you

<character

file

edit.

The

"Edit

the

"Edit

File"

file

name

with

that

the

names with ALTERNATIVES.

3.1.3.2.)

Buffers
take

care

in which you

need

themselves.

When you need

save

When you need

delete

When

Buffers

them in

floating
screen,

under

just

LISP

symbol

prompts

generally

situations

are

arguments

command

Working with

Buffers

the

differs

and

1lie

appears

"Remove

same

CTRL/SPACE

that

has
the

Editor.

each

vyou

"Edit

and

the

symbol.

File"

windows

allow you

whether

The

also

current.

command works

prompts

Editor

New Buffers from Within the

Two

without

help

EDITOR

anywhere

windows

in which

these

are

the

displayed

commands,

not

3.3.2

windows,
be

anchored

window

them when
they

may

LISP

two buffers have

maintain

some

session

with

buffer.

Specifically,

deal

the
a

The

position of

The

select

The

buffers

contents

about

the

LISP

object

buffer

keeps

track

region,

cursor
if

three

common

are:

buffer

the

only

directly

conflicting names

information

regard

with

one

in
1s

the

state

or
of:

text

active

file

your

contained

editing

the

USING THE VAX LISP EDITOR

the

The major and minor styles that are active in that buffer

(see

if any keys are bound

Key bindings,
buffer

Section

(see

the

context

3.5.1)

Section

This information ensures that, when you select a buffer you worked
on
previously, it will be in the same state as it was when you left 1it.

3.3.3.1
Saving Buffer Contents - Three commands save buffer contents.
The
"Write
Current
Buffer"
and
"Write
Modified Buffers" commands
current
single
the
of
(discussed in Section 3.1) save the contents
buffer
and of all buffers that have been modified, respectively.
The
command and
"Exit"
the
third way to save buffer contents is to use
request

that modified buffers be

saved.

When you pause the Editor,

your buffers are not written, but they
are
should
you
however,
If,
Editor.
the
resume
you
when
you
to
available
pause the Editor and then exit LISP, the contents of your buffers will
explains how you can partially recover from
3.4
(Section
lost.
be
this

situation.)

"Delete
Dbuffer.
a
delete
Deleting Buffers - Two commands
3.3.3.2
are currently working on;
vyou
buffer
the
deletes
Buffer"
Current
"Delete Named Buffer" prompts for
a
buffer
name
and
deletes
that
modified
been
has
buffer
the
if
see
to
check
commands
Both
buffer.
before
buffer
the
to write
you want
and, if it has been, ask if
deleting

it.

buffer
the
and you delete
file
existing
an
editing
If you are
not delete the file.
does
Editor
the
file,
the
associated with
file.
the
However, the Editor also does not create a new version of
you are editing the file CLOCK.LSP;l1 and you delete
if
example,
For
However,
the buffer "CLOCK.LSP", the file CLOCK.LSP;1 is not deleted.
saved
had
you
if
created
been
have
would
CLOCK.LSP;2, which
file
the
the buffer contents,

is not created.

Buffer Name Conflicts - The Editor requires that buffer names
3.3.3.3
can cause a problem in the following
requirement
This
be unique.
situations:

You are trying to edit the function definition and
of

the

same

the

value

symbol

You are trying to edit two files having the same name and type
(version number,
respect
other
some
in
differing
but
directory,

and

so on)
3-34

USING THE VAX LISP EDITOR

When your attempt to edit something creates a
buffer
name
conflict,
the
Editor
requests a new buffer name.
You can type in any name you
like.
However, if you should type in no name and
just
type
RETURN,
the
Editor deletes the current contents of the buffer, replacing them
with whatever

3.3.4
The

you

are

trying

edit.

Manipulating Windows
commands most

been

presented

this

CTRL/X CTRL/N
the

Other

commonly used

current

manipulate

windows

have

(bound to

"Next Window")

to make the next window

window

CTRL/X CTRL/R

(bound to

"Remove Current Window")

current window

from the

screen

"Remove Other

Windows"

current window

from the

commands

already

chapter:

remove

windows

remove the

other

than

the

screen

allow you to manipulate windows in other ways.

The "Grow Window" and "Shrink Window" commands make the current window
larger
and smaller, respectively.
If no prefix argument is set, they
make the window one line larger or smaller.
1If a prefix
argument
1is

set,

they

specified

The

make

the

prefix

"Split Window"

window larger or smaller by the number of lines
argument.

command allows you to open two or more windows on a

single
Dbuffer.
The command causes the current window to be split in
two, with identical text appearing in the two windows.
Once
created,
the
two
windows
can
be
treated
as
ordinary
windows;
the
window-manipulation commands move between the two windows
and
remove
them
in
the
normal
fashion.
Each window maintains its own cursor
position and scrolls separately from the other; but
1if
you
type
or
edit in one window, the change will appear in the other as well.
Split windows are useful if you want to
buffer
at
one
time,
or
if you want
another in a buffer.
To move text, you
one
window,
move to the other window,

examine two parts of the
same
to move text from one place to
would delete it or cut
1t
1in
and undelete the text or paste

it.

You can have more than two
windows
on
a
buffer;
Jjust
wuse
"Split
Window" repeatedly.
The number of windows is limited only by the size
of the screen; each window must have at least one line.
Al tucugu

the

:
D.p..l.it Window"

~
””””””
command

s = TV er
ini L lalliy
.

~wres

creates

Two

W1Naows

the
same
buffer,
you
can
cause
one of those windows to switch to
another buffer.
Use the "Select Buffer" command and specify a
buffer

3-35

USING THE VAX LISP EDITOR

not

currently displayed

and

selecting new buffers,

windows

the

you

window.

repeatedly

can view as

many

splitting windows

buffers

you

copy

text

can

fit

screen.

3.3.5

Moving Text Between Buffers

frequently useful

able

move

from

one

buffer

to another.
For example, i1f you have worked on the definition
of a function, you may want to move it to a buffer in
which
you
are
editing a file.
Two general ways of doing this are:

You can delete or cut the text from the source buffer,
to
the
destination buffer, and undelete or paste the
the

destination

3.3.6

buffer

insert an entire buffer

command

change
text in

in another,

use

the

"Insert Buffer"”

Summary of Commands

Table

3-3 summarizes
key bindings.
(Some

pertain

Table 3-3:

buffers

the commands presented in this section and
their
of the general-purpose commands in Table 3-1 also

and windows.)

Commands For Manipulating Buffers And Windows

Name

Select Buffer

Binding

Description

None

for

a buffer

makes

Prompts

that

buffer

and

name,
the

displays

then

current

1in

window

List

Buffers

None

Displays

list

all

Editor

buffers

Delete

Current

None

Named

None

Deletes

the

current

Delete

Prompts

Buffer

None

for

the

name

buffer,

then deletes

Prompts

for

file

3-36

buffer

‘

Buffer

symbol

specification

creates

new

symbol

file

that buffer

buffer

name

edit,

then

for

the

USING THE VAX LISP EDITOR

Table

3-3

(cont.)

Name

Binding

Description

Edit File

None

Prompts
then
file

for

creates
and
a

the name of a file,
a buffer
window

for
1nto

that
the

buffer

Grow Window

None

Enlarges

the

current window by

by the number of
or
line,
one
lines
specified
by
the prefix
argument

Shrink Window

None

Shrinks

the

current

window by

one
1line,
or
by the number of
lines
specified
by
the prefix
argument

Split Window

None

Splits
two

the current windows into

windows

the

current

buffer

Insert Buffer

3.4

None

Prompts

for

the

cursor

location

name

inserts
then
buffer,
at
contents of that buffer

the
the

RECOVERING FROM PROBLEMS

The Editor provides

facilities that let you

recover

from problems with

all or most of your work intact.
Section 3.1.3.3 contains information
on how the Editor responds to minor errors.
This
section
describes
checkpointing,

by means of which the Editor protects work in progress.

Whenever you are editing a file, the Editor periodically makes a
copy
of
the current state of that file.
The copy is a separate disk file,
called the checkpoint file.
It has the same name as the file you
are
editing,

and a

file

type

composed as

follows:

type_version_LSC

where
type
and
version
are
the
file
type
and
version
number,
respectively,
of
the
file you are editing.
For example, 1f you are
editing the file CLOCK.LSP;2, the associated checkpoint file
will
Dbe
named

CLOCK.LSP_2_LSC.

While you are using the

Editor or

the

LISP

interpreter,

error

may

occur
that
returns
you
to
DCL, or you may inadvertently exit LISP
without first saving your Editor buffers, or the system may crash.
1In

3-37

USING THE VAX LISP EDITOR

any
of
these
cases
the
current state of your Editor work is lost.
However, the checkpoint files for any files
you
were
editing
still
remain,
reflecting
the
state of those buffers at the last time that
checkpointing took place.
To use a checkpoint
file
after
you
have
lost
the
associated
buffer, change its file type back to LSP.
Then
use the Editor to edit the file.
When
checkpointing
a
file,
the
Editor
displays
the
message
"Checkpointing ..." in the information area.
You can continue to type
while checkpointing is taking place but whatever you type will not
be
displayed
wuntil
checkpointing
1is
complete.
By default, the Editor
checkpoints after every 350
commands
that
alter
text
in
buffers.
(Each keystroke that inserts a text character counts as a command.)

3.5

CUSTOMIZING THE EDITOR

You can customize the Editor to make it more convenient or comfortable
to use.
This section describes two ways to customize the Editor:

Section 3.5.1 explains how to bind keys or
key sequences
to
commands.
You
can
bind
keys to commands that have no keys
bound to them by
default,
or
you
<can
change
the
default
bindings.

Section 3.5.2 describes keyboard macros.
A keyboard macro
1s
a sequence of keystrokes that the Editor captures for you; you
can then replay the sequence at a later time.

The VAX
LISP/VMS
Editor
Programming
Guide
explains
how
you
can
customize
the
Editor
even
further
by creating new commands or new
editing

3.5.1

styles.

Binding Keys to Commands

As previously stated, you interact with the Editor by using
commands.
Many commands have keys or key sequences bound to them; others do not.
One way you can customize the Editor is to bind a key or key
sequence
to a command.
Once you have bound a key or key sequence to a command,
typing that key or key sequence invokes the command.
The

two ways to bind a key or

While using

the

key sequence

Editor,

you

can

to a command are:

wuse

the

"Bind

Command”

command.

While using the LISP interpreter, you can use the BIND-COMMAN
function.
Your LISP initialization file can contain calls to
BIND-COMMAND to

set up the

Editor.

3-38

USING THE VAX LISP EDITOR

These

two

methods

are

discussed

1in

Sections

3.5.1.1

and

3.5.1.2,

respectively.

No matter
two

how you bind

pieces

keys

information

key

sequences

vyou must

commands,

supply and

third

there
that

are

you may

supply:

You must

You must supply the
key
or
key
sequence
to
bind
to
the
command.
Sections 3.5.1.1 and 3.5.1.2 describe how to specify
the key or key sequence.
Section 3.5.1.3 contains suggestions
on how to select a key or key sequence to bind.

You can optionally supply the context in which the binding
1is
effective.
Section 3.5.1.4 explains the key binding context.

3.5.1.1

key or

command prompts

specify

name

Binding Within the Editor

you to bind a
This

supply the

complete

the

The

key sequence

to a

you

for

each

command

"Bind

to be

invoked.

Command"

command while using the
the

three

items

second prompt

you

allows

Editor.
need

binding.

The "Bind Command" command first prompts
you
for
the
command
you
wish
to
have
bound.
You can use input
alternatives to get a complete command name.
The

command

for

the

key

sequence.

Type

the

name
of
the
completion and

actual

key or

key

sequence
that
you
want
to
bind
to the
command
-not
a LISP
representation of the characters.
However, you
cannot
type
control
characters
or
function
keys
wunless you use CTRL/X \ to quote them.
Since most bindings involve control characters or function
keys,
you
will tend to use CTRL/X \ most of the time.
For example, assume that you want to
bind
the
CTRL/0O to a command.
Both CTRL/X and CTRL/0O are

they must both be quoted.

prompt,

you

would

the

sequence
CTRL/X
control characters so

"Enter

key

sequence"

type:

CTRL/X \ CTRL/X

After you completed
like

1In response to

key

CTRL/X \

this

CTRL/O

sequence,

the

prompting

area

would

appear

this:

.Fxmxm;hsy_aamuanna < w3<"0f
Function keys, arrow keys, and keys on the numeric keypad must also be
quoted.
Each of these keys generates more than one character when it
is struck, so more than one character appears in the
prompting
area.
For

example,

to bind

CTRL/X \ F12

the

F12

key

command,

you would

type:

USING THE VAX LISP EDITOR

This

sequence

echoed

the

prompting

area

as:

uence <ESCAPE>[24°§
The

third

:GLOBAL

prompt

(the

:BUFFER,

followed

Editor

then

Section

3.5.1.4

3.5.1.2

allows

for

default)

for

Binding

particular

style

buffer.

(See

information

binding

the LISP

The

Interpreter

second

argument

sequence

must

For

all

the

keys

BACKSPACE

key

function

the

bindings

three

BIND-COMMAND

wuseful
you use

arguments.

you wish

key

key
as

the

and

may

key

have

all

the

LISP

your

the

The

function

using

LISP

time.

first

bound,

sequence

given

vector

main

part

and

other

numbers,

keys

"CTRL/A"

a VT100

struck.

list
the

the
is

argument

the

that

LISP

characters.

form of

The

-For

those

table

you

that

may use

example,

#\BS,
of

the

A key

keys

character

#\BACKSPACE,

invoke

character.

symbols

character.

keyboard

displays

printing

#\"A.

can be

the

Table 3-4

the

associated with

function

lists

keypad
in Table

the

transmit

each

key

do not

and

numeric

and

the

function

and

arrow

3-4.

keys

BACKSPACE

lacks

keys

particular

keys

keyboard

function

with

keyboard

function

The VT100

the
numeric
characters listed

associated

and

but

these

especially

takes

CHAR-NAME-TABLE

keys,

generates.

Some

The

"A"

1is

transmitted

the

#\"H.

LISP

The

names

for

characters.

remaining

when

context.)

bindings while you are

the

representation
#\a,

editing

given

control

The

LISP

"a"

LISP

command

single

letters,

any valid
#\A,

set

the

string.

command.

produce

the

function

Dbe

file

name

:STYLE

name

the

initialization

the

can

Type

The

context

options.

BIND-COMMAND

character

The

buffer.

these

interpreter.

BIND-COMMAND

key

The

style

one

establish
to

context.

specify

for

from

binding

by RETURN,

prompts

vyou

the

keypad,

than

character

keys,

character

sequence

and editing
keys

arrow

one

keypad

generate

keys,

the

same

”
on

the

LK201

characters.
the

F13

actually

keyboard

For

key

transmit

example,

with

these

are
the

commonly
F12

LINEFEED.

characters,

key
and

" Editor does not treat them as having transmitted these characters.

3-40

1is

However,

the

USING THE VAX LISP EDITOR

Table 3-4:

Characters Generated by Keys

Key

Characters

Numeric

Keypad Keys

Generated

(LK201 and VT100)

keypad

#¥\NESCAPE

#\O

keypad

#\ESCAPE

#\O

#\g

keypad

#\ESCAPE

#\O

#\r

keypad

#\ESCAPE

#\O

#\s

keypad

#\ESCAPE

#\0

#\t

keypad

#\ESCAPE

#\O0

#\u

keypad

#\ESCAPE

#\0O

#\v

keypad

#\ESCAPE

#\0

#\w

keypad

#\ESCAPE

#\0

#\x

keypad

#¥\ESCAPE

#\0

#\Yy

keypad -

#\ESCAPE

#\0O

#\m

keypad

#\ESCAPE

#\0

#\1l

keypad

#\ESCAPE

#\O

#\n

keypad

ENTER

#\ESCAPE

#\0O0

#\M

keypad

PF1

¥\ESCAPE

#\O

#\P

keypad

PF2

#\ESCAPE

#\0

#\Q

keypad

PF3

#\ESCAPE

#\O

#\R

keypad

PF4

#\ESCAPE

#\O

#\S

Arrow Keys

(LK201

#\p

and VvTi00)

Up Arrow

#\ESCAPE

#\[

#\A

Down Arrow

#\ESCAPE

#\[

#\B

Right

#$\ESCAPE

#\[

#\C

#\ESCAPE

#\[

#\D

Left

Arrow

- Function,

F6
F7
F8
F9
F10
F11
F12
F13

HELP,

and DO keys

(LK201)

F14

#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE

#\[
#\[
#\[
#\[
#\[
#\[
#\[
#\[

#\ESCAPE #\[

#\1
#\1
#\1
#\2
#\2
#\2
#\2
#\2

#\7
#\8
#\9
#\0
#\1
#\3
#\4
#\5

#\~
#\"
#\~
#\~
#\"
#\~
#\~
#\

HELP (F15)
DO (F16)
F17
F18
F19
F20

¥\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
¥\ESCAPE
#\ESCAPE

#\[
#\[
#\[
#\[
#\[
#\[

#\2
#\2
#\3
#\3
#\3
#\3

#\8
#\9
#\1
#\2
#\3
#\4

#\~
#\~
#\°
#\~
#\~
#\~

#\2 #\6 #\~

USING THE VAX LISP EDITOR

Table

3-4

(cont.)

Key

Characters
Editing

FIND (E1)
INSERT HERE
REMOVE (E3)
SELECT (E4)
PREV SCREEN
NEXT SCREEN

The

#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE
#\ESCAPE

(E2)

(ES5)
(E6)

(LK201)

#\[
#\[
#\[
#\[
#\[
#\[

#\1
#\2
#\3
#\4
#\5
#\6

third argument to BIND-COMMAND,

binding

context.

that

the

you

Keys

Generated

is,

include

#\°
#\~
#\~
#\~
#\
#\~

which is optional,

you omit this argument,

specifies

the

Editor.

the context is global;

key binding is effective everywhere in
argument, supply it in the form

the

this

"(:STYLE

"style-name")

' ( :BUFFER

Section

The

"buffer-name")

3.5.1.4

describes

following example

"Remove

Other

Alternatively,

(the

REMOVE

Windows"

binds

Windows"

(BIND-COMMAND
you

could

the

command

"Remove

key
shown

binding

context

key

sequence

Other

the

detail.

CTRL/X

Windows"

LK201’s

the

’"#(#\"X

#\"0))

key

sequence

editing

keypad)

"Remove

PF1

#\3 #\7))
of
the

function:

"EDT Back to Start of Line®
"# (#\ESCAPE #\[ #\2 #\4 #\')
*( «:STYLE

"EDT

function,

execution

this

Emulation"))

the

F12

key moves

the

cursor

the
beginning
of
the line, but only if the "EDT Emulation”
active.
(This binding is in effect by default.)
F.

REMOVE

"Remove Other

key on an LK201 keyboard to the "EDT Back to Start
in
the
"EDT
Emulation"
style,
you
would
wuse

(BIND-COMMAND

Following

the

Other Windows"

"# (#\ESCAPE #\O #\P #\ESCAPE #\[

following

here:

(BIND-COMMAND

To bind the F12
Line"
command

CTRL/O

globally:

globally bind

in more

Imk.

3-42

style

1is

USING THE VAX LISP EDITOR

On a VAXstation:
device

You

(movement

description
LISP/VMS

the

Editor

can
and

Programming

3.5.1.3

Selecting a Key or

sequence

Key Sequence

command,

selection does not interfere
with
restrictions and provides
three

sequence

control

characters

the

commands.
function

pointing
See

the

VAX

You

but you

can

bind

should be

almost

careful

any key

that your

Editor
operation.
This
section
to help you make a selection.

hints

you must

not

include

anywhere

1in

key

are:

The cancel character, CTRL/C by default, which
terminates
an
Editor operation.
You cannot include CTRL/C in a key sequence
because typing CTRL/C at any
time
stops
the
collection
of
keystrokes
and
returns
the
Editor
to
the end of the last
completed

actions

Guide.

explains
The

bind

BIND-POINTER-COMMAND

key

also

buttons)

command.

CTRL/S and CTRL/Q, which
are
interpreted
by
the
operating
system
(they
stop
output
to
the
terminal
and resume it,
respectively)
and
therefore
never
reach
the
Editor
for
interpretation.

You

should

sequence,

not

use

any

although

graphic

vyou

(printing)

<can

wuse

character

graphic

characters

start

elsewhere

key

the
sequence.
If you start a key sequence with, say, the
letter
A,
you
will
never
be
able
to
type
the
letter A as part of a word.
The
Editor, as soon as it sees the A, will recognize it as
the
beginning
of a key sequence; unless the next character(s) complete the sequence,
the Editor will signal an error and discard the A.

When you include an alphabetic character in a key
sequence,
remember
that
the
Editor
differentiates
between upper- and lower-case.
For
example, the following two key sequences are different:
"#(#FNTX #\A)
"#(#\"X #\a)
By

convention,

ESCAPE,

and

the

three

keypad PFl.

keys

You

used

can,

as long as they are nonprinting.
ESCAPE key, CTRL/[ transmits the
Finally,

careful

not

select

start

course,

key

use

sequence

others

(On terminals that do
#\ESCAPE character.)
a

key

are

CTRL/X,

if you

choose,
have
an

not

sequence

that

1is

already
bound to a useful command.
Appendix C contains a list of all
the key bindings supplied with the Editor.
Section
3.5.1.4
explains
how
a
single
key
or
key
sequence
can
be bound to two
different
commands

different

contexts.

3-43

USING THE VAX LISP EDITOR

3.5.1.4
Key Binding Context and Shadowing - When you bind
a
key
or
key
sequence
to a command, you can specify the context in which that
binding is effective.
Specifying a context means that the key or
key
sequence invokes the command only in that particular context.
The

three

general

context

are:

context is
a
particular
buffer,
invokes
the command only if that

current.

The style context.
1If the context is a particular style,
the
key
or key sequence invokes the command only if that style is
the major style or one of the minor styles that is
active
1in
the

The buffer context.
If the
the
key
or
key
sequence
buffer

types

current

buffer.

The global context.
1If the context is global, the key or
key
sequence
always
invokes the command.
The default context 1is
global.

Styles

A
style
is
a
«collection
of
key
bindings
and
of
other
Editor
characteristics
that cause the Editor to behave in a certain way.
The
two styles that you encounter in the default
Editor
are
named
"EDT
Emulation”
and
"VAX
LISP".
The
"EDT
Emulation" style causes the
numeric keypad to generate editing actions similar to
those
of
EDT.
The
"VAX
LISP" style provides access to the Editor’s ability to edit
LISP

code

easily.

An Editor buffer can have one major style and one or more minor styles
active
at

the

any time.

label

strip

for

You can tell which styles are active by looking
the buffer:

4 LISP")

The major style is generally established before the Editor is started.
Minor
styles
are activated automatically, depending on what is being
edited.
For example, whenever you edit a LISP object or a file having
the
type
LSP, the "VAX LISP" style is activated for that buffer as a
minor

style.

Shadowing

It is possible to bind the same key or key sequence to
two
different
commands.
I1f the contexts of the two bindings are the same, then the
second binding replaces the first one.
1If, however, the two
bindings
have
different
contexts,
then
the
key
or key sequence may invoke

3-44

USING THE VAX LISP EDITOR

either

command,

command

First

checks

the

situation

key

pressed,

the

see

major

checks

that

key

the

time.

locate

Editor:

bound

the

context

buffer.

see

style

checks

current

activated

when

current

the

depending

execute

that

minor

key

styles,

bound

the

examining

context

the

most

one

recently

first.

see

that

key

bound

the

context of

style.

see

the

that

key

1is

bound

1in

the

global

context.

soon as the
Editor
finds
a
command
to
execute,
1t
does
Therefore,
1if
the
same
key
or
key sequence is bound in, say,
current minor style and the current major style, the
binding
1in
minor
style
"shadows,"
or takes precedence over, the binding in
major

so.
the
the
the

style.

For example,

the CTRL/J key is bound to

"EDT Delete Previous Word"

the
"EDT
Emulation"
style
and to "New LISP Line" in the "VAX LISP"
style.
When you are editing LISP code, "EDT Emulation” is
the
major
style
and
"VAX
LISP" is the minor style.
Therefore, the binding of
CTRL/J to "New LISP Line" shadows the binding to "EDT Delete
Previous
Word".

3.5.2

Keyboard

Macros

A keyboard macro is a series of keystrokes that you ask the Editor
to
"remember"
for
future
wuse.
The keystrokes can be keys that insert
characters, keys or key sequences that
invoke
editing
commands,
oOr
even
commands
that you type in and that issue additional prompts.
A
keyboard macro is useful whenever you
have
a
series
of
1identical,
complicated operations to perform.

To begin a keyboard macro, type CTRL/X (.
Everything
you
type
from
that
point
1is
executed normally, but is also stored for future use.
Typing

CTRL/X )
keyboard
macro,

stops
the
storage
type CTRL/X CTRL/E.

keyboard macro

location.

keyboard

"played back"

macro

of
keystrokes.
To
This sequence causes

starting

that you define

you define another keyboard macro.

the

execute
a
the current

current

cursor

in this way lasts until

You can also use the "Start Named Keyboard Macro" command to define
a
keyboard
macro
having
a name.
Use the "Start Named Keyboard Macro”
command as you would the CTRL/X ( key sequence.
The
command
prompts
you
for
a
name.
After
vyou
enter
the
name,
the
Editor starts

3-45

USING THE VAX LISP EDITOR

remembering keystrokes.
Terminate the macro with CTRL/X ).
The macro
thus
defined
is
the
current keyboard macro (you can invoke it with
CTRL/X CTRL/E) but it is also a named entity that you can treat like a
command.
You
can execute it as a named command or bind a key to it.
A named keyboard macro remains accessible by name even
after
another
keyboard

macro

has

been

defined.

A keyboard macro may not work properly if the context changes
between
the
time
the
macro
1is
<created
and
the time it is executed.
For
example, if you switch to a buffer that has a
different
minor
style
active, the commands invoked by the keyboard macro may fail.

3.5.3

Summary of Commands

Table

3-5

key

summarizes

the

commands presented

in this

section and

Table 3-5:

Commands For Customizing The Editor

Name

Binding

Description

Bind Command

None

Prompts
key

Start Keyboard

CTRL/X

Start Named
Keyboard Macro

None

for a command name and a

sequence

keyboard macro

Prompts for a name, then
collecting
keystrokes
keyboard macro

End Keyboard
Macro

CTRL/X

Execute Keyboard

CTRL/X CTRL/E

Macro

bind

Starts collecting keystrokes for

Macro

3.6

their

bindings.

)

Terminates
keystrokes

Executes

having

starts
for
a

that

name

the
collection
of
for a keyboard macro

the

current

keyboard

macro

USING THE EDITOR ON A VAXSTATION

The behavior and capabilities
of
the
Editor
when
operating
on
a
VAXstation are similar to its operation on an ordinary video terminal.
The same commands are available and
the
same
key
bindings
are
1in
effect.
However,
the Editor incorporates several features that make
use
of
VAXstation
capabilities.
This
section
summarizes
those
features.

USING THE VAX LISP EDITOR

3.6.1

Screen Appearance and Behavior

The most obvious difference in Editor behavior on a VAXstation is that
the
Editor
occupies
a
separate
VAXstation
window
from
the LISP
interpreter.
This window has the title
"VAX
LISP
Editor".
It
is
created the first time you start the Editor, and the cursor is shifted
to it from the window containing the LISP prompt.
The
Editor
window
is taller than the 24 lines normally contained in a video terminal but
is otherwise identical to the Editor display described throughout this
chapter.

When you pause the Editor, the cursor
returns
to
the
LISP
prompt.
When
vyou
resume the Editor, the cursor moves to the spot it occupied
in the Editor window when you paused the Editor.

If you select the Delete option from
the
Window
Options
menu,
Editor exits, giving you the opportunity to save buffers first.

the

While you are using the Editor, you cannot use the
LISP
interpreter,
even
though
the
window containing
the LISP prompt is still on the
screen.
You cannot use the LISP interpreter until you pause
or
exit
from

3.6.2

the

Editor.

Editing with the Pointer

You can use the mouse or other pointing device to perform some editing
You can select a new window to be the current window, move the
tasks.
and paste
cut
and
text insertion cursor within the current window,
text.
When you are editing LISP code, you can also select LISP forms,
describe LISP symbols,

and match parentheses.

that
cursor
the
The Pointer Cursor - The pointer cursor is
3.6.2.1
By
pointing device.
the
screen by moving
the
around
yvou move
you
that
cursor
contrast, the text insertion cursor is the blinking
move around the Editor windows using conventional Editor commands.
LISP
the
1in
The appearance of the pointer cursor changes when it is
Editor window.
When
the
pointer
cursor
is
in
the
window that
represents the current buffer, it looks like this:

L
When the pointer cursor is in a window that represents a buffer
than the current buffer,
S

it looks like this:

other

USING THE VAX LISP EDITOR

When

the

pointer

cursor

the

information

area,

1looks

1like

this:

Y
3.6.2.2
in

button

Selecting

and Removing Windows

window

other

that

cursor

make

than

window

placed

where

Press

the

middle

pointer

window

remove

that

3.6.2.3

Moving

pointer

cursor

the

move

release

text

the

insertion

the

the
1is

text

the

stays

the

select

region.

you

mark

left

and

button

are

editing

LISP

forms

button,

the

text
press

moving

the

same

place.

the

pointer

form

that

encloses

until

the

3.6.2.4

Cutting

and

Pasting

button

cut

the

middle

paste
cut

and

pointer

text

from

paste

text,

Mark

Press

Move

the

the
the

cut

cursor

ress

and

hold

current.

the

current

When

cursor,

you

1If

can

you

where

release

vyou

the

text

also

leave

this,

you
is

the

button

the

first

marked

the

left

pointer

button

first

time

press

the

pointer

The

the

moving

the

pointer

the

you

cursor.

pointer

marked.

current

has

these

pointer

text.

use

been

the

buffer

pointer

the

C)""U

insertion

cursor,

Enclosing

Each
a

LISP

forms

are

reached.

with

middle

paste

4--4-r~.

paste

However,

cursor.

flnally

moves

that

button

the

text

1is

pointer

cursor.

pointer

you

can

left

text between

cursor

form

the

pointer
the

regions.

pointer

outermost

than

The

button without

pointer
Press

you

text

and Marking Text

the

move

code,

cursor
left

window was

other

press

cursor

and where

that

the

screen.

without

select

the

The

time

window

the

pointer

window.

window,

insertion cursor

vyou

marked

LISP
as

time

from

the

press

last
a

insertion cursor also moves.

‘pressed

current

button

down

the

When

window,

Insertion Cursor

the

insertion

cursor

current

was

window

current

button

Text

1left

left button

the

press
a

the

select

middle
region.

left

pointer

button

depressed

the

p01nter

cursor

position.

steps:

using

any

button
to

window,

marked

method.

cut

the p051t10n

the

text.

which

you want

|
the

left

pointer

button,

then

press

the

middle

USING THE VAX LISP EDITOR

3.6.2.5
When
to

Invoking

you

are

invoke

symbol,

and

the

then

the

LISP

press

displays

DESCRIBE

editing

the

LISP

DESCRIBE

the

you

can

function.

right

results

Function

code,

wusing

cursor

use

Move

button.

And

The

the

Matching
the

the

you

right

move

the

pointer

3.6.2.6
a

pointer

information

area.

mark.

When

invoked

the

pointer

the

held

the

key

Guide

(if

function

the

You
the

cursor
pointer

displayed

the

current

invoked

cursor

way

with

buttons

the

Effects

by moving

any

parenthesis

invokes

displayed

any)

pointer

button,

one

can

appears

the

that

you

releasing

the

button

information

the

that

command

area

that

analogous

press

the

out

large

name

When

that

cursor
of

information

invoked

find

highlighted.

pointer

window.

the

displays

then

and

appears

what
to

the

command

area.

Note

button when

release

the

question

the

button,

displayed.

with

the

invoked

buttons

pointer

state.

Pointer Buttons to Commands

pointer

sequences

for

press

right
left

window

button

cursor

help

DESCRIBE

Pointer

pointer

certain

Binding

The

matching

button

command

cursor

movement

3.6.3

you

that

command

Moving

the

Information About

action

that

pointer

button,

pointer

Editor’s

symbol.

Parentheses

right

buttons

commands

commands.

See

the

information.

3-49

VAX LISP/VMS

binding

Editor

keys

Programming

CHAPTER 4
ERROR HANDLING

The

LISP

signaled
error

system

handler

error

handler
create

error

4.1
The

ERROR
VAX

four

LISP

also

error

the

three

nested

Checks

Displays
about

your

programming

needs,

The

this

procedure

errors

are

explains what

Because

handler.

when

chapter

signaled.

function,

the

VAX

for

the

system’s

LISP

allows

creating

chapter.

UNIVERSAL-ERROR- HANDLER,

nested

errors

have

occurred,

displays

message,

read-eval-print
to

the

type

the

Performs
was

performs

error

that

have

occurred.

error

handler

returns

vyou

otherwise,

the

handler

the

and

loop;

the

step.

error.

message

that

provides

you with

information

error.
the

aborts

appropriate

operation

for

the

type

error

that

signaled.

VAX LISP
of

ERROR TYPES
errors

program:

error

number

program,

types

meet

handler

continues

Three

error

handler

This

steps.

top-level

4.2

LISP error

explained

Checks
your

not

own

VAX

evaluation.

HANDLER

sequential
1.

when

might
your

handler

the

program

does

you

invokes

during

Fatal

error

can

occur

during

the

evaluation

LISP

ERROR HANDLING

Continuable

Warning

error

type

error

that

was

signaled

error

system displays
When an error is signaled, the VAX LISP
information:
following
the
with
you
provides
that
message

error,

fatal

The

The name of the function that caused the error

The name of the function that was used to signal the error

continuable error,

ERROR,

CERROR,

or warning

WARN

A description of the error

If a continuable error, an explanation of what will happen if
you continue the program’s evaluation from the point at which
the

error occurred

The format of an error message and the information a message provides
The next three sections describe the
depend on the type of the error.
-error
types of errors; each description includes the
performs.
handler
error
the
operation
format and the

4.2.1

Fatal

type’'s

message

Errors

When a fatal error is signaled, the error handler displays
in

the

following

format:

Fatal error in function function-name (signaled with ERROR).
Error description.

In the preceding format description, function-name is the name of the
function that caused the error, and ERROR is the name of the function
The error
(see Table 4-1).
that was used to signal the error
message
The
occurred.
error
the
why
telling
message
a
is
description
to
<call
the
in
arguments
the
and
string
format
the
from
is generated
one
than
more
on
displayed
be
can
message
the
the ERROR function;
Tanmno

ode de 4 d Vs

An example of a fatal error message follows:

Fatal error in function MAKE-ARRAY (signaled with ERROR).

Only vectors can have fill pointers.

After the message is displayed, the error handler checks the value of
1Its value can be either the
the VAX LISP *ERROR-ACTION* variable.
:EXIT or the :DEBUG keyword.

The /ERROR_ACTION DCL qualifier you
4-2

use

ERROR

with

the

when

you

LISP

:EXIT

(you

error

handler

value

the
VAX

program’s

value

(see

the

Chapter

ERROR_ACTION=EXIT

the

LISP

system

wused

default

After

the

system

(you

LISP

debugger

program.

your

the

:DEBUG

the

sets

LISP

causes

invokes

the

wused

qualifier),

command

invoke

HANDLING

the
an

*ERROR-ACTION*

2).

form

exit

When
of

the

qualifier),

the

error;

ERROR_ACTION=DEBUG

interactive

variable
value
when

the

form

session),

the

handler

error

in your

debugger.

invoked,
you

you can use

locate

the

error,

you

locate

can

the

correct

and

from

the

restart

evaluation.

NOTE
You

cannot

point

The

*ERROR-ACTION*

described

4.2.2
When

the

Error

If
the

that

used

signal
message

generated

from

CERROR
line

the

value

text

LISP
a

the

error

and

the

debugger

handler

displays

(signaled

with

error

displayed,

CERROR).

will

(see

the

for

error

Section

4-3

happen

The
the
you

the

error
message

call

than

one

continue

description.

(signaled with

the

3.2.1).

CERROR).

new value.

handler

function

The

error

variable

4-1).

occurred.

on more

what

prompted

the

arguments

ENTER-NAME
a string.

name

displayed

function
not

the

message is:

name

the

can

the

Table

error

*ERROR-ACTION*
error

the

and

explains
follows

(see

why

string

You will

fatal

error

message

function-name

CERROR

the

specified

and

telling

that

error

you

message

after

explanation.

continuable

continued:

the

VAX

Part

function-name

format

evaluation

Continuable

After

the

function;

program’s

function

error,

The

signaled,

description,

the

example

format

1is

format:

Continue

caused

description

error

preceding

line.

described

description.

function

your

evaluation

occurred.

Errors

continued:

was

program’s

error

following

Continuable

your

fatal

variable

continuable
in

Chapter

Continuable

message

continue

which

checks

same

way

the

value

checks

the

ERROR HANDLING

If the debugger is invoked, you can do one of the following:

the

CERROR

performs

function

Continue from the error;

After you locate the error,
Locate the error in your program.
program’s evaluation.
your
restart
and
it
correct
you can

corrective action that is specified in the error message.

the

The *ERROR-ACTION* variable is described in Part II and
is

the

described

4.2.3

in Chapter

debugger

Warnings

A warning is an error condition that exists in your program, which may
When this type of error
or may not affect your program’s evaluation.
reasons:
following
the
occurs, the system displays a message for

You might want to correct the error later.

Your program might correct the error, but you should know that
the error occurred.

When a warning is signaled, the error handler displays
the

following

message

format:

Warning in function function-name (signaled with WARN).
Error description.

In the preceding format description, function-name is the name of the
function that caused the error, and WARN is the name of the function
The error
(see Table 4-1).
the error
that was used to signal
message
The
occurred.
error
the
why
telling
message
description 1is a
to
call
the
in
arguments
the
and
string
format
is generated from the
line.
one
than
more
on
displayed
be
the WARN function; the message can
An example of a warning error message 1is:

Warning in function TE
3

is not a

(signaled with WARN).

symbol.

After the message is displayed, the error handler checks the value of
the *BREAK-ON-WARNINGS* variable in the same way it checks the value
*ERROR-ACTION* variable after a fatal error (see Section 3.2.1).
NOTE

1f the value of the *BREAK-ON-WARNINGS* variable 1is T,
the debugger is invoked when a warning is signaled.

ERROR

the

debugger

program.

After

debugger,

and

where

error

The

the

invoked,
you

then

continue

can
the

your

The

variable

*ERROR-ACTION*

4.3

CREATING AN ERROR HANDLER

Create

your

described

Chapter

error

your

handler.

own error

This

handler

programming needs.
1.

Define

Bind

locate
can

the

error

it,

exit

correct

evaluation

from

the

your
the

point

the

error

the

create

COMMON

variable

binding

described

LISP:
Part

The

II,

and

the

LISP '*UNIVERSAL-ERROR—HANDLER*

system’s

to
you

described

variable

debugger

The VAX

program’s

the

use

error,

occurred.

*BREAK-ON-WARNINGS*

Language.

you

1locate

HANDLING

system’s

1is

provides

error

bound

you

handler

with

does

way

not

meet

you must:

handler.

*UNIVERSAL-ERROR-HANDLER*

variable

your

defined

handler.
The

*UNIVERSAL-ERROR-HANDLER*

4.3.1
To

Defining

define

This
LISP

system

time

error-handler

arguments

able

least

occurs

function-name
The

handler,

must

passes

error

described

Part

II.

Error Handler

error

function

variable

you
to
two

must

define

arquments

program.

definition

two

the

error
more

the

following

error

function.
since

handler

specify

the

the
each

arguments

format:

&REST

handler

arguments
error

Therefore,

error-signaling-function

provide

an
or

args

with

the

following

information:

The

name

the

function

that

called

the

error-signaling

function

The

name

the

The

arguments

error-signaling

that were

passed

4-5

function
to

the

error-signaling

function.

ERROR HANDLING

An example of an error handler definition 1is:
Lisp>

(DEFUN CRITICAL-ERROR-HANDLER

(FUNCTION-NAME
ERROR-SIGNALING-FUNCTION
&REST

(WHEN

(OR

ARGS)

(EQ ERROR-SIGNALING-FUNCTION
(EQ ERROR-SIGNALING-FUNCTION

’ERROR)
’CERROR))

)
(FLASH-ALARM-LIGHT)

(APPLY #’UNIVERSAL-ERROR-HANDLER
FUNCTION-NAME

ERROR-SIGNALING-FUNCTION
)
ARGS)

CRITICAL-ERROR-HANDLER

The preceding error handler checks whether a fatal or continuable
If either type of error 1is signaled, the handler
error 1is signaled.
M-LIGHT and then passes the error signal
FLASH-ALAR
calls the function
information to the VAX LISP error handler.

When you define an error handler, the definition can include a call to
If the definition does not
the UNIVERSAL-ERROR-HANDLER function.
include a call to this function and you want the handler to check the

of the *ERROR-ACTION* or *BREAK-ON-WARNINGS* variable, you must

value

include a check of the variable in the handler’s definition.

If you want an error handler to display error messages in the

described in Sections
UNIVERSAL-ERROR-HANDLER

4.2.1
or

formats

to 4.2.3, include a call to either the
function.
PRINT-SIGNALED-ERROR

Descriptions of these functions are provided in Part II.

The next three sections describe the arguments an error
be

able

handler

mnmust

accept.

4.3.1.1 Function Name - The function-name argument is the name of the
This argument
function that <calls an error-signaling function.
in the error
name
s
enables the error handler to include the function’

message

the handler displays.

error-signaling-function
Function - The
4.3.1.2 Error-Signaling
that is called to
function
naling
error-sig
argument is the name of the
is called, a
function
which
on
generate the error signal. Depending
.
signaled
is
fatal error, continuable error, or warning
The

error

handler

uses

the

error-signaling-function

determine the contents of the args argument.

argument

the
as
passed
be
can
Table 4-1 1lists the functions that
function.
each
describes
briefly
and
argument
error-signaling-function
4-6

ERROR HANDLING

Table 4-1:

Error-Signaling Functions

Function

Description

CERROR Function

Signals a continuable error

ERROR

Signals

Function

WARN Function

fatal

error

Signals a warning

See COMMON LISP:
The Language for detailed descriptions of the CERROR
and
ERROR
functions.
See
Part
II
for
a description of the WARN
function.

4.3.1.3
Arguments - The args argument is the list of arguments passed
to
the
error-signaling function when the error-signaling function 1is
invoked.
The contents of
the
1list
depends
on
which
function
1is
invoked.
The
1list
can
include one or two format strings and their
corresponding arguments.
The format strings and arguments are
passed
to the FORMAT function, which produces the correct error message.

4.3.2

Binding the *UNIVERSAL-ERROR-HANDLER* Variable

Once
you
define
an
error-handling
function,
you
must
bind
the
*UNIVERSAL-ERROR-HANDLER* variable to it.
The following example shows
how to bind
Lisp>

the variable
(LET

to a

function:

((*UNIVERSAL-ERROR-HANDLER%*

)
#’CRITICAL-ERROR-HANDLER)
(PERFORM-CRITICAL-OPERATION)
)

The LET special form binds the *UNIVERSAL-ERROR-HANDLER*
variable
to
the
CRITICAL-ERROR-HANDLER function that was defined in Section 4.3.1
and calls a function named PERFORM-CRITICAL-OPERATION.
When the
form
is
exited
because
the
evaluation finished or the THROW function 1is
called, the *UNIVERSAL-ERROR-HANDLER*
variable
1is
restored
to
1its
previous

value.

CHAPTER 5
DEBUGGING FACILITIES

Debugging

errors.

When

displays

the

error

message,

which

information:

the

error,

the

name

error,

and

Once
use

the

know

the

VAX

LISP

programming
with

type,

the

function

name

detailed

descriptions.

Table 5-1:

Debugging

correcting

the

VAX

you

with

name

the

LISP

your

the

initial

function

system

programming

error

that

wused

handler

debugging
caused

the

signal

the

error.

function

functions

Table

brief

and

the

debugging

error.

1locating

signaled,

provides

error

description

you

macros

process

5-1

that
and

lists

description

Functions and

macros

the

caused

error,

locate

debugging

each.

See

you

and

can

correct

functions
Part

for

and
more

Macros

Function

Name

or Macro

Description

APROPOS

Function

Locates

contain

symbols

substring
each
APROPOS-LIST

Function

and

symbol

Locates

contain

whose

specified
1t

displays

information

whose

specified

and

locates.

the

break

string

returns

symbols

about

names

arqument

1list

BREAK

Function

Invokes

DEBUG

Function

Invokes the VAX LISP debugger.

DESCRIBE

Function

Displays

detailed

specified

object.

5-1

names

argument

locates.

symbols

substring

string

the

loop.

1information

about

DEBUGGING FACILITIES

Table

5-1

(cont.)

Function

Name

or Macro

Description

DRIBBLE

Function

Sends the input and
interactive

the

output

LISP session to a specified

file.

Function

Invokes the VAX LISP Editor.

ROOM

Function

Displays information about the state

STEP

Macro

Invokes the

TIME

Macro

Displays timing

TRACE

Macro

internal

storage

and

its management.

stepper.

evaluation of a

about

information

the

specified form.

tracer

for

functions

and

Disables the tracer

for

functions

and

you

with

the

Enables the
macros.

Macro

UNTRACE

macros.

This

the

chapter provides

following:

provide

A list of the functions and the macro that

Descriptions of two variables that control the output

debugging

debugger,

information

the stepper,

and the tracer facilities

A description of the VAX LISP control stack

Explanations of how to use the following debugging facilities:
--

Break loop
-

A read-eval-print loop you can invoke while

system is evaluating a program.

the LISP

stack
control
A
-Debugger
and
inspect
to
interactively
control

stack

Stepper

Tracer

through a

use
can
you
debugger
LISP system’s
the
modify

frames.

A facility you can use interactively

step

form’s evaluation.

evaluation.

A facility you can use to inspect

program’s

DEBUGGING FACILITIES

Editor

programs

5.1

An extensible editor that enables you

and

data

edit

structures.

CONTROL VARIABLES

VAX LISP provides
two
variables
that
control
the
output
of
the
debugger,
the
stepper,
and
the
tracer
facilities:
*DEBUG-PRINT-LENGTH* and
*DEBUG-PRINT-LEVEL%*.
These
variables
are
analogous
to
the
COMMON
LISP
variables
*PRINT-LENGTH*
and
*PRINT-LEVEL* but are used only in the debugger.

*DEBUG-PRINT-LENGTH*
|

Controls the number of displayed elements
at
each
level
of
a
nested
data object.
The
variable’s value must either be an integer or
NIL.

*DEBUG-PRINT-LEVEL*

The default value

(no

limit).

Controls the number of displayed levels of
a
nested
data
object.
The
variable’s value
must
either
be
an
default value is NIL

5.2

is NIL

1integer
or
(no limit).

NIL.

The

CONTROL STACK

The control stack is the part of LISP
memory
that
stores
calls
to
functions,
macros,
and
special
forms.
The stack consists of stack
frames.
Each time you call a function, macro, or
special
form,
the
VAX LISP

system does
Opens

Pushes the name of the function associated with the function,
macro, or special form that was called onto the stack frame.

Pushes the function’s arguments onto the stack frame.

Closes the stack frame when all the function’s arguments

the

stack

following:

the

stack

Evaluates

the

frame.

are

frame.

function.

The LISP system can have several open stack frames at a
time
because
expressions.
LISP
frequently
are
functions
LISP
by
used
the arguments

Each control stack frame has a frame number,
which
1is
displayed
as
Stack frame numbers are displayed
the stack frame’s output.
of
part
in the output of the debugger,

the stepper,

and the

tracer.

DEBUGGING

There

always

one

active

FACILITIES

stack

frame,

and

can

either

Dbe

significant or insignificant.
Significant stack frames are those that
invoke documented and
wuser-created
functions.
Insignificant
stack
frames are those that invoke undocumented functions.
Debugger

commands

show

only

significant

stack

frames

wunless

specify
the
ALL
modifier
with
a
debugger
command
(see
5.5.3.1).
Significant stack frames store one of the following

A call

to a

function named by a

symbol

that

the

you

Section
calls:

current

package

See

A call to a function that i1s accessible in the current package
and
is
explicitly
or
implicitly called by another function
that is in the current package

COMMON LISP:

Many

stack

The Language

frames

functions.

These

therefore,
by
representation.

the

The

active

stack

call

the

stack

frames

frames,

ACTIVE STACK FRAME

function

information
store

are

internal,

insignificant

frame

LISP
in

the

you

can

stack

system

1is

active

stack

specify

frame

most users;

not
display
their
debugger and you want

modifier

stores

The

because

undocumented

the ALL

that

evaluating.

function’s
argument values.
Only one
and an active stack frame
can
exist

time

on packages.

default,
the
debugger
does
However,
1if you are using the

5.3

the

control

stack

to examine these stack
debugger commands.

function

for

system
the

<call

can

frame

with

¢to

evaluate

contains

all

stack frame is active at a
anywhere
on
the
control

stack.

The

active

stack

it
can
have
a
frame represents
stack

can have

next
active
the caller of

active

stack

frame

and/or

stack frame.
The previous active stack
the
function
1in
the
current
active

frame.

5.4

BREAK LOOP

The

break

loop

a
program.
evaluated.
placed

frame

read-eval-print

You
<can
1If you do,

the

loop

that

you

can

invoke

debug

invoke the break loop while a program is being
the
evaluation
1is
1interrupted
and
you
are

loop.

5-4

DEBUGGING FACILITIES

5.4.1

Invoking the Break Loop

You can invoke
ways

using

the break loop by calling the BREAK function.
the

BREAK

function

to debug

The

two

bind

program are:

Use the VAX LISP BIND-KEYBOARD-FUNCTION function

ASCII keyboard control character to the BREAK function.
Then
use
the
control
character
to
invoke
the
BREAK
function
directly
while
vyour
program is being evaluated (see Part II
for a description of the BIND-KEYBOARD-FUNCTION function)

Put the BREAK function in specific places

in your program.

In either
case,
the
BREAK
function
displays
a
message
(if
you
specified
one
in
vyour form calling the BREAK function) and enters a
read-eval-print loop.
If you specified a message, the BREAK
function
displays

the message

Break

the

following

function function-name

format:

(signaled with BREAK).

description.

In the preceding format description, function-name represents the name
of
the
function
the LISP system was evaluating when you entered the
break loop.
BREAK is the name of the function that
caused
the
LISP
system
to invoke the break loop.
The description
is optional and can
be printed on more than one line.
A description usually provides
the
reason

the

break

loop was

invoked.

An example

a break

Break

function CHECK-INPUT

Values

are

loop message

of your

(signaled with BREAK).

too high.

After the message is displayed,
margin

follows:

a prompt

1is

displayed

the

left

terminal:

Break>

5.4.2

Exiting the Break Loop

When you are ready to exit the break loop and continue your
evaluation, invoke the VAX LISP CONTINUE function.
Break>

The CONTINUE

continue

program’s

(CONTINUE)

from

function

the

causes
the
evaluation
of
your
program
to
point where the LISP system encountered the BREAK

function.

5-5

DEBUGGING

If you are in
function,

vyou

description

5.4.3

nested
are

the

break

placed

1loop

1in

CONTINUE

FACILITIES

and

the

you

invoke

function

the

break-loop

provided

Part

CONTINUE
level.

program

II.

Using the Break Loop

Once

you

doing

are

the

break

interacting

top-level
*FIRST*

loop.

and

Lisp>

For

with
named

*FIRST*

Lisp>

you

the

example,

function

(DEFVAR

loop,

can

LISP

check

system

suppose

you

COUNTER,

which

what
as

vyour

though

define
uses

the

you

were

variable
variable

the

named

*FIRST*,.

0)
|

(DEFUN
(IF

COUNTER NIL
(<

*FIRST*

(PROGN

100)

(INCF

*FIRST*)

(COUNTER))

*FIRST*)
)

COUNTER

you

bind

interrupt
For

the

BREAK

function

function’s

evaluation

control

typing

character,

the

control

you

can

character.

example:

Lisp>

(BIND-KEYBOARD-FUNCTION

#\"B

#'’BREAK)

Lisp>

(COUNTER)<RET>

Break>

Once

you

are

variable

the

break

1loop,

vyou

can

check

the

wvalue

the

*FIRST*.

Break)>

*FIRST*

16
Break)

you

call

COUNTER

After
was

value

the

CONTINUE

Break>

(CONTINUE)

you

call

the

continued

function,

the

evaluation

the

function

continues.

the

CONTINUE

function,

invoking

variable

the

*FIRST*.

CTRL/B

Break)>

you

break

*FIRST*

93
Break>

5-6

can
loop

see

that

again

and

the

evaluation

rechecking

the

DEBUGGING

Use

the

CONTINUE

Break>

function

again

FACILITIES

complete

the

function’s

evaluation.

(CONTINUE)

100

Changes

that

you

are

your

you

the

program

find

value,
effect

global

loop

continues.

that

you

make

break
the

can

after

For

value

change
you

variables

remain

the

example,

the

variable

variable’s

exit

the

and

effect

global

after

you

are

named

The

1loop

exit
the

*FIRST*

value.

break

definitions

you

and

loop

and

break

loop

and

has

change

continue

while

the

incorrect

remains

your

program’s

evaluation.

NOTE
The

forms

you

type

evaluated

they

are

cannot

you

5.4.4
The

evaluated

examine

interrupt

lexical

with

5.5).

For

LISP:

the

break

environment,

level.

variables

loop.

invoke

information
The

are

top

lexical

wvariables,

COMMON

break

loop

(-),

top-level

uses

loop

uses

preserve

values

VAX

the

are

though

Therefore,
of

you

program

examine

debugger

1lexical

loop

(see

that

those

Section

environments,

see

Language.

copy

asterisk

variables

The

the

you

1lexical

Break Loop Variables

hyphen

5.5

while

null

LISP

(*),

the

them

(see

the

input

system

top-level-loop

slash

(/),

COMMON

and
LISP:

expressions

variables

on)

The

you

the

while

you

are

control

stack

debugger.

the

and

the

These

the

break

(+),

way

Language).

specify

returns

(plus

same

output

loop.

DEBUGGER
VAX

LISP

debugger

interactively

The

debugger

frame.

The

current

commands

inspect

frames.

debugger

displayed

has

and modify
a

pointer

stack

frame

information.

the

that
is

The

LISP

points
the

You

system’s
to

1last

debugger

the

can

use

control
current

frame

for

stack
stack

which

provides

the

several

that:

Display help

Evaluate
stores

form or

reevaluate

function

call

stack

frame

DEBUGGING FACILITIES

errors

Handle

Move the pointer from one stack frame to another

Inspect or modify the function call in a stack frame

Display a summary of the control

stack

The debugger reads its input from and prints its output to the
bound to the *DEBUG-I0O* and the *TRACE-OUTPUT* variables.

stream

NOTE

The stack frames the debugger displays are

longer

active.

Before you use the debugger, you should be familiar with the VAX
The control stack is described in Section 5.2.
control stack.

5.5.1

LISP

Invoking the Debugger

You
The VAX LISP system invokes the debugger when errors occur.
function.
DEBUG
VAX LISP
the
calling
by
debugger
the
invoke

can
For

example:
Lisp>

(DEBUG)

debugger,
When the debugger is invoked, a message that identifies the
command
the
and
frame,
stack
current
the
identifies
that
message
a
prompt are displayed at the
left
margin
of
your
terminal
1in
the
following

format:

Control

Stack Debugger

Frame

#5:

Debug

(DEBUG)

The letter n in the prompt represents an integer, which indicates
the
number
of
the
nested
command
level
vyou
are
1in.
The value of n
increases by one each time the command level increases.
For
example,
If an error is invoked
the top-level read-eval-print loop is level 0.
from the top-level loop, the debugger displays the
prompt
Debug
1>.
If
you
make
a
mistake
again
causing
an
error
while within the
prompt
the
display
to
debugger
the
causes
error
debugger, that
Debug

2>.

After the debugger is invoked, you can use the
debugger
commands
stack.
control
system’s
the
of
contents
the
modify
inspect and

DEBUGGING

description

5.5.2
To

exit

the

Debug

use

the

QUIT

the

control

the
the

returns

provided

Part

II.

debugger

command.

command

causes

the

level.

QUIT

command

prompt

Debug

you

the

when
1>),

the
the

system’s

debugger

command

causes

level.

For

top

level

the

debugger

example:

QUIT

Debug

QUIT

specify

and

function

Debugger

return

Debug

you

DEBUG

debugger,

(indicated
exit

the

Exiting the

debugger

FACILITIES

Lisp>

default,

the

invoked.

you

QUIT

command

exits

For

Debug

the

debugger

displays

continuable

confirmation

error

causes

message

the

before

debugger

example:

1> QUIT

you

really

type

YES,

want

the

return

debugger

the

returns

control

command

the

level?

command

level.

you

really

want

return

the

prompts

you

for

the

command

level? YES

Lisp>
If

you

type

NO,

you

Debug

the

debugger

really want

return

another

command.

command

level? NO

You can prevent the debugger from displaying the confirmation
by

specifying

the

QUIT

command

with

value

other

than

message
NIL.

For

example:
Debug

1> QUIT

Lisp>

description

5.5.3
The

the

QUIT

command

provided

Section

5.5.3.2.

Using Debugger Commands

debugger

stack

frame

commands

let

you

inspect

and

other

stack

move

5-9

and

modify

frames.

the

You must

current
specify

control
many

DEBUGGING FACILITIES

the debugger commands with one or more arguments that qualify
operations.
These arguments are listed in Section 5.5.3.1.

command

You can abbreviate debugger commands to as few characters as you like,
as

long as no ambiguity is

in the abbreviation.

Enter a debugger command by typing the command
and then pressing the RETURN key.
Debug

name

abbreviation

For example:

BACKTRACE<KRET>

If you press only the RETURN key,

the debugger prompts you for another

command.

Table 5-2 provides a
summary
of
the
debugger
commands.
~descriptions of the commands are provided in Section 5.5.3.2.

Table 5-2:

Debugger

Detailed

Commands

Command

DesCription

BACKTRACE

Displays a backtrace of the control stack.

BOTTOM

Moves the pointer to the first stack frame on
control

CONTINUE

Enables you to correct a continuable error.

DOWN

Moves the pointer down the control

stack.

Redisplays the error message

was

ERROR

when the debugger was

invoked.

that

displayed

EVALUATE

Evaluates a

GOTO

Moves the pointer to a specified stack frame.

HELP

(or)

the

stack.

specified form.

Displays help text about the debugger commands.

QUIT

Exits to the previous command level.

REDO

Invokes the function in the current stack frame.

RETURN

Evaluates its arguments
and
causes
the
current
the
values
same
the
return
to
frame
stack
evaluation

Searches

returns.

the

control

function.

5-10

stack

for

specified

DEBUGGING FACILITIES

Table

5-2

(cont.)

Command

Description

SET

Sets the values of the components in
stack

Displays information stored in the

SHOW

the

current

stack

frame.

function

1in

the

TOP

Moves the pointer to the last stack frame

the

Moves the pointer up the control stack.

WHERE

Redisplays the argument list and the function name

STEP

Invokes

the

stepper

current

stack

frame.

control

in the

the

stack.

current

5.5.3.1 Arguments - Some debugger
debugger commands accept optional
is an integer is usually optional;
If you
required.
form 1is
or
required, the debugger prompts you
Debug

for

stack

frame.

commands require an argument; other
An argument whose value
arguments.
an argument whose value is a symbol
do not specify an argument that 1is
For example:
for the argument.

RETURN<RET>

First Value:

The debugger does not prompt for arguments if you specify them in
command

the

line.

Enter an arqument after the command it qualifies and
For

RETURN key.
Debug

then

press

example:

DOWN ALL<RET>

The types of arguments you can specify with debugger commands are:
command

Debugger

Symbol

FForm

Integer

Function name

5-11

the

DEBUGGING

FACILITIES

Modifier

NOTE
Only

parenthesized
expressions
evaluate
(that
1is,
arguments
EVALUATE command) are evaluated.

The

preceding

integer

and

arguments

modifier

are

and

arguments
specified
with

self-explanatory with

the

to
the

exception of

the

arguments.

Integer

arguments represent control stack frame numbers.
Each
stack
frame
on
the
control
stack
has a frame number, which the debugger
displays as part of the stack frame’s output.
The debugger
reassigns
these numbers each time it is invoked.
You can specify a frame number
in a debugger command to refer to a
specific
stack
frame.
If
you
refer to a frame number that is outside the current debugging session,
an error is signaled.
1If you refer to the stack
frame
number
of
a
frame
that
was established in another debugging session i1n a current
nested session, the command in which
vyou
specify
the
frame
number
results in an erroneous or unpredictable result.
Table
with

5-3

provides

debugger

Table 5-3:

summary of

the

modifier

Command Modification

ALL

Operates
stack

both

CALL

Operates

on the

DOWN

Moves

FUNCTION

Operates
stack

the

the
arguments
current stack

the

call

pointer

and

insignificant

on the

down

the
the

function

specified
frame.

current
control

object

stack

with

the

frame.

stack.

1in

the

current

frame.

HERE

Operates

NORMAL

Displays

the

significant

frames.

Operates
function

QUICK

specify

Debugger Command Modifiers

Modifier

ARGUMENTS

arguments you can

commands.

the

stack

function name

control

Displays

current

stack

5-12

and the

argument

1list

control

stack

frames.

function name

frames.

frame.

the

DEBUGGING FACILITIES

Table

5-3

(cont.)

Modifier

Command Modification

TOP

Starts a backtrace

the

top

the

control

stack.

Moves

VERBOSE

the pointer up the

Displays the
variable
in

the

control

function name,

bindings,

control

and

stack

stack.

argument

special

1list,

variable

1local

bindings

frames.

5.5.3.2
Debugger Commands - The VAX LISP debugger
provides
commands
that
vyou
use
to
move
through and modify the system’s control
stack.

Help Command

HELP
?

The
HELP command displays help text about the debugger
commands.
You
<can
specify
this
command
with
one
argument,
which
is
the
name of the debugger command
about which you want help text.
I1f
you
specify
the
HELP command without an argument, the debugger displays
a list of the debugger commands.
You can abbreviate
mark

this

command

wusing

question

(?).

Evaluation Command

You can evaluate LISP expressions while you are in
the
debugger.
If
you
want
the LISP system to evalute a
parenthesized form, you can specify the form
and
then
press
the
RETURN
key.
If
you
want
the system to
evaluate a symbol, you must use the
EVALUATE
command.
You can also evaluate expressions by entering the break
loop.
For information on the break loop,
see
Section
5.4.

EVALUATE

The EVALUATE command explicitly evaluates
form.

You

must

specify the

specified

command with an argument

that is the form you want the LISP system to
evaluate.
The
system
evaluates
the
form
in
the
1lexical
environment of the current stack frame.

5-13

DEBUGGING

FACILITIES

Error-Handling Commands

The

debugger

debugger.
deals
CONTINUE

The

errors

CONTINUE

command

letting
warning

vyou
1if

variable
CONTINUE

1s
T.
function.

error
QUIT

with

deals

Each

The

with

errors

the

following

that

invoke

debugger

the

commands

different way.

causes

return from a
the
wvalue
of
This
See

the

debugger

return NIL,

continuable error or from a
the
*BREAK-ON-WARNINGS*

command is not the same as
Chapter 3 for a description

the
of

types.

QUIT

level.

command
If

the

lets you
current

exit

level

command causes the debugger to
(Lisp>).
You can specify this

to
of

the

the debugger

command
is

the

exit to the LISP
prompt
command with an optional

argument.
If a continuable error invokes the
debugger
and
the
argument
is
NIL,
the
debugger
displays a
confirmation message.
If you respond to the message by
typing YES, the command returns control to the previous
command
level.
If
the
argument
1is
not
NIL,
the
debugger does not display a message.
The default value

for the optional argument is NIL.

REDO

The REDO command invokes the function
1in
the
current
stack
frame, causing the LISP system to reevaluate the
function in that frame.
This
command
1is
wuseful
for
correcting
errors
that
are
not continuable, such as
unbound variables and undefined functions.
To
do
so,
first
bind
the
variables or define the function with
the SET command, then use the REDO command.

RETURN

The RETURN command evaluates its arguments
and
causes
the debugger to force the current stack frame to return
the same
values
the
evaluation
returns.
You
must
specify
the
command
with an argument that i1s a form.
When the command is executed, the
form
1is
evaluated.
When
the
evaluation
is
complete,
the current stack
frame returns the same values that the
evaluated
form
returns.

STEP

The STEP command invokes the stepper for
the
function
that
1is
in the current stack frame.
When the stepper
is invoked, the LISP system reevaluates
the
function.
This

to get

command

is useful
information about

5-14

if you want to repeat an error
the cause of the error.

DEBUGGING

Movement
The

movement

another
stack
BOTTOM

The

stack

frame

ALL

The

DOWN

the

specify

the

pointer

displays

pointer

the

with
to

control

the

new

first

stack.

BOTTOM

the

stack

the

you

command,

first

(oldest)

whether

frame

the

toward

optional

arguments

the

pointer

one

command with

and

the

moves

stack,

significant

You

debugger

pointer

control

command

this

debugger’s

the
stack

frame

1is

insignificant.

specify ALL,

1is

the

command moves

bottom

You

can

arguments.
ALL

the

1insignificant

the

time.

One

1If

you

modifier.

pointer

stack

down

the

frames

stack.

can

which

also

specify

1indicates

command

the

optional

number

to move

the

integer

arqument,

frames

down which

stack

pointer.

The GOTO command moves the pointer to a specified stack
frame.

that
SEARCH

optional

control

GOTO

the

control

the

modifier

moves
on

The

moves

significant
DOWN

frame.

the

information.

stack

the

command

move

command

significant

specify

Commands

commands

frame’s

BOTTOM

FACILITIES

You

specifies

must

specify

the

number

this

command with

the

stack

The SEARCH command searches the
specified
with

two

name.
The

the

command’s

name

function
arguments.

the

DOWN modifier
search.

the

control

You must
first

The

function

specify

second

for

the

for

this

must

command

either

direction

argument

which

integer

stack

specify

argument

frame.

must

command

of
the

search.

You
This

the

can

also

command

indicates
function
TOP

The

TOP

specify
command

must

name

number
that

stack

the

moves

the

with

pointer

stack whether

insignificant.

5-15

the

control

the

TOP

the

last

frame

argument.
argument

vyou

command

pointer

the

name

1integer

occurrences

frame
on

the ALL modifier

1integer

function

The

you want

command moves

control

optional
the

specification.
the

significant

the

specify

argument

the

specify
specified

skip.

last

stack.

(newest)

1If

command,
stack

frame

significant

you

the
on

DEBUGGING FACILITIES

The UP command moves the pointer toward the top of
the
control
stack.
You
can
specify
this
command with
optional arguments.
One of the optional
arguments
1is
the ALL modifier.
1If you specify it, the command moves
the pointer up the significant and insignificant
stack
frames on the control stack.
You can also specify an optional integer argument.
It
indicates
the
number
of
stack
frames
up which the
command is to move the pointer.

WHERE

The WHERE command
redisplays
the
argument list in the current stack

function
frame.

name

and

Inspection and Modification Commands

You
<can
inspect
and
change
the
information
1in
a
function
call
before
the
LISP
system evaluates the
call.
To do this, use the inspection and
modification
commands.
ERROR

The ERROR command redisplays the error message that was
displayed for the error that invoked the debugger.

SET

The SET command sets the values of
the
components
in
the current stack frame.
You must specify this command
with three
arguments.
The
first
argument
must
be
either
the
ARGUMENTS
or
the FUNCTION modifier.
The
modifier
determines
what
the
command
sets.
The
following
1list
describes what is set when you specify
each modifier:

ARGUMENTS -- The value of an argument in the current
stack frame.

FUNCTION -- The function object in the current stack
frame.

If you
specify
the
ARGUMENTS
modifier,
the
second
argument
must be the symbol that names the argument to
be set, and the third argument
must
be
a
form
that
evaluates
to
the
new
value.
I1f
you
specify
the
FUNCTION modifier, the second argument must be
a
form
that evaluates to a function or the name of a function.
The new function must take the same number of arguments
the
SHOW

old

function

takes.

The SHOW command displays
information
stored
1in
the
current
stack
frame.
You
must specify this command
with the ARGUMENTS, CALL, FUNCTION, or
HERE
modifier.
The modifier determines what the command is to display.

5-16

DEBUGGING FACILITIES
The

following

when

you

ARGUMENTS
stack

describes what

-- A list

the

command

displays

modifier:

the

arguments

in the

current

frame.

CALL -- The function call that created
the
current
stack frame.
The command displays the function call
so that its output 1s easy to read.
The
arguments
in

list

specify each

the

call

are

represented

their

values.

FUNCTION -- The function in the current stack frame.
The
function
can be either interpreted or compiled
with the COMPILE function.
The function
cannot
be
displayed
if
it
is
a system function or
loaded in a compiled file.

HERE

-- A description of

the

current

stack

1is

frame.

Backtrace Command
BACKTRACE

The BACKTRACE command displays
the
argument
1list
of
each
stack
frame
in the control stack, starting from
the top of the stack.
You can specify the command with
modifiers
to
specify
the
style
and
extent
of the
backtrace.

The

modifiers

you

can

specify are ALL,

NORMAL,

QUICK,

HERE,
TOP,
or
VERBOSE.
By default, the command uses
the NORMAL and the TOP modifiers.
The
following
1list
describes
the
style
or
extent the BACKTRACE command
uses when you specify each modifier:

ALL

-- Displays significant and insignificant

stack

frames.

NORMAL -- Displays the function
list

each

stack

name

and

argument

frame.

QUICK -- Displays the function name

each

stack

current

stack

frame.

HERE -- Starts the backtrace at

the

frame.

TOP -- Starts
control

the

backtrace

the

top

the

stack.

VERBOSE -list,
and

Displays
the
function
name,
argument
local
variable
bindings
in each stack

frame.

5-17

DEBUGGING FACILITIES

5.5.4

Using the DEBUG-CALL Function

representing the call at the
The DEBUG-CALL function returns a list funct
ion is a debugging tool and
current debug stack frame. This by DEBUG
-CALL can be used to
takes no arguments. The list returned ion in the
current stack frame.
access the values passed to the funct returns NIL.
The following
If used outside the debugger, DEBUG-CALL
example shows how to use the function:
Lisp> (SETE THIS-STRING "abcd")
"abcd"

Lisp> (FUNCTION-Y THIS-STRING 4)

Error in function FUNCTION-Y
.
Frame #4 (FUNCTION-Y "abcd" 4)

Debug 1> (SETF STRING (SECOND (DEBUG-CALL)))
"abcd"

Debug 1> (EQ "abcd"” STRING)
NIL

)

Debug 1> (EQ THIS-STRING STRING

frame 1is FUNCTION-Y.
In this case, the function in the current stack
TION-Y "abcd" 4). The
The call to (DEBUG-CALL) returns the list",(FUNC
the first argument to
form (SECOND (DEBUG-CALL)) evaluates "abcd
ned

that the string retur
FUNCTION-Y in the current stack frame. Note
same string passed to the
by the call (SECOND (DEBUG-CALL)) is theiptio
n of the TRACE macro for
See the descr
function FUNCTION-Y.
|
another example of the use of the DEBUG-CALL function.
5.5.5

Sample Debugging Sessions

(CAR X))
Lisp> (DEFUN FIRST-ELEMENT (X)
|

FIRST-ELEMENT

Lisp> (FIRST-ELEMENT 3)

Fatal error in function CAR (signaled with ERROR).

Argument must be a list: 3
Control Stack Debugger
Frame #11: (CAR 3)
Debug 1> DOWN

Frame #8: (BLOCK FIRST-ELEMENT (CAR X))

Debug 1> DOWN

Frame #5:

(FIRST-ELEMENT 3)

Debug 1> SHOW HERE
It

Format:

cons

FIRST-ELEMENT X

-- Arguments
X : 3

5-18

DEBUGGING

Debug

Type

FACILITIES

SET

Argument

"(1

New Value:
Debug

Frame

#5:

Debug

operation:

Name:

ARGUMENT

WHERE

(FIRST-ELEMENT

3))

REDO

Lisp>

The argument in a stack frame
list,
and
the
function
1is

is changed from an integer to a
reevaluated
with
the correct

argument.

Lisp>

(DEFUN

PLUS-Y

(X)

Y})

PLUS-Y

Lisp>

(PLUS-Y

Fatal error in function SYSTEM::%EVAL

Control
Frame

(signaled with ERROR).

Y
no value:

has

Symbol

Stack Debugger

#8:

PLUS-Y

(BLOCK

Debug

Frame

#5:

Debug

Frame

#8:

Debug

(SETF

Debug

WHERE

Frame

#8:

(BLOCK

Debug

EVALUATE

X Y))

DOWN

(PLUS-Y

PLUS-Y

(BLOCK
Y

Evaluate:

PLUS-Y

Debug

Frame

#5:

Debug

DOWN

(PLUS-Y

REDOC

5
Lisp>

The value of the variable Y is set with the SETF
the body of the function PLUS-Y is reevaluated.

Lisp>

(DEFUN

ONE-PLUS

(X)

(1+

X))

ONE-PLUS

Lisp>

(ONE-PLUS

"(1

4))

Fatal error in function 1+
Argument must be a number:

(signaled with ERROR).
(1 2 3 4)

Control Stack Debugger
Frame #11: (1+ (1 2 3 4))

5-19

macro,

and

DEBUGGING

Debug

SET

Function:

FACILITIES

FUNCTION

'CAR
WHERE

Debug

Frame

#11:

Debug

(CAR

4))

DOWN

Frame

#8:

Debug

(BLOCK

ONE-PLUS

(1+

X))

Frame

#11:

Debug

(CAR

4))

REDO

Lisp>

(PPRINT-DEFINITION

(DEFUN

ONE-PLUS

(X)

(1+

’‘ONE-PLUS)
X))

Lisp>

This

example

frame

does

the

5.6

shows
not

function

that

changing

change

that was

the

contents

originally

contents
of

other

stack

frames

evaluated.

STEPPER

The stepper is a facility you can use to
the

evaluation

commands

form.

displays

and

You

can

evaluates

step

control
each

1interactively
the

through

stepper with

subform

stepper

specified

form.
The

stepper

the

system’s

has

for

which

pointer

control

the

that

stack.

stepper

points

The

displayed

the

current

stack

frame

stack

frame

the

last

frame

information.

The stepper prints its command interaction to the stream bound to

the

*DEBUG-IO*

the

variable;

*TRACE-OUTPUT*

5.6.1
You

prints

its

output

the

stream bound

variable.

Invoking the Stepper
can

invoke

argument.
function

named

Lisp>
When

the

first

output

the

The

following

#9:

calling

the

(STEP

displayed

the

displays

specified
1left

Step>

5-20

line

form and

margin

format:

(FACTORIAL

stepper with

form as

call

3))

invoked,

the

the
|

(FACTORIAL

subform of

STEP macro with

invokes

FACTORIAL:

stepper

following example

the

text

that

stepper

your

1includes

prompt.

terminal

1in

The
the

DEBUGGING FACILITIES

After the stepper is invoked, you can
use
the
stepper
commands
to
the stepper performs and the way the stepper
operations
the
control
displays

5.6.2

output.

Exiting the Stepper

Usually,
stepper
from the
command.
previous

the
when you use the stepper, you press the RETURN key until
If you want to exit
steps through the entire specified form.
stepper
stepper before it steps through a form, use the QUIT
the stepper to return control to the
causes
command
This
command level that was active when the stepper was invoked.

Step>

QUIT

Lisp>

By default,

the QUIT command displays a confirmation message before 1t

causes the stepper to exit.
Step>

Do you

For example:

QUIT

really want to exit the

stepper?

If you type YES, the stepper exits and returns control to the
level that was active when the stepper was invoked.
Do you

really want to exit the

command

stepper? VES

Lisp>

If you type NO,
Do you

the stepper prompts you for another command.

really want to exit the

stepper? NO

Step>

message
confirmation
You can prevent the stepper from displaying the
For
NIL.
than
other
a value
command with
QUIT
the
specifying
by
example:
Step>

QUIT

Lisp>

A description of the QUIT command is provided in Section 5.6.4.2.

5.6.3

Stepper Output

the
Once you invoke
types
displays two
form:

stepper
the
form,
specified
stepper with a
of information as the LISP system evaluates the

DEBUGGING

A description

each

the

description

subform

descriptions

being

subform
return

evaluated

FACILITIES

line

the

value

from

symbol,

text

specified
each

the

that

form

subform

stepper

includes

displays

the

following

information:

The

The nested level

The

control

and

its

The

symbol

The

return

stepper

When

the

After

stack

following

#n:
If

the

symbol

frame

number

value

are

that

indicates

where

the

symbol

stored

value

indicates

making

control

stack

return

number

the

nested

level

nested

levels

increases,

appropriate

frame

indentation,

number,

the

symbol

the
the

symbol,

with

stepper

and

indentation.

indentation

the

increases.

displays

return value

the

format:

symbol

subform

return-value

being

evaluated

descriptions

1line

not

symbol,

text

that

the

stepper

includes

the

displays

following

information:

The

nested

The

control

subform
@
The

The

stepper

When

the

After

#n:
The

the

stack

subform

frame

number

that

indicates

where

the

stored

the

nested

level

nested

levels

increases,

appropriate

frame

number

indentation,

and

the

subform with

the
the

subform

includes

the

indentation.

indentation
stepper

the

increases.

displays

following

the

format:

(subform)
of

The

nested

The

control

value

the

stack

indicates

number

description

subform

making

control

level

The

return

level
stack

value

the

return

value

frame

number

that

stored

return

value

5-22

following

indicates

information:

where

the

return

DEBUGGING

The

stepper

also

indentation.
corresponding

stepper
in

the

indicates
The

After

displays

#n =>
Suppose

nested

indentation

call.

following

the

FACILITIES

making

control

level

matches
the

stack

each

the

return

appropriate

frame

value

indentation

number

with

the

indentation,

the

and

the

return

value

format:

return-value

you

define

Lisp>

(DEFUN

( IF

function

FACTORIAL

(<=

1 )

named

FACTORIAL.

(N
{ N)
¥
&

( (*

(FACTORIAL

1)))))

FACTORIAL

The

following

displays

example

when

Lisp>

you

illustrates

invoke

with

the

format

form

the

output

(FACTORIAL

the

stepper

3):

(STEP (FACTORIAL 3))

#4: (FACTORIAL 3)
Step> STEP

: #10:
.

(BLOCK FACTORIAL (IF (<= N 1)

: #14:

(IF (<= N 1)

(* N (FACTORIAL (- N 1)))))

(= N (FACTORIAL (- N 1))))

Step> STEP

+ . ¢ #18:
Step> STEP
s

(<= N 1)

#22:

N => 3

#18 => NIL

: ¢+ ¢ #17: (* N (FACTORIAL (- N 1)))
Step> STEP
s

#21:

oot

N => 3

#29:

---- #27:
oo

(BLOCK FACTORIAL (IF (<= N 1) 1 (= N (FACTORIAL (- N 1)))))

#27 => 2

N => 3

#26 => 2

#21-=> 2

#17 => 6

#14 => 6

#10 => 6

#4 => 6
6

Note

that

preceding

indicates
indicated
indicates
an

by a

the
the
the

function

has

nested

with

1integer.

colon

FACTORIAL

example,

three

1level

colon

followed

number

stack

The

integer

recursive

each

the

1levels

o0f

subform
by

frame

preceded with

(#n:).

5-23

function

and,

recursion.

with

space
which
a

(:
a

the

stepper

indentation,

call

number

The
The
is

sign

stepper

stored
and

with

followed

DEBUGGING FACILITIES

The nested level of each return value matches the indentation of the
The stepper indicates the number of the
corresponding subform.
control stack frame onto which the LISP system pushes the value with
an integer that matches the stack frame number of the corresponding
is preceded by a number sign and followed by an
The integer
subform.
arrow (#n =>)

that points to the return value.

Using Stepper Commands

5.6.4

Stepper commands let you wuse the stepper to step through the
You must specify some
evaluation of a LISP expression, form by form.
commands with arguments. They provide the stepper with additional
information on how to execute the command.

like,

You can abbreviate stepper commands to as few characters as you
as long as no ambiguity is in the abbreviation.

Each time a command is executed, the stepper displays a return value
if the subform returns a value, displays the next subform, and prompts
Enter a stepper command by typing the
you for another command.
command name or abbreviation and then pressing the RETURN key. For
example:
Step>

STEP<RET>

#22:

(IF

(<= N 1)

(* N (FACTORIAL

(- N 1))))

Step>

the LISP system evaluates the
If you press only the RETURN key,
If the evaluation returns a value, the
subform the stepper displays.
stepper displays the value and the next subform and then prompts you
for

another

command.

Step><RET>
#22:

(IF

(<= N 1)

(* N (FACTORIAL

(- N 1))))

Step>

Table 5-4 provides a summary of the stepper commands.

the stepper commands are provided in Section 5.5.4.2.

Table 5-4:

Descriptions of

Stepper Commands

Command

Description

BACKTRACE

Displays a backtrace of a form’s evaluation.

DEBUG

Invokes the debugger.

EVALUATE

Evaluates

specified

disabled.

5-24

form

with

the

stepper

DEBUGGING FACILITIES

Table

5-4

(cont.)

Command

Description

FINISH

Finishes

the

evaluation

specified
in
the
stepper disabled.

HELP

(or)

Evaluates
with

the

SHOW

Displays

QUIT

Exits

RETURN

the

subform

form

that

was

STEP macro with

the

the
the

Arguments

subform

specify with
Integer

Form

Stepper

the

current

stack

frame

the

current

stack

frame.

stepper.

the

subform

the

current

stack

Stepper

the

subforms with

the

stepper

command arguments modify

stepper

frame

enabled.

disabled until

stepper
gets back to a subform that
subform in the current stack frame.

commands
perform.
some commands accept

®@

disabled.

stepper

Evaluates

can

the

stepper

Evaluates

with

you

the

Forces the current stack frame to return a value.

STEP

5.6.4.1

Displays help text about the stepper commands.

OVER

the
stepper
argument, and

call

the

Some
stepper
commands
optional arguments.
The

commands

contains

operations

require an
arguments

are:

command

NOTE
Only
parenthesized
expressions
evaluate
(that
1is,
arguments
EVALUATE command) are evaluated.

Enter

an arqument

key.

For
Step>

after

the

command

it modifies

example:
EVALUATE

(<=

and
arguments
specified with

1)<RET>

5-25

and press

to
the

the

RETURN

DEBUGGING FACILITIES

and you omit 1it,
required

If an argument is

the

]

EVALUAL E <

Evaluate: -

you

Step>

prompts

For example:

argument.
mx

the

for

stepper

the

The stepper does not prompt for arguments if you specify them
command

line.

5.6.4.2

Stepper Commands - The stepper provides commands that let you

control how it steps through a form’s evaluation.

Help Command

HELP

The

HELP

commands.

command displays help text about the stepper

You

can

specify

this

with

command

one

name of the stepper command about which
the
argument,
command
HELP
the
If you specify
you want help text.
without an argument, the stepper displays a list of the
stepper

commands.

You can abbreviate this command
mark

wusing

question

(?2).

Evaluation Command

the
1in
are
vyou
expressions while
You can evaluate
the LISP system to evaluate a
want
you
If
stepper.
then
parenthesized form, you can specify the form and
press

the

RETURN

Kkey.

you

want

the system to

evaluate a symbol, you must use the EVALUATE command.

EVALUATE

to
system
LISP
the
causes
command
EVALUATE
The
specify
must
You
form.
explicitly evaluate a specified

the command with an argument, which must

you
the

the

form

The system evaluates
want the system to evaluate.
form
the
of
environment
lexical
the
in
form

currently being stepped.

Debugger

DEBUG

Command

The DEBUG command invokes the debugger at

the

control

that stores the call to the current form.
frame
stack
the
stepper,
When the debugger returns control to the
stepper prompts you for a command.

DEBUGGING

Display

The

SHOW

stack

command

Command

displays

The

command

causes

command

stepper

was

QUIT

the

invoked.

optional

displays

stepper

typing
other
The

The

argument.
exit.

the

than

NIL,

default

BACKTRACE

with

the

subforms

its

way

lists

the

current

invoked.

1lists

before

exits.

does

not

return

when

the

command with
the

you

optional

lists

are

the

stepper

causes

the

display

argument

the

message

specify

subforms

You

can

which

1in

value

message.

the

specify

determines

listed.

number

the

not

all

this

specify NIL,
respond

specified

you

and

active

NIL.

Command

subforms

stepper

exit

was

you

integer,

that

back

the

you

through.

optional

specify

the

command

stepped

can

stepper

for

that

message

stepper

value

stepper

level

confirmation

YES,

being

the

You

Backtrace
BACKTRACE

subform

Command

control

the

frame.

Exiting
QUIT

FACILITIES

The

the

form

the

command

the

number

stepper works

subforms

and

order

in which

they were

then

specify

the

argument,

subforms

the

LISP

the

system

evaluating.

Commands

That

Continue
Several
form

FINISH

Evaluation of
stepper

being

commands

stepped

evaluation

The

FINISH

command

the

call

command with

the

evaluates
other

the

evaluation

evaluation.

STEP

optional

form.

that

command,

the

form until

the

stepper

the

5-27

it
and

<call

optional

specify
form.

When

system

value

through

the

1in

the

LISP

returns

the

NIL,

the

LISP

evaluates

the

form

STEP macro.

The

the

argument

end

the

returns

then

specified

can

steps

reaches

evaluation

1in

the

the
the

the

evaluation
stepper

the

for

continuing

form you

argument

the

value

the

You

system disables
default

evaluation

macro.

the

1If

NIL,

the

command

way.

you

specified

each

evaluates

executes

than

continue

different

Form Being Stepped Through

through,

the

stepper

the

NIL.

DEBUGGING FACILITIES

The OVER command causes the LISP system to evaluate the
stack frame with the stepper
<current
subform in the

OVER

disabled.

The RETURN command causes the LISP system

RETURN

evaluate

the RETURN command’s argument and causes the stepper to
values
the
return
to
frame
force the current stack
be
must
command
This
evaluation.
the
by
returned
When
form.
a
be
must
that
argument
an
specified with
you execute the command, the LISP system evaluates the
current
the
complete,
is
When the evaluation
form.
the
by
returned
the wvalues
returns
frame
stack
evaluated

form.

The STEP command causes the LISP system to evaluate the

STEP

subform
enabled.

RETURN

stack frame with the stepper
current
in the
to pressing the
This command is equivalent

key.

The UP command causes the LISP system to evaluate
control
stepper disabled wuntil
with the
subforms

returns to the subform that contains the subform in the
You can specify the command with
stack frame.
current
specify the
If you
an optional integer argument (n).
subforms with the
system evaluates
the
argument,
subform
stepper disabled until control returns to the
frame n
stack
current
the
in
subform
the
contains
that
is 1.
argument
the
of
value
default
The
levels deep.

5.6.5

Using Stepper Variables

The stepper
debugging

facility has
when
tools

two special variables
stepper:
the
in

that are useful
and
*STEP-FORM*

*STEP-ENVIRONMENT*.,

5.6.5.1 *STEP-FORM* - The *STEP-FORM* variable is bound to the form
For example, while executing the form
being evaluated while stepping.
(STEP

(FUNCTION-Z ARGl ARG2))

the value of *STEP-FORM* is the list (FUNCTION-Z ARGl ARG2).
stepping,

the value is undefined.

When not

5.6.5.2 #*STEP-ENVIRONMENT* - The *STEP-ENVIRONMENT* variable is bound
to the 1lexical environment in which *STEP-FORM* is being evaluated.
By default in the stepper, the lexical environment is used i1f you use
5-28

DEBUGGING

the
of

EVALUATE
dynamic

Some

command.

and

COMMON

LISP

MACROEXPAND)
to

the

these

See

lexical

functions

take

functions

stepped

COMMON LISP:

environment

an
to

(for

optional

*STEP-ENVIRONMENT*

FACILITIES

Language

example,
environment

variable

allow

The

for

description

variables.

can be

evaluaton

EVALHOOK,

APPLYHOOK,

argument.

The

passed

forms

the

value

context

to
the

form.

example
special

variables.

Lisp>
"Top

(SETF X
level

Lisp>

"Top

value

(DEFUN
(IF

level

value

of X")

FUNCTION-X
3)

(X)

(FUNCTION-X

1))

(FUNCTION-X

2)))))

FUNCTION-X

Lisp>
#4:

(STEP

(FUNCTION-X

Step>

5))

STEP

(BLOCK FUNCTION-X

#10:

(< X 3)

(IF

(+
Step>

(IF

(< X

Step>

STEP

#18:

Step>

STEP

: o

$#22: X => 5
$#18 => NIL
#17: (+ (FUNCTION-X

Step>

1))

(FUNCTION-X

X 1))

(FUNCTION-X

2))))

(FUNCTION-X

X 1))

(FUNCTION-X

(- X 2)))

1))

#25:

STEP

#29:

#25 =>
#27:

Step>

STEP

X =>

(BLOCK

#31:

(IF
-

X 2)))))

STEP

Step>

#21:

Step>

(FUNCTION-X

STEP

o
Step>

(FUNCTION-X

STEP

#14:

bound

environment

5.6.5.3
Example Use
of
Stepper
Variables - The
following
illustrates
the use of the *STEP-FORM* and *STEP-ENVIRONMENT*

and

FUNCTION-X

(FUNCTION-X

(< X 3) 1
(+ (FUNCTION-X

(FUNCTION-X

STEP

$#35:

(IF

(< X 3)

5-29

X
X

1))
2))))

DEBUGGING FACILITIES

Step>

STEP

#34:

(+-(FUNCTION-X

STEP

(FUNCTION-X

#38:

S
Step>

EVAL

Step>

FUNCTION-X

(BLOCK

#44:

X =>
3

oo #46:
$#42 =>

(IF

(+
EVAL

(BLOCK

(IF

1
(-

1))

(FUNCTION-X

2)))))

*STEP-FORM*

(< X 3)

(FUNCTION-X

STEP

(IF

#48:

(- X 1))

(¢ X 3)

(FUNCTION-X

(- X 2)))))

(FUNCTION-X

1))

(FUNCTION-X

2))))

STEP

$#52:

oottt
STEP

S
s

Step>

STEP

Step>

EVAL

FUNCTION-X

Step>

(FUNCTION-X

(+
Step>

(- X 1))

STEP

s o oo oror
1ottt

Step>

(- X 2)))

STEP

$#42:

Step>

(FUNCTION-X

1))

S
Step>

(- X 1))

*STEP-FORM*

(FUNCTION-X

s
e

NIL

#35 =>

Step>

X =>

#39:

(< X 3)

#56: X => 3
#52 => NIL
#51: (+ (FUNCTION-X

(- X 1))

(FUNCTION-X

#55:

2)))

(FUNCTION-X (- X 1))

3
Step>

(EVAL

'X)

"Top level value
Step>

EVAL

(FUNCTION-X
Step>

of X"

*STEP-FORM¥*

(EVALHOOK

"Top level value

1))
"X

NIL

Step>

(EVALHOOK

’'X NIL

Step>

(EVALHOOK

(CADR

Step>

STEP

Step>

3ozt

NIL

NIL)

NIL

*STEP-ENVIRONMENT*)

of X"

otz

*STEP-FORM*)

s 2
A

S
s oo

NIL

*STEP-ENVIRONMENT®*)

(- X 1)

oot

#59:

: #63: X => 3
#59 => 2
#61: (BLOCK FUNCTION-X

STEP

:
s

NIL

(IF

5-30

DEBUGGING

FACILITIES

Step>

(FUNCTION-X

1))

(FUNCTION-X

2)))))

FINISH

5
This

example

the

form

the

shows

being

that

The

EVALHOOK

call

environment

call

value

which

the

stepper.

The

stepper,

with

null
EVAL

example

bound

command

stepped

the

form

is,

with

environment

1lexical

EVAL function uses

5.6.6

The

that

null

environment

uses

the null

variable

currently

evaluates

special

stepping.

special

the

EVALHOOK
1in

*STEP-FORM*

evaluated while

*STEP-ENVIRONMENT*

environment

the

form
(-

is
X

the

specified
differs

Lisp>

(DEFUN

FIRST-ELEMENT

environment.

(X)

(CAR X))

FIRST-ELEMENT

Lisp>

(SETF

(FIRST

SECOND

Lisp>

#9:
Step>

(STEP

SECOND

(FIRST-ELEMENT

MY-LIST))

MY-LIST => (FIRST SECOND THIRD)
(BLOCK FIRST-ELEMENT (CAR X))

STEP

#22:

(CAR X)

EVALUATE

(CAR

FIRST

Step>

FINISH

FIRST

Lisp>

(DEFUN

PLUS-Y

(X)

Y))

PLUS-Y

Lisp>

(SETF

(STEP

(PLUS-Y

5
Lisp>

#9:
Step>

10))

(PLUS-Y 10)
STEP

#15:
Step>

(BLOCK PLUS-Y

(+ X Y))

EVALUATE

Evaluate:

15
Step>

THIRD))

STEP

Step>

’(FIRST

THIRD)

(FIRST-ELEMENT MY-LIST)

#14:
#15:

Step>

MY-LIST

STEP

$#22:

(+ X Y)

5-31

bound
shows

the

that

lexical

the

shows
from

evaluated.

binding

*STEP-ENVIRONMENT*

lexical

Sample Stepper Sessions
1.

also

being

local

lexical

that
that

X'’s
the

environment;

DEBUGGING FACILITIES

Step> BACKTRACE
(PLUS-Y 10)
(BLOCK PLUS-Y

(+ X Y))

(+ X Y)

SHOW

Step>
(+

Step>

OVER

$#22 =>

: #15 =>
#9 => 15

15
Lisp>

Lisp>

(DEFUN ADDITION (X)

(+ X Y))

ADDITION

Lisp>
5

Lisp>
#9:
Step>

(SETF Y 5)

(STEP

(ADDITION 4)

STEP

#15:

(ADDITION 4))

(BLOCK ADDITION (+ X Y))

STEP
$#22: (+ X Y)
Step> BACKTRACE
(ADDITION 4)
(BLOCK ADDITION (+ X Y))

Step>

Step> EVALUATE
Evaluate: (+ X Y)
9

Step>

STEP

#27: X =>
#26:

: #22 =>
=> 9
#15
:
#9 => 9

9
Lisp>

5.7

TRACER

The VAX LISP tracer is a macro you can

use

1inspect

program’s

The tracer informs you when a function or macro is called
evaluation.
during a program’s evaluation by printing information about each call
and return value to the stream bound to the *TRACE-OUTPUT* variable.
To use the tracer, you must enable it for each function and macro you

want

traced.

5-32

DEBUGGING

FACILITIES

NOTE
You

5.7.1

cannot

trace

special

forms.

Enabling the Tracer

You can enable the tracer for one or more functions and/or
specifying
TRACE

the

macro.

Lisp>

function

For

The

TRACE

traced.

you

warning

macro

try

returns

trace

for

description

For

disable
the

macros

call

the

function

macro

displayed.
to
is

functions

that

avoid

produce

enabled.

macros

that

are

already

being

error,

call

this

1list

For

and

the

traced,
the

TRACE

functions

and

example:

the

COUNTER)

TRACE

macro

provided

Chapter

tracer

functions

for

call

and

macros

function
to

for

the

macro,

UNTRACE

which

specify

macro.

tracing

has

just

the

name

returns
been

the

list

disabled.

example:

can

enabled

(UNTRACE

disable

message

The

COUNTER)

ADDITION

macro

(FACTORIAL

ADDITION

list

tracing

the
or

Lisp>

You

arguments

Disabling the Tracer

function
of

(TRACE)

(FACTORIAL

5.7.2

names

COUNTER)

argument

which

Lisp>

message

without

macros

FACTORIAL

ADDITION

macro

example:

(TRACE

(FACTORIAL

and

UNTRACE

FACTORIAL

ADDITION

tracing

calling

tracing

for

the

for

ADDITION

all

UNTRACE

COUNTER)

the

functions

macro

function

that

without

not

for

which

tracing

argument.

being

traced,

The

Language.

displayed.

macro

described

COMMON LISP:

1is

you

try

warning

DEBUGGING FACILITIES

Tracer Output

5.7.3

tracer
the
macro,
or
function
a
for
tracer
Once you enable the
1is
macro
or
function
two types of information each time that
displays
called during a program’s evaluation:

A description of each call to the specified function or macro

A description of each return value from the specified function
Oor

macro

The description of a call to a function or macro consists of a line of
text that includes the following information:
@

The nested level of the call

The control stack frame number that indicates where
is

the

call

with

the

stored

The name and arguments of the

function

function or macro that is called

associated

1indentation.
<call with
a
of
The tracer indicates the nested level
Wwhen the number of nested levels increases, the indentation increases.
the
displays
tracer
the
indentation,
After making the appropriate
frame number, the function name, and the arguments in
stack
control
the

following

#n:

format:

(function-name arguments)

of each
The tracer also displays a line of text for the return value
value
each
for
text the tracer displays
line of
The
evaluation.
includes

following

the

information:

The nested level of the return value

The control stack frame number that indicates where the return
value

The

stored

return value

return value with
of each
The tracer indicates the nested 1level
the
indentation of
the
matches
indentation
The
indentation.
After making the indentation, the tracer displays
corresponding call.
stack frame number and the return value in the following
control
the
format:

#n =>

return-value

5-34

DEBUGGING FACILITIES
Suppose

you

Lisp>

define
(DEFUN
(IF

function

FACTORIAL
(<=

named

FACTORIAL.

(N)

(FACTORIAL

1)))))

FACTORIAL

The

following

displays

example

when

Lisp>
#11:

the

(FACTORIAL
(FACTORIAL

#43:

format

called

the

output

with

the

tracer

argument

(FACTORIAL

#43

the

FACTORIAL

(FACTORIAL

#27:
.

illustrates

function

$27 =>
#11 => 6
6
The

FACTORIAL

preceding

function

example,

indicates

the

nested

indentation

The

tracer

stored

with

followed

The

nested

an
by

stack

frame

arrow

5.7.4
You

call

period

the

stack

integer

case

recursion.

with

return

value

tracer

the

and

call

with

The

that

and,
of

indentation.
followed

frame

which

preceded with

the

The

tracer

Each

level

space

call

number

).
1is

sign

(#n:).
matches

indicates

LISP

system

matches

the

preceded

with

1integer

=>)

each

number

each

which

one

1levels

points

the

the
the

indentation

the

wvalue

with

number

the

return

frame

number

sign

and

the

pushes

stack

number

control

followed

value.

Tracer Options

can

call

(#n

the

colon

This

corresponding
an

indicated

call.

onto

integer.

recursive
three

integer.
a

level

corresponding

level

indicates

and

is
has

modify

the

output

TRACE

the

macro.

pair.

The

format

TRACE

macro

is:

in which

(TRACE

(function-name

tracer

Each

option

specify

specifying

consists

keyword-value

options

the

keyword-value

pairs

for

the

keyword-1

keyword-2

value-1

value-2

-))
You

can

The

TRACE

also

specify

macro

functions
(TRACE

and

options

format

for

in which

list

specify

functions

the

same

macros is:

((name-1

name-2

...)

keyword-1

value-1

keyword-2

value-2

-))
5-35

and/or

optlons

for

macros.

list

DEBUGGING FACILITIES
NOTE

Forms the system evaluates just before or just after a
call to a function or macro for which tracing 1is
enabled are evaluated in a null 1lexical environment.
information on lexical environments, see COMMON
For
LISP:

The Language.

The keywords you can use to specify options are:
-—-

:DEBUG-IF

| -- Invoke the debugger

: PRE-DEBUG-IF
: POST-DEBUG-IF
:PRINT

: PRE-PRINT
: POST-PRINT

|-- Add information to tracer output

:STEP-IF -- Invokes the stepper

:SUPPRESS-IF -- Removes information from tracer output

:DURING -- Determines when a function or macro is traced

5.7.4.1

the

Invoking the Debugger - You can cause the

debugger

specifying

the

:DEBUG-1F,

tracer

invoke

:PRE-DEBUG-IF,

oOr

- POST-DEBUG-IF keyword. These keywords must be specified with a form.
The LISP system evaluates the form before, after, or before and after
each call to the function or macro being traced. 1If the form returns
5 value other than NIL, the tracer invokes the debugger after each
evaluation.

5.7.4.2

Adding Information to Tracer Output - You can add information

tracer output by specifying the :PRINT, :PRE-PRINT, or : POST-PRINT

The
keyword. You must specify these keywords with a list of forms.
the
displays
tracer
the
and
forms
LISP system evaluates the list of
the
to
<call
each
after
and
return values before, after, or before
one
values
the
function or macro being traced. The tracer displays
per line and indents them to match other tracer output. If the forms
to be evaluated cause an error, the debugger is invoked.

5.7.4.3 Invoking the Stepper - You can cause the tracer to invoke the
stepper by specifying the :STEP-IF keyword. You must specify this
keyword with a form. The LISP system evaluates the form before each
call

the

function

or macro being traced.

1If the form returns a

value other than NIL, the tracer invokes the stepper.
5-36

DEBUGGING

5.7.4.4

Removing

information
You

must

the

form

the

tracer

specify

form

the

from

Information
this

before
returns

arguments

output

call

the

other

the

Tracer

Output

specifying

with

value

and

from

keyword

each
a

FACILITIES

The

LISP

function

macro

value

the

tracer

the

You
system

being
does

function

Defining When a

function

keyword

are

and

traced

only
of

when

the

macro

macros

they are

functions

traced.

1If

display

macro

the

names

can

enabled,

being

define
is

specify
function

tracer

(directly or

whose

You

must

list

which

You

for

called

macros

Traced

tracing

name

functions

one

which

keyword.

function

this
and/or

enabled

indirectly)

from

specified

with

are

keyword.

Tracer Variables

can

use

helpful

and

debug

values

from

special

5.7.5.1

variables with

the

*TRACE-CALL*

and

tools:

the

preceding

tracer

step depending on
a

the

Lisp>

the

TRACE

options,

arguments

macro.

These

*TRACE-VALUES*.

you
to

can

With

control

function

macro

when
the

The

call

*TRACE-CALL*

being

traced.

variable

The

bound

following example

the

shows

how

(DEFUN

FUNCTION-X
3)

(FUNCTION-X

1))

(FUNCTION-X

2)))))

FUNCTION-X

(TRACE

(FUN
.

ECOND

*TRACE-CALL*)

(FUNCTION-X)

Lisp>

(FUNCTION-X

Control
Frame

¢to

return

variable:

(IF

Lisp>

are
these

function.

*TRACE-CALL*

function
use

two

debugging

variables

for

Macro

:DURING

5.7.5
You

with

macro,

the

The

within
the

specifying

Function or

names.

macro

keyword.
evaluates

5.7.4.5

traced

remove

not

traced.

when

can

:SUPPRESS-IF

form.

than NIL,

return

the

Stack

#26:

Debug

Frame

#21:

Debugger

(DEBUG)

DOWN

(BLOCK

(IF

FUNCTION-X

(FUNCTION-X

1
(-

1))

(FUNCTION-X

2)))))

5-37

DEBUGGING

Debug

Frame

#19:

Debug

FACILITIES

DOWN

(FUNCTION-X

(CADR

(DEBUG-CALL))

3
Debug

Control

CONTINUE

Stack

Frame

#19:

Debug

Debugger

(DEBUG)

CONTINUE

this

example,

Then the TRACE macro
is
<called
for
FUNCTION-X.
TRACE
specified
to
invoke
the
debugger
1if the first argument
FUNCTION-X (the function call being traced) is
less
than
Since
the
PRE-DEBUG-IF
option is specified, the debugger
invoked

before

option

has

trace

output.

FUNCTION-X

the

call

a value

DOWN command moves

first defined.

FUNCTION-X.

calls

FUNCTION-X do not

Finally the

CONTINUE

5.7.5.2
of

variable

Before

command

frame.

*TRACE-VALUES* - The *TRACE-VALUES* variable is bound to
wvalues
returned
by
a
traced function.
Consequently,

the
the

continues

the

can be used only with the :POST- options to the TRACE
macro.
being
bound
to
the return values, the variable returns NIL.

Lisp>

example

(TRACE

shows

how

use

the

:POST-DEBUG-IF
Lisp>

(FUNCTION-X

#11:

(FIRST

(FUNCTION-X

#18:

(FUNCTION-X

#25: (FUNCTION-X 2)
$#25=> 1
#25: (FUNCTION-X 1)
#25=> 1
#18=>

variable:

(FUNCTION-X

(FUNCTION-X)

stack.

following

#4:

control

any

evaluation

FUNCTION-X.

list

stack

the

cause

The
DEBUG-CALL
function
returns
a
1list
representing the
current
debug frame function call.
1In this case, the CADR of
the list is 3.
This
accesses
the
first
argument
to
the
current

down

1is

:SUPPRESS-IF

the

pointer

the

The

the

1is
to

function

The

#18: (FUNCTION-X 2)
#18=> 1

5-38

*TRACE-VALUES*)

2)))

DEBUGGING

Control

Stack

Frame

#12:

Debug

Debugger

(DEBUG)

BACKTRACE

Backtrace

Frame

#12:

Frame

#7:

start

(DEBUG)
(BLOCK

FUNCTION-X

(IF

(FUNCTION-X

1))

(FUNCTION-X

2)))))

Frame

#5:

(FUNCTION-X

Frame

#1:

(EVAL

Backtrace

Frame

#12:

Debug

(FUNCTION-X

ends

5))

(DEBUG)

CONTINUE

#11=>
#11:

FACILITIES

(FUNCTION-X

#18: (FUNCTION-X 2)
#18=> 1
#18: (FUNCTION-X 1)
#18=> 1
#11=> 2
Control
Frame
Debug

#4=>

Stack

(DEBUG)

CONTINUE

called

TRACE

exceeds

returns

The
and

THE EDITOR

The

VAX

create

you

know which

the
LISP

the

LISP

to
a

and

start

returned
end when

powerful,

LISP

programs.

function

For

the

edit

Editor

Editor,

FUNCTION-X

value

Editor

and

Editor.

for

example)

5.8

use

Debugger

#5:

in your

correct

complete

the

(the
the

exceeds
it

Once

error.
how

LISP Editor Manual.

5-39

function
if

twice

editor

you have

1in

the

value

returned

once

when

the

that

located

causing

Use

the

extensible

program

returns

description

1instructions

same

debugger

the

enables

you

error

and

you

can

error,

function

the

function,

use

the

Editor,

see

invoke

the
the

VAX
VAX

CHAPTER 6

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

Pretty printing clarifies the meanings of LISP
objects
by
modifying
their printed representations.
It inserts indentation and line breaks
at appropriate places, making pretty-printed
output
easier
to
read
than
output
produced with standard print functions.
Pretty printing
is an alternative to standard printing for all LISP
objects,
but
1is
particularly
wuseful
for
printing LISP code, complex data lists, and
arrays.*

When pretty printing is
enabled,
any
output
function
that
prints
output can potentially perform pretty printing.
The following example
contrasts
the
standard
and
pretty-printed
treatments
of
a
COND
structure:

Lisp>

(SETF

'VT240)

T-QUESTION

START)

' (COND

(PRIN1

((EQUAL

' (WHAT

TERMINAL

TYPE

ARE

YOU

USING?)))))

(COND

( (EQUAL TERMINAL

(QUOTE VT240))

(QUOTE

(WHAT

TERMINAL TYPE ARE

Lisp>

(PPRINT

(COND

( (EQUAL TERMINAL

'VT240)

TERMINAL

T-QUESTION)

(PRIN1

’(WHAT

START)

(PRIN1

YOU USING?)))))

START)
TYPE ARE

YOU USING?))))

The first version (produced
by
the
standard
read-eval-print
1loop)
breaks the line at an awkward place and provides no indentation.
Only
one line is being printed.
The line is either wrapped
or
truncated,
depending
on
the operating system (VMS or ULTRIX-32) and the setting
of the terminal.
The pretty-printed (PPRINT) version 1s more readable

because
it
starts
a
new
indenting the list to
1line
equivalent

level

the

1line
at
wup
with
first line.

the beginning of a nested list,
the
structure
nested
to
the

* VAX LISP pretty printing and the extensions to FORMAT are based on a
program
described
in
the
paper PP:
A Lisp Pretty Printing System,
A.I.
Memo No.
written
by
Intelligence

816, December, 1984.
Richard
C.
Waters,

Laboratory.

The paper and the
program
were
Ph.D.,
of
the
MIT
Artificial

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

This

chapter

describes

four ways

Section 6.2

tells how to control

that

6.1

control

the format of

pretty-printed

variables.

tells how to use

support

the vVvAX

LISP

FORMAT

directives

pretty-printing.

Sections 6.4 through 6.9 tell how you can extend the VAX
LISP
print
functions
to
handle
specific structures and types of
structures by defining new print functions.

PRETTY PRINTING WITH DEFAULTS

Three

control

functions let you pretty-print

without

explicitly

PPRINT

formats

an object and prints

PPRINT-DEFINITION formats the
1t

it to a

stream.

function object of a symbol

and

stream.

PPRINT-PLIST formats the property list of a symbol and
it

wusing

variables:

prints

Use
an
The
the

LISP objects:

tells how to pretty-print objects.

Section 6.3

Section 6.1

objects using print

prints

strean.

PPRINT when you want to let the system decide how best
to
format
object.
PPRINT
prints whatever object is given as its argument.
COND structure at the beginning of this chapter is an
example
of
output
format
specified
for
1lists
starting with a particular

symbol.

Lisp>

THIS

(DEFUN

(CAR

BELONGS

PILE))

(THIS

PILE)

(COND

(BELONGS

THIS

((NULL

PILE

(CDR

PILE)

1list

You can use PPRINT-DEFINITION
to
print
the
definition
of
a
function.
Supply the function name as the argument, as follows:
NIL)

LISP

((EQUAL

) ) )

BELONGS

Lisp>

(PPRINT-DEFINITION

(DEFUN

(THIS

PILE)

( (NULL

PILE)

NIL)

( (EQUAL

THIS

(COND

’BELONGS)

BELONGS

(BELONGS

(CAR

THIS

PILE))

(CDR

PILE)

PILE)))))

the object to be printed is the property

PPRINT-PLIST,
Lisp>

(SETF

(AUGUSTA

shown
(GET

the

’'PLACES

SACRAMENTO)

symbol,

following example:
'CITIES)

' (AUGUSTA SACRAMENTO))

wuse

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT
Lisp>

(SETF

(MAINE

CALIFORNIA)

Lisp>

(PPRINT-PLIST

(STATES

CITIES

(GET

(MAINE

’'PLACES

'STATES)

' (MAINE

CALIFORNIA))

’'PLACES)

CALIFORNIA)

(AUGUSTA

SACRAMENTO)
)

PPRINT-PLIST prints only indicator-value pairs for which the indicator
is
accessible
in
the
current package.
PPRINT-PLIST emphasizes the
relationships between the indicator-value pairs.

6.2

HOW TO PRETTY-PRINT USING CONTROL VARIABLES

VAX LISP supports the
global
print
control
variables
included
1in
COMMON
LISP.
In
addition,
VAX
LISP provides three variables that
affect only pretty-printed output:
®

*PRINT-RIGHT-MARGIN%*

*PRINT-MISER-WIDTH%*

®@

*PRINT-LINES*

By
changing
the
wvalues
of
these
variables,
you
pretty-printed output to suit a variety of situations.

can

adjust

You can also specify values for these three variables in calls to
the
WRITE
and
WRITE-TO-STRING
functions.
These
functions
have
been
extended to accept the following keyword arguments:
|
+RIGHT-MARGIN
+:MISER-WIDTH

:LINES

If you specify any
of
these
arguments,
the
~variable is bound to the value you supply with
output

6.2.1

corresponding
special
the argument before any

produced.

Explicitly Enabling Pretty Printing

LISP variable

pretty

prlntlng

If you

set

*PRINT-PRETTY*
*PRINT-PRETTY*

TT
1-IN1
L,

is
to

you

can

129
enapi
1a

pretty pr

by calling any print function.
The
LISP
read-eval-print
also pretty-print when *PRINT-PRETTY* 1is non-NIL.

1loop

The

call

when

following example

pretty printing

shows

enabled:

the

effect of a PRIN1

function

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

*PRINT-PRETTY*

(SETF

Lisp>
T

Lisp>
THE

(PRIN1

NIGHT)

' ((TIGER TIGER BURNING BRIGHT)

(WHAT

IMMORTAL

HAND

EYE)

(IN THE

(COULD

FRAME

FORESTS OF
THY

FEARFUL

))
SYMMETRY)

((TIGER

(IN

TIGER

THE

BURNING

IMMORTAL

(WHAT

(COULD

FRAME

BRIGHT)

THE

HAND

FORESTS

THY

NIGHT)
EYE)

FEARFUL

SYMMETRY))

You can also enable pretty printing by specifying a non-NIL value
for
the :PRETTY keyword in functions such as WRITE and WRITE-TO-STRING.

6.2.2

Limiting Output by Lines

Pretty printing lets you abbreviate output by controlling
the
number
With the variable *PRINT-LINES* set to any integer
1lines printed.
of
specified
the
value, the print function you use stops after printing
number
of
lines.
The output stream replaces omitted output with the
only when
Abbreviation by number of lines occurs
characters " ...".
pretty
printing
1is
enabled.
See
Section
6.7 for more details on
abbreviating output.
|
The following example shows pretty-printed output
set

with

*PRINT-LINES*

Lisp>

(SETF

*PRINT-LINES*

(SETF

*PRINT-PRETTY*

Lisp>

Lisp> (PRINT ' ((IN WHAT DISTANT DEEPS OR SKIES) (BURNT THE FIRE
OF THINE EYES) (ON WHAT WINGS DARE HE ASPIRE) (WHAT THE HAND
DARE

SEIZE

THE

FIRE)))

((IN WHAT DISTANT DEEPS
(BURNT

6.2.3

THE

FIRE

OR SKIES)

THINE

Controlling Margins

the width of
lets you adjust
variable
*PRINT-RIGHT-MARGIN*
The
it specifies
integer;
an
be
The value should
output.
pretty-printed
With the left margin at
the exclusive upper limit on column numbers.
specifies the number of columns in which you
*PRINT-RIGHT-MARGIN*
0,
to
functions
print
the
causes
The default value, NIL,
can print.
The default
right margin value.
the
stream for
output
query the

varies,

but is always appropriate to the output device.

a 1long
Output may exceed the right margin if the printer encounters
can
you
but
0,
normally
is
margin
The left
string.
or
name
symbol
6-4

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

change
(see

it by using logical blocks with the

Section

6.2.4

FORMAT function

indent

6.3).

Conserving Space with Miser Mode

Miser mode can help you avoid running out of horizontal space when you
print
complicated
structures.
Pretty printing adds line breaks and
indentation to output to indicate levels of nesting,
so
that
deeply
nested
structures
often
use
up much of the line width.
Miser mode
conserves line width by minimizing indentation and inserting new lines
where
possible.
You
<can
use
this feature by setting the variable
*PRINT-MISER-WIDTH* to an integer value two or three times the
1length
of the longest symbol in the output (usually a value between 20 and 40
1s

appropriate).

The system subtracts the value of *PRINT-MISER-WIDTH* from
the
right
margin
of
the
output
stream to determine the column at which miser
mode takes effect.
1In other words, miser mode becomes effective
when
the
total line width available for printing after indentation is less
than
the
value
*PRINT-MISER-WIDTH*
more

of
*PRINT-MISER-WIDTH*.
to NIL to disable miser mode.

You
can
See Section 6.8

set
for

details.

The

default value

*PRINT-MISER-WIDTH*

6.3

EXTENSIONS TO THE FORMAT FUNCTION

VAX LISP
provides
eight
specified in COMMON LISP.

Logical blocks,

Multiline mode new lines,

fit

Indentation,

40.

FORMAT
directives
1in
addition
to
those
The added directives allow you to specify:

cannot

which are groupings of related output tokens

one

which result in new lines

output

line

which aids

in indenting portions of a form

Table 6-1 lists and briefly describes the FORMAT directives
that
VAX
LISP
provides.
This
section
provides
a
gquide to their use.
The
section presupposes a thorough knowledge of the LISP FORMAT
function.
See COMMON LISP:
The Language for a full description of FORMAT.
Use

the

FORMAT

function as

follows:

FORMAT destination control-string &REST argquments

This function formats
the
arguments
according
to
the
format
you
specify
with directives in the control string.
destination specifies

6-5

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

the output stream.
The arguments identify the objects to be
operated
on
by
the
control
string.
The
sections that follow describe the
application of these directives and
the
effects
of
the
<colon
and
at-sign modifiers

Table 6-1:

them.

Format Directives Provided by VAX LISP

Directive
a4

Effect

Prints
the

~ !

wunder

direction

print variable values.

logical

block.

Specifies a multiline mode new line.
effective

“nI

corresponding argument

Begins a logical block.
Depending on
modifiers,
this
directive
causes
FORMAT
to
print one or more of the
arguments following the control string.
Ends

the

current

only

in a

logical

This directive

block.

Sets indentation to n columns after the
1logical
block
or
after the prefix.
This directive is effective only
in

logical

block.

“n/FILL/

Prints the elements of a list with as many elements
possible
on each line.
If n is 1, FORMAT encloses
printed
1list
1in
parentheses.
This
directive
effective only in a logical block.

“n/LINEAR/

If the elements of the list to
be
printed
cannot
be
printed
on
a
single line, this directive prints each
element on a separate line.
If n is 1, FORMAT encloses
the
printed
1list
1in
parentheses.
This directive 1is
effective only in a logical block.

“n,m/TABULAR/

Prints the list in tabular form.
If
n
1is
1,
FORMAT
encloses
the
1list
in
©parentheses;
m
specifies the
column spacing.
This directive is effective only in
a
logical

as
the
18

block.

These FORMAT directives provide the sole means
of
performing
pretty
printing
in
VAX
LISP.
All functions that explicitly perform pretty
printing (for example, PPRINT and PPRINT-DEFINITION) do
so
by
wusing
these
directives.
Objects
printed with FORMAT are printed normally
unless pretty printing is enabled.
Pretty printing
1is
enabled
when
both the following conditions exist:

6-6

PRETTY

logical

*PRINT-PRETTY*

block

logical

prevents

NIL.

within

the

logical

block

this

format

data,

can

You

can

will

according

values

any

LISP

control

use

the

FORMAT

colon

logical

lets
is

the

when

specified

*PRINT-PRETTY*

feature

use

one

either
of

specified

results

pretty-printed

you

value

indentation

This

data

block

lines

ignored.

FORMAT

modifier

(" :!).

new

opposed

output.

control

printed

1in
By

string

normally

*PRINT-PRETTY*.

FORMAT Directive

FORMAT directive

current

directive

starting

the

Using the WRITE
the

non-NIL,

flexibility,

EXTENSIONS TO

started.

and

USING

conditional

output,

pretty-printed,

the

from
any

allowing

Use

you

However,

normal-looking

6.3.1

block

AND

Nothing
1s

PRINTING

the

object.

an element when you want

control

contrast,

variables.

"A and S

The

wuse

argument

specify

the

for

wvalues

variables.

four

prefix

parameters

with "W

pad

the

printed

object:

“"mincol,colinc,minpad,
padcharw
For

explanation

"FORMAT

The

colon

for

the

The

parameters,
with

(7 :W)

binds

the

WRITE:

following

Lisp>

these

Provided

modifier

duration

*PRINT-LENGTH*

NIL.

Directives

NIL,

VAX

the

LISP"

the

Part

following

contrasts

(SETF

*PRINT-PRETTY*

NIL)

(SETF

*PRINT-ESCAPE*

NIL)

(SETF

*PRINT-LENGTH*

(SETF

COLORS

the

description
II

*PRINT-ESCAPE*

*PRINT-LEVEL*

example

see

NIL,

this

control
T,

and

effects

wunder

manual.

wvariables

*PRINT-PRETTY*

*PRINT-LINES*

using "W and " :W.

NIL

Lisp>
NIL

Lisp>

2
Lisp>

"Pink"

Lisp>

"Beige"

(FORMAT

((Yellow

(("Yellow"

"Buff")

("Peach"

"~W"

COLORS)

Purple

...)

(Agqua

Pink

"Purple"

"Violet"

...)

NIL

Lisp>

(FORMAT

(("Yellow"
("Peach"

"7 :W"

"Purple"
"Violet"

COLORS)

"Orange"

"Green'")

"Chartreuse®))

6-7

"Orange"

...)

"Green")

"Chartreuse")))

("Aqua

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

The first FORMAT call truncates the first two sublists to
two
colors
and
truncates the outer list to two sublists.
This truncation occurs
because *PRINT-LENGTH* is 2.
The first FORMAT
call
omits
quotation
marks
because *PRINT-ESCAPE* is NIL.
The second FORMAT call produces
the full list of colors
and
includes
quotation
marks,
because
it
implicitly
sets
*PRINT-LENGTH*
to NIL and *PRINT-ESCAPE* to T.
The
second FORMAT call also indents the lists because it
implicitly
sets
*PRINT-PRETTY*

6.3.2

Controlling the Arrangement of Output

Two concepts support the dynamic
arrangement
of
output
for
pretty
printing:
logical
blocks
and conditional new lines.
Logical block
directives divide the total output into hierarchical groupings,
which
are referred to as logical blocks or subblocks.
The goal of FORMAT is
to print an entire logical block (including all its subblocks) on
one
line.
If pretty printing is enabled, the logical block is printed on

one line only if the logical block fits between the current
left
and
right
margins.
Printing all the output on one line is referred to as
single-line

mode

printing.

The output for a logical block may not fit on
one
1line
when
pretty
printing.
In this case, the block must be subdivided into sections at
points where it may be split into
multiple
lines.
Conditional
new

line
directives specify these points.
Multiline mode printing is the
name given to the condition where a logical block must occupy multiple
lines.

When pretty printing is enabled, FORMAT
buffers
the
contents
of
a
logical
block
wuntil it can decide whether to use single-line mode or
multiline

mode

A third mode,
detail

printing.

miser mode,
is described briefly in Section 6.2.4 and 1in

Section

6.8.

Use the "!

and .

directives to specify a logicai block in the form:

“1blockTM.

where block can include any FORMAT directives.
A logical block
takes
one
argument
from
the
FORMAT argument list.
If that argument is a
list, any directives within the logical block that take arguments take
them from that list, as shown in the following example:
Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

(SETF

*PRINT-PRETTY*

Lisp>
T

40)

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

L
S
o ¥

Lisp>

(FORMAT T

""!"W

DENEB

SIRIUS))

(PLANETS

MARS

JUPITER

(STARS

SATURN

(BETELGEUSE

(PLANETS

NEPTUNE

DENEB

(MERCURY VENUS
JUPITER

' ((STARS
(MERCURY

(BETELGEUSE
VENUS

EARTH

PLUTO))))

SIRIUS))

EARTH MARS

SATURN

URANUS

NEPTUNE

PLUTO)
)

The logical block takes the entire
directive
within
the logical
list because *PRINT-PRETTY* is

If the

argument

is not

1list

block causes
set to T.

1list,

the

The

FORMAT
to pretty-print

1its

the

1logical

argument.

block

effectively

replaced by the "W directive.

You can alter the directive to start a logical block
(7!)
by
adding
two
modifiers.
Wwhen
the
directive
includes
a
colon
(7 :!), the
directive
sets
*PRINT-PRETTY*
and
*PRINT-ESCAPE*
to
T
and
*PRINT-LENGTH*,
*PRINT-LEVEL*,
and
*PRINT-LINES* to NIL for all the
printing

controlled by the

When the 7!

directive

logical

includes

block.

at-sign

(7@!),

the

directives

within
the
logical
block
take successive arguments from the FORMAT
argument list.
The logical block uses up all the arguments, not
just
a
single list argument.
Therefore, no directives that take arguments
from the argument list can appear after a logical block modified by an
at-sign
in
the logical block directive (see the last example in this
section).
You can use the "" directive
1inside
a
1logical
block
to
check
whether
the
1logical
block
arguments
have been reduced to a
non-NIL atom.
See Section 6.9 for information on handling
improperly
formed

argument

lists.

The output associated with any FORMAT directive is
printing
when
the
directive
occurs
within
a
*PRINT-PRETTY*

subject
1logical

to
pretty
block
and

non-NIL.

A logical block defines an indentation level and can define
a
prefix
and
a
suffix.
By
default,
when
pretty
printing is enabled, the
indentation level is the
position
of
the
first
character
in
the
logical
Dblock.
Each
1line
following
the first line in the logical
block is printed preserving indentation and per-line prefixes, so that
the
first
<character
in
the
1line
normally lines up with the first
character in the block following
the
prefix.
However,
no
default
prefix or suffix is associated with a logical block.
You can create nested
“tblockTM.
directive.

logical blocks within a logical
For example:

block,

using the

PRETTY PRINTING AND USING

Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

(SETF

*PRINT-PRETTY*

EXTENSIONS TO FORMAT

70)

70
Lisp>

Lisp>

(FORMAT T

' ( (BETELGEUSE

Stars:

In this
logical

BETELGEUSE

example,
block.

Eas

""!Stars:

"!7S

FOF

DENEB)

DENEB

g P

(MARS

Planets:

" !7 s

fad

JUPITER)))

MARS

two logical blocks are
Each
logical
block

P, TN

Planets:

JUPITER

created within
wuses
the
next

the
principal
argument
for

printing:

The enclosing logical block uses
list

The

((BETELGEUSE DENEB)

first

the elements of the principal

JUPITER))

arguments.

the

1list

The second inner logical block uses the elements of

the

1list

DENEB)

JUPITER)

1its

1ts

arguments.

Lisp> (FORMAT T "":!Stars: "!°S "S”.
"{(BETELGEUSE

Stars:

this

its

(MARS

inner logical block uses the elements

(BETELGEUSE

(MARS

BETELGEUSE

example,

printing

the

implicitly,

DENEB)

DENEB

colon

(MARS

Planets: "!”s "§7.7."
JUPITER)})

Planets:

MARS JUPITER

7:!

the

producing

the

directive

same

output

enables

pretty

the

example.

Lisp>

(SETF

*PRINT-PRETTY*

s "&"s ."
Lisp> (FORMAT T "7@!"Ss "%"S "%
" (BETELGEUSE

DENEB

SIRIUS)

"POLARIS

'VEGA

'ALGOL

' ALDEBERAN)

(BETELGEUSE

DENEB

SIRIUS)

POLARIS
VEGA
ALGOL

In this example, the at-sign causes
the
1logical
block
to
wuse
all
following
arguments.
Unneeded
arguments are used up by the logical
block but not printed.
The first "S applies
to
the
first
argument

(the

list

(BETELGEUSE

directives

apply

unprinted,

because

DENEB

POLARIS,

there

SIRIUS)).

The

VEGA,

ALGOL.

and

three

ALDEBERAN

°S

goes

is no corresponding directive.

Lisp> (FORMAT T ""@!Stars: ~!”S "S".
"(BETELGEUSE

Stars:

remaining

DENEB)

BETELGEUSE DENEB

' (MARS

Planets:

Planets: "!"5 "8 .7."
JUPITER))

MARS

JUPITER

In this example

the at-sign in the outermost logical

block

directive

("@!)

the logical block to use all the arguments.

The first

directs

6-10

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

inner

the

logical

second

block

inner

uses

the

1logical

elements

block uses

the

list

(BETELGEUSE

elements

the

DENEB);

list

(MARS

JUPITER)
.

6.3.3
Five

Controlling Where New Lines Begin
FORMAT

directives

start
according
to
delimits a section in

The
used

places

the

where

situation.

per-line

new

1lines

produces a fresh
the
directive

line.
When
preserves

wused
within
a
1indentation
and

prefixes.

logical

wused

block.

new

line

when

wused

new

line

when

wused

block.

The "@_ directive produces a miser-mode
within

can

Each directive

prefixes.

The ":_ directive produces an if-needed
within

specify

The "_ directive produces a multiline mode new line when
within

and

The "& directive
logical
block,
per-line

you

directive produces an
unconditional
new
1line.
When
within
a
logical
Dblock,
the
directive
preserves

indentation

®@

let

the
demands
of
a logical block.

block.

You can specify unconditional new lines (" %) and fresh lines
("&)
if
you know in advance how the text should be laid out.
If a new line 1is
produced by one of
these
directives
when
the
FORMAT
function
1is
printing
a
logical
block,
FORMAT
prints
the logical block in the
multiline mode, preserving indentation and per-line prefixes.
The

“& directive
specifies
a
fresh
1line,
whether
or
not
pretty
printing
1s
enabled.
If
the
7& directive occurs inside a logical
block when pretty printing is enabled and any output is
on
the
1line
other
than
prefixes
and indentation, the FORMAT call starts a fresh
line, preserving indentation and
per-line
prefixes.
The
following

examples

show the use

the "%

and "&

6-11

directives:

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT
(FORMAT T

Lisp>

"StarsT :!;:;7@;7%TS T%TS T%TsT

"{BETELGEUSE

DENEB

SIRIUS))

stars;

;

BETELGEUSE

;

DENEB

SIRIUS

NIL

(FORMAT T

Lisp>

"StarsTM :!;7@;7& S

"{BETELGEUSE

DENEB

&N SM

8¢

SIRIUS))

BETELGEUSE

Stars;
s+

DENEB

;

SIRIUS

The first FORMAT call starts a new line after the prefix ";",
because
the
7%
directive
starts
a
new line wherever the directive occurs.
Replacing the "% directive with the "& directive changes
the
output,
because the fresh line is not needed after the prefix.

The remaining three new line directives offer flexibility because they
are
conditional.
However,
they
have
no
effect on output (except
length abbreviation -- see Section 6.7.1) when pretty printing is
not
enabled.

The ~
directive (multiline mode new line) starts a new
line
1if
the
line
one
on
fit
to
long
too
is
block
logical
enclosing
the
for
output
new line.
a
<causes
block
or if any other directive in the logical

When
the output is too long, FORMAT uses multiline mode, and every " _
The ~:_ directive
directive in a logical block starts a new 1line.
1if the
new line if it is needed:
a
produces
(if-needed new 1line)
line.
current
the
following section of output is too long to fit on
~@_directive (miser-mode new line) produces a new line if pretty
The
printing is enabled with miser mode in effect
(see
Section
6.8
for
The FORMAT function ignores the three conditional new line
details).
directives when they occur outside a logical block.

The following example shows how you can specify a multiline
line

and an

Lisp>
16

Lisp>

mode

new

if-needed new line:

(SETF *PRINT-RIGHT-MARGIN*

16)

(FORMAT T "“:!”s ~_"s ~:_~s ~_"sTM."

' (BETELGEUSE ALDEBERAN MERCURY JUPITER))

BETELGEUSE
ALDEBERAN

MERCURY

JUPITER

This FORMAT function produces output in the
multiline
mode,
because
The multiline mode new line
on one line.
fit
not
output will
the

The "~ :_
for each element.
a new line
produce
directives (7_)
needed
if
MERCURY
before
line
new
a
start
to
FORMAT
directs
directive
(and a new line

is needed).

6-12

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

You can produce printed output that fills up the
space
available
1in
each
1line
by
wusing the at-sign (@) modifier with the directive that
ends the logical block (" !blockTM@.).
This modifier causes
FORMAT
to
start
a
new line if needed following every blank space or tab and 1is
equivalent to inserting a ":_
directive
after
each
element
to
be
printed, as shown in the following example:
Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

25)

Lisp>

(FORMAT

""@:!ANTARES ALPHECCA ALBIREO
POLLUX MIRZAM ALGOL

CANOPUS

BELLATRIX

MIRFAK DUBHE POLARIS "@."
ANTARES ALPHECCA ALBIREO
CANOPUS
MIRZAM

CASTOR
ALGOL

CAPELLA MIRA

CASTOR

CAPELLA MIRA

)

POLLUX

BELLATRIX

MIRFAK

DUBHE

POLARIS

6.3.4

Controlling Indentation

With pretty printing enabled, a call to FORMAT indents the output
for
a
logical
block
so that the first character in each succeeding line
falls under the first character following
the prefix
1in
the
first
line.
When
pretty printing is not enabled, the FORMAT call does not
produce indentation, and the indentation directive has no effect.

Use the “nI directive or the "n:I directive if you want to change
the
standard
pretty-printed indentation.
The "nI directive causes FORMAT
to indent subsequent lines n spaces from the
position
of
the
first
character
in
the
1logical
block.
The "n:I directive, on the other
hand, causes FORMAT to indent
subsequent
1lines
n
spaces
from
the
output
column corresponding to the position of the directive.
1If you
omit the parameter n, the default is 0.
Although this
parameter
can
be
1less
than 0 when used with the colon, the indentation cannot move
to the
left
of
the
first
character
in
the
1logical
Dblock.
An
indentation
directive affects only indentation produced on subsequent
new

lines.

The

following example shows

several

variations

the

directive:

Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

15)

Lisp>

(FORMAT T

"~ :!7S ~2I17:_"s ":1"s “_"s "117_"sTM."

' (BETELGEUSE
BETELGEUSE
DENEB

SIRIUS

VEGA
ALDEBERAN

DENEB

SIRIUS VEGA ALDEBERAN))

indentation

PRETTY

DENEB

lines

produces

beginning
the
of

under

new

line

the

lines

BETELGEUSE,

past

The

directives

and

directives

the

precede

6.3.5

the

new

can

the

are

available.

you

specify

divide

suffix,
the

" ;

suffix.

the

the
in

resets

7 :_

SIRIUS,

the

directive

spaces

third

up with

logical

past

argument
so that

the

sets
the

first

indentation

one

block.

They

not

start

new lines begin.

ALDEBERAN,

Although

FORMAT

call

and

pretty

prefix

suffix

indented
the

block

the

new

Therefore,

indentation

suffix,

the

FORMAT

abbreviation
the

control

twice,

call

directives

following

add

logical

string

the

prefixes

block.

into

directives

second

omit

the

second

" ;

directive,

the

body

can

any

FORMAT

output
is

second
the

for

logical

enabled,

line

lines
When

prints

eliminate
"Stars

the

some

marks

(FORMAT T

"“!Stars

"(SIRIUS
Stars

VEGA

forms

up with
the

suffix
the
the

body

< ;7S "%
S

"~ !Stars

' (SIRIUS

VEGA

<~ ;7S5 %78 ~_~§7;>"."
DENEB))

VEGA...>

6-14

the

that
line

the
of

prefix,

NIL

(FORMAT T

string,

includes
of

first

DENEB>

Lisp>

beginning

control

block

DENEB))

*PRINT-LENGTH*

first

1is

the

<SIRIUS

(SETF

and

suffix

logical

VEGA

Lisp>

the

prefix

block

second

suffix.

Lisp>

sections

directives.

prefix.

always

examples,

options

The

the

FORMAT

suffixes

specify

prefix;

include

and

Several

three

string will

the

printing

the

that

“tprefix” ;body” ;suffix” ..

prints

that

for

cannot

following

strings

produced

end

If you

When

and

format

and

the

lines

indentation.

control

follows:

marks

specified.

DENEB

for

first

directive
in

the
of

directives.

directive

prefix

the

take effect until

output

the

directive

for

directive

71I

because

indentation

ALDEBERAN

set the

FORMAT

printed

inserting

FORMAT

Producing Prefixes and Suffixes

You

only

line

":1I

character

they do not

EXTENSIONS TO

BETELGEUSE,

causes

column

the

first

lines

The

the

because
the

T
~2I

the

up with

column

the
and

block.

indentation
VEGA

PRINTING AND USING

end,

the
and

the

output

character
includes

even

block.
">"

forms

PRETTY

the

second

PRINTING

example,

FORMAT

because

*PRINT-LENGTH*

adds

suffix

the

SIRIUS
You

can

the

first

specify

("1!blockTM.),
prefix

after

and

the

Lisp>

list

column

for

the

prefix

parameter

the

EXTENSIONS TO

FORMAT

the

two

truncates
set

last

(FORMAT T

' (CASTOR

USING

the

causing

suffix,

AND

(see

1list

element.
body
1

FORMAT

Section

the

<call

6.7),

VEGA

lines

logical
logical

wuse

elements,

but

still

under

block.
block

directive

parentheses

for

the

shown:

""1:!75 7%7g87."

POLLUX))

(CASTOR
POLLUX
)

You

can

create

at-sign
prefix

per-line

prefixes

modifier
in the 7;
This modifier
of

Lisp>

each

line,

(FORMAT T

’ (ALGOL

logical

shown

the

"7 :1<<7@;"S "%7S A

ANTARES

block

specifying

the

directive used to indicate the end of
causes FORMAT to repeat the prefix at

(7@;).

beginning

ALBIREO

following

the
the

example:

- S

ALPHECCA))

< <ALGOL
<<ANTARES

<<ALBIREO
<<ALPHECCA>>

The

prefixes

you

shown:

nest

and

the

logical

list

elements

blocks,

you

can

Lisp> (FORMAT T "":!Bright
ST a7 LT
still twinkle.
."
"(SIRIUS

Bright

VEGA

stars

DENEB

prefix

and

"still

twinkle".

printed

the

suffix

each

first

line

1logical

">>",

6.3.6

Using Tabs

You

printed

can use

pretty

the

beginning with
block.

tab

printing
The

the

for

the

The

prefix

after

the

suffix

the

with

each

block,

for

6-15

the

"Bright

block,
the

stars”

"<<",

prefix

inner

logical

1in

columns.

is
for

block,

block.

"n,mT

the

specifies

are

logical

required

arrange

the

block

inner

indentation

The

enabled,
n

prefix

twinkle.

logical

for

end

indentation

integer

still

outer

directive

VEGA

block.

once

specify

starsTM; "@!<<"@;"s S "%"s ~

<<DENEB ALGOL>>

and

up.

ALGOL))

<<SIRIUS

The

line

output

tab directive

immediately
number

counts

-enclosing

columns.

The

When

spaces,
1logical

integer

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT
the number of columns to be added at one time
specifies an increment:
The at-sign modifier
<column width is at least n columns.
the
until

so
relative,
directive
tab
makes the
column.
output
current
the
with
beginning

spaces
counts
"n,m@T
that
When pretty printing is not

enabled, on the other hand, the "n,mT directive counts spaces from the
The defaults for
of the line, as specified in COMMON LISP.
beginning
n and m are 1

(see COMMON LISP:

The Language for details).

the tab directive precedes

In the iterative example that follows,
if-needed new

Lisp>
29

Lisp>

line

(SETF

the

directive:

*PRINT-RIGHT-MARGIN*

29)

(FORMAT T "Stars: ~:@!~{7s”

~11T"s "~

~: "}7."

' (POLARIS DUBHE MIRA MIRFAK BELLATRIX CAPELLA ALGOL
MIRZAM POLLUX CANOPUS ALBIREO CASTOR ALPHECCA
ANTARES)
)

Stars:

POLARIS

DUBHE

MIRA

MIRFAK

BELLATRIX

CAPELLA

ALGOL

MIRZAM

POLLUX

CANOPUS

ALBIREO

CASTOR

ALPHECCA

ANTARES

Since the tabs are counted from the indentation of the logical block,
tab directives do not have to account for the fact that the whole
the

block is shifted seven columns to the

6.3.7

right.

Directives for Handling Lists

VAX LISP provides three FORMAT directives that simplify the printing
Each implicitly uses the "W directive repeatedly to print
of 1lists.
elements.

If pretty printing is enabled, the "n/FILL/

FORMAT

directive

causes

fill the available line width by inserting a space

and an if-needed new line after each list element except the
If
FORMAT encloses the list in parentheses if n is 1.
last.
to
FORMAT
causes
“n/FILL/
enabled,
pretty printing is not

print the output in single-line mode.

If pretty printing is enabled, the "n/LINEAR/ directive causes
the list on a single line if the list fits.
to print
FORMAT
each element on a separate line.
prints
FORMAT
Otherwise,
If pretty
in parentheses if n is 1.
list
the
encloses
FORMAT
the
print
to
FORMAT
causes
printing is not enabled, “n/LINEAR/
output in single-line mode.

6-16

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

If pretty printing is
enabled,
the
"n,m/TABULAR/
directive
causes FORMAT to print the list as a table, using columns of m
spaces for list elements.
The default
wvalue
for
m
1s
16.
FORMAT
encloses the list in parentheses if n is 1.
1If pretty
printing is not enabled, "n,m/TABULAR causes FORMAT
to
print
the output in single-line mode.

The
the

following examples

show the

kinds

*PRINT-RIGHT-MARGIN*

36)

formats you can produce

list-handling directives:
Lisp>

(SETF

Lisp>

(FORMAT T

"Stars:

~@:!”/FILL/
."

" (POLARIS

DUBHE

MIRZAM

POLLUX

MIRA MIRFAK
CANOPUS

BELLATRIX

ALBIREO

CAPELLA ALGOL

CASTOR ALPHECCA

ANTARES)
)

Stars:

POLARIS

DUBHE

BELLATRIX

MIRZAM

POLLUX

ALBIREO

MIRA MIRFAK

CAPELLA ALGOL

CANOPUS

CASTOR ALPHECCA

ANTARES
NIL

Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

NIL)

NIL

Lisp>

(FORMAT T

"(POLARIS

MIRZAM

DUBHE

POLLUX

"Stars:

“@:!” /JLINEAR/ ."

MIRA MIRFAK

CANOPUS

BELLATRIX

ALBIREO

CAPELLA ALGOL

CASTOR ALPHECCA

ANTARES)
)

Stars:

POLARIS
DUBHE
MIRA

MIRFAK

BELLATRIX

CAPELLA
ALGOL
MIRZAM
POLLUX

CANOPUS
ALBIREO

CASTOR
ALPHECCA
ANTARES
NIL

Lisp>

(FORMAT T "Stars: “@:!"0,20/TABULAR,/ . "

* (POLARIS
MIRZAM

DUBHE MIRA MIRFAK BELLATRIX CAPELLA ALGOL

POLLUX

CANOPUS ALBIREO CASTOR ALPHECCA

ANTARES)
)

Stars:

POLARIS

DUBHE
BELLATRIX

MIRA
CAPELLA

ALGOL

MIRZAM

POLLUX

CANOPUS
ALPHECCA

ALBIREO
ANTARES

CASTOR

MIRFAK

6-17

with

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

6.4

DEFINING YOUR OWN FORMAT DIRECTIVES

VAX LISP lets you define your own FORMAT directives to supplement
the
directives
supplied
with
the system.
Any FORMAT directive that you
define you can use in the control string argument to a FORMAT call.
DEFINE-FORMAT-DIRECTIVE

name

(arg stream colon at-sign
&OPTIONAL (parameterl default)
(parameter?2 default)
e o)

&BODY

forms

This macro defines a directive named name.
After you define a
FORMAT
directive,
vyou can use it (whether or not pretty printing is enabled)
by including " /name/ in a FORMAT control string.

NOTE
If you do not specify a package
with
name
when
you
define
the
directive,
name is placed in the current
package.
If you do not specify
a
package
when
you
refer
to the directive, the FORMAT directive looks 1in
the USER package for the directive definition.

For the body of the macro
call,
the
symbols
you
stream, colon, and at-sign are bound as follows:

supply

for

arg,

arg is bound to the argument list for the FORMAT directive you
define.

stream is bound to the stream on which the printing is

done.

The colon and at-sign arguments are bound to

NIL

wunless

colon and at-sign modifiers are used with the directive.

the

There must be one optional argument for each prefix parameter that
1is
allowed
in
the
directive.
A
parameter
argument will receive the
corresponding prefix parameter if it was specified in
the
directive.
Otherwise,
the
default
value
will
be
wused,
as with all optional
arguments.

The body is evaluated

to print

the argument arg on the output

stream.

A
user-defined
FORMAT
directive can be useful because it provides a
level of
indirection.
In
addition,
vyou
can
<call
the
directive
repeatedly,
which
may
save you some time coding and debugging.
The
following example shows a
format
directive
wused
to
produce
error
messages:

6-18

PRETTY

Lisp>

PRINTING

AND

USING

(DEFINE-FORMAT-DIRECTIVE

EXTENSIONS TO

EVALUATION-ERROR
(SYMBOL

STREAM

&OPTIONAL
(DECLARE

(IGNORE

(FRESH-LINE

(PRINC

FORMAT

COLON-P

(SEVERITY

ATSIGN-P

0))

ATSIGN-P))

STREAM)

(CASE

SEVERITY

"Warning:

"Error:

"Severe

Error:

"))

STREAM)

(FORMAT

(WHEN

STREAM

"7 :!The

symbol

“S

" : _does

integer

value.

%$Its

SYMBOL

(SYMBOL-VALUE

not

value

have

is:

an ~

SYMBOLY}))

COLON-P

(WRITE-CHAR

#\BELL

STREAM)))

EVALUATION-ERROR

Lisp>

(SETF

PROCESS

NIL)

NIL

Lisp>

(FORMAT

Error:

""1:/EVALUATION-ERROR/"

The

symbol

Its

value

PROCESS
1s:

does

not

'PROCESS)

have

integer

value.

NIL

<BEEP>

This

example

application
the

shows

current

the

package

1is

" :/EVALUATION-ERROR/"
signaled.

The

definition

directive,

colon

and

USER.
the

printed
The

indicates

the

FORMAT

directive,

output.

prefix

parameter

severity
call

the

produces

assumes

that

error
beep

being

the

terminal.

6.5

DEFINING

You

can

use

specific

define

DEFINE-LIST-PRINT-FUNCTION

kinds

are

checks

the

element

PRINT FUNCTIONS FOR LISTS

lists

formats

effective

only

first

element

printed

list-print

list

matches

according
function

of each
name

the

according

list
of

format

the

DEFINE-LIST-PRINT-FUNCTION

Symbol

macro

defines

redefines

element

symbol.

the

first

and

stream

The

forms

are

For

example,

MY-SETQ,

any

bound

evaluated
if

you
list

that
vyou

bound

on which

output

list.

list-print
with

6-19

prints.

the

first

function,

the

list

have

printer

specified.

Create

format:

stream)

function

stream

beginning

you

The

(list

that

enabled.

list-print

the

define

Functions

forms

1list

functions

choice.

following

&BODY
This

define

your

pretty printing

the

for

the

lists

list

printing

function

MY-SETQ

will

to
is

for
be

for

be
to

the

printed

which

printed
be

done.

symbol
in

your

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

format when pretty-printing
Lisp>

is enabled:

(DEFINE-LIST-PRINT-FUNCTION MY-SETQ
(FORMAT

STREAM

nUITTA

Y ITR{TWTS

(LIST STREAM)

L
T TWhTeT

LIST))

MY-SETQ

Lisp>

(SETF BASE

(MY-SETQ HI
Lisp>

3
3

(PPRINT

(MY-SETQ HI
BYE

BYE

3 BYE

4))

BASE)

(PRINT

(MY-SETQ HI
(MY-SETQ HI
Lisp>

' (MY-SETQ HI

BYE
BYE

4)
4)

BASE)

3
4)

When pretty printing is not enabled,

the

wvalue

BASE

without regard to the list-print function defined for MY-SETQ.

PPRINT

wvalue

the

enables pretty printing, producing a representation of

printed
of

BASE using the specified list-print function.

functions
VAX LISP pretty printing incorporates predefined list-print
However, if you define a list-print
for many standard LISP functions.
function for a LISP keyword, your function will override the one built
into

the

system.

NOTE
When

vyou

wuse

DEFINE-LIST-PRINT-FUNCTION,

may

you

encounter two kinds of output that you do not expect:

the
1is
element
In most cases, a list whose first
be
will
function
list-print
defined
a
for
symbol
the
1f
even
specified,
format
the
in
printed
and meaning of the list are irregular and
context
your
For example, 1if
the format is inappropriate.
IT BE) and LET is the symbol of a
(LET
says
data
defined list-print function,

may be

the

resulting

output

inappropriate.

a
List-print functions are not used when you print
FORMAT
wuser-defined
a
of
control
under
list
directive.

You

can

disable

any

defined

1list-print

UNDEFINE-LIST-PRINT-FUNCTION macro.

UNDEFINE-LIST-PRINT-FUNCTION symbol

6-20

function

Its format is:

using

the

PRETTY PRINTING AND US!NG EXTENSIONS TO FORMAT
This

macro

disables

following

example

the

Lisp>

the

list-print

disables

beginning

function defined

LET

this

list-print

for

symbol.

function defined

The
in

the

section:

(UNDEFINE-LIST-PRINT-FUNCTION MY-SETQ)

MY-SETQ

6.6

the

DEFINING GENERALIZED PRINT FUNCTIONS

Using generalized print functions, you can specify how any
object
1s
pretty-printed, regardless of its form.
Functions that you define and

enable
define

are effective only if pretty printing is
enabled.
First
you
a
function
with DEFINE-GENERALIZED-PRINT-FUNCTION.
Then you
enable
the
function.
You
can
enable
it
globally,
using
GENERALIZED-PRINT-FUNCTION-ENABLED-P.
Or
vyou can enable it locally,
using WITH-GENERALIZED-PRINT-FUNCTION.

Use

the

following

format when you define

generalized print

DEFINE-GENERALIZED-PRINT-FUNCTION name (Object
predicate
&BODY

function:

stream)

forms

This

macro defines or redefines a print function with the
name
name.
object
1is
bound to the object to be printed.
stream is bound to the
stream
to
which
output
1is
to
be
sent.
predicate
governs
the
application
of
the
generalized
print
function.
The predicate 1is
operative on any LISP object.
A generalized print
function
will
be
used
if
it
1is
enabled
and
the predicate evaluates to true on the
object to be printed.
(NULL OBJECT) is the predicate
1in
the
sample
generalized
print
function
shown
at
the end of this section.
The
output stream can use your generalized print
function
to
print
any
object
for
which
the
©predicate
does
not
evaluate to NIL.
forms
identifies arguments to be evaluated in the call to FORMAT.

generalized print

symbol
A

are

function

both

function
is

function

enabled,
lets

the
you

and

list-print

generalized print
test whether

can

also use

function,

for

specific

the

same

used.

generalized

enabled:

GENERALIZED-PRINT-FUNCTION-ENABLED-P

You

function

function will

using

this
SETF

function
as

globally

shown:

6-21

name

change

the

status

the

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

(SETF

(GENERALIZED-PRINT-FUNCTION-ENABLED-P

name)

(SETF

NIL)

(GENERALIZED-PRINT-FUNCTION-ENABLED-P name)

Use the WITH-GENERALIZED-PRINT-FUNCTION
generalized print

function

in the

macro

following

locally

enable

format:

WITH-GENERALIZED-PRINT-FUNCTION name &BODY forms

This macro locally enables the generalized print function
when

evaluates

the

named

name

specified forms.

The printer checks generalized print functions that have been
enabled
in reverse order from the order of their enabling.
This means that in
cases where two or more generalized print functions
apply,
the
most
recently enabled

function

is used.

Enabling a generalized print function globally is less efficient
than
enabling
it
locally, because the printer must check the predicate of
globally enabled print functions against every object to
be
printed.
If
you
enable
the
generalized
print function locally, the printer
checks the function’s predicate against the object being printed
only
during
execution
of
the
code within the macro, instead of on every

call to a print function.

often,

the difference

Consider

the

Lisp>

Since

the

read-eval-print

in efficiency can be

significant.

loop

1is

used

following examples:

(SETF

*PRINT-RIGHT-MARGIN*

25)

Lisp>

(GENERALIZED-PRINT-FUNCTION-ENABLED-P

‘PRINT-NIL-AS-LIST)

NIL

Lisp>

(DEFINE-GENERALIZED-PRINT-FUNCTION PRINT-NIL-AS-LIST
(OBJECT
(NULL

(PRINC

STREAM)

OBJECT)

STREAM))

PRINT-NIL-AS-LIST

Lisp>

(PRINT

NIL)

Lisp>(PPRINT

NIL)

NIL
NIL

NIL

Lisp>

(WITH-GENERALIZED-PRINT-FUNCTION
(PRINT
(PPRINT

NIL)
NIL))

NIL

()

6-22

’'PRINT-NIL-AS-LIST

PRETTY

Lisp>

(SETF

PRINTING AND USING

EXTENSIONS TO FORMAT

(GENERALIZED-PRINT-FUNCTION-ENABLED-P
"PRINT-NIL-AS-LIST)

LISP>

(PPRINT

NIL)

()
The

first

call

The

first

enabled.

function

call

prints

second
is

call

enabled

prints

globally

because

call

prints

1locally

(

and

NIL,

PPRINT

and

because

pretty

because

call

PRINT-NIL-AS-LIST

NIL,

PPRINT

prints

not

because

the

pretty printing

the

printing

the

The

again

enabled.

print
The

function

an object
1.

The
or

The

function controls
the printing
the following conditions exist:

generalized print

third

PPRINT

enabled

globally

locally.

predicate

specified

PRINT-FUNCTION

function

The object
control of

1is

with

DEFINE-GENERALIZED-

true.

to
be
printed
does
not
come
a user-defined FORMAT directive.

under

In cases where two or more generalized print functions
are applicable, only one is chosen.
The one chosen is
the
most
recently
enabled
(globally
or
locally)
generalized
print
function
for
which the predicate
specified
with
DEFINE-GENERALIZED-PRINT-FUNCTION
1s
true.

Generalized print functions
are
print an object under control of

not
wused
when
you
a user-defined FORMAT

directive.

6.7

ABBREVIA

You

can

abbreviate

The
M~
ER

8 wy

printed

length of

the object

epth of nested

The number

output

lines

according

to be printed

logical

to:

the

blocks

output

6-23

The

function

enabled.

only

not

enabled.

NOTE
A generalized

generalized

second

not

generalized

printing

because

enabled.

pretty printing

(

pretty

NIL,

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

Length

and

depth

effective

abbreviation
VAX

LISP;

6.7.1
You

the

can

control

sections
7 _,

the

are

supported

pretty

number

printing

lines

only when

COMMON

output

pretty

number

sections

The

value

variable.
to

7%,

printed

and "&

for

mark

for
details).
sections
of
a

the

processing

not

truncated

The

following

example

Lisp>

and

1In

printing

any

the

printed

are

addition,

supported

1in

enabled.

the
the

sections

shows

setting

supply specifies the

affected

logical

block.

logical

The

block

(see

After
the
output
stream
prints
1logical
block, it prints an ellipsis

immediately enclosing
value

output

you

...) and stops processing the logical block.
nested with other logical blocks, the output
of

LISP

enabled.

Output Length

the

Section
6.3.3
*PRINT-LENGTH*

not

effective

*PRINT-LENGTH*

directives

(

based

this

Abbreviating

number

abbreviation

whether

*PRINT-RIGHT-MARGIN*

(SETF

*PRINT-LENGTH*

11)

(SETF

*PRINT-PRETTY*

1logical
terminates

block.

block
only

Output

1is

NIL.

abbreviation

(SETF

the

logical

*PRINT-LENGTH*

output

1If

stream

based

length:

47)

477
Lisp>
11

Lisp>
T

Lisp>

(FORMAT T

"Stars:

“@!"{"w~

' (POLARIS

DUBHE

MIRZAM

POLLUX

"} ."

MIRA MIRFAK

BELLATRIX

CANOPUS

ALBIREO

MIRFAK

BELLATRIX

CAPELLA ALGOL

CASTOR

ALPHECCA

ANTARES)
)

Stars:

POLARIS

DUBHE

CAPELLA ALGOL

MIRA

MIRZAM

POLLUX

CANOPUS

ALBIREO

Each

star

section.
indicate

6.7.2

name

FORMAT
that the

the

1list

prints
list has

<constitutes

" ..."
after
the
been abbreviated at

separate

1logical

eleventh
star
that point.

output

Abbreviating Output Depth

Use the variable *PRINT-LEVEL* to control the depth of printed
*PRINT-LEVEL* specifies the lowest level of dynamically nested
blocks

block
name

to be

printed.

stream keeps

output when
inaicates

When your
track

program calls

the

level

reaches

where

the

stream nas

actual

nesting

*PRINT-LEVEL*.
truncatea

FORMAT

tne

The

level

output.
logical

recursively,

the

and abbreviates

printed character

output.

You
a9 %

can

falat &

prevent

L a2V

Vel

Fala!

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

Dynamic

nesting

logical

blocks

occurs

frequently

when

you

complicated
structures.
This nesting may not be obvious as you read
the program.
For example, if you have
defined
1list-print
functions
for
the
primitives
IF
and
PROGN,
printing
a program that uses a
combination of these
primitives
would
involve
dynamic
nesting
of
logical
blocks,
since each list print function uses the "W directive
implicitly.
The
following
example
shows
how
the
output
stream
abbreviates

the

printing

structure

*PRINT-LEVEL*

in accord with

the value

*PRINT-LEVEL*:

Lisp>

(SETF

Lisp>

(PPRINT

(LEVEL1

Lisp>

' (LEVEL1

(LEVELZ2

(SETF

(LEVELZ

(LEVEL3

(LEVEL4

(LEVELS))))))

(LEVEL3

(LEVEL4

(LEVELS))))))

#)))

*PRINT-LEVEL*

Lisp>

(PPRINT

(LEVEL1

Lisp>

' (LEVEL1

(LEVELZ2Z

(PPRINT

(LEVELZ

%))

' (LEVEL1

(LEVEL2

(LEVEL3

(LEVEL4

(LEVELS5))) ) ))

(LEVEL1

6.7.3

(LEVEL2

#))

Abbreviating Output by Lines

You

can control the number of lines printed in the output
by
setting
the *PRINT-LINES* variable.
The value you supply specifies the number
of lines to be printed for the outermost logical
block.
The
output
stream
prints " ..." at the end of the last line to indicate where it
has truncated the output.
If *PRINT-LINES* is NIL, the output
stream
will
not
abbreviate
the number of lines printed.
This abbreviation
mechanism is effective only when pretty printing is enabled.
In

the

following example,

printing

stops

the

end

the

fourth

line:

Lisp>

(SETF

*PRINT-LINES*

Lisp>

(FORMAT T

"Stars:

~:!” /LINEAR/"."

' (POLARIS

DUBHE

MIRZAM

POLLUX

MIRA MIRFAK
CANOPUS

ANTARES)
)

Stars:

POLARIS
DUBHE
MIRA

MIRFAK

6-25

BELLATRIX

ALBIREQ

CASTOR

CAPELLA ALGOL
ALPHECCA

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT
6.8

USING MISER MODE

you
blocks,
If you print large structures with deeply nested logical
Indentation produced in the output by
may find the miser mode useful.
the nesting of logical blocks, prefixes, and the "nI directive reduces
Miser mode helps you avoid
length available for printing.
line
the
Miser mode
running out of space and printing beyond the right margin.
problems.
these
of
elimination
the
guarantee
however,
does not,

line.
Pretty printing uses single-line mode if the output fits on one
requires
output
the
and
lines
If the FORMAT control string permits new
The
two or more lines, pretty printing normally uses multiline mode.
mode
a logical block in miser
print
to
determines whether
printer

according to the current column of the output at the beginning of

the

logical block and the values of two variables:
@

*PRINT-RIGHT-MARGIN%*

*PRINT-MISER-WIDTH*

*PRINT-RIGHT-MARGIN* specifies

the

location

the

right

margin.

of columns before the right
number
a
specifies
*PRINT-MISER-WIDTH*
logical
When the current output column at the beginning of a
margin.
between
difference
the
than
greater
or
to
equal
1s
block
block
1logical
*PRINT-RIGHT-MARGIN* and *PRINT-MISER-WIDTH*, then the
condition occurs when the total
This
in miser mode.
printed
is
available line width is less than the value of *PRINT-MISER-WIDTH*, as
in

shown

Figure

6-1.

COLUMN AT WHICH
PRINTER

ENTERS MISER MODE

* PRINT-RIGHT-MARGIN*

|«——*PRINT-MISER-WIDTH*—*

Figure 6-1:

Variables Governing Miser Mode

You can disable miser mode by setting *PRINT-MISER-WIDTH* to NIL.
Miser mode

saves

space

by:

Ignoring indentation FORMAT directives

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

Starting a new line
Multiline mode

every conditional

new line

If-needed new line
Miser mode
The
mode

two

examples

and

miser

Lisp>

that

directive:

(7 )

(" :_)

new line
follow

new line

(7@_)

contrast

pretty

printing

multiline

mode:

(SETF

*PRINT-RIGHT-MARGIN*

(SETF

*PRINT-MISER-WIDTH*

60)

Lisp>

35)

Lisp>

(FORMAT T

"":!Stars with Arabic names: "S °S "2717:_"8 7
Y.I17@."S
T 7S Y117 _Tsv.

' (BETELGEUSE
ALDEBERAN

Stars

with Arabic

(DENEB
ALGOL

names:

SIRIUS

(CASTOR

BETELGEUSE
ALDEBERAN

VEGA)
POLLUX)

(DENEB

BELLATRIX))

SIRIUS

VEGA)

ALGOL
(CASTOR

POLLUX)

BELLATRIX

NIL

Lisp>

(FORMAT T

""" !Stars with Arabic names:
@P S N ¥2717: 7s T:1"@_"Ss
T _"s T117 _"°§”
"

"({BETELGEUSE
ALDEBERAN

Stars

with

Arabic

(DENEB
ALGOL

names:

SIRIUS

(CASTOR

VEGA)
POLLUX)

BELLATRIX))

BETELGEUSE
(DENEB

SIRIUS

VEGA)

ALDEBERAN

ALGOL

(CASTOR

POLLUX)

BELLATRIX

In the first output sample, FORMAT uses multiline mode.
Miser mode 1is
never
enabled, because the logical block begins at column 0 and miser
mode takes effect only if the column begins at column 25
(60
35).
ALDEBERAN
1lines
wup
with
the
T
in
BETELGEUSE,
because
the "27I
directive sets the indentation for following lines at
column
27
and

the
the

7~ :_
directive
produces a new line.
The
":I"@_"S directive sets
column for the next line at the level of the A in ALGOL.
The
"11I

directive

controls

indentation

column

the

last

argument,

BELLATRIX,

setting

the

The second output example shows the effects of miser mode, because the
text
in
the
outer logical block, "Stars with Arabic names:", causes
the
inner
logical
block
to
begin
at
column
26.
With
*PRINT-MISER-WIDTH*
set
to
35,
FORMAT
enables miser mode when the
logical block begins
past
column
25.
FORMAT
conserves
space
by

starting

and every

if-needed new line directive

new

line at every multiline mode new line directive

6-27

(" :_).

FORMAT also

("_)

inserts

PRETTY PRINTING AND USING EXTENSIONS TO FORMAT

new
line
at
the miser mode new line directive
indentation directives (" nl).

6.9

("@_)

and

ignores

the

HANDLING IMPROPERLY FORMED ARGUMENT LISTS

VAX LISP provides a method for gracefully handling argument lists that
are improperly formed.
The function of the "* directive, when used in
a logical block, differs slightly from the corresponding
function
1in
COMMON

LISP.

In COMMON LISP the " directive is used with the iteration
directives
“{
and 7} to check whether the argument list has been reduced to NIL.
If

the

list

NIL,

iteration

stops.

You can also use the 7" directive to check whether the
argument
1list
for
a logical block has been reduced to a non-NIL atom.
If the check
shows that the argument list is a non-NIL
atom,
the
printer
prints
space-dot-space
( . ) and uses the "W directive to print the value of
the atom.
FORMAT then
stops
processing
the
immediately
enclosing
logical
block, after printing the suffix (if one is there).
No error
condition results.
The following example shows the use of
FORMAT
to
print

dotted

Lisp>

pair:

(FORMAT T

"“1:t!~@{~s~~ ~}~."

' (CASTOR

(CASTOR

POLLUX

DENEB

ALDEBERAN)
)

ALDEBERAN)

This feature serves as a useful debugging tool, because
it
1lets
the
FORMAT function work even when the argument list is improperly formed.

NOTE
When the 7* directive is included in a logical
block,
the
FORMAT
function checks whether the argument list
is a non-NIL atom, even when pretty
printing
is
not
enabled.

6-28

CHAPTER 7

VAX LISP/VMS IMPLEMENTATION NOTES

'VAX LISP is an implementation of LISP that is based on COMMON LISP
as
described
in
COMMON
LISP: The Language.
This chapter describes how
implementaton-dependent aspects of COMMON LISP are implemented on
the
VMS
operating
system.
This chapter does not describe implementation
differences between VAX LISP/VMS (VAX LISP as implemented on VMS)
and
VAX
LISP/ULTRIX
(VAX
LISP
as
1implemented
on
ULTRIX).
For such
differences, see the VAX LISP/VMS Release Notes.
These are on-line 1in
the
file
SYSSHELP:LISPnnn.RELEASE
NOTES,
where
nnn is the VAX LISP
version
number.
For
example,
LISPO20.RELEASE_NOTES
1is
the
file
containing the release notes for Version 2.0.
Most of the information in this chapter refers to subjects that COMMON
LISP: The Language refers to as implementation dependent.
The purpose
of this chapter is to clarify the
implementation
specifics
for
the
following

topics:

representation

Data

Pathnames

The

Input

Interrupt functions, including keyboard functions that execute
asynchronously when you type a contrcl character

The

®@

Functions

garbage

collector

and output

compiler

and macros

NOTE

LISP: The
COMMON
in
documented
Complex numbers are
Language, but they are not implemented in VAX LISP.

VAX LISP/VMS

VAX

LISP

packages

7.1

only

LISP,

LISP

defines

does

not

the

data

types.

VAX

LISP.

COMMON

LISP:

This

types

section

Complete

are

1in

the

VAX

LISP

but

The

i1nformation

type

information

data

types

following

data

types

are

COMMON

data

descriptions

Characters

Arrays

Strings

provided

require

specific
VAX

LISP

Numbers
7.1.1.1

integer

and

7.1.1.2

provide

floating-point

1Integers - COMMON LISP
and

bignums.

implementation.

2**%29-1

are

VAX

fixnums

LISP,

values

two

these

two

the integers

fixnums;

bignums.

integers

VAX

information

about

types.

LISP

subtypes

integer

types

in the

range

not

the

stores

integers:
depend

-2#%*%*29

fixnum

bignums

range
two’s

sequences.

the

having

dependent.
values

bit

data

defines

ranges

1In VAX LISP,

represented

complement

The

implementation

number

fixnums

The

implemented

provides

7.1.1.1

that

UIS.

information:

Numbers

Sections

are

and

implementation-dependent

Language.

7.1.1

the data

define

The

implementation

the

symbols

EDITOR,

NOTES

DATA REPRESENTATION

COMMON

the

supports
named

IMPLEMENTATION

the

The

function
same

COMMON

names

returns

when

called

with

two

value.

LISP

integer

the

constants

and

follow:

MOST-POSITIVE-FIXNUM

536870911

MOST-NEGATIVE-FIXNUM

-536870912

7-2

the

are

implementation

corresponding VAX LISP

VAX LISP/VMS IMPLEMENTATION

NOTES

NOTE
The

range

likely
is,

intedgers

cut

the

integers

(-2**28
The

current

Remember
your

Descriptions

represented

half

range

2**28-1)
range

this

for

note

in VAX

-268,435,456

will

fixnums

when

fixnums

LISP Version
to

placing

will

That

+268,435,456

represented
1s

3.0.

=-2**29

fixnums.

2**29-1.

FIXNUM declarations

programs.

these

constants

are

provided

1in

COMMON

LISP:

The

Language.

7.1.1.2

Floating-Point Numbers

types

floating-point

COMMON LISP

Short

Single

floating-point numbers

Double

floating-point

Long

In VAX LISP,

defines

the

following

numbers:

floating-point

numbers

floating-point numbers
these

four

types

are

implemented with VAX

floating

data

types.
Both
the
short
and
single
floating-point
numbers
are
implemented as VAX F_floating data.
Double floating-point numbers are
implemented
as
VAX G_floating data.
Long floating-point numbers are
implemented as VAX
H_floating
data.
For
1information
on
the
VAX
floating data types, see the VAX Architecture Handbook.
Table 7-1 lists the types of COMMON LISP floating-point
numbers,
corresponding VAX data types, and the number of bits allocated for
exponent and significand of each floating-point type.

Table 7-1:

VAX LISP Floating-Point Numbers

COMMON LISP Type

VAX Type

SHORT -FLOAT

F_floating

SINGLE-FLOAT

F_floating

DOUBLE-FLOAT

G_floating

H_floating

113

LONG-FLOAT

Exponent

Significand

the
the

VAX LISP/VMS IMPLEMENTATION

The

wvalues

o0of

implementation

the

COMMON

dependent.

LISP

You

NOTES

floating-point

can

use

the

values

constants

these

are

constants

compare the range of values and the degrees of precision of the VAX
floating-point types.
Table 7-2 lists the names of the constants

LISP

and

provides

approximations

Table 7-2:

the
for

actual
VAX

hexadecimal

values

and

the

decimal

LISP.

Floating-Point Constants

Approximate
Hexadecimal

Constant

Decimal

Representation

Value

DOUBLE-~-FLOAT-EPSILON

H0UBBABAa

AULAB3CCH

DOUBLE—FLOAT-NEGATIVE-EPSILON

ARBABALO AANB3CCH

LEAST-NEGATIVE~-DOUBLE-FLOAT

WANBOAVAE

BBYUYBALA

LEAST-NEGATIVE-LONG~-FLOAT

WBVvPaYLA

GUOVYIVE

LEAST-NEGATIVE-SHORT~-FLOAT

povnNBuBH

-2.94e-39

LEAST-NEGATIVE-SINGLE-FLOAT

VUuaBUBY

-2.94e-39

LBAST—POSITIVE*DQUBLE-FLOAT

B6VVVOYE vhBoHAle
VHOVOYHON

1.114-16

1.114-16
-5.56d4-3¢9
HRUPUDGA

PBBABAL]

-8.41L-4933

5.56d4-369

LEAST-POSITIVE-LONG-FLOAT

ABAVUVLA

LEAST-POSITIVE-SHORT-FLOAT

BUBBBABY

VBANAVEY

VPOUALAL

8.41L-4933

2.94e-39

LEAST-POSITIVE-SINGLE-FLOAT

hiAveusy

2.94e-39

LONG-FLOAT-EPSILON

VB000RAY DBUBAAAN AUBAYAYA ABBA3FIP

9.63L-35

LONG-FLOAT-NEGATIVE-EPSILON

VUBYAALE AOOAUBYA CAAAUNAAY BUUU3IFIN

‘9.63L—35

MOST-NEGATIVE-DOUBLE-FLOAT

FFFFFFFF FFFFFFFF

-8.99d4387

MOST-NEGATIVE-LONG-FLOAT

FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF

-5.95L4931

MOST-NEGATIVE-SHORT-FLOAT

FFFFFFFF

-1.78e38

MOST-NEGATIVE~-SINGLE-FLOAT

FFFFFFFF

-1.76e38

MOST-POSITIVE-DOUBLE~FLOAT

FFFFFFFF FFFFTFFF

8.99d387

MOST~-POSITIVE~-LONG-FLOAT

FFFFFFFF FFFFFFFF FFFFFFFF FFFFTFFF

5.95L4931

MOST-POSITIVE-SHORT-FLOAT

FFFFTFFF

1.76e38

MOST-POSITIVE-SINGLE-FLOAT

FFFFITFFF

l.78e38

SHORT-FLOAT-EPSILON

nReBa3484a

5.96e-8

SHORT-FLOAT-NEGATIVE-EPSILON

98063480

5.96e-8

SINGLE~-FLOAT-EPSILON

BAnve3484

5.96e-8

SINGLE-FLOAT-NEGATIVE-EPSILON

44043484

5.96e-8

Descriptions of these

constants

are

provided

1in

COMMON

LISP:

The

Language.

COMMON LISP allows an implementation to define a floating-point
zero.
In VAX LISP, floating-point minus zero does not exist.

minus

VAX LISP/VMS IMPLEMENTATION NOTES

7.1.2

Characters

COMMON LISP defines characters as objects that have three
attributes:
code,
Dbits, and
font.
The
code
attribute
specifies
the
way a
character is printed or
formatted.
The
bits
and
font
attributes
specify extra flags to be associated with a character.
In VAX LISP,

The code attribute consists of eight bits and is encoded using
the

the character attributes are defined as follows:

extended ASCII

set.

The bits attribute consists of
CONTROL,

character

The

HYPER,

META,

and SUPER.

the

four

COMMON

LISP

bits:

font attribute consists of four bits.

NOTE
The CONTROL attribute
bit
has
no
association
control characters in the ASCII character set.

with

The VAX LISP implementation of
COMMON
LISP
functions
that
perform
character comparisons bases its comparisons on the numeric values that
correspond to the extended 8-bit ASCII character set.
The
character
predicate
functions
and
the rules that the functions use to compare
characters are described in COMMON LISP: The Language.

The ordering of two characters
that
have
different
bits
and
attributes and the same character code is undefined in VAX LISP.

font

The COMMON LISP character
constants
that
are
the
exclusive
upper
limits
on
the
code,
bits,
and
font
attributes
have
implementation-dependent values.
The names of the constants
and
the
corresponding VAX LISP values

are:

CHAR-CODE-LIMIT

256

CHAR-BITS-LIMIT

CHAR-FONT-LIMIT

NOTE

The values of these constants might change
releases

of VAX

Descriptions of these

future

LISP.

constants

are

Language.

7-5

provided

COMMON

LISP: The

VAX LISP/VMS

You

can

obtain

the

VAX

LISP

7.1.3
COMMON

LISP

defines

according

dimensions

dimensions,
The

table

valid

CHAR-NAME-TABLE

VAX

LISP

function

NOTES

character

described

names

Part

<calling

II.

Arrays

arranged

IMPLEMENTATION

names

and

array
a

called
total

the

its

size

array

Cartesian

rank.
are

object

whose

coordinate

system

The

1limits

implementation

constants

and

the

components
and

are

whose

number

array’s

rank,

dependent.

corresponding

VAX

LISP

values

are:

ARRAY-DIMENSION-LIMIT

536870911

ARRAY-RANK-LIMIT

536870911

ARRAY-TOTAL-SIZE-LIMIT

536870911

These

constants

COMMON

only

LISP

are

defines

elements

array

(SIGNED-BYTE

32),

not

general

7.1.4

array

LISP

LISP,

string

COMMON

specialized

specific
when
or

(element

type

The

array

LISP
or

element

Language.
that

creates

type

1is

element

FLOAT

these

LISP:

VAX

array’s

subtype

one

array

type.

have

defines

string

can

character

object.

character

set

font

can

STRING-CHAR,

(UNSIGNED-BYTE
types,

VAX

contain

efficient

LISP

1-29).

creates

T).

LISP,

LISP

the

vector

that

can

characters

characters.

many

string
as

that

String

characters.

65,535

stored

compose

the

characters

characters.

string

8-bit ASCII

cannot

have

represents

attribute.

pathname

specification.

COMMON

composed

character

string

PATHNAMES

divided

are

7.2

COMMON

LISP,

file

string

VAX

bits

Strings

COMMON
VAX

does

specialized
array

described

pathnames

This
as

VMS

LISP

section
file

follows:

7-6

data

object

describes

that

how VAX

specifications.

LISP
The

implements
section

1is

VAX LISP/VMS IMPLEMENTATION NOTES

7.2.1

Namestrings

Logical

When

Fields of a COMMON LISP pathname

Field values of a VAX LISP pathname

Three ways

Comparing

Converting pathnames

Functions

that use pathnames

Using the

*DEFAULT-PATHNAME-DEFAULTS* variable

names

to use

and pathnames

pathnames

create pathnames

similar pathnames

into namestrings

Namestrings

In VAX LISP, file names can be represented by pathnames,
namestrings,
symbols,
or streams.
Besides the term PATHNAME, COMMON LISP uses the
term NAMESTRING.
Since computer systems (for example, VMS and ULTRIX)
have
different
ways
of
formatting
file
names,
COMMON
LISP uses
namestrings to translate between pathnames (implementation-independent
names) and file names (implementation-dependent names).

A namestring is a string naming a file in an
implementation-dependent
form customary
for the file system.
A VAX LISP namestring is a string

containing a valid VMS file specification.

For example,

if a file

the
VMS
file
system is called SYSSLOGIN:LOGIN.COM;4, the equivalent
namestring would be displayed as "SYSSLOGIN:LOGIN.COM;4".
File system functions, such as LOAD, accept pathnames
convert
pathnames
to
namestrings.
For
more
namestrings,

7.2.2

see

Section

but
internally
information
on

7.2.8.

Logical Names and Pathnames

In VAX LISP/VMS, logical names are translated at the time
a
pathname
is
created.
This
1is
to
allow
pathnames
to
be merged properly.
Translation of logical names is not
normally
a
problem
wunless
the
logical
name
has
multiple translations.
1In general, use of strings
(rather than pathnames) for file specifications improves
the
wutility
of
logical
names
with
multiple
translations.
Some functions that
accept pathnames or strings as arguments (such as OPEN and PROBE-FILE)

VAX LISP/VMS IMPLEMENTATION NOTES

can
be
and the

passed a string including a reference to such a logical name,
appropriate
translation
will
be
used.
Other
functions,

however,

(such

LOAD and COMPILE-FILE)

convert

string arguments

pathnames in order to merge in the file type
and
directory,
1f
not
specified.
In
that case, the first translation for which the device
and directory exist is used.
Providing a complete file
specification
in
the
string
argument
to
LOAD
or
COMPILE-FILE
allows
all the
translations of included logical names to be used.
If a

file

names

are

specification includes a

7.2.3

When to Use Pathnames

not

translated

reference to a

remote node,

logical

the resulting pathname.

Pathnames do not replace the traditional ways of representing
a
file
in
LISP.
Instead, the pathnames add a new way of representing a file
to
make
LISP
programs
portable
between
systems
with
different
file-naming

conventions.

Pathnames, however, do not have to refer to an existing file
or
give
complete
file
specifications; pathnames can exist as data objects in
themselves and are
used
as
arguments
to
pathname
functions
(see
Section

7.2.9

and COMMON LISP:

The Language).

Several pathname functions and most functions that deal with the
file
system
can take either pathnames, namestrings, symbols, or streams as
their arguments.
However, the values of the
following
variable
and
arguments

must

pathnames:

*DEFAULT-PATHNAME-DEFAULTS* variable

The

The defaults

argument

1in

cal

the

PARSE-NAMESTRING

function

See Section 7.2.10 and COMMON LISP:
the

preceding variable

7.2.4

Fields of

and

The Language for a description

function.

a COMMON LISP Pathname

A COMMON LISP pathname is a LISP data object composed of
six
Each
field
represents
one
of
the
following
aspects
of
specification:

file

system

Host

Device

- file structure or a
device

on which

(physical or logical)

files are

stored

fields.
a
file

VAX LISP/VMS IMPLEMENTATION

directory

String,

NIL,

The

:WILD

the

VMS

you

must
An

example

"DBAl".

the

keyword

specify

omit

wildcard

:WILD

the

final

device

keyword.

translated

symbol

VAX LISP/VMS IMPLEMENTATION NOTES

Table

7-3

Pathname

(cont.)

Field

VMS

Component

Value

asterisk

(*).

string, you must
brackets
([ ])

(< >).
field

Examples
values

"SMITH.COMMAND",
: NAME

filename

vyou

specify a

omit
the
square
or angle brackets

of
are
and

directory
"SMITH",
"SMITH...".

String, NIL, or the :WILD keyword.
The :WILD keyword is translated to
the
VMS
wildcard
symbol
-asterisk
(*).
I1f
vyou specify a
string, you must omit
the
period
(.)
that
follows
the
name.
Examples of name field values
are
"LISP"

cTYPE

filetype

and

"L*SP".

String, NIL, or the :WILD keyword.
The :WILD keyword is translated to
the
VMS
wildcard
symbol
-asterisk
(*).
If
you specify a
string, you must omit
the period
(.)
that
precedes
the
type.
Examples of type field values
are
"LSP"

:VERSION

version

and

"FAS".

String, integer, NIL, or
An
integer
can
be
negative,

represents

the

keyword.
positive,

Zero.

Zzero

newest version of a

file,

and
minus
one
(-1)
represents the previous version of
a file.
The
following
keywords
can be specified:

: NEWEST
: PREVIOUS
:WILD

equivalent
equivalent
equivalent

to
to
to

O
-1
"#*"

If you specify a string, you
must
omit
the
initial
semicolon (;).
Examples of version
field
wvalues
are 0, -14, "2%", and "4*",

VAX LISP/VMS

7.2.6
You

Three

can

the

Ways to

create

pathname

following

The

Create

Lisp>

any

you

one

three

:HOST

Lisp>

"TEST"

: TYPE

"LSP"

:HOST

"MIAMI"

:NAME

"TEST"

The

"MIAMI"

:DEVICE

:NAME

"LOGIN"

:TYPE

:HOST

The

MAKE-PATHNAME

the

"SMITH"

:HOST,

function

:DEVICE
:TYPE

directly

:DIRECTORY

:VERSION

the

"DBAI"
"COM"

"SMITH"

and

:DIRECTORY

:VERSION

creates

:DIRECTORY,

and

"DBAl1"

"COM"

"MIAMI::DBAl1:[SMITH]LOGIN.COM")

"LOGIN"

function

keywords

PATHNAME

pathname

:DIRECTORY

:VERSION

function

"MIAMI"

:NAME

user-input

"DBA1"

"LSP"

"MIAMI::DBAl1:[SMITH]LOGIN.COM;4")

(PARSE-NAMESTRING

#S(PATHNAME

:TYPE

:HOST

PARSE-NAMESTRING

Lisp>

:DEVICE

function

(PATHNAME

#S (PATHNAME

which

"SMITH"

:NAME

:VERSION

PATHNAME

"DBAI"

:DIRECTORY

The

depending

"MIAMI®"

:DEVICE

ways,

use:

function

(MAKE-PATHNAME

#S (PATHNAME

NOTES

Pathnames

functions

MAKE-PATHNAME

IMPLEMENTATION

pathname

on.

PARSE-NAMESTRING

"SMITH"

the

from
other

function

the
hand,

create

by:

Using

pathname,

namestring,

symbol,

stream

argument.

Parsing

the

Returning

argument.

pathname,

the

parse

operation

success.

NOTE
The

LISP

exlsting
create

system does

not

wusable

you

perform

succeed.
pathname

field

in VMS.

1If

that

operation,

the

for

and

see

values

vyou

VMS

operation

you

must

file

description

VAX
7-11

a pathname that
situation occurs, and

the

Section

enter

create

problem,
a

that

specification when you

can

conform with

Chapter

the

file

you

correct

specifications

check

So,

file

not

complete

pathname.

See

7.2.5

LISP

for

will
change

not
the

specification.
of

pathname.

VMS

file

description

VAX LISP/VMS IMPLEMENTATION NOTES
host
the
in
You can specify any valid DECnet-VAX node specification
Each
function.
parsing
a
pathname when you are calling
a
of
field
as
(::)
host name in the specification must be followed by two colons
shown

in the

following example:

Lisp> (PATHNAME "FIRST::SECOND::THIRD::DBAL:[SMITH]PATHNAME")
#S(PATHNAME :HOST "FIRST::SECOND::THIRD" :DEVICE "DBAl"
-DIRECTORY "SMITH"
:VERSION

"PATHNAME"

:NAME

:TYPE NIL

NIL)

The PATHNAME function concatenated the three nodes, FIRST,
THIRD, into a single string in the pathname’s host field.
call
a
logical

in
the namestring argument
If
a
is
function
PARSE-NAMESTRING

SECOND,

and

the
PATHNAME or
the
to
the logical name 1is
name,

translated.

return
functions
PARSE-NAMESTRING
and
The values that the PATHNAME
function
PATHNAME
The
other.
each
from
functions different
the
make
an
returns
succeeds and
operation
returns a pathname if the parse

if the operation fails.
error signal
if the parse
also returns a pathname

The PARSE-NAMESTRING function
the
1f
operation succeeds;

fails, the function either returns NIL or signals an error,
operation
depending on the value of the :JUNK-ALLOWED keyword.
and
PATHNAME,
MAKE-PATHNAME,
the
Descriptions of
Language.
The
LISP:
COMMON
in
functions are provided

7.2.7

PARSE-NAMESTRING

Comparing Similar Pathnames

same
You should use the EQUAL function to compare pathnames with the
their
and
keywords
to
sensitive
1is
function
This
entries.
field
1s
equivalent symbols (that is, :WILD is equivalent to "*"), and case
and
MAKE-PATHNAME
the
if
example,
For
considered in comparisons.
not
file
for the
PARSE-NAMESTRING functions create different pathnames
that
pathname
you can use the EQUAL function to compare the
TEST.*;,
The
is returned by each function (see COMMON LISP: The Language).
to the SETF macro set the pathnames created by the
following calls
and PARSE-NAMESTRING functions to the variables X and Y:
MAKE - PATHNAME
Lisp>

(SETF X

(MAKE-PATHNAME

:NAME "Test"
:TYPE

:WILD

:VERSION

#S (PATHNAME

0))

:HOST "MIAMI" :DEVICE NIL :DIRECTORY NIL
-NAME "Test" :TYPE :WILD :VERSION O0)

Lisp> (SETFEF ¥ (PARSE-NAMESTRING "Test.*;"))
#S(PATHNAME :HOST "MIAMI" :DEVICE NIL :DIRECTORY NIL
:NAME

"TEST"

:TYPE

"*"

:VERSION

:NEWEST)

VAX LISP/VMS

The

EQUAL

though
:WILD

function

the
and

case

1ts

Lisp>

(EQUAL

function

are

equal.

used

compare

characters

equivalent

("*")

1s
are

the

variables

not

the

same

and

can

the

values

the

indicating

pathname

call

argument

you

host

the

that

the

1into

NAMESTRING

specify

DECnet-VAX

specified

used.

the

pathname

and

namestring

contains

the

name

perform network

current

implementation

host.

specifying

host,

operations
avoid

wusing

if the value is the same as the translation value
of
following
call to the TRANSLATE-LOGICAL-NAME function

Lisp>

the

function
or

not

the

DECnet-VAX,

value

node

the NAMESTRING

the

whether

LISP

current

function.

VAX

the

even

keyword

returns

convert

invokes

The

and

Converting Pathnames into Namestrings

pathname
If

the

NOTES

The

You

string

7.2.8

can

o0f

IMPLEMENTATION

function

removes

the

the
host

SYSS$SNODE.
shows that

MIAMI:

(TRANSLATE-LOGICAL-NAME

"SYSSNODE")

(" _MIAMI::")
If

you

wuse

the

THIS-PATHNAME,

PATHNAME

whose

NAMESTRING

function

returns.

The

the

pathname
Lisp>

does

(SETF

When

the

pathname’s

host:

Lisp>

<create

the

1is

host

the

SETF

the

PATHNAME

the

1in

macro

pathname

current

the

namestring

THIS-PATHNAME

the
sets

called

node,

function:

THIS-PATHNAME

"MIAMI::DBALl:[SMITH]LOGIN.COM;4"))

:HOST

"MIAMI"

:DEVICE

:NAME

"LOGIN"

:TYPE

NAMESTRING

argument,

include

call

wvalue

created with

(PATHNAME
#S (PATHNAME

field

not

following

that

function

host

function

namestring

(NAMESTRING

1s
that

"DAB1"

"COM"

called
1is

:DIRECTORY

:VERSION
with

returned

"SMITH"

THIS-PATHNAME
does

not

include

1its
the

THIS-PATHNAME)

"DBA1:[SMITH]LOGIN.COM;4"

Suppose

you use

the

PATHNAME

function

THAT-PATHNAME whose

host

the

SETF macro

THAT-PATHNAME

the

PATHNAME

sets

function:

field value

to
is

the

<create

BOSTON.

pathname

The

following

that

called
call

created with

VAX LISP/VMS IMPLEMENTATION NOTES

Lisp>

(SETF

THAT-PATHNAME

(PATHNAME

"BOSTON: :DBAl:[SMITH]LOGIN.COM;4"))

#S (PATHNAME :HOST "BOSTON"
:NAME

"LOGIN"

:DEVICE "DBA1l"
"COM"

:TYPE

:DIRECTORY "SMITH"

:VERSION 4)

Because the current
node
is
MIAMI
and
the
host
field
wvalue
of
THAT-PATHNAME
is BOSTON, the NAMESTRING function returns a namestring
that

includes
Lisp>

all

the pathname

(NAMESTRING

field values:

THAT-PATHNAME)

"BOSTON: :DBA1:[SMITH]LOGIN.COM;4"

If you want to invoke DECnet-VAX and you want to specify

host,

specify

host.

the

Lisp>

the host with an access control

For

(SETF

#S (PATHNAME
Lisp>

the

current

string or specify zero

example:
THAT-PATHNAME

(PATHNAME

:HOST "0"

:NAME

(NAMESTRING

"0::THATDEVICE:[SMITH]LOGIN.COM"))

:DEVICE "THATDEVICE"

"LOGIN"

"COM"

:TYPE

:DIRECTORY "SMITH"

:VERSION NIL)

THAT-PATHNAME
)

"0::THATDEVICE: [SMITH]LOGIN.COM"

Table 7-3 noted that in VAX LISP the host
field
of
a
pathname
can
include
an
access
control
string.
If
the NAMESTRING function 1is
called with a pathname argument whose host field
1includes
an
access
control
string,
the
namestring
that is returned includes the host,
even if the value in the pathname’s host field
1is
the
same
as
the
current

node.

Assume that the current host is MIAMI.
The following SETF
expression
sets
THIS-PATHNAME
to the pathname that is created with the PATHNAME
function:
Lisp>

(SETF

THIS-PATHNAME

( PATHNAME

"MIAMI\"SMITH MYPASSWORD\"::THISDEVICE:[SMITH]FILE"))

#S (PATHNAME :HOST "MIAMI:\SMITH mypassword\""
:DIRECTORY "SMITH"

:NAME

"FILE"

:DEVICE "THISDEVICE"

:TYPE NIL VERSION:

NTL)

The host field of the pathname that is created contains the host MIAMI
and
the
access
control
string
SMITH
MYPASSWORD.
The NAMESTRING
function, when called with THIS-PATHNAME as its
argument,
returns
a
namestring that includes all the pathname field values:
Lisp>

(NAMESTRING

THIS-PATHNAME)

"MIAMI\"SMITH mypassword\"::THISDEVICE: [SMITH]FILE"

VAX LISP/VMS IMPLEMENTATION NOTES

7.2.9

Functions That Use Pathnames

Most

the

functions

pathnames are
have at least
In
VAX LISP,
be
The

pathname,
following

camn

use

create

and

manipulate

VAX

LISP

namestring,
two

need

stream.
1in

The DIRECTORY function (described in
Part
1II)
converts
argument
to
a
pathname
and
merges
that pathname with
following VMS file specification:

1its
the

The

functions

symbol,

given

COMMON LISP:

®@

you

described in COMMON LISP: The Language.
These functions
one required argument and some have optional
arguments.
the value of a pathname function’s required argument can

further

explanation

than

Language.

The DIRECTORY function

host::device:[directoryl*.*;*

The values for the host,
device,
and
directory
fields
are
supplied by the *DEFAULT-PATHNAME-DEFAULTS* variable (see next
section).

The DEFAULT-DIRECTORY

function

The DEFAULT-DIRECTORY

function
(described
in
Part
1II)
1is
supplied
by
VAX
LISP
in addition to the pathname functions
described in COMMON LISP: The Language.
This function returns
a pathname that refers to the current directory.

7.2.10

Using the

*DEFAULT-PATHNAME-DEFAULTS* Variable

The value

of the *DEFAULT-PATHNAME-DEFAULTS* variable is used by
some
pathname
functions
to
£fill
pathname
fields not specified in their
arguments.
The default value of this variable
1is
a
pathname
whose
host
and
directory
fields
indicate the current directory and whose
device, name, type, and version fields contain NIL.

In
VAX
LISP,
you
can
change
the
*DEFAULT-PATHNAME-DEFAULTS* variable in two ways:
®

With

the

value

the

SETF macro

The following example illustrates
wusing
the
change a pathname’s directory from [SMITH] to

SETF
macro
[SMITH.TEST]:

VAX LISP/VMS IMPLEMENTATION NOTES

Lisp>

(SETF

*DEFAULT-PATHNAME-DEFAULTS*

(MAKE-PATHNAME

#S (PATHNAME

:DIRECTORY

:HOST "MIAMI"
:DIRECTORY
:TYPE

With

the

"[SMITH.TEST]"))

"DBAl"

:DEVICE

"[SMITH.TEST]"

NIL

:VERSION

DEFAULT-DIRECTORY

function

:NAME NIL

NIL)

The value of the *DEFAULT-PATHNAME-DEFAULTS* variable
1is
set
to
the
wvalue
of your default directory when LISP starts and
when
vyou
change
your
directory
with
the
form
(SETF
(DEFAULT-DIRECTORY)
...).
To check the value of your default
directory, call the DEFAULT-DIRECTORY function.
For example:
Lisp>

(DEFAULT-DIRECTORY)

#S (PATHNAME

:HOST

"MIAMI"

:DIRECTORY
:TYPE

NIL

:DEVICE

"SMITH"
:VERSION

"DBAl"

:NAME NIL
NIL)

The pathname returned
in
this
example
1indicates
that
the
default
directory is SMITH on host MIAMI.
1In this case, each
time a pathname function fills a pathname field with a default
value, the corresponding value in the directory SMITH is used.
To change the value of your default directory, set it with the
SETF
macro.
For= example,
the following illustrates how to
change

default directory

Lisp>

(SETF

from SMITH

(DEFAULT-DIRECTORY)

SMITH.TEST:

"[.TEST]")

"[ .TEST]"

The next
example
illustrates
that
when
the
directory
1is
changed, the DEFAULT-DIRECTORY function returns a new pathname
referring

Lisp>

the

new default

directory:

(DEFAULT-DIRECTORY)

#S (PATHNAME

:HOST "MIAMI" :DEVICE "DBAl"
:DIRECTORY "SMITH.TEST" :NAME NIL
:TYPE

NIL

:VERSION

NIL)

NOTE
The value of the *DEFAULT-PATHNAME-DEFAULTS*
wvariable
must
be
a
pathname.
Do not set this variable to a
namestring,

symbol,

stream.

VAX LISP/VMS IMPLEMENTATION NOTES

7.3

GARBAGE COLLECTOR

When VAX LISP is executing,
LISP
objects
are
created
dynamically.
Some
of the objects that are created are always used and referred to,
while others are referred to for only
a
short
time.
When
a
LISP
object
the
that
space
the
to,
referred
be
longer
no
can
object
occupies can be reclaimed by the VAX LISP
system.
This
process
of
reclaiming

space

called garbage collection.

The VAX LISP garbage collector is a stop-and-copy
garbage
collector.
The
LISP system includes a dynamic memory pool, which is divided 1into
a
At
space.
dynamic-0 space and dynamic-1
two equal-sized spaces:
or
dynamic-0
either
in
allocated
are
objects
LISP
time,
given

dynamic-1 space.
When the memory in the current space
1is
exhausted,
LISP
processing
is
temporarily suspended, and the LISP data objects
The
space.
other
to the
that can still be referred to are copied
objects that cannot be

referred to are not copied.

You can ignore garbage collections of dynamic memory
space
when you
Garbage collections occur automatically
LISP programs.
are writing
processing
LISP
and
exhausted,
is
space
when the current dynamic
continues when a garbage collection is complete.

Sections 7.3.1 through 7.3.6 provide information about
garbage

7.3.1

the

VAX

LISP

collector.

Frequency of Garbage Collection

The frequency of garbage collection is proportional to the

dynamic

memory

space

amount

that is available in the VAX LISP system.

You

by
can set the amount of dynamic memory space that is to be available
you
when
2)
Chapter
(see
qualifier
command
the DCL /MEMORY
specifying
1f you
Garbage collection occurs less often
invoke the LISP system.
space.
memory
dynamic
the
use this qualifier to increase the size of
size
the
The degree to which the frequency of garbage collection and
memory affects run-time efficiency depends on the program
dynamic
of
than
objects
more permanent
If a program creates
being executed.
the
time,
of
period
short
a
for
to
referred
be
can
that
objects
result,
a
As
operations.
copy
more
perform
to
has
garbage collector
The fewer the copy operatlons the garbage
the program slows down.
1s
collection
the garbage
faster
the
to perform,
collector has
finished.

7.3.2

Static Space

LISP objects that are created in static space are not collected by the
do not move and they are not
These objects
<collector.
garbage
7-17

VAX

deleted,

even

objects

LISP/VMS

they

static

can

space

MAKE-ARRAY

function

(see

that

defined

are

structures.

Part

7.3.3
LISP

(See

the

LISP

VAX

the

using
II)

referred

the

to.

You

:ALLOCATION

with

the

can

create

keyword with

constructor

DEFINE-ALIEN-STRUCTURE

description

suspended

system

LISP

queues

during

interrupt

macro

the

functions

for

alien

DEFINE-ALIEN-STRUCTURE

macro

garbage

functions,

BIND-KEYBOARD-FUNCTION

functions,

for

Interrupt

functions

When

Part

Processing

processing

7.3.4

longer

NOTES

II.).

operating

the

IMPLEMENTATION

delivery
are

after

discussed

and

collection.

such

those

The

VMS

defined

INSTATE-INTERRUPT-FUNCTION

garbage

collection

Section

7.5.

message

finished.

1is

finished.

Messages
a

garbage

operation
messages

NIL.

When

You

can

the

variables.

The

are

occurs,

when

the

value

specify

variables

and

changing

also

values

collection

begins

value
is

the

VAX

the

*GC-VERBOSE*,

VAX

messages

contents

LISP

described

NIL,

LISP
are

the

displayed
when
the
You can suppress these
*GC-VERBOSE*

not

variable

displayed.

messages

changing

the

*PRE-GC-MESSAGE*

and

*POST-GC-MESSAGE%*

*PRE-GC-MESSAGE*,

and

*POST-GC-MESSAGE*

Part

II.

NOTE
you

suppress

messages

and

garbage

stack

control

- program

Therefore,
messages

7.3.5

change

overflow,
in

you

garbage

not

due

whether

loop

suppress

debug your

collection

initiated

determine

recursive

should

before

the

collection

your

difficult.

change

the

program.

Available Spac
=

Garbage
created.

collection
If

space

this

situation

later

with more

suspend

generally

garbage

available

and

allocate

exists,

you

dynamic-memory

resume

occurs

collection

LISP

the

can

and

LISP
not

object

enough

object,

error

suspend

the

LISP

image

space.

image,

when

occurs

see

For

information

Chapter

2 2.

1is

being

dynamic

memory

signaled.

When

and

resume

about

how

VAX

7.3.6
The
a

Garbage Collection

garbage
garbage

the

LISP/VMS IMPLEMENTATION

size

process

collection

1is

the

control

space

must

cannot

contain

all

image

terminated,

and

function

that

usually
is

recursive

INPUT AND OUTPUT

VAX

LISP

set

I/0

driver.

(particularly
Services

The

(RMS).

for

VAX

The

See

Newline

Terminal

End-of-file

Record

File

Functions

LISP

DCL

level.

This

error,

such

two

low-level

I/0

way

functions

by way

VAX

sets

Record
VAX

functions.

direct

handles

calls

to VAX

Management

QIOs

all

other

One

the

I/0

Record Management

Services

Reference

RMS.

dependencies

for

I/O0O

have

with

the

topics

organization

Sections

defines

from the
the

value
LISP,

#\NEWLINE

programming

space

the

to,

length

7.4.1

LISP

VAX

dynamic

operations

COMMON

LISP,

referred

memory

input

Newline Character

integer

amount

dynamic

example,
overflow,

character

7.4.1

set

implementation-dependent

returned

the

for

stack

nonterminating.

terminal

implementation

and

can

1If,

control

reduced

returns

user

with

about

topics:

provided

VAX

that

files)

the

information

LISP

following

objects

complete.

increase,
the

and

other

disk

because

handles

The

must

implemented

functions

fail

control

caused

7.4

Manual

stack

decrease.

LISP

may

initiated

the

condition

terminal

Failure

collection

memory

NOTES

the

#\NEWLINE

READ-CHAR

character

information

through

character

function as

«code

for

about

these

character

7.4.6.

the

an end-of-line
#\NEWLINE

that

1is

indicator.

1In

character

has

255.
WRITE-CHAR

character

and

WRITE-STRING

follows:

7-19

functions

interpret

the

VAX LISP/VMS IMPLEMENTATION NOTES

When the WRITE-CHAR function
is
<called
with
the
#\NEWLINE
character as its argument value, the function starts writing a
new line.
This call is equivalent to a
call
to
the
TERPRI
function

(see

COMMON LISP:

The Language).

When the WRITE-STRING function
1is
<called
with
an
argument
string
that
contains
the
#\NEWLINE character, the function
divides the string into
two
lines.
The
following
example
shows
the
output
that
1is
displayed
by
the
WRITE-STRING
function when the #\NEWLINE character is not used:
Lisp>

(WRITE-STRING

(CONCATENATE

’'STRING
1 NEW 1A}

"LINE"))
NEWLINE

"NEWLINE"

Both of the strings NEW and LINE are
displayed
on
the
same
line.
A
call to the WRITE-STRING function, which includes a

string argument that contains the #\NEWLINE

the

character,

looks

following:

Lisp>

(WRITE-STRING

(CONCATENATE

’'STRING
WNEWW

(STRING

#\NEWLINE)

NEW
LINE

"NEW

LINE"

This call to the WRITE-STRING function
NEW and LINE on separate lines.

displays

the

strings

The #\NEWLINE character is the only character that causes a
new
line
to be written.
VAX LISP writes carriage returns and linefeeds without
special

7.4.2

interpretation.

Terminal

In VAX LISP,
is

Input

terminals perform input operations in line

mod

returned by the READ-CHAR function only after you press

key.

The READ-CHAR function returns ASCII characters as data unless one
the

following

conditions

exists:

VAX LISP/VMS IMPLEMENTATION NOTES

A character
is defined to invoke an interrupt function.

See the VAX/VMS I/0 Reference
Manual:
Part
I
for
i1information
on
terminal control characters, and see Section 7.5 for information about
interrupt

functions.

You can
change
the
mode
in
which
your
terminal
performs
input
operations
by
invoking the VAX LISP SET-TERMINAL-MODES function with
the :PASS-THROUGH keyword (see Part II).
For example:
Lisp>

(SET-TERMINAL-MODES

:PASS-THROUGH

I1f the value of the :PASS-THROUGH keyword is T, the SET-TERMINAL-MODES
pass-through
mode, control characters processed by the VMS system and
characters defined to invoke interrupt functions are not recognized by
the
LISP
system.
In addition, the READ-CHAR function performs input
operations differently than it does when the terminal is in line mode.
In line mode, the READ-CHAR function does not return a character until
you press the RETURN key; in pass-through mode, that function
returns
a
character
as soon as the character is typed.
See COMMON LISP: The
Language for a description of

the READ-CHAR function.

To
put
your
terminal
back
into
line
mode,
invoke
the
SET-TERMINAL-MODES function with the :PASS-THROUGH keyword set to NIL.
Lisp>

(SET-TERMINAL-MODES

:PASS-THROUGH

NIL)

7.4.3

End-of-File Operations

In VAX LISP, read operations from a file do not indicate
the
end
of
the
file
wuntil the operation after the last character in the file 1is
performed.

Read operations from a terminal do not indicate the end of a
VAX

file

1in

LISP.

In VAX LISP, you can close a stream that is connected to your terminal
if
the stream is not related to the stream bound to the *TERMINAL-IO*
variable.
1If you attempt to close the stream bound to
*TERMINAL-IO¥*,
no

action

7.4.4

performed.

Record Length

VAX LISP uses RMS to process file I/O0.
Therefore, the maximum
record
length
in
VAX LISP must conform to the maximum record length in RMS.
A maximum of 32,767 characters can be written to a disk
file,
and
a

7-21

VAX LISP/VMS

maximum

exceed

these

written

The

9995

the

with

number

invoke

the

Your

function

causes

stream.

calls

you

TERPRI

vyou

quota

with

the

can

make

function

<can

magnetic

written

error

signaled

invoking

the

tape.

and

writing

quota

You

function
a

you

nothing

1is

when

1is

limit

the

before

the

can

maximum

find

out

GET-PROCESS-INFORMATION

(see

Part

II).

"SMITH"

you

terminal.

determines

terminal.

(GET-PROCESS-INFORMATION

(:BIO-BYTE-QUOTA

operation

there

WRITE-CHAR

LISP

keyword

result,

are

your

VAX

the

you

immediate

I/0 byte limit
write

:BIO-BYTE-QUOTA

Lisp>

limits,

terminal

user-buffered

length

can

NOTES

file.

WRITE-CHAR

called

characters

record-length

IMPLEMENTATION

For

string
what

the

function

example:

:BIO-BYTE-QUOTA)

30000)

NOTE
You

can

from

prevent

function
your

7.4.5
VAX

File

LISP

(for

reads

specifying

RMS

files

sequential

the

byte
calls

#\NEWLINE

the

variable-length

Functions

Four

COMMON LISP
further

attribute.

WRITE-BYTE

records,

7.4.6

sequentially.
organization,

carriage-return

following

I/0

including

1limit
to

the

quota
TERPRI

character

1in

output.

example,

need

buffered

Organization

have

implied

your

overflowing

and

functions

FILE-LENGTH

®@

FILE-POSITION

OPEN

WRITE-CHAR

Files

function)

functions used

explanation.

Character

provided

created

have

for
in

created

records,

for

sequential

carriage-control

The

files

variable-length

binary

by VAX
and

output

organization,

attributes.

I/O have VAX LISP dependencies
implementation
the

four

the

information
sections:

for

and
the

VAX LISP/VMS IMPLEMENTATION NOTES

7.4.6.1
FILE-LENGTH Function - The length of a file
1s
measured
1in
units
of the OPEN function’s :ELEMENT-TYPE keyword.
1In VAX LISP/VMS,
files cannot be measured in these units for all the supported
element
types.
Therefore, the FILE-LENGTH function returns NIL.
You can determine the total number of 8-bit bytes that
can
occupy
a
file
by
invoking
the
GET-FILE-INFORMATION
function
with
the
:END-OF-FILE-BLOCK and :FIRST-FREE-BYTE keywords, and then
performing
the

following

steps:

Multiply
the
wvalue
returned
keyword minus one by 512

for

Add the value you get in Step 1
:FIRST-FREE-BYTE keyword

For more

the

:END-OF-FILE-BLOCK

the value

information on the GET-FILE-INFORMATION

returned

function,

for

see

the

Part

IT1.

7.4.6.2
FILE-POSITION Function - The FILE-POSITION
function
returns
or
sets
the
current
position
within
a
random-access
file.
VAX
LISP/VMS does not support random-access files; therefore, the function
returns

NIL.

7.4.6.3
OPEN Function - Before you can access a file, you
must
open
it
with
the
OPEN
function
or
the WITH-OPEN-FILE macro.
The OPEN
function can be specified with keywords that
determine
the
type
of
stream
that
is
to be created and how errors are to be handled.
The
keywords you can specify are the following:
@

:DIRECTION

:ELEMENT-TYPE

:IF-EXISTS

:IF-DOES-NOT-EXIST

VAX LISP restricts the
wvalues
vyou
can
specify
for
the
preceding
keywords.
The rest of this section explains the restrictions.
In VAX LISP/VMS, you can specify the
:I0
wvalue
for
the
:DIRECTION
keyword
only
if
the
specified stream is connected to a terminal or
mailbox.
When you specify the :I0 value, the target device must exist

before

the

OPEN

funciton is called.

therefore,

if you specify this

value for the :DIRECTION keyword, you cannot
specify
the
:IF-EXISTS
keyword, and you can specify the :IF-DOES-NOT-=EXIST keyword only with
the

:ERROR value.

VAX LISP/VMS IMPLEMENTATION

The

:IF-EXISTS

For

the

:OVERWRITE

:IF-EXISTS

: SUPERSEDE,

the

option

keyword values

o0ld

file

not

supported

:RENAME,

renamed

NOTES

the

in VAX

LISP/VMS.

:RENAME-AND-DELETE,

same

name with

the

and

string

"old"

appended to the file type.
On closing files opened with any
of
three
wvalues,
and
specifying
:ABORT
T,
the new version 1is
deleted and the old is restored to its former name.
On closing
files
with
: ABORT
NIL,
on
: RENAME,
there
1s
no
action;
with
these

: RENAME-AND-DELETE
VAX

LISP

supports

CHARACTER.
VAX
maximum byte size

or
all

:SUPERSEDE,
the

LISP
for a

values

the
for

old
the

file

1is

deleted.

:ELEMENT-TYPE

allows
vyou
to
open
binary
stream is 512 8-bit bytes.

7.4.6.4

WRITE-CHAR Function

bit

and

font

7.5

INTERRUPT FUNCTIONS AND KEYBOARD FUNCTIONS

attributes

The WRITE-CHAR

keyword

streams,

except

but

function disregards

the

characters.

interrupt function is a function that is invoked
when
a
specific
event
occurs.
If an interrupt function is defined for an event, the
VAX LISP system interrupts the current LISP processing and invokes the
interrupt function when the event occurs.
When the interrupt function
exits, the VAX LISP system resumes processing at the
point
where
1t
was

interrupted.

VAX LISP provides two
functions
you
can
wuse
to
define
1interrupt
functions:
INSTATE-INTERRUPT-FUNCTION
and
BIND-KEYBOARD-FUNCTION.
The INSTATE-INTERRUPT-FUNCTION function is part of a general mechanism

that
lets
vyour
program respond to asynchronous events (ASTs) in the
VMS operating system.
This mechanism is described in the VAX LISP/VMS
System Access Programming Guide.
The

BIND-KEYBOARD-FUNCTION function is
a
more
specialized
function
that
binds an ASCII control character to an interrupt function.
Once
a control character is bound to a function, you can cause the VAX LISP
system
to
interrupt
the
current
evaluation
and call the function
asynchronously by typing the control character.
Functions bound using
BIND-KEYBOARD-FUNCTION are also called keyboard functions.
Interrupt functions are not always called as soon as the defined event
occurs.
If
a low-level LISP function, such as CDR or CONS, is being
evaluated or
a
garbage
collection
1is
being
performed,
interrupt
functions
are
placed in a queue until they can be evaluated.
Delays
in interrupt function evaluation are generally
not
perceptible.
An
example of when you might perceive a delay is when the system performs
a

garbage

collection.

VAX LISP/VMS IMPLEMENTATION NOTES

VAX LISP also provides a means
by
which
you
<can
priorities
for
interrupt
and keyboard functions.
called interrupt levels,
Access

are described

the

assign
different
These priorities,
VAX
LISP/VMS
System

Programming Guide.

If you suspend the LISP system when interrupt functions
are
defined,
the
functions that are defined by the BIND-KEYBOARD-FUNCTION function
are still defined
when
the
system
1is
resumed.
The
key/function
bindings
are
not
lost.
Any other interrupt functions that you may
have defined are uninstated when the system is suspended and
are
not
reinstated when

the

system is

resumed.

Besides the BIND-KEYBOARD-FUNCTION function are the VAX LISP functions
GET-KEYBOARD-FUNCTION
and
UNBIND-KEYBOARD-FUNCTION.
The
GET-KEYBOARD-FUNCTION function returns information
about
a
function

that is bound to a control character, and the UNBIND-KEYBOARD-FUNCTION
function removes the binding of a function from a control character.

Descriptions of the BIND-KEYBOARD-FUNCTION, GET-KEYBOARD-FUNCTION,

UNBIND-KEYBOARD-FUNCTION functions are provided in Part II.

7.6

and

COMPILER

For information on how to compile LISP expressions and the
advantages
and
disadvantages of compiling LISP expressions, see Chapter 2.
This
COMPILE
the
with
(one
restrictions
section describes two compiler
function
and
one
with
the
COMPILE-FILE
function)
and
compiler
optimizations.

7.6.1

Compiler Restrictions

The VAX LISP compiler translates interpreted function definitions into
function
objects that contain VAX instructions.
The COMPILE function
symbols
the
of
definitions
causes these objects to be bound as the
The COMPILE-FILE function puts the objects into an
them.
name
that
such
handle
functions
two
these
way
Because of the
output file.
functions.
the
of
each
of
use
the
for
exists
objects, a restriction

COMPILE Function - The compiler cannot compile pieces of code
7.6.1.1
Therefore,
unless they are function definitions defined at top level.
you cannot use the COMPILE function to compile a function wunless you
An
create the function in a null lexical environment (not top level).
follows:
evaluated
be
cannot
that
expression
LISP
a
of
example
Lisp>

(LET

((COUNTER 0))
(COMPILE NIL #’(LAMBDA

7-25

()

(INCF COUNTER))))

VAX LISP/VMS

The

COMPILE

function

preceding

cannot

example

environment

function

object:

Lisp>

(LET

was

call

lambda

((COUNTER

the

that

increments
not

the

COMPILE

COMPILE-FILE

object

Consider

the

Lisp>

the

that

being

the

lexical

the

following

example,

expression

rather

(INCF

the

than

COUNTER))))

preceding

value

the

special

form

can

1is

example

returned

COUNTER.

The

COUNTER,

which

compiles

compiled

compiled
encloses

the

object

object
the

call

output

file.

the

COMPILE-FILE

function

encloses

is compiling with an anonymous

function
as

cannot

data

put

into

compiled

output

file.

form:

SETF

NIL

#:G1149

function

part

The

file

recognized

’'#.(COMPILE

the

compiled,

1is

third

compiled

the

C))))

the

form

file

1is

created.

This

1list

whose

first

the

SETF

into

the

function

element

form.

but

(PRINT

preceding

anonymous

special

(C)

#x504C4C>

reads

the

’(LAMBDA

The
1list

the

preceding
cannot

from

call

put

Compiler Optimizations

VAX

speed

LISP,

you

the

set

the

VAX

LISP,

The

code

default
globally

you

either

can

/OPTIMIZE

Language).

call

results.

and

you

For

want

object

code)

the

two

qualities

and whether

value
and

use

qualifiers

Both

same

control

wvalues

declaration

use

can

generated

performed.

and

COMPILE-FILE
becomes

lambda

()

that

value

Therefore,

Function

function

value

local

that

(SETF

element

7.6.2

' (LAMBDA

function

following

#<Compiled
When

NIL

Function

form

definition.

function

1In

with

object

depends

function.

top-level

function

object

created.

dynamic
the

the

NOTES

0))

The

the

increment

7.6.1.2

each

COMPILE

expression.

does

the

called

(COMPILE

The

compile

because

which

COMPILE

IMPLEMENTATION

for
DCL

(see

the

these

locally.

the

methods

example,

are

set

the

global

and

the

safety quality

DCL

command

the

following

set

values

the

function

setting

safety

command

Chapter

you

compiled

qualities

LISP

PROCLAIM

run-time

the

level

7-26

the

/COMPILE

OPTIMIZE

LISP:

The

produce

the

operation

(speed

checking)

specification:

LISP/COMPILE/OPTIMIZE=(SPEED:3,SAFETY:2)

globally

quality

error

MYPROG.LSP

can

COMMON
values

the

You

the

specify

speed

(run-time

values

(see
DCL

with

quality

the

<code:

checking

of
to

VAX LISP/VMS

you

and
in

are

safety
the

same

LISP

and

you

qualities,

IMPLEMENTATION

want

specify

file.

For

example,

set

values

that

were

set

following

call

the

set

the

PROCLAIM

the

global

PROCLAIM
the

values

function

values

the

NOTES

the

preceding

function

the

qualities

example,

first

form

speed

first

form

the

specify

the

file

MYPROG.LSP:

(PROCLAIM

You

can

the

OPTIMIZE

also

set.

' (OPTIMIZE

set

the

(SPEED

quality

(SAFETY

values

locally.

declaration within
Local

the

form

2)))

for

which

optimization

quality values

are

the

this,

you

you want

override

must

the

global

use

values
quality

values.
All

proclamations

occur

when

proclamations
OPTIMIZE

you

are

greater

When
to

OPTIMIZE

SPEED

quality

does

check

for

safety

concerned

1is
1,

the

value

are

safe

the

uses

Code

that

checks

list

that

value

the

exists

arguments

that

Code

the

speed

are

code

the

your

the
the

stack

proper

greater

code
must

two

code

they

also

INLINE
than

the

overflow.

safety

quality

between

Safe

that

observes

than

the

speed

quality

must

than

less

quality values,

that

data

checks

type.

the

arguments

Examples

following:

Code

require

not

the

code.

about

evaluated,

relationship
that

code

compiler

the

generates

ensure

safe

file

the

and

this

fastload

However,

quality,

than

compiler

into

only when

SPACE

which

put

fastloaded.

generic
if

arithmetic

the

arguments

arquments
are

checks whether

calls

used

functions

that

lists

indices

access

arrays

are

bound
If

you

than

are

1in

interested

producing

safe

greater

than

equal

than

equal

less

two

quality values,

generates

code.

you

must

values

1If

the

you want

producing

and

the
the

speed

and

following

and

the

that

1is

the

value

the

speed

the

value

the

safety

When

this

compiler
code.

the
the
code

speed

code

relationship

<considers

Type-specific

compiler

specify declarations

Consider

quality

type-specific

safe

code,

your

code

safety qualities
and

suppose

quality

7-27

code

the

between

the

addition

correct

value

and

faster

type-specific

must

declarations

executes

the

fast

must

quality

exists

type

generate

evaluated

quality

than

code,

setting

the

values.
the

safety

VAX LISP/VMS IMPLEMENTATION NOTES

(DEFUN

(DO

LOOP-OVER-A-SUBLIST (INPUT-LIST)
((I (GET-INITIAL-VALUE) (1+ I))
(CDR

INPUT-LIST

((OR

(>=

(ENDP

FIXNUM

(THE

*FINAL-VALUE*))

L))

L)
(DECLARE

L)))

(FIXNUM
L

(DO-SOME-WORK

L))

(LIST

I)))

Since the value of the safety quality is less than 2 and the value
of
the
speed
quality
is
greater than 1, the compiler regards the type
declarations.
1In this example, the types FIXNUM and LIST are declared
with

the

following

(DECLARE

form:

(FIXNUM
(LIST

L))

When the
example
<code
1is
compiled,
the
compiler
wuses
the
type
the
in
functions
>=
and
ENDP,
CDR,
1+,
the
translates
and
declarations
code

follows:

The 1+ function becomes one VAX instruction.

The CDR function becomes one VAX instruction.

The ENDP function is transformed into the NULL function.

The >= function becomes

comparison and a branch.

two

VAX

instructions:

longword

the
of
The value of the *FINAL-VALUE* variable and the return value
Also, the INPUT-LIST
fixnums.
be
function must
GET-INITIAL-VALUE
argument specified for the LOOP-OVER-A-SUBLIST function must be a true
list

(not

an atom or a dotted list).

signaled.
If a declaration is violated, the error that results is not
with the
function
LIST
LOOP-OVER-A-SUB
the
call
you
if
example,
For
but
list,
a
not
is
argument
the
because
symbol LOOP, an error results
to
damage
cause
can
this
as
Errors such
not signaled.
1is
error
the
the
default,
By
repaired.
be
cannot
the LISP environment, which
safety qualities are set such that error
and
speed
the
of
values
such
operations;
all
for
checking and signaling code are generated
values prevent you from damaging the LISP environment.

guaranteed
If the INPUT-LIST argument in the preceding example is not
the DO
before
check
type
explicit
an
add
can
you
list,
always be a
to
check:
type
explicit
an
of
example
an
The following form is
loop.
(UNLESS

(LISTP

INPUT-LIST)

sbut doesn’t check for a dotted-list

(ERROR "Cannot loop through this object: S."

7-28

INPUT-LIST))

VAX LISP/VMS IMPLEMENTATION

The

check

even
If

performed

though

the

you want

INLINE.

has

specifically
more

release

7.7

the

function

Declaring

function

For

compiler

been

LISTP

might
be

information

the

compiled

function

proclaimed

declared

function

heed

evaluated

FIXNUM

and

inline,

INLINE

INLINE,

1is

has

LIST

you

will

NOTES

must

effect.
be

run

time,

declarations.
proclaim

However,

compiled

once

inline

unless

NOTINLINE.
on

making

LISP

compiled

code

run

fast,

see

the

notes.

FUNCTIONS AND MACROS

Several

have

functions

and

implementation

functions

and macros

information

and

that

description

macros

provides

these

functions

return

value,

and

further

information

regarding

names

explanation

and

lists

macros,

functions

and

these

type

summary

II.

Each

macro’s

use,

applicable

COMMON LISP:

Part

Language

the

For

see

format,
See

dependent.

function’s

use.
these

The

the

brief

the

LISP:

7-4

information,

examples

COMMON

Table

implementation

consists

implementation-dependent

Table 7-4:

described

dependencies.

The

arguments,
Language

for

macros.

Summary of Implementation-Dependent Functions and Macros
Function

Implementation-Dependent

Name

Information

APROPOS

Function

Macro

Optional

argument

and

DO-SYMBOLS

argument

and

DO-SYMBOLS

macro

APROPOS-LIST

Function

Optional
macro

BREAK

Function

Facility

invoked

COMPILE-FILE

Function

Keywords

and

DESCRIBE

Function

Displayed

DIRECTORY

Function

Argument

merged with wildcards

DRIBBLE

Function

Terminal

I/0 while

not

output

saved;

Function

Arguments

GET-INTERNAL-RUN-TIME

Function

Meaning of

7-29

return value

cannot

the

Editor

nest

calls

return value

VAX LISP/VMS IMPLEMENTATION NOTES

Table

7-4

(cont.)

Name

Function
or Macro

Implementation-Dependent
Information

LOAD

Function

Finds

LONG-SITE-NAME

Function

Logical name and return value

MACHINE-INSTANCE

Function

Logical name and return value

MACHINE-VERSION

Function

Return value

MAKE-ARRAY

Function

:ALLOCATION keyword

REQUIRE

Function

Modules

ROOM

Function

Displayed output

SHORT-SITE-NAME

Function

ALogical name and return value

TIME

Macro

Displayed output

TRACE

Macro

Keywords

WARN

Function

Facility invoked

7-30

latest

file

PART i

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

VAX LISP/VMS FUNCTION,

APROPOS

MACRO, AND VARIABLE DESCRIPTIONS

Function

Searches through packages for symbols
whose
print
names
contain
a
specified
string.
The
function
1s
not
sensitive
to the case of
characters.
The string can be either the print name or a substring of
the

symbol’s

name.

The APROPOS

function displays a message that shows the string that
1is
being searched for and the name of the package that i1s being searched.
When the function finds a symbol whose print name contains the string,
the
function
displays the symbol’s name.
If the symbol has a value,
the function displays the phrase "has a value"
after
the
symbol
as
follows:

*MY-SYMBOL*,

If the
phrase

has

a value

symbol has a function definition,
the
"has a definition" after the symbol as

MY-FUNCTION,

has

function
follows:

displays

the

a definition

In VAX LISP, the APROPOS function uses
the
DO-SYMBOLS
macro
rather
than
the DO-ALL-SYMBOLS macro.
As a result, the function displays by
default only symbols that are accessible from the current or specified
package.
For information on packages, see COMMON LISP:
The Language.
Format

APROPOS string 5OPTIONAL package
Arguments

string

The string to be searched for in the symbols’
print
names.
If
you
specify
a symbol for this argument, the symbol’s print name
is

used.

package

An optional argument.
If you specify the argument,
the
symbols
in
the
specified
package
are searched.
1If you specify T, all
packages are searched.
If you do not specify the
argument,
the
~
symbols that are accessible in the current package are search Tl
Return Value

No wvalue.

VAX

APROPOS

LISP/VMS

Function

FUNCTION,

MACRO,

AND VARIABLE DESCRIPTIONS

(cont.)

Example
Lisp>

(APROPOS

Symbols

"*PRINT")

package

*PRINT-CIRCLE*,

USER
has

containing

*PRINT-SLOT-NAMES-AS-KEYWORDS*,

*PRINT-RADIX*,

has

*PRINT-ESCAPE*,
*PRINT-ARRAY*,

has
has

*PRINT-GENSYM*,
*PRINT~-LEVEL*,

has

a
a

value

has

value

*PRINT-RIGHT-MARGIN*,

has

*PRINT-LINES*,

Searches
list

the
the

has

package
symbols

wvalue

value

has

value

*PRINT-PRETTY*,

*PRINT-CASE*,

has

value

*PRINT-LENGTH*,

*PRINT-BASE~*,

"*PRINT":

value

*PRINT-MISER-WIDTH*,

string

value

has

the

value

has
has

a
a

value
value

value
value
a

value

USER
that

for

the

contain

string
the

*PRINT

specified

and
string.

displays

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

APROPOS-LIST Function
Searches

through

specified

packages

string.

characters.

The

the

symbol’s

When

the

symbols
In

string

function

whose

can

completes

print
the

symbols

function
be

VAX

LISP,

than

the

either

includes

default

package

names

its

the

names

sensitive

contain

name

returns

the

case

substring

only

symbols

1list

the

string.

function

DO-ALL-SYMBOLS

1list

The

not

search,

contain

APROPOS-LIST

the

whose

name.

rather

COMMON LISP:

for

The

wuses

macro.
that

returns.

the

DO-SYMBOLS

result,

macro

the

function

the

current

are

accessible

from

For

information

packages,

see

names.

symbol’s

name

Language.

Format

APROPOS-LIST

string

&OPTIONAL package

Arguments

string
The

string

you
is

specify

searched

symbol

for

this

the

symbols’

argument,

the

used.

package

optional

the

argument.

specified

packages

are

symbols

that

searched.
are

you

package

specify
are

you

the

accessible

the

argument,

searched.

not

1If

specify

current

you

the

symbols

specify

argument,

package

are

all

the

searched.

Return Value

list

the

symbols

whose

names

contain

the

string.

Example

Lisp>

(APROPOS-LIST

(ARRAY-TOTAL-SIZE

SIMPLE-ARRAY
ARRAYP

"ARRAY")

ARRAY-DIMENSION

ARRAY-DIMENSION-LIMIT

*PRINT-ARRAY*

MAKE-ARRAY

ARRAY-RANK

ARRAY

ARRAY-ELEMENT-TYPE

ARRAY-RANK-LIMIT

ARRAY-TOTAL-SIZE-LIMIT

ADJUST-ARRAY

ARRAY-DIMENSIONS

ARRAY-ROW-MAJOR-INDEX

ARRAY-IN-BOUNDS-P

ADJUSTABLE-ARRAY-P

ARRAY-HAS-FILL-POINTER-P)
______

Searches
for

the

contain

the

string

the

symbols

4. L. . &

that

ARRAY

specified

are
and

string.

e o

accessible

returns

1 ist

the

current

the

package

symbols

that

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
ATTACH

Function

Connects your terminal to a process and puts the current LISP

process

into a VMS hibernation state, a state in which a process is inactive
function to
You can use this
but can become active at a later time.
switch terminal control from one process to another.

For
to the DCL ATTACH command.
similar
1is
The ATTACH function
information about the ATTACH command, see the VAX/VMS DCL Dictionary.
NOTE

1is
LISP
1if
only
can be used
The ATTACH function
invoked
is
LISP
if
invoked from DCL; it cannot be used
from another command language

interpreter

(CLI).

Format
ATTACH

process

Argument
process

The name or identification (PID) of the

process

which

vyour

To specify the process name, use a
is to be connected.
terminal
string or a symbol; to specify the PID, use an integer.

Return Value

Undefined.
Examples
1.

Lisp>

(SPAWN)

S ATTACH SMITH
Lisp>

(ATTACH

"SMITH_1")

*DCL-S-RETURNED,

control returned to process SMITH_1

named

The call to the SPAWN function creates a subprocess
1.
SMITH_

The DCL ATTACH command attaches your terminal back to
process

The call to the VAX LISP ATTACH function
to

the

SMITH.

process

returns

control

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

ATTACH Function (cont.)
2.

Lisp>

(DEFUN ATTACH-MAIN
(ATTACH

(SECOND

NIL
(GET-PROCESS-INFORMATION
NIL

: OWNER-PID))))
ATTACH-MAIN

Defines a function that attaches back to the main process
the LISP system is running as a subprocess.

1if

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
BIND-KEYBOARD-FUNCTION Function
Binds an ASCII keyboard control character (characters of
codes
0
to
31)
to
a function.
When a control character is bound to a function,
you can execute the function by typing the control character
on
your
terminal
keyboard.
A function bound in this way is called a keyboard
function.

When you type the control character, the LISP system is interrupted at
its
current point, and the function the control character is bound to
is called asynchronously.
The LISP system then evaluates the function
and returns control to where the interruption occurred.
You can delete the binding of a function and a
control
character
by
using
the
UNBIND-KEYBOARD-FUNCTION
function.
You
can
use
the
GET-KEYBOARD-FUNCTION function to get
information
about
a
function
that

bound

control

character.

You can specify an interrupt level (an integer in the range 0
through
7)
for
a
keyboard function by using the :LEVEL keyword.
A keyboard
function can only interrupt code that is
executing
at
an
1interrupt
level
below
1its
own.
Keep
the
following guidelines in mind when
specifying an

interrupt

level:

The default interrupt level for keyboard functions is 1.

Interrupt level 6 is used by LISP to
handle
keyboard
1input;
therefore,
a keyboard function executing at interrupt level 6
cannot receive input from the keyboard.
For this
reason,
be
careful when using

Interrupt level 7 can interrupt any code that is
not
1in
the
body
of
a
CRITICAL-SECTION
macro.
A
keyboard
function
executing at interrupt level 7 must terminate by
executing
a
THROW to a

interrupt level

tag,

such as

CANCEL-CHARACTER-TAG.

If you
bind
a
control
character
to
the
BREAK
or
DEBUG
functions,
use
a level that is high enough to interrupt your
other keyboard and interrupt functions but that is
less
than
6.

If you bind a control character to the ED

default

interrupt level

(1)

function,

wuse

the

or a lower level.

The
VAX
LISP/VMS
GSystem
Access
Programming
Guide
contains
information
about
using
interrupt
levels
and
about
CRITICAL-SECTION macro and interrupt functions.

more
the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

BIND-KEYBOARD-FUNCTION Function (cont.)
NOTE
When you bind a control character to a
function,
the
stream
bound
to
the
*TERMINAL-IO* variable must be
connected to your terminal.

See

Chapter

for

explanation

about

calling

functions

asynchronously.
Format

BIND-KEYBOARD-FUNCTION control-character function
&KEY

<ARGUMENTS

:LEVEL

Arguments

control-character

The ASCII control character to be bound to the function.
You can
bind a function to any control character except CTRL/Q or CTRL/S.
function

The

function to which the

control

character

to be bound.

: ARGUMENTS

A list
containing
arguments
to
be
passed
to
the
specified
function
when
it
1s
<called.
The
argquments
in the list are
evaluated when the BIND-KEYBOARD-FUNCTION function is called.
:LEVEL

An integer in the range 0-7, specifying the
the keyboard function.
The default is 1.

interrupt

1level

for

Return Value
T.

Examples

Lisp>

(BIND-KEYBOARD-FUNCTION

#\"B

#"BREAK)

Lisp>

Break>

Binds CTRL/B to the BREAK function.
break

loop by typing

CTRL/B.

You can

then

invoke

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

BIND-KEYBOARD-FUNCTION Function (cont.)
2.

Lisp>

(BIND-KEYBOARD-FUNCTION

#\“E

#’ED)

Lisp>

(now

Binds
Editor

the

Editor)

CTRL/E to the ED function.
by

typing

CTRL/E.

You

can

then

1invoke
|

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

BREAK

Function

Invokes a break loop.
A break loop is a nested read-eval-print
For more information about break loops, see Chapter 5.

loop.

Format

BREAK

&OPTIONAL

format-string

&REST args

Arguments

format-string

The

string of

create

the

characters

that

is passed to the

FORMAT function

break-loop message.

args

The

arguments

for

the

format

that are passed

the

FORMAT

function as

arguments

string.

Return Value

when the CONTINUE function is called to exit the break loop,
BREAK

function

returns

the

NIL.

Example

(WHEN

(UNUSUAL-SITUATION-P

(BREAK

"Unusual

STATUS)

situation "D encountered.

Please

investigate"”

)
STATUS)

Calls the BREAK function if the value of the
UNUSUAL-SITUATION-P
function
is
not
NIL.
The break message contains the condition
code.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

CANCEL-CHARACTER-TAG Tag
CANCEL-CHARACTER-TAG, when used in
throw
that
occurs
whenever
the
keyboard.
1In VAX LISP/VMS, CTRL/C
can
use
CANCEL-CHARACTER-TAG
in
behavior

when

user

types

a
CATCH
construct,
<catches
the
<cancel
character
1is typed at the
1is the cancel character.
Thus, you
a
CATCH
construct
to
alter the

CTRL/C.

You

can also use CANCEL-CHARACTER-TAG in a THROW construct to cause an
exit
to
the
VAX
LISP
read-eval-print
1loop.
1In this way, you can
partially simulate the action of the cancel character from within your
code.
(The cancel character also invokes the CLEAR-INPUT function on
the

*TERMINAL-IO*

stream.)

Format

CANCEL-CHARACTER-TAG

Example
Lisp>

(DEFUN

TRAPPER

()

(CATCH

'CANCEL-CHARACTER-TAG

(PRINC

"Execution

(LOOP)
)

came

through here"))

TRAPPER

Lisp>

(TRAPPER)

Execution came through here
"Execution came through here"
Lisp>

The
TRAPPER
function
sets
up
a
catcher
CANCEL-CHARACTER-TAG, then enters an infinite loop.

The

The PRINC function prints a string, indicating that
execution
continued
following
the
CATCH
form
rather
than returning

user

directly

types

the

for

CTRL/C.

Lisp>

prompt.

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

CHAR-NAME-TABLE Function
Displays

formatted

list

the

VAX

LISP

character

Format

CHAR-NAME-TABLE

Return

Value

value.

Example

Lisp>

Hex

(CHAR-NAME-TABLE)

Code

Preferred

Name

Other

NULL

~ A

SOH

STX

ETX

Names

NUL

EOT

“E

ENQ

“F

ACK

BELL

“G

BACKSPACE

“H

TAB

HT
LF

LINEFEED

“K

BEL

PAGE

“L

FORMFEED

RETURN

“N

DLE

“Q

XON

DC2

~ S

XOFF

DC4

NAK

SYN

“W

ETB

CAN

SUB

ESCAPE

ESC

DC1

DC3

ALTMODE

SPACE

RUBOUT

DELETE

DEL

names.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
CHAR-NAME-TABLE Function (cont.)
84

IND

NEL

SSA

ESA

HTS

HTJ

VTS

PLD

PLU

SS2

SS3

DCS

PU1

PU2

STS

CCH

SPA

EPA

CSI

OSC

APC

NEWLINE

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

COMPILEDP Function
A

predicate

compiled

that

checks

function

whether

object

1is

symbol

that

has

definition.

Format

COMPILEDP

name

Argument
name

The

to
Return

symbol

whose

function,

macro,

special

form

definition

1is

definition,

checked.

Value

The

interpreted

the

symbol

the

COMPILE

definition
Returns

function,

has

macro,

function.

Returns

that

not

NIL,

special

interpreted definition

was
the

symbol

the

compiled

form

that was

symbol

with

the

not

have

defines

does

has

compiled with
a

compiled

COMPILE

function.

compiled

function

definition.
Example

Lisp>

(DEFUN ADD2

(X)

(COMPILEDP

’ADD2)

2))

ADD?2

Lisp>
NIL

Lisp>

(COMPILE

ADD2

compiled.

'ADD2)

ADD2

Lisp>

(COMPILEDP

(LAMBDA

(X)

call

'ADD2)

(BLOCK ADD2

the

2)))

The

first

the

COMPILEDP

the

function ADD2

has

not

The

call

The

call

second

the

DEFUN macro

COMPILE

call

interpreted

function

previously

compiled.

been

function

compiles

COMPILEDP

definition,

returns

NIL,

because

compiled.

function

the

function named ADD2.

the

function ADD2.

functioh

because

the

returns

function

ADD2

the

was

VAX LISP/VMS FUNCTION,

MACRO,

AND VARIABLE DESCRIPTIONS

COMPILE-FILE Function
Compiles

fast-loading

binary

specified LISP

source

file

(type

FAS).

file

and writes

the

compiled

code

The

compiler

uses

the

file

Format

COMPILE-FILE
&KEY

input-pathname

:LISTING

:MACHINE-CODE

:QUTPUT-FILE

:VERBOSE

:0OPTIMIZE
:WARNINGS

Arguments

input-pathname

A pathname,
value

namestring,

the

specification
defaults

symbol,

stream.

*DEFAULT-PATHNAME-DEFAULTS*

components

that are

not

variable

specified.

fill

The

file

type

LSP.

:LISTING

Specifies whether the compiler is to produce a listing
value
can
be
T,
NIL,
or
a
pathname, namestring,

file.
The
symbol, or

stream.
If you specify T, the compiler produces a listing
file.
The
1listing
file
1is
assigned the same name as the source file
with the
contains

file

type

the

source

LIS, and
file.

1is

placed

1in

the

If you specify NIL, no listing is produced.

directory

that

The default value is

NIL.

If you specify a pathname,
compiler uses the value as

The

compiler uses

input-pathname
that

are

not

the
fill

namestring,

the

LIS
the

symbol,
specification of

file

type

components

and
of

the

or
the

the
file

stream,
the
listing file.

wvalue

the

specification

specified.

:MACHINE-CODE

Specifies whether the compiler is to include the machine code
it
produces
for
each function and macro it compiles in the listing
file.
The value can be T or NIL.
1If you specify T, the
1listing
file
contains the machine code.
1If you specify NIL, the listing
file does not contain the machine code.
The
default
value
1is
NIL.

:OPTIMIZE

Specifies the optimization
qualities
the
<compiler
1s
to
wuse
during
compilation.
The value must be a list of sublists.
Each
sublist must contain a symbol and
a
value,
which
specify
the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
COMPILE-FILE Function (cont.)
optimization qualities and corresponding values that the compiler
is

to use during compilation.
((SPACE

(SAFETY

For

example:

1))

The default value for
each
quality
discussion of compiler optimizations,

1s
one.
For
see Chapter 7.

detailed

:OUTPUT-FILE

Specifies whether the compiler is to produce a fast-loading file.
The
value
can
be T, NIL, or a pathname, namestring, symbol, or
stream.
If you specify T, the compiler produces
a
fast-loading
file.
The
output
file is assigned the same name as the source
file with the file type FAS and is placed in the
directory
that
contains the source file.
The default value is T.

If you specify NIL,

no fast-loading file is produced.

If you specify a pathname, namestring,
symbol,
or
stream,
the
compiler
wuses the value as the specification of the output file.
The compiler uses
the
FAS
file
type
and
the
wvalue
of
the
input-pathname
to
fill the components of the file specification
not

that are

specified.

: VERBOSE

Specifies
whether
the
compiler
1is
to
display
the
name
of
functions and macros it compiles.
The value can be T or NIL.
If
you specify T, the compiler displays the name
of
each
function
and
macro.
If a listing file exists, the compiler also includes
the names in the listing file.
1If you specify NIL, the names are
not displayed or included in the listing file.
The default value
is the value of the *COMPILE-VERBOSE* variable (By default, T).
: WARNINGS

Specifies whether the compiler is to
display
warning
messages.
The
wvalue
can
be
T
or
NIL.
If you specify T, the compiler
displays
warning
messagdes.
If
a
1listing
file
exists,
the
1If you
also includes the messages in the listing file.
compiler
1in
included
or
specify NIL, warning messages are not displayed
the
of
wvalue
the
1is
wvalue
default
The
file.
1listing
the
*COMPILE-WARNINGS* variable (By default, T).
Return Value

If the

compiler

returned.

generated

Otherwise,

NIL is

output
PR

returned.

file,

namestring

1is

VAX

LISP/VMS

FUNCTION,

MACRO,

AND

VARIABLE

DESCRIPTIONS

COMPILE-FILE Function (cont.)
Examples
1.

Lisp>

(COMPILE-FILE

Starting

compilation

FACTORIAL

compiled.

Finished

compilation

Errors,

"FACTORIAL"

:VERBOSE

file

DBAl:[SMITH]FACTORIAL.LSP;1

file

DBAl:[SMITH]FACTORIAL.LSP;1

Warnings

"DBAl:[SMITH]FACTORIAL.FAS;1"

Compiles

the

file

directory.
produced.

the

A
The

:VERBOSE

Lisp>

FACTORIAL.LSP,

fast-loading
compilation

keyword

(COMPILE-FILE

which

file
logged

specified with

"FACTORIAL"

1is

1in

named
the

the

terminal,

value

:QOUTPUT-FILE
:LISTING

the

current

FACTORIAL.FAS
because

NIL

:WARNINGS

NIL

: VERBOSE

NIL)

NIL

Compiles

the

file

FACTORIAL.LSP,

directory.

:OUTPUT-FILE

keyword

listing
messages

file
are

fast-loading
named

1is

specified

the

which
1is

value

because

NIL.

not

the

1in

produced,

with

FACTORIAL.LIS

suppressed,

specified with

file

the

1is

the

wvalue

produced.

:WARNINGS

current

because

the

NIL.
Warning

keyword

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
*COMPILE-VERBOSE* Variable

Controls the amount of information that the compiler displays.
The COMPILE-FILE function binds the *COMPILE-VERBOSE* variable to
the
If the :VERBOSE keyword 1s
the :VERBOSE keyword.
by
supplied
value
the
of
value
existing
the
function wuses
the
specified,
not
wvalue is not NIL, the compiler
the
If
*COMPILE-VERBOSE* variable.

displays the name of each function as it is compiled; 1if the value 1is
NIL,

the

value

<compiler

does not display the function names.

The default
|

Example
Lisp>

(COMPILE-FILE

'MATH)

Starting compilation of file DBAl:[SMITH]MATH.LSP;1
FACTORIAL
FIBONACCI

compiled.
compiled.

Finished compilation of file DBAl:[SMITH]MATH.LSP;1
0 Errors, 0 Warnings
"DBA1l:[SMITH]MATH.FAS;1"
Lisp>

(SETF

*COMPILE-VERBOSE*

NIL)

NIL

Lisp>

(COMPILE-FILE

'MATH)

"DBALl:[SMITH]MATH.FAS;2"

the output
The first call to the COMPILE-FILE function shows
file, when
a
of
compilation
the
during
the compiler displays
the *COMPILE-VERBOSE* variable is set to T.

The call to the SETF macro sets the value of the

wvariable

NIL.

The second call to the COMPILE-FILE function compiles the file
the variable’s value 1is
because
without displaying output,
NIL.

VAX LISP/VMS FUNCTION,

*COMPILE-WARNINGSTM*

Variable

Controls

compiler

whether

the

MACRO, AND VARIABLE

displays

warning

DESCRIPTIONS

messages

during

compilation.

The

COMPILE-FILE

value
is

supplied

not

function binds
with

specified,

the

*COMPILE-WARNINGS*
displays

warning

display warning

the

*COMPILE-WARNINGS* variable

:WARNINGS
function

variable.

messages;

the

The

1If

wuses

the

value

messages.

keyword.

value

default

:WARNINGS

existing

NIL,

value

the
not
the

wvalue

NIL,

the

compiler

to the
keyword
the

compiler
does

not

NOTE
The

compiler

error

always

displays

messages.

fatal

and

continuable

Example
Lisp>

(COMPILE-FILE

Starting
Warning

bound

value

but

wvalue

compiled.

Finished

compilation

Errors,

not

used.

not

used.

file

DBAl:[SMITH]MATH.LSP;2

FIBONACCI

file

compiled.

bound

FACTORIAL

but

FACTORIAL
Warning

’'MATH)

compilation

DBA1:[SMITH]MATH.LSP;2

Warnings

"DBAl:[SMITH]MATH.FAS;3"
Lisp>

(SETF

*COMPILE-WARNINGS*

NIL)

NIL

Lisp>

(COMPILE-FILE

'MATH)

Starting

compilation

FACTORIAL

compiled.

FIBONACCI

compiled.

Finished

compilation

Errors,

file

DBAl:[SMITH]MATH.LSP;?2

file

DBA1:[SMITH]MATH.LSP;?2

Warnings

"DBAl:[SMITH]|MATH.FAS;4"

The
the

first call
compiler

the

*COMPILE-WARNINGS*

variable

e o

The

call

to the COMPILE-FILE
displays during the

the

£ v Py T

SETF

e Em

macro

sets

function shows
compilation of
set
e o=

the
output
file, when

to T.
1

the value

the

- o mm am o

variable

VAX LISP/VMS FUNCTION,

*COMPILE-WARNINGS*
@

MACRO, AND VARIABLE DESCRIPTIONS

Variable (cont.)

The second call to the COMPILE-FILE
without displaying warning messages
variable’s

value

1is

NIL.

function compiles the file
in the output, because the

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

CONTINUE Function
Enables

you

causes

the

BREAK

exit

program

continue

the

break. loop.

function
from

the

When

you

return NIL

point

call

and

which

#'BREAK)

this

the

function,

evaluation

the

break

your

1loop

was

needed

entered.
Format

CONTINUE

Return Value
NIL.

Example
Lisp>

(BIND-KEYBOARD-FUNCTION

Lisp>

(LOAD

;

"FILEB.LSP")

contents

file

LISPWS:[SMI...

“ B

0—3~e

wme

Break>

(LOAD

Loading
Finished

file

LISPWS:[SMITH]FILEA.LSP;1

LISPWS$:[SMITH]FILEA.LSP;1

(CONTINUE)

Continuing

;

FUNCTION-A

Break>
;

"FILEA.LSP")

contents

from break

loop...

FUNCTION-B

Finished

LISPWS:[SMITH]FILEB.LSP;1

Lisp>

The

BREAK

FILEB.LSP

The

function
is

programmer,

realizing that

invokes

BREAK

FILEA.LSP

Finally,
loading

the
of

top-level

CTRL/B.

loaded.

initialize
the

is bound

environment

FILEA.LSP

for

(which

FILEB.LSP)

not yet

loaded,

loop.

then loaded.

call
to
the
CONTINUE
function
continues
FILEB.LSP
and then returns the programmer to

loop.

the
the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

DEBUG

Function

Invokes

the

For

VAX

LISP

debugger.

information about how to use

the VAX LISP debugger,

see

Chapter

the debugger

other

Format
DEBUG

Return Value

Returns NIL.
(see

Chapter

You can cause

return

wvalues

5).

Example

Lisp>

(DEBUG)

Control

Stack

Frame

#5:

Debug

Debugger

(DEBUG)

Invokes the VAX LISP debugger. When you invoke the debugger,
displays an identifying message, stack frame information, and
debugger

prompt.

1t
the

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

DEBUG-CALL Function
Returns
This

list

representing

function

returned by

passed

1is

the

DEBUG-CALL

function

the

debugging

current

debug

tool

takes

function

the

and

can be

current

stack

frame
no

used

function

arguments.

access

call.

The

the

list

values

frame.

Format
DEBUG-CALL

Return Value

A list
is

representing

returned

this

the

current debug

function

called

frame

function

outside

the

call.

NIL

debugger.

Example

Lisp>

(SETF THIS-STRING

"abcd")

Lisp> (FUNCTION-Y THIS-STRING 4)
.
Error in function FUNCTION-Y
Frame #4 (FUNCTION-Y "abcd" 4)
Debug

(SETF

STRING

(SECOND

(EQ

"abcd"

(EQ

THIS-STRING

(DEBUG-CALL)))

"abcd"

Debug

STRING)

NIL

Debug

STRING)

In this
case,
the
function
in
the
current
stack
frame
1is
FUNCTION-Y.
The
call
to
(DEBUG-CALL)
returns
the
1list
(FUNCTION-Y "abcd 4).
The form (SECOND
(DEBUG-CALL))
evaluates
"abcd",
the
first
argument
to FUNCTION-Y in the current stack
frame.
Note
that
the
string
returned
by
the
<call
(SECOND
(DEBUG-CALL) )
1s
the
same
string
passed
to
the
function
FUNCTION-Y.
See the description of the TRACE macro
for
another
example of the use of the DEBUG-CALL function.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*DEBUG-PRINT-LENGTH*

Variable

Controls the output that the debugger, stepper, and tracer
facilities
display.
This
variable
controls
the
number
of
objects
these
facilities can display at each level of a
nested
data
object.
The
variable’s
wvalue
can
be
either
a positive integer or NIL.
If the
value is a positive integer,
the
integer
1indicates
the
number
of
objects
at
each
level
of
a nested object to be displayed.
1If the
value is NIL, no limit is
on
the
number
of
objects
that
can
be
displayed.

The

default

value

NIL.

The value of this variable might cause the printer to truncate output.
An

ellipsis

(...)

This variable

COMMON LISP:

The

indicates

similar

truncation.

the

*PRINT-LENGTH* variable

described

1in

Language.

Example

Lisp>

(SETF ALPHABET

'(A B

(ABCDETFGHTIJ

Lisp>

(SETF

CDEFGHTIJK))

*DEBUG-PRINT-LENGTH*

5
Lisp>

Fatal

error

Argument
Control

ALPHABET)

must

function +
be

(signaled with ERROR).

number:

(A B

CDEF

Debugger

Frame

#5:

Debug

(SETF

#5:

(A B

CDE

...))

*DEBUG-PRINT-LENGTH#*

Frame

(A B

...))

The call to the SETF macro sets the symbol ALPHABET to a
of

single-letter

1list

symbols.

The value of the *DEBUG-PRINT-LENGTH* variable is set to 5.

The illegal call to the plus sign (+) function causes the LISP
system
to
invoke
the
debugger.
The debugger displays only
five elements of the list that is
the
wvalue
of
the
symbol
ALPHABET
the
first time it displays the stack frame numbered
5.

The call to the SETF macro within the debugger sets the
of

the

*DEBUG-PRINT-LENGTH* variable

The debugger displays three elements of the
e

change

the value

the variable.

wvalue

1list,

after

you

e e -

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
*DEBUG-PRINT-LEVEL*

Variable

Controls the output that the debugger, stepper, and tracer
facilities
display.
This
variable
controls
the
number of levels of a nested
object these facilities can display.
The
wvariable’s
value
can
be
either a positive integer or NIL.
If the value 1s a positive integer,
the integer indicates the number of levels of a nested
object
to
be
displayed.
If
the value is NIL, no limit is on the number of levels
that can be displayed.
The default value 1s NIL.
The

value

A number

this

variable

sign

(#)

indicates

might

cause

the

printer

This variable is similar to the *PRINT-LEVEL*
COMMON

LISP:

The

truncate

output.

truncation.

variable

described in

Language.

Example

Lisp>

(SETF ALPHABET

Lisp>

Fatal

error

Lisp>

’(A

(E)))))

(SETF

*DEBUG-PRINT-LEVEL*

(E))))))

ALPHABET)

Argument

must

Control

Stack

function +
be

number:

(signaled with
(A

ERROR).

(E)))))

Debugger

Frame

#5:

Debug

(SETF

#)))

*DEBUG-PRINT-LEVEL*

NIL)

NIL

Debug 1> WHERE
Frame

The

#5:

call

nested

to the

(E))))))

SETF macro

sets

the

symbol

ALPHABET

list.

The value of the

The illegal call to the plus sign (+) function causes the LISP
system
to
invoke
the
debugger.
The debugger displays only
three levels of the nested list (that
1is
the
wvalue
of
the
symbol
ALPHABET)
the
first time it displays the stack frame

numbered

The

to the SETF macro within the debugger

*DEBUG-PRINT-LEVEL* variable

call
the

*DEBUG-PRINT-LEVEL*

The debugger displays all
you change

the value

set

the

value

the levels of the nested list,

after

variable

to NIL.

the variable.

sets

to 3.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
DEFAULT-DIRECTORY Function
Returns
with

The

the

a pathname with the host,
values

the

DEFAULT-DIRECTORY

command.
VAX/VMS

For
DCL

current

function

information

device,

default

and directory fields

filled

directory.

similar

about

the

SHOW

DEFAULT

SHOW DEFAULT command,

the

DCL

see the

Dictionary.

You can change the default directory by using the SETF macro.
Setting
your
default
directory
with this macro also resets the value of the
*DEFAULT-PATHNAME-DEFAULTS* variable.
Performing
this
operation
1s
similar
to
wusing
the
DCL
SET
DEFAULT command.
See Chapter 7 and
COMMON LISP:
The Language for information
about
pathnames
and
the
*DEFAULT-PATHNAME-DEFAULTS*

Note

variable.

that the directory must exist

for

the

change

directory

succeed.
Format

DEFAULT-DIRECTORY
Return Value

The

pathname

that

refers

the

default directory.

Examples

Lisp>

(DEFAULT-DIRECTORY)

#S (PATHNAME

:HOST

:DIRECTORY

"SMITH"

:VERSION

Lisp>

"MIAMI"

:DEVICE

:NAME NIL

"DBAl"

:TYPE NIL

NIL)

(SETF

(DEFAULT-DII RECTORY)

"[.TESTS]")

"[ .TESTS]"
Lisp>

(DEFAULT-DIRECTORY)

#S (PATHNAME
:DIRECTORY
:VERSION

:HOST "MIAMI"
"SMITH.TESTS"

:DEVICE "DBAl"
:NAME NIL

:TYPE NIL

NIL)

The first call to the DEFAULT-DIRECTORY
function
the pathname that points to the default directory.

returns

The call to the

default

directory

SETF
to

macro

changes

the

wvalue

the

SMITH.TESTS.

The second call to the DEFAULT-DIRECTORY function verifies
the

directory

change.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
DEFAULT-DIRECTORY Function (cont.)
2.

Lisp>

(DEFAULT-DIRECTORY)

#S (PATHNAME :HOST "MIAMI" :DEVICE "DBA1l"
:DIRECTORY "SMITH.TESTS" :NAME NIL :TYPE NIL
:VERSION

Lisp>

NIL)

*DEFAULT-PATHNAME-DEFAULTS*

#S (PATHNAME :HOST "MIAMI" :DEVICE "DBA1l"
:DIRECTORY "SMITH.TESTS" :NAME NIL :TYPE NIL
:VERSION NIL)

Lisp>

(NAMESTRING

(DEFAULT-DIRECTORY))

"DBAl:[SMITH.TESTS]"
Lisp>
n[_

(SETF

(DEFAULT-DIRECTORY)

"[-]")

Lisp>

(NAMESTRING

(DEFAULT-DIRECTORY))

"DBAl:[SMITH]"
Lisp>

(NAMESTRING

*DEFAULT-PATHNAME-DEFAULTS*)

"DBAl:[SMITH]"

The
the

first call to the DEFAULT-DIRECTORY
function
pathname that points to the default directory.

returns

The call to the *DEFAULT-PATHNAME-DEFAULTS* variable shows
that
its
wvalue
1is the same as the value returned by the
DEFAULT-DIRECTORY function.

The call
as

The

call

default

The
the
the

to the NAMESTRING function

returns

the

pathname

string.

to the
directory

SETF

macro

changes

the

wvalue

the

to DBAl:[SMITH].

last two calls to the NAMESTRING
function
show
that
return
values
of the DEFAULT-DIRECTORY function and
*DEFAULT-PATHNAME-DEFAULTS*
variable
are
still
the

same.

VAX

LISP/VMS

FUNCTION,

DEFINE-FORMAT-DIRECTIVE
Defines

directive

directives

directive

for

supplied

you

have

MACRO,

AND

VARIABLE

FORMAT

control

LISP.

1In

DESCRIPTIONS

Macro

use

with

VAX

defined

the

string,

call

supplementing

FORMAT,

specify

form:

~ /name/
You

can

also

specify

colon

and

at-sign

modifiers:

“@:/name/
You

can

also

specify

one

parameters:

“n,n/name/
DEFINE-FORMAT-DIRECTIVE

provides

directive

presence

See

vyou
or

Section

define

absence

6.4

for

means

receive

colon

and

for

the

at-sign

information

the

value

body

the

parameters

format

and

the

modifiers.

about

defining

format

directives.

Format
DEFINE-FORMAT-DIRECTIVE

name

(arg stream colon-p atsign-p
&OPTIONAL

&BODY

(parameterl

default)

(parameter?2

default)...)

forms

Arguments
name

The

name

the

FORMAT

directive

defined

with

this

macro.

NOTE
If

you

current
when

not

define

specify

the

package.

vyou

refer

package

directive,

If
to

directive

looks

1in

directive

definition.

you
the

the

with

name

not

1is

specify

directive,

USER

name

placed

package

when

the

package

the

FORMAT

for

the

arg

symbol
b

F .

CctC

}_J

that

bound

the

argument

LS
F o
VS
e

formatted

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

DEFINE-FORMAT-DIRECTIVE Macro (cont.)
stream

A symbol
be

that

bound

the

stream to which the printing

that

is bound to T or NIL,

done.

colon-p

A symbol
was

specified

the

indicating

whether

colon

directive.

atsign-p

A symbol
was

that

specified

is bound to T or NIL,
in

the

indicating whether an at-sign

directive.

parameters

There must be one optional argument
for
each
prefix
parameter
that
1is
allowed
in
the
directive.
A
symbol
supplied as a
parameter argument will be
bound
to
the
corresponding
prefix
parameter
if
it was specified in the directive.
Otherwise, the
default value will be used, as with all optional arguments.
forms

Forms which are evaluated to print argument to stream.
The
can begin with a declaration and/or documentation string.

body

Return Value

The name

of the

FORMAT directive

that has been defined.

Example

Lisp>

(DEFINE-FORMAT-DIRECTIVE

EVALUATION-ERROR
(SYMBOL

STREAM

&OPTIONAL
(DECLARE

(IGNORE

(FRESH-LINE
(PRINC

ATSIGN-P

0))

ATSIGN-P))

STREAM)

(CASE

SEVERITY

"Warning:

"Error:

"Severe

Error:

STREAM)
(FORMAT STREAM

""" :!The symbol "S " :_does not have an ~
integer value. %Its value is: ": "8 ."
(SYMBOL-VALUE

COLON-P

(WRITE-CHAR

"))

SYMBOL
(WHEN

COLON-P

(SEVERITY

#\BELL

STREAM)))

EVALUATION-ERROR

SYMBOL))

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
- DEFINE-FORMAT-DIRECTIVE Macro (cont.)
Lisp>

(SETF

PROCESS

NIL

Lisp>

Error:

(FORMAT T

NIL)

"“1:/EVALUATION-ERROR/"

"PROCESS)

The symbol PROCESS does not have an integer value.
Its value

i1s:

NIL

<BEEP>

a use

This example shows the definition of a FORMAT directive,

indicates
"71:/EVALUATION-ERROR/"
in
The prefix parameter 1
The colon produces
severity of the error being signaled.
the

of the directive,

a beep on the

and the printed output.

terminal.

VAX LISP/VMS FUNCTION, MACRO, AND VAR!ABLE DESCRIPTIONS
DEFINE-GENERALIZED-PRINT-FUNCTION Macro
Defines a
printed,

function that specifies how
regardless
of
1ts
form.

effective only when they are enabled
pretty
printing
1s
enabled.
You
function

globally,

wusing

any
object
1is
to
be
pretty
Generalized print functions are

(globally or
can
enable

1locally)
and
when
a generalized print

GENERALIZED-PRINT-FUNCTION-ENABLED-P.

Or,

you
can enable it locally, using WITH-GENERALIZED-PRINT-FUNCTION.
An
enabled generalized print function is used if its predicate
evaluates
to

See

non-NIL

value.

Section

6.6

for

information

about

generalized

functions.
Format

DEFINE-GENERALIZED-PRINT-FUNCTION name
&BODY

(object

stream)

predicate

forms

Arguments
name

The

name

the

generalized print

function being defined.

object

symbol

that

bound to

symbol

that

is bound

the

object

to be printed.

the

stream to which

stream

output

1is

sent.

predicate

A form.
When the generalized print
function
has
been
enabled
(globally
or
locally), the system evaluates this form for every
object to be pretty printed.
1If the form evaluates to non-NIL on
the
object
to be pretty printed, the generalized print function
will

used.

forms

Forms that print object to stream,
or
take
any
other
action.
These
forms
can
refer to the object and stream by means of the
symbols used for object and stream.
The body can
begin
with
a
declaration and/or documentation string.
Return Value

The name

the

generalized print

function that has been defined.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
DEFINE-GENERALIZED-PRINT-FUNCTION Macro (cont.)
Example

Lisp>

(DEFINE-GENERALIZED-PRINT-FUNCTION PRINT-NIL-AS-LIST
STREAM)

(OBJECT

OBJECT)

(NULL

(PRINC

STREAM))

PRINT-NIL-AS-LIST

Lisp>

(PRINT

NIL)

Lisp> (PPRINT

NIL)

NIL
NIL

NIL

Lisp>

(WITH-GENERALIZED-PRINT-FUNCTION

’PRINT-NIL-AS-LIST

NIL)

(PRINT

(PPRINT

NIL))

NIL

()

Lisp>

(SETF

(GENERALIZED-PRINT-FUNCTION-ENABLED-P
"PRINT-NIL-AS-LIST)

T)
T

Lisp>

(PPRINT

NIL)

()

The first PRINT call prints NIL, because the generalized print

The first PPRINT call prints NIL, because PRINT-NIL-AS-LIST 1is

function PRINT-NIL-AS-LIST is not enabled.

still

not

enabled.

The second PRINT call prints NIL, because pretty
not

printing

1is

enabled.

The second PPRINT call prints

(

because

the

generalized

The third PPRINT call

prints

(

because

the

generalized

print function is enabled locally.

print function is enabled globally.

VAX LISP/VMS FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

DEFINE-LIST-PRINT-FUNCTION Macro

Defines and enables a function
specified
printing

name

Defined

enabled.

printed

format

See

element.

for a

have

Section

The

system

match.

1If

the

first

function,

the

list

list-print

you

functions
checks

lists

that

are

effective

the

first

element
is

begin

element

printed

with

only when
of

list

each

matches

according

pretty

list

the
the

defined.

6.5

for

information

about

list-print

functions.

Format

DEFINE-LIST-PRINT-FUNCTION symbol

(list

stream)

&BODY

printed

1in

forms

Arguments

symbol
The

first

element

any

1list

the

defined

format.

list
A

symbol

that

bound

the

list

printed.

symbol

that

bound

the

stream on which

stream

printing

done.
forms

Forms

and

the

stream.
also

evaluated.

stream
The

The

by means

body

can

forms

include

the

refer

the

symbols you

declarations.

list

supply
Calls

for

printed

list

FORMAT

included.

Return Value

The

name

the

list-print

function

that

has

been

defined.

Example

Lisp>

(DEFINE-LIST-PRINT-FUNCTION
(FORMAT

MY-SETQ

Y ITR{TWTS

T WAL

MY-SETQ

(SETF

(MY-SETQ

BASE
3

STREAM)

STREAM
LIST))

Lisp>

(LIST

BYE

' (MY-SETQ

BYE

4))

and
may

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

DEFINE-LIST-PRINT-FUNCTION Macro (cont.)
Lisp>

(PRINT

BASE)

(MY-SETQ HI

BYE

(MY-SETQ HI

BYE

Lisp>

(PPRINT

(MY-SETQ

HI
BYE

BASE)

3
4)

function MY-SETQ is defined.

The list-print

The call to PRINT does not use the list-print function MY-SETQ
to
print
the
value
of BASE, because pretty-printing is not
enabled.

The call
print

the

to PPRINT does use the list-print function MY-SETQ to
value

BASE.

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE

DESCRIPTIONS

DELETE-PACKAGE Function
Uninterns

all

packages

the

signaled

the

symbols

function

interned

wuses,

package
1s

used

-and
by

the

deletes
any

other

package,

the

package.

Format

DELETE-PACKAGE package
Argument

package

A package,

string

symbol

naming

Return Value
T.

Example

Lisp>

(DELETE-PACKAGE

"TEST-PACKAGE")

Lisp>

(FIND-PACKAGE

"TEST-PACKAGE")

NIL

wunuses

package.

package

all

error

the

VAX

LISP/VMS

DESCRIBE

Function

Displays

information

object
in
of

has

addition

the

For

the

symbol’s

internal

about

specified

other

the

wvalue,
If

string,

information

function

example,

information.
tracking

MACRO,

documentation

information

object.

FUNCTION,

things

DESCRIBE

object

this

function
depends

specified,

properties,
number

displayed

DESCRIPTIONS

displays

symbol

roundoff

object.

function

definition,

representation

VARIABLE

the

floating-point

such

AND

the

specified

displays

the

displays.
on

the

and

the

type

function

other

specified,

the

way

that

string

The

type
of

types
useful

errors.

Argument

object

Return

object

about

which

information

displayed.

Value

value.

Examples

Lisp>

(DESCRIBE

’C)

the

Package:

symbol
USER

Value:

unbound

Function:

undefined

Lisp>

(DESCRIBE

’'FACTORIAL)

the

FACTORIAL

symbol

Package:

USER

Value:

unbound

Function:

compiled-function

FACTORIAL

Lisp>

(DESCRIBE

the

PI)

long-float

3.1415926535897932384626433832795L0

Sign:

Exponent:

Significand:

0.78539816339744830961566084581988L0

(radix

number’s

Format

The

the

displays

for

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
DESCRIBE Function (cont.)
4.

Lisp>

(DESCRIBE

’#(1°2

5))

simple-vector

Dimensions:

(5)

Element .type:

Adjustable:

Fill

Pointer:

Displaced:

Displays information about the simple-vector #(1 2

3 4

5).

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

DIRECTORY Function
Converts its argument
to
a
pathname
and
returns
a
pathnames
for
the
files
matching the specification.
function is similar to the DCL DIRECTORY command.

1list
of
the
The DIRECTORY

Format

DIRECTORY pathname
Argument

pathname

The pathname, namestring, stream, or symbol for which the list of
file
system
pathnames
is to be returned.
1In VAX LISP/VMS, this
argument is merged with the following default file specification:
host::device:[directoryl*.*;*

The host, device,
and
directory
values
*DEFAULT-PATHNAME-DEFAULTS* variable.

are

Specifying
Jjust
a
directory
1s
equivalent
directory
with
wild
<cards
(*)
1in the name,
fields
of
the
argument.
For
example,
the
expressions are equivalent:
(DIRECTORY

"[MYDIRECTORY]")

(DIRECTORY

"[MYDIRECTORY]*.*;*")

Both expressions
files

the

return a

list

of pathnames

supplied

the

to
specifying
a
type, and version
following
two

that

represent

the

directory MYDIRECTORY.

Specifying just a directory with a
specified
wversion
field
1is
equivalent
to specifying a directory and version with wild cards
(*) in the name and type fields of the
argument.
For
example,
the following two expressions are equivalent:
(DIRECTORY

" [MYDIRECTORY];0")

(DIRECTORY

"[MYDIRECTORY]*.%*;")

Both expressions return a list of the
pathnames
that
represent
the newest versions of the files in the directory MYDIRECTORY.

The
for

following equivalent expressions
files in your default directory:

return the

list of pathnames

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

DIRECTORY Function (cont.)
(DIRECTORY

"")

(DIRECTORY

(DEFAULT-DIRECTORY))

Return Value

A list
NIL,

pathnames,

the

pathname

the

specified pathname

not matched.

1is

matched,

and

"“%The following "~ :[files are” ;file
in the directory "A:["A]:"

is 7]

Example

Lisp>

(DEFUN MY-DIRECTORY
(LET

((PATHNAME
(DIRECTORY

(COND

( (NULL

(&OPTIONAL

(PATHNAME

""))

FILENAME ) ))

(DIRECTORY

DIRECTORY)

(FORMAT

"YoNo

files match "A.

(NAMESTRING
(T

(FILENAME

FILENAME))

(FORMAT

FILENAME)
))

(EQUAL

(LENGTH

DIRECTORY)

(PATHNAME-DEVICE

(NTH

DIRECTORY))

(PATHNAME-DIRECTORY

(NTH
(DOLIST

DIRECTORY)))

(DIRECTORY)

(FORMAT T

2T A"

(FILE-NAMESTRING X)))

(TERPRI)
))

(VALUES)))
MY-DIRECTORY

Lisp>

The

(MY-DIRECTORY)

following

files

are

the

directory DBAl:[SMITH.TESTS]:

TEST5.DRB;1
TEST1.LSP;7

TEST1.LSP;6
TEST1.LSP;5

EXAMPLE.TXT;
2
TEST3.LSP;15
TEST6.LSP;1
Lisp>

The

(MY-DIRECTORY

following

files

".LSP;")

are

the

directory DBAl:[SMITH.TESTS]:

TEST1.LSP;7

TEST3.LSP;15
TEST6.LSP;1

The call

to the DEFUN macro defines a

function

that

formats

the
output
of the DIRECTORY function, making the output more
readable.
The function is defined such
that
1t
accepts
an
optional argument and does not return a value.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
DIRECTORY Function
The first
function

(cont.)

call to
formats

the
the

function
MY-DIRECTORY
shows
how
directory output when an argument is

the
not

specified.

The

second call
to
argument; the output

names

type

the

function
MY-DIRECTORY
1includes
an
includes only the latest versions of file

LSP.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
DRIBBLE Function

Echoes the input and output
of
an
interactive
LISP
session
to
a
enabling you to save a record of what you do during
file,
specified
the

session in the

form of a

file.

When you want to stop the DRIBBLE
function
from
echoing
input
and
output to the pathname, close the file by calling the DRIBBLE function
without

argument.

In VAX LISP/VMS,
function

restrictions

When you are in the Editor,

the

wuse

the

DRIBBLE

terminal I/O is not recorded in

file.

dribble

the two

are:

You cannot nest calls to the DRIBBLE function.

Format

DRIBBLE

&OPTIONAL pathname

Argument

pathname

The pathname to which the input and output of the LISP session is
to

sent.

Return Value

function,
the
specified with
If an argument is
If debugging
and dribbling is turned on.
returned
1is
T
then
function is called with no arguments,
is off
If dribbling
off.
turned
is
dribbling

without an argument,

NIL is

1is
no value
the
is on and
and
returned
and is called

returned.

Examples

Lisp> (DRIBBLE "NEWFUNCTION.LSP")
Dribbling to DBAl:[SMITH]NEWFUNCTION.LSP;1
Lisp>

LISP
The
named NEWFUNCTION.LSP.
file
dribble
Creates a
system sends input and output to the file until you call the
DRIBBLE function again (without an argument) or exit LISP.
2.

Lisp>

(DRIBBLE)

Closes the dribble file that was previously opened.

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

Function

Invokes

the

VAX

LISP

Editor.

This

function

can

specified

with

optional
argument
whose
value
can
be
a
namestring, pathname, or
symbol.
In VAX LISP, the argument’s value can also
be
a
1list.
In
addition,
you
<can
specify
a
:TYPE argument whose value can be the
: FUNCTION

:VALUE

keyword.

NOTE
If you bind a control character (such
as
CTRL/E)
to
the
ED function using BIND-KEYBOARD-FUNCTION, specify
an interrupt level of 1 (the default) or
0
with
the
: LEVEL
keyword.
Do
not
specify a higher interrupt
level.

See

Chapter

for

information on using the VAX LISP Editor.

Format

&OPTIONAL

&KEY

:TYPE

Arguments
X

The namestring, pathname, symbol, or list that is to
be
edited.
If
you
specify
a list, the list must be a generalized variable
that can be specified in a call to the SETF macro.
The
1list
1is
evaluated
and
it
returns a value you can edit.
When you write
the buffer containing the value, the Editor replaces the value of
the generalized variable with the new value.

If you specify
a
symbol,
you
can
also
specify
the
keyword
argument.
The
value
of the keyword informs the Editor whether
you want to edit the symbol’s function or macro definition or its
value.
:TYPE

You can specify this argument if the x argument is a symbol.

The

value
is
a
keyword
that
affects
the interpretation of the x
argument’s value.
You can specify one of the following keywords:

: FUNCTION

The Editor is
or

macro

specified

: VALUE

invoked to edit

definition

the

associated

the

symbol.

The Editor is invoked to edit the
symbol’s

function
with

value.

specified

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

Function
The

(cont.)

default value

for

the

:TYPE

keyword

the

:FUNCTION

keyword.

Return Value
No

wvalue.

Examples
1.

Lisp>

(ED

Invokes

"[SMITH.LISP]NEWPROG.LSP")

the

Editor

edit

directory

[SMITH.LISP].

Lisp>

’'FACTORIAL)

(ED

Invokes
Lisp>

the

(ED

Invokes

Editor

to edit

"GAMEBOARD-ARRAY

the

Editor

the

file

NEWPROG.LSP

function named

:TYPE

edit

1in

the

FACTORIAL.

:VALUE)

the

wvalue

the

symbol

GAMEBOARD-ARRAY.

Lisp>

(DEFSTRUCT

ROOM

DOORS

WINDOWS

OUTLETS

COLOR)
ROOM

Lisp>

(SETQ ROOMZ

(MAKE-R

:DOORS 1
:WINDOWS

:OUTLETS

:COLOR

:DOORS 1

#S(ROOM

Lisp>

The

(ED

:WINDOWS 3

'BLUE))

:QOUTLETS 4

:COLOR BLUE)

’ (ROOM-COLOR ROOM2))

call

to the DEFSTRUCT macro defines a structure

named

ROOM.

The
the

®@

call

to the SETQ special

structure

form creates an

1instance

ROOM.

e E ditor
S
The call to the ED function invo kes
COLOR slot o f t he structure bound to ROOM
o

P I

—

edit

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
"ERROR-ACTION*
Determines

the

Variable

action

when

error
oOccurs.
The
value
of
this variable can be the :EXIT or
:DEBUG keyword.
If the value 1is :EXIT, the error handler
causes
LISP
system
to exit; if the value is :DEBUG, the handler invokes

the
the
the

VAX LISP debugger.
sessions:

set

the

addition

Chapter

2).

the

The

VAX

LISP

error

default value

1is

:EXIT

handler

:DEBUG

for

take

interactive

LISP

otherwise.

setting this variable within a LISP form, you can
LISP initialization with the /ERROR_ACTION qualifier

also

(see

Example
Lisp>

(CAR

'A)

Fatal

error in function CAR
must be a list: A.

(signaled with ERROR).

Argument

Control

Debugger

Stack

Frame

#5:

Debug

(CAR A)

Lisp>

(SETF

QUIT
*ERROR-ACTION*

:EXIT)

: EXIT

Lisp>

(CAR

'A)

Fatal

error in function CAR
must be a list: A.

(signaled with

ERROR).

Argument

When the first error occurs, the LISP system invokes
the
VAX
LISP debugger because the value of the *ERROR-ACTION* variable
is

:DEBUG

The call

(the

default).

to the SETF macro sets the value of the

wvariable

exits

and

cEXIT.

The second time the error occurs,
control

returns

the VMS

the LISP

command level.

system

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

EXIT Function
Invokes

and

You

can

when

When

the

VMS

return
pass

vyou

the

command

Exit

system ‘service,

control
the

exit

LISP

status
the

the VMS
of

the

LISP

causing

command

LISP

system

system by

system exits,

the

LISP

system

exit

level.
to

the

specifying

the

argument’s

value

that

indicates

the

VMS

command

optional

passed

level

argument.

the

VMS

level.

Format

EXIT

&OPTIONAL

status

Argument
status

fixnum or

keyword

status

the

LISP

system
that
1is to be returned to the VMS command level when the
LISP system exits.
The keywords you can specify and the types of
status

they

return

are

the

following:

: ERROR

Error

: SUCCESS

Success

status

:WARNING

Warning

status

Return Value

The

EXIT

function

Lisp>

(EXIT)

does

not

return

LISP.

Examples
1.

Exits

the

Lisp>

(EXIT

LISP

system.

:ERROR)

SHOW SYMBO

$STATUS
Exits

the

command

"%$X112D8012"

LISP

system.

level,

the

When

VAX

LISP

status.

control

exit

returns

status

contains

the

VMS

error

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
Format Directives Provided with VAX LISP
VAX LISP
provides
eight
directives
for
the
FORMAT
function,
1in
addition
to
those
described in COMMON LISP:
The Language.
Table 1
lists and describes
these
directives.
See
Section
6.3
for
more
information about using

Table 1:
Directive
a4

these directives.

Format Directives Provided with VAX LISP
Effect

Prints the corresponding argument
under
direction
of
the current print variable values.
The argument for "W
can be any LISP object.
This directive takes
a
colon
and

modifier

four prefix parameters.

Use the colon modifier
(" :W)
when
you
want
to
set
*PRINT-PRETTY*
and
*PRINT-ESCAPE*
to
T,
and
set
*PRINT-LENGTH*,
*PRINT-LEVEL*,
and
*PRINT-LINES*
to
NIL.

The

prefix

parameters

are

parameters

identical

specify

those

padding.

These

wused with the "A

directive.

“mincol,colinc,minpad,padcharWw

mincol specifies the
minimum
width
of
the
printed
FORMAT inserts padding
of the object.
representation
least
at
characters on the right, until the width is
Use the at-sign with minpad to insert
mincol columns.
The
instead.
1left
the
on
characters
the padding
for mincol

default

padding
the number of
colinc specifies an increment:
to be inserted at one time until the width
characters
The default is 1.
is at least mincol columns.
of
number
minimum
the
specifies
minpad
0.
is
default
The
inserted.
be
to
characters

padchar,
padding

preceded by a
character.

quote,
single
default
The

padding

the
specifies
space
the
is

character.

Begins

logical

block.

logical

block

hierarchical grouping of FORMAT directives treated as a
block with
FORMAT must be processing a logical
unit.
printing.
pretty
enable
to
true
*PRINT-PRETTY*
of
elements
to
refer
block
logical
Directives inside a
FORMAT.
to
list
1list taken from the argument
single
a

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
Format Directives Provided with VAX LISP (cont.)
Table

(cont.)

Directive

Effect

(If the argument supplied to the logical block 1is not a
list,
then
the
1logical
block
1is
skipped
and
the
argument is printed as if with "W.) The
logical
block
directive takes colon and at-sign modifiers.

When the directive

is modified by a colon

(" :!),

the

directive
sets
*PRINT-PRETTY* and *PRINT-ESCAPE* to T
and *PRINT-LENGTH*, *PRINT-LEVEL*, and *PRINT-LINES* to
NIL.

When the directive is modified by an at-sign (" @!), the
directives
within
the
logical
block take successive
arguments from the FORMAT argument list.
The
1logical
block uses up all the arguments, not just a single list
argument.
Arguments not needed by
the
logical
block
are used up as well, so that they are not available for
subsequent

directives.

Specify a parameter of 1

(71!)

to enclose

the output in

parentheses.

Ends a logical block.
If modified by an at-sign (" €!),
the
directive inserts a new line if needed after every
blank

space

character.

Specifies a multiline mode new line and marks a logical
block
section.
This directive takes colon and at-sign
modifiers.
When
modified
by
a
<colon
(7:_),
the
directive
starts
a new line if not enough space is on
the line to print the next logical block section.
When
modified
new line

by
an
at-sign (" @_), the
if miser mode is enabled.

directive

starts a

The ~ _ directive and its variants
are
effective
only
when
wused
within a logical block with pretty printing
enabled.

Sets indentation for
subsequent
1lines
to
n
columns
after
the
beginning of the logical block or after the
prefix.
When modified by a colon ("n:I), the directive
causes
FORMAT to indent subsequent lines n spaces from
the
column
corresponding
to
the
position
of
the
directive.
The "nI directive and the "n:I variant are
effective only when used within a
1logical
block
with
pretty printing

enabled.

VAX LISP/VMS FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

Format Directives Provided with VAX LISP (cont.)
Table

(cont.)

Directive

“n/FILL/

Effect

Prints

the

possible
printed

~“n/LINEAR/

each

list

enabled,

the

output

elements

the

printed

not

enabled,

output

Prints

the

encloses

with

1If

pretty

the

list

line,

many

elements

FORMAT

encloses

the

printing

FORMAT

line.

not

the

printed

cannot

directive

1If

pretty printing

causes

prints

this

parentheses.

directive

single
list

causes

single

this

the

line.

separate

column spacing.
this
directive
single

list

parentheses.

list

directive

the

line.

single

element

“n,m/TABULAR/

elements

FORMAT

each

encloses

is
the

line.

tabular

1list

1in

form.

parentheses;

1is

FORMAT

specifies

the

If pretty
printing
1s
not
enabled,
causes FORMAT to print the output on a

line.

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

GC Function
Invokes

the

collection
disable

garbage

collector.

during

normal

this

initiate

process.

garbage

The

LISP

system use

However,

collection

the

during

system

whenever
GC

system

1initiates

necessary.

function

garbage

You

enables

cannot
you

interaction.

NOTE
The

LISP

system

initiate

the

You

might

just

function

want

before

this

initiating

does

garbage

use

does

the

not

garbage

the

reduces

part
the

collection

garbage

invoke the

LISP

critical

¢to

redefining

collection.

©possibility

when

function

Therefore,

prevent

function

time-critical
way

wuse

collections.

garbage

program.
of

the

part

collector

Using
LISP
the

the

system

program

executing.

SeeVChapter 7 for a description of the garbage collector.
Format

Return Value
T,

when

garbage

collection

completed.

Example

Lisp>

(GC)

;

Starting

garbage

collection
due

function.

;

Finished

garbage

collection

function.

due

Invokes
when

the

garbage

*GC-VERBOSE*

collector.

<collection

Whether
occurs

variable.

the

messages

depends

the

are
value

printed
of

the

VAX LISP/VMS FUNCTION,

*GC-VERBOSE*
A variable

system

AND VARIABLE DESCRIPTIONS

Variable

whose

MACRO,

value

used

flag

display messages when

determine

garbage

the flag is NIL, the system displays messages.
NIL,
the
system
displays
a
message
before
collection
The

occurs.

messages

the

*PRE-GC-MESSAGE*
For

The

default

value

LISP

system displays

and

*POST-GC-MESSAGE*

information

garbage

the

LISP

occurs.

If
the
flag
and
after
a

are

whether

collection

1is
not
garbage

controlled

the

VAX

LISP

variables.

collector

messages,

see

Chapter

Example

Lisp>

*GC-VERBOSE*

Lisp>

;
;

(GC)

Starting
Finished

garbage
garbage

collection due
collection due

to GC
to GC

function.
function.

Lisp>

(SETF

*GC-VERBOSE*

NIL)

NIL

Lisp>

(GC)

The first evaluation of the *GC-VERBOSE* variable returns
the
default
wvalue
T,
which
1indicates that the LISP system will
display a message before and after a garbage collection occurs
(depending
on
the
values
o0f
the
*PRE-GC-MESSAGE*
and
*POST-GC-MESSAGE* variables).

The call to the GC function shows
system
displays
when
a
garbage
variable’s value

The

call

to the

the
default
messages
the
collection
occurs and the

1s T.

SETF macro

sets

the value of

the

wvariable

NIL.

The

second call

to the GC function shows that the

not display messages when

the variable’s value

system

is NIL.

does

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GENERALIZED-PRINT-FUNCTION-ENABLED-P Function
Used

globally

enable

generalized

ENABLED-P

generalized

function

predicate,

and

1is

enabled.

can

function

test

whether

GENERALIZED-PRINT-FUNCTION-

used

place

form

with

SETF.

See

Chapter

for

information

about

wusing

generalized

functions.
Format

GENERALIZED~PRINT-FUNCTION—ENABLED—P name
Argument
name

symbol

identifying

the

generalized

function

enabled

tested.

Return Value
T

NIL.

Example

Lisp>

(GENERALIZED-PRINT-FUNCTION-ENABLED-P

’'PRINT-NIL-AS-LIST)

NIL

Lisp>

(DEFINE-GENERALIZED-PRINT-FUNCTION

(OBJECT

PRINT-NIL-AS-LIST

STREAM)

(NULL OBJECT)
(PRINC

STREAM))

PRINT-NIL-AS-LIST

Lisp>

(SETF

(GENERALIZED PRINT-FUNCTION-ENABLED-P
"PRINT-NIL-AS-LIST)

T)
T

Lisp>

(PPRINT

NIL)

()
@

The

first

function
named

The

wuse

The

call

function

The
-

the
NIL,

been

generalized

function

SETF

function

defined.

defines

the

PRINT-NIL-AS-LIST.

globally

enables

the

generalized

because

the

generalized

PRINT-NIL-AS-LIST.

PPRINT

function

has

DEFINE-GENERALIZED-PRINT-FUNCTION

GENERALIZED-PRINT-FUNCTION-ENABLED-P
because

PRINT-NIL-AS-LIST

generalized

returns

call

prints

enabled

(

globally

and

pretty

printing

enabled.

VAX LISP/VMS

FUNCTION,

GET-DEVICE-INFORMATION
Returns

information

function

determine

This

function

information

Services
Part

the

type

similar

AND

VARIABLE

DESCRIPTIONS

Function

about

the

MACRO,

device.

of
the

and

keywords

information

S$GETDVI

Reference Manual

The

$GETDVI

system

the

VMS

VAX/VMS

system

device

&REST

I/0

specify

function

service,

the

you

the

User’s

the

returns.

service.

see

with

For

VAX/VMS

System

Reference Manual:

Format

GET-DEVICE-INFORMATION

{keyword}*

Arguments

device
The

string

that

names

the

device

about

which

information

returned.

keyword

Optional keywords that specify types
specified
Table

they

device.

lists

the

not

keywords

information

specify values
that

you

can

with

the

specify

about

the

keywords.
and

the

values

return.

Table 2:

GET-DEVICE-INFORMATION

Keyword

Keywords
Return

:ACP-PID

An
ACP

: ACP-TYPE

:BUFFER-SIZE

integer
process

integer

ACP

type

integer

buffer
:CLUSTER-SIZE

device.

specifies

the

1ID.

that

specifies the

that

specifies

the

that

specifies

the.

size.

cluster

integer

number

that

code.

integer

volume
:CYLINDERS

Value

size.

that

specifies

cylinders

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-DEVICE-INFORMATION Function (cont.)
(cont.)

Keyword

Return Value

+DEVICE-CHARACTERISTICS

vector

that

bits

specifies
the
device
characteristics.
See
the
VAX/VMS
I/0
User’s
Reference
Manual
for
information
about
device characteristics.

:DEVICE-CLASS

An integer

:DEVICE-DEPENDENT-0

:DEVICE-DEPENDENT-1

bit

:DEVICE-NAME

string

:DEVICE-TYPE

An integer

: ERROR-COUNT

An integer

: FREE-BLOCKS

An integer

: LOGICAL-VOLUME-NAME

: MAX-BLOCKS

An integer

that

:MAX-FILES

An integer

that

specifies

: MOUNT -COUNT

An integer

that

specifies

device

bit

that

class.

wvector

device-dependent

wvector

device-dependent

specifies

that

the

specifies

information.

that

specifies

information.

specifies

the

that

specifies

the

that

specifies

the

number
of
errors
that
occurred on the device.

has

specifies

the

device

number
device;

that

name.

type.

that

of
free
blocks
otherwise, NIL.

string

that

on the

specifies

the

specifies

the

logical name associated with the
This
device.
the
on
volume
keyword is valid only for disks.

maximum number of logical blocks
that can exist on the device.

number

times the device h

been mounted.

that can

maximum number of files
exist on the device.

the

Table

VAX LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

GET-DEVICE-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

:NEXT-DEVICE-NAME

string

the

that

specifies

volume

the

name

volume

set.

:OPERATION-COUNT

integer

number
been
An

:OWNER-UIC

performed

: RECORD-SIZE

that

record

integer

number

the
:ROOT-DEVICE~-NAME

of the

integer

: REFERENCE-COUNT

that

blocked

the

that

has

device.

specifies

the

specifies

the

owner.

integer

that

the

process

specifies

operations

integer

UIC
:PID

that

specifies

the

size.

that

owner.

specifies

channels

the

assigned

device.

string

the

that

root

specifies

volume

the

name

volume

set.

: SECTORS

integer

number
An

:SERIAL-NUMBER

that

that
tracks

integer

number

specifies
per

the

track.

specifies

the

specifies

the

number.

integer

number
: TRANSACTION-COUNT

that
sectors

integer

serial
: TRACKS

per

that

files

cylinder.

specifies
open

the

that

specifies

the

that

specifies

the

device.
An

:UNIT

integer

unit
An

: VOLUME-COUNT

number.

integer

number
set.

volumes

the

volume

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-DEVICE-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

: VOLUME -NAME

A string that specifies the name

: VOLUME-NUMBER

An integer

the volume

number

that
the

the

device.

specifies

the

bits

that

volume

the

device.

vector

: VOLUME-PROTECTION

specifies

the volume protection

mask.

Return Value

The keywords and their values are
the

following

returned as a property list

(:keyword-1 value-1

:keyword-2 value-2

The function preserves the order of the
the

argument

...)

keyword-value

pairs

1in

list.

If you do not specify keywords,
keyword-value pairs.
the
all
function

format:

returns

of
1list
a
the function returns
the
exist,
not
does
device
If the

NIL.

Example

Lisp>

(GET-DEVICE-INFORMATION "DBAL1"
:DEVICE-NAME
: ERROR-COUNT

: MOUNT-COUNT )

(:DEVICE-NAME "_DBAl:"

:ERROR-COUNT 0

Returns the device name,
the

device

:MOUNT-COUNT 1)

the error count, and the mount count for

DBAl.

VAX LISP/VMS FUNCTION,

GET-FILE-INFORMATION
Returns

the

information

function

The

keywords

Function

about

determine
correspond

attribute

block

Reference

Manual

file.

the

type

The

keywords

that

information

the

access

block

you

specify

function

RMS

file

fields.

See

the

VAX

Record Management

information

FAB

and

XAB

(XAB)

for

MACRO, AND VARIABLE DESCRIPTIONS

(FAB)

with

returns.

and

extended
Services

fields.

Format

GET-FILE-INFORMATION

pathname

&REST

{keyword}*

Arguments

pathname

A pathname,

namestring,

name

file

the

symbol,

stream

about

which

information

that

return

specific

that

represents

returned.

the

keyword

Optional

the
-

specified

Table

they

keywords

lists

file.
the

not

keywords

types

specify values
that

you

can

with

information

the

specify

about

keywords.

and

the

values

return.

Table 3:

GET-FILE-INFORMATION Keywords

Keyword

Return Value

:ALLOCATION-QUANTITY

integer

number

allocated
: BACKUP-DATE

The

last

file

has

:CREATION-DATE

The

the

and

time

file.
date

backed up.
been

returns

the

that

backed

1If

the

up,

the

NIL.

that

specifies

the

size.

was

the

date

and

time

the

created.

integer

number

was

was
not

universal

file
:DEFAULT-EXTENSION

for

integer

block

specifies

blocks

universal

the

function
:BLOCK-SIZE

that

specifies

blocks

that was

file’s

extended.

size when

the

added

file

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-FILE-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

:END-OF-FILE-BLOCK

An integer
that
specifies
the
ends.
file
the
block in which

:EXPIRATION-DATE

the
The universal date and time
If an expiration
expires.
file
the
recorded,
not
1s
date
function

returns

NIL.

: FIRST-FREE-BYTE

the
specifies
that
An integer
of the first byte in the
offset
file’s end-of-file block.

: FIXED-CONTROL-SIZE

An integer

: GROUP

An integer

fixed

owner

that

control

specifies

that

the

size.

area

specifies

the

group number.

the
specifies
that
An integer
in
record
longest
the
of
length

: LONGEST-RECORD-LENGTH

the

file.

that
An integer
a
size
maximum

: MAX-RECORD-SIZE

file

can

the
specifies
1in the
record

be.

that

specifies

the

: MEMBER

An integer

:ORGANIZATION

An integer

: PROTECTION

that
bits
16
of
vector
A
specifies the protection code.

: RECORD-ATTRIBUTES

An integer

: RECORD-FORMAT

An integer

: REVISION

An integer

:REVISION-DATE

The last universal date and time
the file was revised.

owner member number.

that

specifies

the

organization.

that

specifies

the

specifies

the

specifies

the

record attributes.

record

that

format.

that

revision number.

VAX

LISP/VMS

FUNCTION,

GET-FILE-INFORMATION
Table

Function

MACRO,

AND VARIABLE

(cont.)

Keyword

Return

:UIC

:VERSION-LIMIT

Value

integer

owner

that

integer

can

specifies

the

UIC.

maximum

Return

DESCRIPTIONS

that

version

specifies

number

the

file

have.

Value

The

keywords

the

following

and

their

(:keyword-1
The

the

function
a

list.

list

exist,

value-1

preserves

argument

returns

not

values

are

returned

property

list

pairs

format:

the

1If

all

:keyword-2

the

function

order

you

value-2

not

the

keyword-value

specify

keyword-value

returns

...)

keywords,

pairs.

the

function

file

does

the

file

NIL.

Examples

Lisp>

(GET-FILE-INFORMATION

"IMPORTANT.DA
c:ALLOCATION-QUANTITY

: BACKUP-DATE)
(:ALLOCATION-QUANTITY

Returns

the

252

allocation

:BACKUP-DATE

quantity

and

2654202351)

backup

date

for

IMPORTANT .DAT.

Lisp>

(DEFUN
(LET

SHOW-FILE-SIZE

(FILE)

((SIZE-LIST

(GET-FILE-INFORMATION

FILE
: ALLOCATION-QUANTITY
: END-OF-FILE-BLOCK)
))

Ead

S,
ey,
Ry

NAMESTRING

(TRUENAME

FILE))

GETF

SIZE-LIST

:ALLOCATION-QUANTITY)

GETF

SIZE-LIST

:END-OF-FILE-BLOCK))))

SHOW-FILE-SIZE

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-FILE-INFORMATION Function (cont.)
Lisp> (SHOW-FILE-SIZE "MYFILE.TXT")
DBAl:[SMITH]MYFILE.TXT; 4
Blocks allocated: 240
239
Blocks used:
NIL

The call to the DEFUN macro defines a function named
SHOW-FILE-SIZE, which displays the amount of space that is
allocated for a specified file and the amount of space the
file

uses.

The call to SHOW-FILE-SIZE displays the amount of space
that is allocated for the file MYFILE.TXT and the amount
of

space

the

file uses.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-GC-REAL-TIME Function
Lets you inspect the elapsed time used by the garbage collector during
program execution.
This function is useful for tuning programs.
The
function
measures
its
value
in
terms
of
the
INTERNAL-TIME-UNITS-PER-SECOND
constant.
This
wvalue 1s cumulative.
It includes the elapsed time used for all the garbage collections that
have
occurred.
A
description of the INTERNAL-TIME-UNITS-PER-SECOND
constant is provided in COMMON LISP:
The Language.

When a

suspended

For more

system is

information on the

resumed,
garbage

the

elapsed time

collector,

see

set

Chapter

Format
GET-GC-REAL-TIME

Return Value

The

real

time that has been used by the garbage

collector.

Examples
1.

Lisp>

(GET-GC-REAL-TIME)

3485700000
Lisp>

;
;

(GC)

Starting garbage collection due
Finished garbage collection due

to GC function.
to GC function.

Lisp>

(GET-GC-REAL-TIME)

401210000

The
the

first call to the
GET-GC-REAL-TIME
function
real time used by the garbage collector.

The call to the GC function invokes a garbage collection.

The second call to the GET-GC-REAL-TIME
function
returns
the
updated
real
time that has been used by the garbage
collector.

returns

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

GET-GC-REAL-TIME Function (cont.)
LiSp>

(DEFMACRO
NLET*

GC-ELAPSED-TIME
((START-GC

(VALUE

,FORM)

(END-GC

( FORMAT

(FORM)

(GET-GC-REAL-TIME)
)

(GET-GC~-REAL-TIME)))

*TRACE-QUTPUT*

%W@%x

elapsed

time:

seconds
%"

(TRUNCw»

GC-ELAPSED-TIME

"MYFILE.SUS"))

(SUSPEND

garbage

collection

due

function.

Wwe

(GC-ELAPSED-TIME

Starting
Finished

garbage

collection

due

function.

wWe

Lisp>

Starting

garbage

collection

due

SUSPEND

function.

Starting

garbage

collection

due

SUSPEND

function.

elapsed

time:

seconds

NIL

The

call

the

DEFMACRO
macro
defines
a
macro
named
which
evaluates a form and displays the
amount of elapsed
time
that
was
used
by
the
garbage
collector during a form’s evaluation.

GC-ELAPSED-TIME,

The call to

the

GC-ELAPSED-TIME

function

displays

amount of elapsed time the garbage collector used when
LISP system evaluated the form (SUSPEND "MYFILE.SUS").

the
the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-GC-RUN-TIME Function
Lets you inspect the CPU time used by
the
program execution.
This function is useful

garbage
<collector
during
for tuning programs.

The
function
measures
its
value
INTERNAL-TIME-UNITS-PER-SECOND
constant.
It includes the CPU time used for all
the

in
terms
of
the
This
wvalue is cumulative.
garbage
<collections
that

have
occurred.
A
description of the INTERNAL-TIME-UNITS-PER-SECOND
constant is provided in COMMON LISP:
The Language.

When a suspended system is resumed,
For more

the CPU time is set to 0.

information on the garbage collector,

see Chapter 7.

- Format

GET-GC-RUN-TIME

Return Value

The CPU time that has been used by the garbage collector.
Examples

Lisp>

(GET-GC-RUN-TIME)

6933
Lisp>

;
;

(GC)

Starting garbage collection due to GC function.
Finished garbage collection due to GC function.

Lisp>

(GET-GC-RUN-TIME)

8423

The first call to the GET-GC-RUN-TIME function returns the

The call to the GC function invokes a garbage collection.

returns
function
GET-GC-RUN-TIME
The second call to the
that has been used by the garbage
time
CPU
updated
the

CPU time used by the garbage collector.

collector.

VAX LISP/VMS

FUNCTION,

MACRO, AND VARIABLE

DESCRIPTIONS

GET-GC-RUN-TIME Function (cont.)
2.

Lisp>

(DEFMACRO
“(LET*

GC-CPU-TIME
((START-GC
(VALUE

(GET-GC-RUN-TIME))

, FORM)

(END-GC
( FORMAT

(FORM)

(GET-GC-RUN-TIME)))

*TRACE-QUTPUT*

""%GC

CPU

time:

seconds”
%"

(TRUNCATE

END-GC

START-GC)

INTERNAL-TIME-UNITS-PER-SECOND) })

GC-CPU-TIME

Lisp>

(GC-CPU-TIME

(SUSPEND

"MYFILE.SUS"))

;

Starting

garbage

collection due

function.

;

Finished

garbage

collection

due

function.

;

Starting

garbage

collection

due

SUSPEND

function.

;

Starting

garbage

collection due

SUSPEND

function.

CPU

time:

seconds

NIL

The call to the
DEFMACRO
macro
defines
a
macro
named
GC-CPU-TIME,
which
evaluates
a
form
and
displays the
amount of CPU time that was used by the garbage
collector
during

form’s

The

call

CPU

time

system

evaluation.

the

GC-CPU-TIME
the

evaluated

the

garbage

form

function

displays

collector

(SUSPEND

the

wused when

"MYFILE.SUS").

amount
the

LISP

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-INTERNAL-RUN-TIME Function

Returns an integer that represent$ the elapsed CPU time used for the
function wvalue 1is measured in terms of the
The
current process.
the
of
description
A
INTERNAL-TIME-UNITS-PER-SECOND constant.
LISP:
COMMON
in
provided
is
INTERNAL-TIME-UNITS-PER-SECOND constant
The

Language.

Format

GET-INTERNAL~-RUN-TIME

Return Value

The elapsed CPU time used for the current process.
Example

Lisp>

(DEFMACRO MY-TIME

“(LET*

(FORM)

((START-REAL-TIME (GET-INTERNAL-REAL-TIME))
( START-RUN-TIME (GET-INTERNAL-RUN-TIME))
(VALUE

, FORM)

( END-RUN-TIME (GET-INTERNZ
( END-REAL-TIME (GET-INTEE

( FORMAT

*TRACE-QUTPUT*

" sRun Time:

Real Time:

~ ,2F sec.,

~,2F sec. %"

(- END-RUN-TIME START-RUN-TIME)
INTERNAL-TIME-UNITS-PER-SECOND)
(/ (~ END-REAL-TIME START-REAL-TIME)
)
INTERNAL-TIME-UNITS-PER-SECOND)

)
VALUE)
MY-TIME

Defines a

macro

that

displays

evaluation of a specified form.

timing

information

about

the

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

GET-KEYBOARD-FUNCTION Function
Returns

information

about

the

function

that

bound

control

character.
Format

GET-KEYBOARD-FUNCTION

control-character

Argument

control-character
The

control

character

which

function

bound

bound.

Return Value

Three

values:

The

function

The

function’s

argument

The

function’s

interrupt

the

function

that

not

returns

bound

NIL

the

control

character.

list.

level.

for

the

all

specified

three

control

character,

values.

Examples
1.

Lisp>

(BIND-KEYBOARD-FUNCTION

#\"B

(GET-KEYBOARD-FUNCTION

#\"B)

Lisp>

#<Compiled
NIL

Function

BREAK

#x261510>

;

The

call

CTRL/B

The

call

Lisp>
NIL

;

NIL

;

the

BIND-KEYBOARD-FUNCTION

CTRL/B

NIL),

function

binds

function.

GET-KEYBOARD-FUNCTION

to which

(which

(which
2.

the
BREAK

function

list

to
the

and

the

bound,

the

function

returns

function’s

the

argument

interrupt

level

1).

(GET-KEYB OARD

#\*S)

NIL

All

three

bound

values
a

returned

are

function.

NIL,

because

CTRL/S

1is

not

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-PROCESS-INFORMATION Function

nonexistent,
1s
If the process
Returns information about a process.
The keywords you specify with the function
this function returns NIL.
determine the type of information the function returns.
For more
This function is similar to the $GETJPI VMS system service.
System
VAX/VMS
the
see
service,
system
SGETJPI
the
on
information
Services Reference Manual.
Format

GET-PROCESS-INFORMATION process &REST {keyword}*
Arguments
process

about which
The name or the identification of the process (PID)
a string, an
specify
can
You
returned.
to be
information 1is
is the
argument
the
1If you specify a string,
integer, or NIL.
PID.
the
is
process name; if you specify an integer, the argument
returns
function
information the
the
If you specify NIL,
corresponds

to the

current process.

keyword

Optional keywords that return specific types of information about
Do not specify values with the keywords.
the process.
and

Table 4 lists the keywords that you can specify
they

the

values

return.

Table 4:

GET-PROCESS-INFORMATION Keywords

Keyword

Return Value

: ACCOUNT

:ACTIVE-PAGE-TABLE-COUNT

An integer

:AST-ACTIVE

string

specifies

the

specifies

the

Dbits

that

system traps

(ASTs)

that

account.

that

table

active page

vector

the
specifies
that
modes
asynchronous
for

the

number of access
active
has

that

remaining AST

four

process.

An integer

: AST-COUNT

count.

specifies

quota.

the

VAX

LISP/VMS

FUNCTION,

GET-PROCESS-INFORMATION
Table

MACRO,

Function

AND VARIABLE

DESCRIPTIONS

(cont.)

Keyword

Return Value

:AST-ENABLED

vector

the

number

has

enabled

that

integer

AST

quota.

that

vector

specifies

access

ASTs

for

specifies

the

bits

that

the

privileges

authorized

integer

base

that

the

enable.

specifies

the

priority.

Either

:BATCH

that

process.

process
:BASE-PRIORITY

bits

specifies

:AUTHORIZED-PRIVILEGES

four

modes

the
cAST-QUOTA

returns

batch

NIL.

1if

job;

The
the

function

process

otherwise,

returns

NIL.

:BIO-BYTE-COUNT

integer

that

remaining
count

:BIO-BYTE-QUOTA

integer

I/0

the

Dbyte

quota.

buffered
:BIO-COUNT

specifies

buffered

that

I/0

integer

remaining

specifies

byte

count

that

the

guota.

specifies

buffered

I/0

the

operation

quota.

:BIO-OPERATIONS

integer

number

that

specifies

operations

the

buffered

I,/0

the

process

has

that

SPeCifies

the

performed.

An integer

:BIO-QUOTA

:CLI-TABLENAME

buffered

I/0

that

string

name

language

operation

current

interpreter

integer

CPU

time

that

limit

10-millisecond

specifies

the

quota.

the

file

command

table.

specifies
the

units.

process

the
1in

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

GET-PROCESS-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

:CPU-TIME

integer

that

accumulated
process
:CURRENT-PRIORITY

time

that

the

10-millisecond

integer

current

: CURRENT-PRIVILEGES

specifies

CPU

the

units.

specifies

the

bits

that

priority.

vector

specifies

the

current

privileges.
:DEFAULT-PAGE-FAULT-CLUSTER

integer

default
:DEFAULT~-PRIVILEGES

that

page

vector

specifies

fault

size.

bits

that

specifies

the

cluster

the

default

privileges.
:DIO-COUNT

integer

that

remaining

specifies

direct

I/0

the

operation

quota.
:DIO-OPERATIONS

integer

number

the
:DIO-QUOTA

: ENQUEUE-QUOTA

I/0

specifies

operation
that
lock

integer

vector

specifies

the

quota.

specifies

manager

that

manager

the

operations

performed.

that

I/O

integer

lock
: EVENT-FLAG-WAIT-MASK

has

integer

number

specifies

direct

process

direct
: ENQUEUE~-COUNT

that

the

engqueues.

specifies

enqueue

the

event

the

guota.
bits

that

flag wait

mask.
:FIRST-FREE-PO-PAGE

integer

first

the
:FIRST-FREE-P1-PAGE

program
1integer

first

the

free

control

that

specifies

page

the

end

the

region.
that

specifies

page

region.

the

end

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-PROCESS-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

: GLOBAL-PAGES

integer
number
of

working

that
specifies
global
pages in

the
the

set.

: GROUP

An integer
that
specifies
group field of the UIC.

the

: IMAGE -NAME

A
string
that
specifies
current image file name.

the
|

: IMAGE-PRIVILEGES

A
vector
of
64
bits
that
specifies
the
privileges
with
which the current image
of
the
process was installed.

: JOB-SUBPROCESS-COUNT

integer

number

that

specifies

: LOCAL-EVENT-FLAGS

A
vector
of
32
bits
the local event
specifies
the process has in effect.

: LOGIN-TIME

An integer
specifies
was

the

subprocesses.

that
flags

in internal time that
the
time the process
created.

: MEMBER

An integer
that
specifies
member field of the UIC.

the

: MOUNTED-VOLUMES

specifies
that
An integer
volumes.
mounted
of
number

the

:OPEN-FILE-COUNT

An integer

specifies

the

:OPEN-FILE-QUOTA

An integer

remaining

open

file

An integer

:OWNER-PID

process

that
open

file quota.

that

specifies

the

specifies

the

quota.

that

ID of

the

owner.

specifies
that
An integer
number of page faults.

: PAGE-FAULTS

the

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

GET-PROCESS-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

: PAGE-FILE-COUNT

integer

number

that

being used
An

: PAGE-FILE-QUOTA

:PAGES-AVAILABLE

that

virtual

available

for

expansion.

integer

that

the

that

specifies

the

process.

This

differs

:PID-OF-PARENT

that

top-level

: PROCESS-NAME

instant.

the

process

the

current

process

(Process

over

specifies

the
at

1index

reassigned

processes
that

that

wused

specifies
the

are

string

:SITE-SPECIFIC

that

given

while

bit-vector

number

the
flags
process.

integer

different

refers

process,

above

index

numbers

:OWNER-PID

subprocess.

32-bit

specifies
create the

from

refers

immediately
process

the

parent

:OWNER-PID

: PROCESS-INDEX

specifies

integer

the

the
pages

ID.

integer
of

the

specifies

: PROCESS-CREATION-FLAGS

specifies

quota.

integer

"PID

the
pages

process.

that

file

process

:PID-OF-PARENT

the

file

number

+PID

integer

paging

specifies

paging

time.)
the

name

specifies

the

process.

longword

contents

that

the

site-specific

longword.

: STATE

integer

that

specifies

the

bits

that

state.

ector
C

i
specifies

the

status

flags.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-PROCESS-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

: SUBPROCESS-COUNT

integer

number
the

: SUBPROCESS-QUOTA

: TERMINAL

specifies

integer

that

subprocess

quota.

string

the

that

specifies

terminal

the

name

with which

the

interacting.

integer

that

specifies

termination mailbox unit
:TIMER-QUEUE-COUNT

the

owned

process.

process
: TERMINATION-MAILBOX

that

subprocesses

integer

remaining

the

number.

that

specifies

timer

queue

the
entry

quota.

: TIMER-QUEUE-QUOTA

integer

timer

: UAF-FLAGS

queue

user who
An

specifies
quota.

12-bit

specifies

cUIC

that
entry

the

bit-vector

the
owns

integer

UAF
the

that

flags

the

process.
specifies

the

UIC.

s USERNAME

string

that

specifies

the user

name.

: VIRTUAL-ADDRESS-PEAK

integer

peak virtual
:WORKING-SET-AUTHORIZED-EXTENT

that

specifies

address

space

the

size.

integer
that
specifies
the
maximum
authorized
working set
extent.

: WORKING-SET-AUTHORIZED-QUOTA

integer

that

authorized working

An integer
number
of

: WORKING-SET-COUNT

working

set.

specifies

the

set quota.

that
specifies
the
process pages in the

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

GET-PROCESS-INFORMATION Function (cont.)
Table

(cont.)

Keyword

Return Value

: WORKING-SET-DEFAULT

integer

default

: WORKING-SET-EXTENT

integer

current

: WORKING-SET-PEAK

that

working

that

working

integer

peak

specifies
set

that

working

size

the

extent.

specifies

set

the

size.

the

size.

: WORKING-SET-QUOTA

An integer
that
specifies
current working set quota.

the

: WORKING-SET-SIZE

An integer
that
specifies
current working set size.

the

Return Value

The

keywords

following

and

their

values

(:keyword-1

value-1

The

function preserves

the

argument

not

keyword-value

the

:keyword-2

the

If you do
exist,

returned

value-2

...)

1list

1in

the

order

the

keyword-value

pairs

1in

1list

list.

all

the

are

format:

specify

function

keywords,

pairs.

returns

the

function

the

returns

specified process

does not

NIL.

Examples

Lisp>

(GET-PROCESS-INFORMATION

"SMITH"
:BATCH
:CPU-TIME

:BASE-PRIORITY
: GLOBAL-PAGES)

(¢:BATCH NIL

:CPU-TIME

: GLOBAL-PAGES

Returns

base

the

:BASE-PRIORITY 4

68)

value

priority,

process

45884

and

the

batch

setting,

the

CPU

time,

the

number of global pages used for the

SMITH.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-PROCESS-INFORMATION Function (cont.)
2.

Lisp>

(DEFUN
(LET

PARENT
((PID

NIL

(SECOND

(GET-PROCESS-INFORMATION
NIL

: OWNER-PID))))

(IF

(ZEROP

PID)

NIL

(ATTACH

PID))))

PARENT

system
LISP
Defines a function that just returns NIL if the
is running in the main process and attaches you to the parent
process if the system is running in a subprocess.

VAX LISP/VMS FUNCTION,

MACRO,

AND VARIABLE DESCRIPTIONS

GET-TERMINAL-MODES Function
Returns

information

associated

with

system.

the

LISP

system

function
This

function

the

signals

the

stream

error.

type

similar

terminal

*TERMINAL-IO*

specified

determine

information

about

the

SHOW

characteristics

variable

connected

The

keywords

you

DCL

SHOW

TERMINAL

the

you

not

information

the

when

TERMINAL

LISP
the

specify with

the

returns.

command.

see

device

the

terminal,

function

command,

the

invoke

the

For

VAX/VMS

DCL

Dictionary.
Format

GET-TERMINAL-MODES

&REST

{keyword}*

Argument

keyword

Optional
stream

keywords
that

1is

specify values
Table

they

lists

that

return

bound

with
the

the

the
the

terminal

characteristics

*TERMINAL-IO*

variable.

the

not

keywords.

keywords

that

you

can

specify

and

the

wvalues

return.

Table 5:

GET-TERMINAL-MODES Keywords

Keyword

Return Value

: BROADCAST

Either

or NIL.

returns

receive
as

1if

The

your

broadcast

MAIL

terminal

messages

notifications

messages;

function

otherwise,

and

can

such
REPLY

returns

NIL.

ECHO

Either

returns

displays
that

NIL.

The

function

the

terminal

the

returns

input

character

receives;

otherwise,

NIL.

returns

NIL,

displays

only data

the

system or

the
the

function
terminal

output

user

from

application

program.

Either

3v)
=i

)

returns
escape

NIL.

The

function

ANSI

standard

sequences

transmitted

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-TERMINAL-MODES Function (cont.)
Table

(cont.)

Keywérd

Return Value

from the terminal are handled as
multicharacter
single
a
terminator;

returns

otherwise,

The terminal driver checks
NIL.
escape sequences for syntax
the
the
to
passing them
before
more information
For
program.
the
see
sequences,
escape
on
Reference
User’s
I/0
VAX/VMS
Part

Manual:

function
The
Either T or NIL.
terminal’s
the
1if
T
returns
half-duplex,
is
operating mode

: HALF-DUPLEX

the function returns NIL if
and
is
mode
operating
the
For a description
full-duplex.
of terminal operating modes, see
the VAX/VMS I/0 User’s Reference
Part

Manual:

function
The
Either T or NIL.
returns T if the system does not
expand tab characters to blanks,
line
or
return
carriage
fill
recognize
characters,
feed
characters, and receive
control
The
messages.
broadcast
the
1if
NIL
returns
function
an
to
data
all
system passes
binary
as
program
application

: PASS-ALL

data.

compatibility

kept

the

for

sake

with Version 1 of VAX LISP, but

is not recommended that you use

:PASS-ALL.

FEither T or NIL.
same as the
the

: PASS-THROUGH

except

(CTRL/S,

has

=to

«-PASS-ALL

NOTE

that
b d 4 A b

1s
mode
This
:PASS-ALL mode,

"TTSYNC"
by P el B

CTRL/Q)

protocol
LR W AT

is still used.

VAX LISP/VMS

FUNCTION,

MACRO, AND VARIABLE

DESCRIPTIONS

GET-TERMINAL-MODES Function (cont.)
Table

(cont.)

Keyword

Return Value

: TYPE-AHEAD

Either

NIL.

The

function

the

terminal

that

returns

accepts
there

input
1s

and

the

terminal

function

and

accepts

program

typed when

outstanding
returns

driver
input

read,

NIL

1if

dedicated

only

when

issues

the

system

NIL.

The

function

the

terminal

read.

: WRAP

Either

returns

generates
a

line

the

when

reached.

function

carriage

feed

terminal-width

NIL.

and

end of

Otherwise,

returns

line

return
the

The

the
end

determined by the
setting.

Return Value

The keywords and their
following format:

(:keyword-1

values

value-1

The

function preserves

the

argument

returned

:keyword-2 value-2

...)

the

are

order

the

1list

keyword-value

1in

the

pairs

list.

If you do not specify keywords,
the
keyword-value
pairs.
The

that the list can be
SET-TERMINAL-MODES

the function returns
list is returned in a

specified as an argument

in a

a
1list
of
format such

call

the

function.

Example

Lisp>

SRS

S, S G

@ G G

T mm S

Sme

(GET-TERMINAL-MODES)

( :BROADCAST

:ECHO T

:ESCAPE

:TYPE-AHEAD

:WRAP

:PASS-THROUGH

NIL

:HALF-DUPLEX NIL
NIL)

Returns a list of all the keyword-value pairs.

:PASS-ALL NIL

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
GET-VMS-MESSAGE Function
Returns

the

system message associated with a

specified VMS

status.

Format

&OPTIONAL flags

GET-VMS-MESSAGE status
Arguments

status

A fixnum that specifies the VMS status code of the
message
that
is
to be returned.
See the VAX/VMS System Messages and Recovery
Procedures Reference Manual for information on VMS message status
codes.
flags

A bit vector of length four that specifies
the
content
of
the
message.
The
default value is #*0000, which indicates that the
process default message flags are to be
used.
The
information
that is included in the message when each of the four bits is set
follows:

Information

Bit
0

Text

Message

Severity

Facility

1ID

Return Value

Returns the message that corresponds to the,Specified status code
as

code

string.

The function returns NIL if you specify a status

that does not exist.

Examples

Lisp>

(GET-VMS-MESSAGE

"$SYSTEM-W-NOPRIV,

32)

no privilege for attempted operation”

Returns the VMS message text for message 32
set.

Lisp

(GET-VMS-MESSAGE

"$SYSTEM,

no privilege

flags

all

flags

#%*1001)

for attempted operation"

Returns the VMS message text for message
facility and text

with

set.

with

only

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

HASH-TABLE-REHASH-SIZE Function
Returns

how

the

much

rehash

hash

size

table

hash

table.

The

rehash

increase when

size

1indicates

specify
the
MAKE-HASH-TABLE
see COMMON LISP:
The

that value when you create
a
hash
table
with
function.
For
information
on
hash
tables,

full.

You

Language.

Format

HASH-TABLE-REHASH-SIZE hash-table
Argument

hash-table

The

name

the hash table whose

rehash size

to be

returned.

Return Value

An integer greater than 0 or a floating-point number greater than
1.
If an integer is returned, the value indicates the number of
entries that are to be added to the table.
If
a
floating-point
number is returned, the value indicates the ratio of the new size
to

the

old

size.

Example

Lisp)

(SETF

*PRINT-ARRAY*

NIL

NIL)
|

Lisp>

(SETF TABLE-1

(MAKE-HASH-TABLE

:TEST # 7" EQUAL
+:SIZE

200

- REHASH-SIZE

1.5

: REHASH-THRESHOLD

#<Hash Table #x503BAS8>

Lisp>

(HASH-TABLE-REHASH-S5IZE

.95))

TABLE-1)

1.5

The

first call

*PRINT-ARRAY*

the

variable

SETF

macro

sets

the

wvalue

the

to NIL.

The second call to the SETF macro sets
TABLE-1
to
the
hash
table created by the call to the MAKE-HASH-TABLE function.

The

call

rehash

to the HASH-TABLE-REHASH-SIZE

size

the

hash

table,

TABLE-1.

function

returns

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

HASH-TABLE—REHASH-THRESHOLD Function
Returns the rehash threshold for a hash table.
The
rehash
threshold
indicates
how
full
a
hash
table can get before its size has to be
increased.
You specify that value when you create a hash
table
with
the
MAKE-HASH-TABLE
function.
For
information on hash tables, see
COMMON LISP:

The Language.

Format

HASH-TABLE-REHASH-THRESHOLD hash-table
Argument

hash-table

The hash table whose

rehash threshold is to be

returned.

Return Value

An integer greater than 0 and less than hash table’s rehash
or a floating-point number greater than 0 and less than 1.

size

Example

Lisp>

(SETF

*PRINT-ARRAY*

NIL)

NIL

Lisp>

(SETF TABLE-1

(MAKE-HASH-TABLE

:TEST #'EQUAL
:SIZE 200
:REHASH-SIZE 1.5
: REHASH-THRESHOLD

.95))

#<Hash Table #x503BAS8>

Lisp>

{%ASEWTAELEwRE%ASHwTH?ESHQLD TABLE-1)

0.95

The first call to
*PRINT-ARRAY*

the

variable

SETF

macro

sets

the

wvalue

the

to NIL.

hash
the
to
The second call to the SETF macro sets TABLE-1
function.
MAKE-HASH-TABLE
the
to
call
the
by
table created

function
The call to the HASH-TABLE-REHASH-THRESHOLD
the rehash threshold of the hash table, TABLE-1.

returns

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

HASH-TABLE-SIZE Function
Returns the current size of-a hash table.
You specify that value when
you
create
a
hash
table
with
the
MAKE-HASH-TABLE function.
For
information on hash tables, see COMMON LISP:
The Language.
Format

HASH-TABLE-SIZE

hash-table

Argument

hash-table

The hash table whose

initial

size

to be

returned.

Return Value

An integer that indicates the initial

size of the hash table.

Example

Lisp>

(SETF

*PRINT-ARRAY*

NIL

Lisp>

(SETF TABLE-1

NIL)

(MAKE-HASH-TABLE

:TEST

#’EQUAL

:SIZE

200

: REHASH-SIZE

1.5

:REHASH-THRESHOLD
Lisp>

.95))

#<Hash Table #x503BAS8>

(HASH-TABLE-SIZE TABLE-1)

233

The first call to
*PRINT-ARRAY*

the

variable

SETF

macro

sets

the

wvalue

the

to NIL.

hash
the
to
TABLE-1
The second call to the SETF macro sets
table created by the call to the MAKE-HASH-TABLE function.
”

The call to the HASH-TABLE-SIZE function returns
size

the

hash

table,

TABLE-1.

the

initial

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

HASH-TABLE-TEST Function
Returns

value

compared.

The

the

MAKE-HASH-TABLE

COMMON

LISP:

symbol

value

The

that

indicates

specified

function.

For

when

how

you

hash

table’s

create

hash

information

hash

keys

are

table

with

tables,

see

Language.

Format

HASH-TABLE-TEST

hash-table

Argument

hash-table
The

hash

table

whose

test

value

1is

returned.

#'EQL,

#'EQUAL)

Return Value

Either

function

EQUAL).

EQL

(#’EQ,

the

default when

creating

symbol

hash

(EQ,

EQL,

table.

Example

Lisp>

(SETF

*PRINT-ARRAY*

(SETF

TABLE-1

NIL)

NIL

Lisp>

(MAKE-HASH-TABLE

:TEST

#'EQUAL

:SIZE

200

:REHASH-SIZE

1.5

: REHASH-THRESHOLD

#<Hash Table
Lisp>

#x503BAS8>

(HASH-TABLE-TEST

.95))

TAB LE-1)

EQUAL

The

first

call

*PRINT-ARRAY*

the

variable

SETF
to

macro

sets

the

wvalue

the

NIL.

The second call to the SETF macro sets
TABLE-1
table created by the call to the MAKE-HASH-TABLE

to
the
hash
function.

The
the

the

call
hash

to the
table,

HASH-TABLE-TEST
TABLE-1.

function

returns

test

for

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

LOAD Function
Reads

and

In VAX
file

evaluates

LISP,

type,

the

contents

specified

LOAD

file

function

file

into

name

does

locates

the

not

LISP

specify

source

file

environment.

an
(type

explicit
LSP)

fast-loading file (type FAS) with the latest file write date and loads
it.
This
ensures
that
the
latest
version of the file is loaded,
whether

not

the

file

compiled.

Format

LOAD

filename
&KEY

::IF-DOES-NOT-EXIST

:PRINT

:VERBOSE

Arguments

filename

The

name

the

file

loaded.

:IF-DOES-NOT-EXIST

Specifies whether the LOAD function signals an error if the
file
does
not
exist.
The value can be T or NIL.
If you specify T,
the function signals an error if the file does not exist.
1If you
specify NIL, the function returns NIL if the file does not exist.
The

default

value

1is

: PRINT

Specifies whether the value
of
each
form
that
1is
loaded
1is
printed
to
the
stream bound to the *STANDARD-OUTPUT* variable.
The value can be T or NIL.
If you specify T, the value
of
each
form
in
the file is printed to the stream.
If you specify NIL,
no action is taken.
The default value is NIL.
This
keyword
1s
useful

for

debugging.

: VERBOSE

Specifies whether the LOAD function is to print a message in
form

comment

the

stream bound to the

the

*STANDARD-OUTPUT*

variable.
The value can be T or NIL.
If
you
specify
T,
the
function prints a message.
The message includes information such
as the name of the file that is being
loaded.
If
vyou
specify
NIL, the function uses the value of *LOAD-VERBOSE* variable.
The
default

1is

Return Value

A value other than NIL if the load operation is successful.

VAX LISP/VMS FUNCTION,

LOAD

MACRO, AND VARIABLE

DESCRIPTIONS

Function (cont.)

Example

Lisp>

(COMPILE-FILE

"FACTORIAL")

Starting

compilation

FACTORIAL

compiled.

Finished

compilation

Errors,

file

DBAl:[SMITH]FACTORIAL.LSP;1

file

DBAl:[SMITH]FACTORIAL.LSP;1

Warnings

"DBAl1:[SMITH]FACTORIAL.FAS;1"

H e

Lisp>

(LOAD

"FACTORIAL")

contents

file

DBAl1:[SMITH]FACTORIAL.FAS;1

FACTORIAL

Finished

DBAl:[SMITH]FACTORIAL.FAS;1

The call to the COMPILE-FILE
file named FACTORIAL.FAS.

The call to the LOAD function locates
FACTORIAL.FAS and loads the file into

function

produces

the
the

fast-loading

fast-loading
f£file
environment.

LISP

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
LONG-SITE-NAME

Function

Translates

1logical

the

character

string
its

assumed

content

location

running.

the

the
1is

the

first

itself

LISPSLONG_SITE_NAME.

string

file

returned
computer

the

translation

name

resulting

sign

specification.

string

hardware

character

that

on which
of

returned

the

(@),

The

the
rest

file

1is

represents
VAX

translation

the

If
the

long-site

not

the

read

the

LISP

first
of

and

physical

system
an

1is

sign,

name

name.

Format
LONG-SITE-NAME

Return Value

The

contents

file

the

translation

the

1logical

that

represents

the

the VAX

LISP

1is

returned as

physical

the

computer hardware

system

location

running.

long-site

returned.
Example

Lisp>

(LONG-SITE-NAME)

"Smith’s

Computer

Artificial

Plum

Company

Intelligence

Group

Road

Canterbury,

Ohio

47190"

string

LISPSLONG_SITE_NAME

name

on which

is not defined,

NIL

1is

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

MACHINE-INSTANCE
Translates

the

Function

logical

name

LISPSMACHINE_INSTANCE.

Format

MACHINE-INSTANCE

Return

Value

The

translation

returned as
DECnet-VAX is
name

1is

not

the

1logical

a
string.
running, the
defined

and

DECnet-VAX

returned.
Example

Lisp>

name

LISPSMACHINE_INSTANCE

1f the logical name is
node name is returned.

(MACHINE-INSTANCE)

"MIAMI"

1is

not

1is

not defined and
1If the logical
running,

NIL

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
MACHINE-VERSION Function

a
as
Returns the content of the system identification (SID) register
the
which
on
hardware
computer
of
version
the
represents
string that
The contents of the SID are determined by
VAX LISPsystem is running.
For more
or 730.
750,
780,
for example,
-of CPU
type
the
Handbook.
information about CPU types, see the VAX Architecture
Format

MACHINE-VERSION

Return Value

The contents of the SID register are returned as a string.
Example

Lisp>

(MACHINE-VERSION)

"SID Register:

#x01383550"

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
MAKE-ARRAY Function

:ALLOCATION
the
added
has
LISP
VAX
Creates and returns an array.
keyword
to this COMMON LISP function.
When the function is used with
the :ALLOCATION keyword and the value :STATIC, the function creates
a
statically allocated

array.

During system usage,

the garbage collector moves
LISP
objects.
You
allocating
by
object
an
moving
from
collector
garbage
the
prevent
can
it in static space.
Arrays, vectors, and strings
can
be
statically
wuse the :ALLOCATION keyword and :STATIC value in a
you
if
allocated
call to
the
MAKE-ARRAY
function.
Once
an
object
1is
statically
Note that such
change.
not
does
address
virtual
its
allocated,
be
cannot
space
their
and
collected
garbage
never
ar
objects
reclaimed.
By default, LISP objects are allocated in dynamic space.

NOTE

A statically allocated

even

address

object

maintains

SUSPEND/RESUME

1ts

memory

operation

performed.

: STATIC
+:ALLOCATION
the
with
function
MAKE-ARRAY
the
Calling
keyword-value
pair
is
wuseful
if
you
are
creating a large array.
Preventing the garbage collector from moving
the
array
causes
the
garbage

collector

faster.

can be
that
keywords
The MAKE-ARRAY function has a number of other
The Language for information on the other
COMMON LISP:
See
used.
MAKE-ARRAY

keywords.

VAX LISP creates a specialized array when the array’s element type
1s
BYTE
(UNSIGNED
or
FLOAT
of
subtype
a
or
32),
(SIGNED-BYTE
STRING-CHAR,
a generalized
creates
For all other element types, VAX LISP
1-29).
types with
VAX
of
compatibility
For
the element type T.
with
array,
on data
tables
the
see
LISP types when calling external routines,
the call-out chapter of the VAX LISP/VMS System Access
in
conversion
Programming Guide.
Format

MAKE-ARRAY dimensions

&KEY

:ALLOCATION other-keywords

Arguments

dimensions

A list of positive integers that are to be the dimensions of
array.

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

MAKE-ARRAY Function (cont.)
: ALLOCATION

‘Specifies whether the LISP object is to be statically
You
can specify one of the following values with the

allocated.
:ALLOCATION

keyword:

: DYNAMIC

The

LISP object

allocated.

: STATIC

The

LISP

is not

This value

object

1is

to be

statically

the

default.

statically

allocated.
other-keywords

See

COMMON LISP:

The Language.

Return Value

The

statically allocated object.

Example

Lisp>

(DEFPARAMETER

(MAKE-ARRAY

BIT-BUFFER

’ (1000

1000)

:ELEMENT-TYPE
:ALLOCATION

'BIT

:STATIC))

BIT-BUFFER

Creates a large array of bits
named
intended
to
be
removed
from
the
keyword is one of the other keywords
The Language)

that

this

BIT-BUFFER,
which
1s
not
system.
The :ELEMENT-TYPE
(described in
COMMON
LISP:

function accepts.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*MODULE-DIRECTORY*

Variable

A variable whose value refers to the directory containing
that
1is
being
1loaded into the LISP environment due to a
REQUIRE

function.

The value

the
module
call to the

pathname.

This variable is useful to determine
the
location
of
a
module
1if
additional files from the same directory must be loaded by the module.
For
example,
consider
the
following
contents
of
a
file
called
REQUIREDFILE1.LSP:

(PROVIDE

(LOAD
(DEFUN

"REQUIREDFILE1")

(MERGE-PATHNAMES

"REQUIREDFILE2"

*MODULE-DIRECTORY*))

TEST

When you specify the preceding module with the REQUIRE
function,
do
not have to identify the module’s directory if it is in one of
places the REQUIRE function
searches
(see
the
description
of
REQUIRE
function
later
in
Part
1II).
Furthermore,
wusing

*MODULE-DIRECTORY* variable as in this example ensures that

the

you
the
the
the

file

REQUIREDFILE2
will
be
1loaded
from
the
same directory.
After the
module is loaded, the *MODULE-DIRECTORY* variable is rebound to NIL.

NOTE
As this variable is bound during calls to the
REQUIRE
function, nested calls to the function cause its value
to be updated appropriately.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*POST-GC-MESSAGETM* Variable
Controls
the
message
the
LISP
system
displays
after
a
garbage
collection occurs.
The value of this variable can be NIL, a string of
message text, or the null string ("").
If
the
wvalue
1s
NIL,
the
system
displays
a
system
message.
If
the value is a string, the
system displays the string.
If
the
wvariable’s
wvalue
1s
the
null
string (""), the system displays no output.
The default value is NIL.
The

system messages appear

;

in the

following

Finished garbage collection due

form:

to GC function.

System
messages
differ
according
to
the
cause
of
the
garbage
collection.
If
you
set the *POST-GC-MESSAGE* variable, the message
you establish supersedes all system messages displayed after a garbage
collection,

regardless of

cause.

Example
Lisp>

;
;

(GC)

Starting garbage collection due
Finished garbage collection due

to GC function.
to GC function.

Lisp>
1

(SETF

*POST-GC-MESSAGE*

"")

Lisp>

;

(GC)

Starting garbage collection due to GC function.

Lisp>
"GC

Lisp>

;
GC

(SETF *POST-GC-MESSAGE*

"GC

finished")

finished"
(GC)

Starting garbage collection due to GC function.
--

finished

The first call to the GC function shows the garbage collection
messages the LISP system displays by default.

The first call to

The second call to the GC function shows that the system does
not
display
a
message when a garbage collection is finished

the

SETF

*POST-GC-MESSAGE* variable

when the variable’s value

The second call to the

variable to the

SETF

string "GC

macro

sets

to the null

the null

macro

the

string

wvalue

("").

the

string.

sets

finished".

the

wvalue

the

The third call to
the
GC
function
shows
that
the
system
displays the new message when a garbage collection is finished
if the variable’s value

is a

string.

VAX LISP/VMS FUNCTION,

PPRINT-DEFINITION
Pretty prints

MACRO, AND VARIABLE DESCRIPTIONS

Function
a

stream

the

function definition

symbol.

Format

PPRINT-DEFINITION

symbol

&OPTIONAL

stream

Arguments

symbol ‘
The

symbol

whose

function value

stream

to which

pretty-printed.

stream

The

default

stream

the

<code

the

stream

1is

bound

pretty-printed.

the

The

*STANDARD-OUTPUT*

variable.
Return Value

value.

Examples

Lisp>

(DEFUN

"Returns

(COND

the

((<= N

FACTORIAL

(N)

factorial

integer.”

(FACTORIAL

1))))))

FACTORIAL

Lisp>

(PPRINT-DEFINITION

(DEFUN

FACTORIAL

"Returns

(COND

The

the

((<= N

call

factorial

to the DEFUN

FACTORIAL,

which

call

the

function value

integer.”

(FACTORIAL

macro
the

(DEFUN

(NAME

AGE

the

1))))))

defines

function

factorial

to the PPRINT-DEFINITION

Lisp>

symbol

function

(SYMBOLP

(ERROR

"7
S must be
NAME

pretty-prints

FACTORIAL.

MARRIED?)

NAME)

'AGE)

symbol."

NAME))

AGE

(GET

NAME

'NUMBER-OF-SIBLINGS)

(GET

NAME

'IS-THIS-PERSON-MARRIED?)

RECORD-MY~-STATISTICS

SIBLINGS
MARRIED?)

called

integer.

RECORD-MY-STATISTICS

SIBLINGS

(UNLESS

(GET

returns

The

(SETF

'FACTORIAL)

(N)

NAME)

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
PPRINT-DEFINITION
Lisp>

Function (cont.)

(PPRINT-DEFINITION

(DEFUN

(UNLESS

(SYMBOLP

(ERROR
(SETF

"RECORD-MY-STATISTICS)

RECORD-MY-STATISTICS

(NAME AGE

SIBLINGS

MARRIED?)

NAME)

"7
S must
'AGE)

symbol."

NAME))

(GET

NAME

AGE

(GET

NAME

’'NUMBER-OF-SIBLINGS)

(GET

NAME

’'IS-THIS-PERSON-MARRIED?)

SIBLINGS
MARRIED?)

)
NAME

The

call

the

DEFUN

macro

defines

function

called

RECORD-MY-STATISTICS.

The

call

the

function value

to the PPRINT-DEFINITION
of

the

symbol

function

pretty-prints

RECORD-MY-STATISTICS.

VAX LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

PPRINT-PLIST Function
Pretty-prints

list

1is

value
list

or
in

their

list
an

stream

expression.

a way

the

property

symbol-value

that

The

pairs;

list

each

PPRINT-PLIST

emphasizes

the

symbol.

symbol

function

relationship

property

associated with

prints

between

the

property

symbols

and

values.

PPRINT-PLIST

accessible

prints

COMMON LISP:

all

the

even

those

The

only

not

The

the

current

following

pairs

accessible
'ME)

symbol-value

package.

Language.)

symbol-value

(PPRINT-PLIST

"ME).

the

not

the

other

entire

the

current

shows

hand,

which

symbol

1is

packages,

see

SYMBOL-PLIST

property

the

for

information

(the

equivalent

example

pairs

(For

list)

package.
form

So,

returns

symbol,

the

form

(PPRINT (SYMBOL-PLIST

differences

between

the

two

forms:
Lisp>

(MAKE-PACKAGE

Lisp>

(SETF

'PLANET)

(SYMBOL-PLIST

' (GIRL

'ME)

"SAMANTHA"

BOY

"DANIEL"

PLANET:
: INHABITANT-OF

(GIRL

"SAMANTHA"

Lisp>

(PPRINT

(GIRL

"SAMANTHA"

Lisp>

(PPRINT-PLIST

(GIRL
BOY

The

form

BOY

(SYMBOL-PLIST

BOY

package
be

The

not

"EARTH")

’'ME))

"DANIEL"

PLANET::INHABITANT-OF

"EARTH")

'ME)

"SAMANTHA"

(PPRINT

(SYMBOL-PLIST

that

pair.

PLANET

This

not

package

but

the

prints

but

because

accessible

symbol

'ME))

"EARTH",

another

symbol-value
PPRINT-PLIST
1s

"EARTH"))

PLANET::INHABITANT-OF

"DANIEL")

PLANET:
: INHABITANT-OF
not

"DANIEL"

still

form

the

symbol

the

package

symbol-value

(PPRINT-PLIST

current

accessible

current

the

in
1s

INHABITANT-OF

package
the

current

associated

symbol

pair
does
the

can

package).
with

the

pair INHABITANT-OF "EARTH" in the PLANET package, but the
function does not print that symbol-value pair because it

accessible

the

current

package.

Format

PPRINT-PLIST

symbol

&OPTIONAL

stream

Arguments

symbol

The

’'ME)

symbol

whose

property

list

to be

pretty-printed.

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

PPRINT-PLIST Function (cont.)
stream

The

stream

default

to which

the

stream

1is

(SETF

(GET

pretty-printed

the

stream

output

bound

the

sent.

The

*STANDARD-QUTPUT*

variable.
Return Value

value.

Examples

Lisp>
(DANNY

Lisp>

’CHILDREN

’'SONS)

’(DANNY

’CHILDR EN

’DAUGHTERS)

GEOFFREY))

GEOFFREY)

(SETF

(GET

'SAMANTHA)

SAMANTHA

Lisp>

(PPRINT-PLIST

(DAUGHTERS

SONS

’'CHILDREN)

SAMANTHA

(DANNY

GEOFFREY))

The calls to the
properties
SONS
symbol
is

SETF macro give
and DAUGHTERS.

CHILDREN has

SAMANTHA

and

the symbol
CHILDREN
The property list of

two properties:
SONS

whose

DAUGHTERS

wvalue

the

the
the

whose

value

list

(DANNY

GEOFFREY)
.

The

call

property

output
and
2.

Lisp>

its

the

1list

PPRINT-PLIST

function
CHILDREN.

pretty-prints

the

symbol

The

emphasizes

the

relationship between

each

(DEFUN

RECORD-MY-STATISTICS
(SYMBOLP

(ERROR
(SETF

(NAME AGE

SIBLINGS

"7
S must

symbol."

NAME))

( GET

NAME

’'AGE)

(GET

NAME

’'NUMBER-OF-SIBLINGS)

| GET

NAME

’'IS-THIS-PERSON-MARRIED?)

AGE
SIBLINGS
MARRIED)

NAME)

(DEFUN

SHOW-MY-STATISTICS

(UNLESS

(SYMBOLP

(NAME)

NAME)

""S

must be

(PPRINT-PLIST

symbol."

NAME))

SHOW-MY-STATISTICS

(RECORD-MY-STATISTICS

’‘TOM

TOM

Lisp>

(SHOW-MY-STATISTICS

(IS-THIS-PERSON-MARRIED?

NUMBER-OF-SIBLINGS
AGE

MARRIED?)

NAME)

RECORD-MY-STATISTICS

Lisp>

property

value.

(UNLESS

Lisp>

the

pretty-printed

'"TOM)
NIL

29)

NIL)

NAME))

VAX

LISP/VMS

FUNCTION,

PPRINT-PLIST Function
The

MACRO,

AND

VARIABLE

DESCRIPTIONS

(cont.)

first

call

the

DEFUN

macro

defines

function

named

RECORD-MY-STATISTICS.

The

second

call

the

DEFUN

named

SHOW-MY-STATISTICS.

PPRINT-PLIST

The

the

call

properties

the
for

The

call

the

property

the

macro

The

symbol

function

call

for

the

function

inputs

the

TOM.

SHOW-MY-STATISTICS

list

includes

function.

RECORD-MY-STATISTICS
the

defines

definition

symbol

function

TOM.

pretty-prints

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*PRE-GC-MESSAGETM*

Variable

Controls
the
message
the
LISP
system
displays
when
a
garbage
collection starts.
The value of this variable can be NIL, a string of
message text, or the null string ("").
If
the
wvalue
1s
NIL,
the
system displays a system message.
If the value is a string of message
text, the system displays the message text.
If the
wvariable’s
wvalue
is
the null string, the system displays no output.
The default value
1is

NIL.

System messages

;

appear

in the

Starting garbage

following

collection due

form:

to GC

function.

VAX LISP messages preceding garbage collection differ depending on the
cause
of
the
garbage
collection.
If you set the *PRE-GC-MESSAGE*
variable, the message you establish supersedes
all
system
messages,
regardless

cause.

Example
Lisp>

;
;

(GC)

Starting garbage
Finished garbage

collection due
collection due

to GC
to GC

function.
function.

to GC

function.

Lisp>

(SETF

*PRE-GC-MESSAGE*

"")

B0 00

Lisp>

;

(GC)

Finished garbage

collection due

Lisp> (SETF *PRE-GC-MESSAGE*
"GC -- started"
Lisp>

(GC)

started

;

Finished garbage

"GC

collection due

started")

to GC

function.

The first call to the GC function shows the garbage collection
messages

that

are printed by default.

The first call to
the
SETF
macro
sets
the
wvalue
*PRE-GC-MESSAGE* variable to the null string ("").

the

The second call to the GC function causes the
system
display a message when the garbage collection starts.

not

The second call to the

SETF

macro

the

variable to the

"GC

started".

string

sets

the

wvalue

The third call to the GC function causes the system to display
the new message

text when the garbage

collection starts.

VAX LISP/VMS FUNCTION,

*PRINT-LINES*

Variable

Specifies

number

block.

the
The

default

abbreviation.
enabled.

When

for

the

specified

four

characters

The

WRITE

and

system
on

the

:LINES

*PRINT-LINES*

produced.

Chapter

bound

for

printed

wvariable

effective

limits
line

the

you

outermost

NIL,

which

only when
to

specifies

1is

the

have

vyou

with
been

number

information

lines

replacing

extended

the

wusing

the

...".

specify

supply with

1logical

pretty printing

abbreviation

value

printed

functions

keyword.

output

indicates

last

WRITE-TO-STRING

any

See

this

*PRINT-LINES*,

accept
output

lines

*PRINT-LINES*

last

MACRO, AND VARIABLE DESCRIPTIONS

the

in VAX

this

LISP

keyword,

keyword

before

*PRINT-LINES*

variable.
Example

Lisp>

(SETF

*PRINT-LINES*

Lisp>

(FORMAT

"Stars:
RA

MIRZAM

POLLUX

CANOPUS

"~ :!7 /JLINEAR/
."

MIRFAK

BELLATRIX

ALBIREO

CASTOR

CAPELLA

ALPHECCA

ANTARES)
)

Stars:

POLARIS
DUBHE

MIRA
MI

With

*PRINT-LINES*

fourth

The

last

MIRFAK

set

printing

stops at the

end of

the

line.

four

becomes

characters of
MI.

the

last

1line

are

not

printed.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*PRINT-MISER-WIDTH* Variable
Controls miser mode printing.
If the available line width between the
indentation
of
the
current logical block and the end of the line 1is
less than the value of this variable, the pretty printer enables miser
mode .
When
output
is
printed
1in miser mode, all indentations are
ignored.
1In addition, a new line is started for every conditional new
line
directive
(",
T,
“e_).
The
default
value
for
*PRINT-MISER-WIDTH*

You

can

prevent

1is

the

*PRINT-MISER-WIDTH*

40.

use

variable

miser

mode

setting

the

to NIL.

The WRITE and WRITE-TO-STRING functions have been extended in VAX LISP
to
accept
the
:MISER-WIDTH
keyword.
I1f you specify this keyword,
*PRINT-MISER-WIDTH* is bound to the value you supply with the
keyword
before

any output

is produced.

For
more
information
about
miser
mode
and
the
*PRINT-MISER-WIDTH* variable, see Sections 6.5 and 6.8.

use

the

Example

Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

(SETF

*PRINT-MISER-WIDTH*

60)

Lisp>

35)

Lisp>

(FORMAT T

""!Stars with Arabic names:
@(e 5 - me ”
"
A
N
7s T":17@_"S T_"S B
Y2717:

' (BETELGEUSE (DENEB SIRIUS VEGA)
ALDEBERAN ALGOL (CASTOR POLLUX)
Stars with Arabic names: BETELGEUSE
(DENEB

SIRIUS

BELLATRIX))

VEGA)

ALDEBERAN

ALGOL

(CASTOR

POLLUX)

BELLATRIX

1logical
outer
the
in
The text, "Stars with Arabic names:",
inner logical block to begin at column 26.
the
causes
block
mode
With *PRINT-MISER-WIDTH* set to 35, FORMAT enables miser
when the logical block begins past column 25.

starting
by
space
FORMAT conserves
multiline mode new line directive (" _)
line directive

every
at
new line
a
and every if-needed new

(" :_).

FORMAT starts a new line at the miser mode new line

(“@_) and ignores the indentation directives (" nI).

directive

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*PRINT-RIGHT-MARGIN*

Variable

Specifies the
this
margin

right margin for pretty
printing.
Output
may
exceed
if
vyou
print
1long symbol names or strings, or if your
FORMAT control string specifies no new line directives
of
any
type.
If the value of *PRINT-RIGHT-MARGIN* is NIL, the print function uses a
value appropriate to the output device.
The WRITE and WRITE-TO-STRING functions have been extended in VAX LISP
to
accept
the
:RIGHT-MARGIN
keyword.
If you specify this keyword,
*PRINT-RIGHT-MARGIN* is bound to the value you supply with the keyword
before any output is produced.

See

Chapter

for

*PRINT-RIGHT-MARGIN*

information

about

using

the

variable.

Example

Lisp>

(DEFUN

(NAME

AGE

(ERROR

"7
S must

symbol."

’'AGE)

NAME

(GET

MARRIED?)

NAME)

(SYMBOLP

(UNLESS

(SETF

RECORD-MY-STATISTICS

SIBLINGS

NAME))

AGE

(GET

NAME

'NUMBER-OF-SIBLINGS)

(GET

NAME

"IS-THIS-PERSON-MARRIED?)

SIBLINGS

MARRIED)

)
NAME

RECORD-MY-STATISTICS

Lisp>

(SETF

*PRINT-RIGHT-MARGIN*

40)

Lisp>

(PPRINT-DEFINITION

"RECORD-MY-STATISTICS)

(DEFUN

RECORD-MY-STATISTICS

(NAME

AGE

SIBLINGS

MARRIED?)

(UNLESS

(SYMBOLP

NAME)

(ERROR

"S must

symbol."

)
NAME)

(SETF

AGE

(GET

NAME

'AGE)

(GET

NAME

'NUMBER-OF-SIBLINGS)

SIBLINGS

(GET
NAME

"IS-THIS-PERSON-MARRIED?)
MARRIED)

)
NAME

The

call

the

DEFUN

macro

RECORD-MY-STATISTICS.

defines

function

named

VAX LISP/VMS FUNCTION,

*PRINT-RIGHT-MARGIN*

MACRO, AND VARIABLE DESCRIPTIONS

Variable (cont.)

The
call
to
the
SETF
macro
*PRINT-RIGHT-MARGIN* variable to

The
<call
to
the
PPRINT
function
shows
the
effect
the
variable’s
value
has
on
the
pretty-printed
output.
PPRINT-DEFINITION stops printing
each
1line
Dbefore
reaching
column

40.

sets
40.

the

value

the

VAX LISF5/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
PRINT-SIGNALED-ERROR Function
Used

message

the

the VAX LISP
error
handler
when an error is signaled.

stream bound

formats

are

the

described

*ERROR-OUTPUT*

Chapter

You

can include a call to
create (see Chapter 4).

this

display

The

formatted
error
all output to

function prints

variable.

The

error

message

function

error

handler

that

vyou

Format

PRINT-SIGNALED-ERROR function-name

error-signaling-function

&REST args

Arguments

function-name

The

name

the

error-signaling

function

that

1is

call

the

specified

function.

error-signaling-function

The

name

are

ERROR,

an error-signaling

The

specified

CERROR,

function.

Valid

function

function’s

arguments.

names

and WARN.

args

error-signaling

Return Value

Undefined.
Example

CONTINUING-ERRO R-HANDLER

(FUNCTION-NAME
ERROR-SIGNALING-FUNCTION

&REST

ERROR-SIGNALING-FUNCTION

m@%

(DEFUN

ARGS)

'CERROR)

OGN

—~

Lisp>

APPLY

#’'PRINT-SIGNALED-ERROR
FUNCTION-NAME

ERROR-SIGNALING-FUNCTION
ARGS)

(FORMAT

*ERROR-OUTPUT
*

"“&It will
NIL)

100

continued automatically.”
2%.")

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
PRINT-SIGNALED-ERROR Function (cont.)
(APPLY

#'UNIVERSAL-ERROR-HANDLER
FUNCTION-NAME

ERROR-SIGNALING-FUNCTION
ARGS) ) )

CONTINUING-ERROR-HANDLER

a
from
continues
automatically
that
Defines an error handler
other
All
message.
after displaying an error
error
continuable
errors are passed to the system’s error handler.

101

VAX LISP/VMS

FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

*PRINT-SLOT-NAMES-AS-KEYWORDSTM*
Determines
are

how

names

are

the

slot
The

names
wvalue

preceded with

value

NIL,

slot

can

colon

:COUNT

:AREA 4

#S(SPACE
If

the

displayed.

Variable
structure
T

(:).

are

NIL.

For

formatted

the

value

when

they

slot

example:

10)

names

are

not

preceded

with

colon.

For

example:

COUNT 10)

#S(SPACE AREA 4
The

default

value

Example
Lisp>

(DEFSTRUCT

HOUSE
ROOMS

FLOORS
)

HOUSE

Lisp>

(MAKE-HOUSE

#S (HOUSE
Lisp>

:ROOMS

(SETF

:ROOMS

:FLOORS

*PRINT-SLOT-NAMES-AS-KEYWORDS*

NIL)

NIL

Lisp> (MAKE-HOUSE :ROOMS 8
#S (HOUSE ROOMS 8 FLOORS 2)
@

The

call

:FLOORS

the DEFSTRUCT

macro

defines

named

structure

HOUSE.

The first call to the constructor function MAKE-HOUSE
creates
a
structure
named
HOUSE.
Colons are included in the output
because
the
wvalue
of
the
*PRINT-SLOT-NAMES-AS-KEYWORDS*
variable

The
<call
to
the
SETF
macro
changes
the
value
*PRINT-SLOT-NAMES-AS-KEYWORDS* variable to NIL.

The

second call

structure

output because
variable

to the constructor

named

HOUSE.

the value

NIL.

102

function MAKE-HOUSE

Colons

the

are

the

creates

not included in the

*PRINT-SLOT-NAMES-AS-KEYWORDS*

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
REQUIRE Function

Examines the *MODULES* variable to determine if a specified module has
1is not loaded, the function loads the
module
the
If
loaded.
been
files that you specify for the module.
If the module is
loaded,
1its
files

are

not

reloaded.

function checks
the
When you call the REQUIRE function in VAX LISP,
the files it 1is
name
that
pathnames
specified
explicitly
vyou
whether
files the
the
loads
function
the
pathnames,
If you specify
to load.
function
the
pathnames,
specify
not
do
If you
represent.
pathnames
order:
searches for the module’s files in the following

The function searches the current directory for a source file
If
file with the specified module name.
fast-loading
a
or
the
file- into
the function finds such a file, it loads the
This search forces the function to locate
environment.
LISP
a
locates
function
the
before
created
have
you
a module
public
the
of
one
in
present
is
that
name
same
of the
module

places

(see

following

steps).

function
the
defined,
is
If the logical name LISPSMODULES
name refers to for a
1logical
directory this
the
searches
source file or a fast-loading file with the specified module
search enables the VAX LISP sites to maintain a
This
name.

central directory of modules.

The function searches the directory to which the logical name
for a source file or a fast-loading file
refers
LISPSSYSTEM

you
This search enables
with the specified module name.
system.
locate modules that are provided with the VAX LISP

If the function does not

module name,

find

file

with

the

specified

an error is signaled.

When you load a module, the pathname that refers to the directory that
A
1is bound to the *MODULE-DIRECTORY* variable.
the module
contains
1in
earlier
provided
is
description of the *MODULE-DIRECTORY* variable
Part

II.

The REQUIRE function checks the *MODULES* variable to determine if a
However, the REQUIRE function, when
module has already been loaded.
loading a module, does not update the *MODULES* variable to indicate
The PROVIDE function (described in
that the module has been loaded.
Use
the *MODULES* variable.
update
does
The Language)
COMMON LISP:
to
loaded
be
to
module
a
containing
in a file
the PROVIDE function
this
of
module
a
indicate to the LISP system that the file contains
If

the

subsequen

name.

oes

not

conta in

ng
rre
correspondi

PROVIDE,

QUIRE of the module will cause the file to be reloaded.

103

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

REQUIRE Function (cont.)
Format

REQUIRE module-name &OPTIONAL pathname
Arguments

module-name

A string or a

symbol

that names

the module whose

files

are

loaded.

pathname

A pathname or a list of pathnames that represent the files to
be
loaded
into LISP memory.
The files are loaded in the same order
the pathnames are listed, from left to right.
Return Value

Undefined.
Example
Lisp>

*MODULES*

("CALCULUS"
Lisp>

"NEWTONIAN-MECHANICS")

(REQUIRE

'RELATIVE)

Lisp>

*MODULES*

("RELATIVE"

"CALCULUS"

"NEWTONIAN-MECHANICS")

The first evaluation of the *MODULES* wvariable shows
modules CALCULUS and NEWTONIAN-MECHANICS are loaded.

The call to the REQUIRE function

checks

whether

that

the

module

RELATIVE
is loaded.
The previous evaluation of the *MODULES*
variable indicated that the module was not loaded;
therefore,
the function loaded the module RELATIVE.

The second evaluation of the
module RELATIVE was

loaded.

104

*MODULES* variable

shows

that the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

ROOM

Function

Displays
the

information

following

about

memory

LISP

memory.

Information

displayed

for

spaces:

@ Read-only spaée

The

Static

Dynamic

following

space

information

number

provided

of memory pages

for

that

each

type

space:

Total

can be used

Current number of memory pages being used

Percentage of free memory pages available for use

The information for éach storage type is displayed on one line in
following

format:

Read-Only Storage
All

counts

are

the

Total Size: 4352, Current Allocation: 4113, Free: 5

512-byte

pages.

Format

ROOM

&OPTIONAL

value

Argument

value

Optional argument whose value can be T or NIL.

If you

specify

NIL,
the function displays the same information that it displays
the
when the argument is
not
specified.
If
you
specify
T,
function
displays
additional
information
for
the
read-only,
static, and dynamic storage spaces.
The
additional
information
consists
of
a breakdown of the storage space being used by each
the
VAX
LISP
data
type.
The
information
1is
displayed
1in
following

tabular

Read-Only Storage
(reserved)
Strings:

Table

Total Size: 4352, Current Allocation: 4113, Free: 5J
Functions:
191
Arrays:
0 B-Vectors:
6
S Flo Vecs:

D Flo Vecs:

L Flo Vecs:

L Wrd Vecs:

Bignums:

(reserved)

Sngl Flos:

Dbl Flos:

Long Flos:

Ratios:

Complexes:

Symbols:

Conses:

(reserved)

Ctrl Stack:

Bind Stack:

function

lists

381

format:

the

displays

U-Vectors:

3403

headings

and

VAX

LISP

for

type

storage

each

105

128

data
space.

types

the

ROOM

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

ROOM

Function (cont.)

Return

Value

value.

Table 6:

Data Type Headings

Heading

Data

Functions

Compiled

function descriptors

Arrays

Nonsimple

array descriptors

B-Vectors

Type

Boxed vectors

simple vectors

LISP

objects

Strings

Character

U-Vectors

Unboxed vectors -- simple vectors that contain
compiled code, alien structures, or integers of
type

strings

(mod n)

Flo Vecs

Simple

float vectors

Flo Vecs

Simple double

Flo Vecs

Simple

long

float vectors

L Wrd Vecs

Simple longword vectors

Bignums

Sngl

Single

float numbers

Double

float numbers

Dbl

Flos
Flos

Long Flos

Long

float numbers

Ratios

Complexes

Complex numbers

Symbols

Conses

Ctrl

Stack

Control

Stack

Bind Stack

Binding

Stack

106

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

ROOM Function (cont.)
Examples
1.

Lisp>

(ROOM)

Total Size: 4352, Current Allocation: 4113, Free: 5%/

Read-Only Storage

Static Storage

Total Size:

2176,

Current Allocation:

2146,

Free:

1Y%

Dynamic-0 Storage

Total Size:

3065,

Current Allocation:

1292,

Free:

58Y

Displays

1li st

the

current

memory

storage

information.

Lisp> (ROOM T)
Read-Only Storage

(reserved)
Strings:

Total Size:

4352,

Current Allocation:

Functions:

191

381

U-Vectors:

3403

4113,

Free:

5Y%

Arrays:

B-Vectors:

S Flo Vecs:

D Flo Vecs:

L Flo Vecs:

L Wrd Vecs:

Bignums:

(reserved)

Sngl Flos:

Dbl Flos:

Long Flos:

Ratios:

Complexes:

Symbols:

Conses:

(reserved)

Ctrl Stack:

Bind Stack:

Static Storage

Total Size:

(reserved)
Strings:

L Flo Vecs:

2176,

Current Allocation:

Arrays:

B-Vectors:

576

U-Vectors:

267

S Flo Vecs:

D Flo Vecs:

Bignums:

(reserved)

Long Flos:

Ratios:

(reserved)

L Wrd Vecs:

Dbl Flos:
Symbols:

Ctrl Stack:

Bind Stack:

Dynamic-0 Storage

360

Total Size:

3065,

2564

U-Vectors:

L Wrd Vecs:

Sngl Flos:

Complexes:

Read-Only Storage

Displays

544

Current Allocation:

Functions:

129

Conses:

Ctrl Stack:

322

L Flo Vecs:

Free:

Functions:

Sngl Flos:

Strings:

2146,

Complexes:

(reserved)

128

1280,

Free:

58Y%

Arrays:

B-Vectors:

S Flo Vecs:

D Flo Vecs:

Bignums:

(reserved)

Dbl Flos:

Long Flos:

Ratios:

Symbols:

Conses:

(reserved)

Bind Stack:

Total Size:

detailed

4352,

1list

information.

107

656

214

Current Allocation:

the

4113,

current

Free:

memory

59Y%

storage

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

SET-TERMINAL-MODES Function
the
stream bound to
the
characteristics of
terminal
the
Sets
to
Changes
system.
LISP
the
invoke
vyou
when
variable
*TERMINAL-IO*
the stream affect all streams attached to the terminal.

A change
Be careful when you change the settings of terminal modes.
to the
open
are
that
streams
the
to terminal modes affects all
example,
for
If you put a stream into pass-through mode,
terminal.
all the streams open to the terminal are put into pass-through mode.
NOTE

from
Create an error handler to prevent your terminal
3.3
Section
See
being placed in a nonstandard state.
handler.
for information about how to create an error

Format

SET-TERMINAL-MODES

&KEY

:BROADCAST :ECHO :ESCAPE :HALF-DUPLEX
:PASS-ALL :TYPE-AHEAD :WRAP :PASS-THROUGH

Arguments
:BROADCAST

Specifies whether the terminal

can

receive

broadcast

messages

The value can be
such as MAIL notifications and REPLY messages.
receive
can
terminal
the
T,
specify
you
If
either T or NIL.
receive
cannot
terminal
the
NIL,
if you specify
messages;
messages.

+:ECHO

Specifies whether the terminal displays the input characters it
If you specify T,
The value can be either T or NIL.
receives.
the
NIL,
specify
you
if
characters;
input
displays
the terminal
terminal displays only data output from the system or from a user

application program.
:ESCAPE

Specifies whether ANSI standard escape sequences transmitted from
are handled as a single multicharacter terminator.
the terminal
escape
the
1If you specify T,
either T or NIL.
be
can
value
The
The
terminator.
ter
multicharac
single
a
as
handled
sequences are
before
syntax
for
sequences
escape
the
terminal driver checks
For more information on escape
the program.
passing them to
Part I.
sequences, see the VAX/VMS I/0O User’s Reference Manual:
108

VAX LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

SET-TERMINAL-MODES Function (cont.)
: HALF-DUPLEX

Specifies
T

the

NIL.

terminal’s
If

half-duplex.
full-duplex.

the

VAX/VMS

I/0

you

operating

specify

you

For

specify

The

value

terminal’s

NIL,

description

User’s

mode.

the

operating

terminal

Reference Manual:

can

operating

Part

either
mode

mode

modes,

see

: PASS-ALL

Specifies
can

whether
either

the
T

expand

tab

feed

characters,

broadcast

data

terminal

NIL.

you

characters

blanks,

1If

application

you

pass-all

specify

fill

recognize

messages.

the

carriage

control

specify NIL,

program as

mode.

The

wvalue

system does
return

characters,

the

passes

system

not
line

receive

all

binary data.

NOTE
:PASS-ALL

with

has

been

Version

recommended

kept

that

you

for

VAX
use

compatibility

LISP,

but

with

1is

not

:PASS-ALL.

: PASS-THROUGH

Specifies

value

whether

can

:PASS-ALL

still

the

terminal

either

mode,

except

that

NIL.

pass-through

This

"TTSYNC"

mode

protocol

mode.

the

The

same

(CTRL/S,

the

CTRL/Q)

used.

:TYPE-AHEAD

Specifies

whether

there

1is

specify

you

outstanding
and

the

read.

accepts

terminal

outstanding

input

accepts

read.

The

terminal

you

input

value

accepts

input

specify NIL,

only when

program

the
or

that

can

even

terminal
the

typed

either

there
is

system

when

NIL.

not

dedicated
issues

read.
:WRAP

Specifies
and

either

generates

line

whether

line

terminal

feed

or
a

terminal
the

NIL.
The

end

carriage

reached.
width

the

when

you
return

end

setting.

109

driver
a

generates

line

specify

and

the

line

1line

carriage

reached.

the
feed

The

value

terminal
when

return
can

driver

the

end

determined

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
SET-TERMINAL-MODES Function (cont.)
Return Value

Undefined.
Example

Lisp> (DEFVAR *OLD-TERMINAL-STATE*)
*OQLD-TERMINAL-STATE*

Lisp> (DEFUN PASS-THROUGH-HANDLER (FUNCTION ERROR &REST ARGS)
(LET ((CURRENT-SETTINGS (GET-TERMINAL-MODES) ) )
(APPLY #’SET-TERMINAL-MODES *OLD-TERMINAL-STATE*)
(APPLY #'UNIVERSAL-ERROR-HANDLER FUNCTION ERROR ARGS)
(APPLY #’'SET-TERMINAL-MODES CURRENT-SETTINGS) ))
PASS~-THROUGH-HANDLER
Lisp> (DEFUN UNUSUAL-INPUT NIL

(LET ((*OLD-TERMINAL-STATE* (GET-TERMINAL-MODES) )
(*UNIVERSAL-ERROR-HANDLER* #"PASS-THROUGH-HANDLER) )
(UNWIND-PROTECT

(PROGN
(SET-TERMINAL-MODES
:PASS-THROUGH
T

:ECHO
NIL)

)
(GET-INPUT)

(APPLY #'SET-TERMINAL-MODES
) ))
*QLD-TERMINAL-STATE*)
UNUSUAL-INPUT

informs

the

LISP

system

that

The call to the DEFVAR macro

The first call to the DEFUN macro defines an error handler
named PASS-THROUGH-HANDLER, which is used when the terminal is

*OLD-TERMINAL-STATE* is a special variable.

placed in an unusual state.

handler

assumes

that

the

wvalue

The second call to the DEFUN macro defines

function

normal

terminal

modes

*OLD-TERMINAL-STATE* variable.

The

are

UNUSUAL-INPUT,

stored

the

named

which causes the function PASS-THROUGH-HANDLER

to be the error handler while the function GET-INPUT is Dbeing
The GET-INPUT function is 1inside a call to the
executed.
UNWIND-PROTECT function so an error or throw puts the terminal
back in its original

state.

110

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

SHORT-SITE-NAME Function
Translates

the

logical

name

LISP$SHORT_SITE_NAME.

Format

SHORT-SITE-NAME

Return Value

The translation
of
the
returned as a string.
If

logical
name
LISPSSHORT_SITE_NAME
the logical name is not defined, NIL

returned.
Example

Lisp>

(SHORT-SITE-NAME)

"Smith’s

Computer

Company"”

111

1is
is

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

SPAWN

Function

Creates

subprocess

for

executing

Command Language

Interpreter

(CLI)

commands.
This function causes the LISP system to interrupt execution
of a LISP process and to optionally execute the specified CLI command.
If
you
specify
the
:PARALLEL
keyword
with a value of T, the LISP
process continues to execute while the subprocess
1is
executing.
If
you
do
not
specify
this keyword or if you specify it with NIL, the
LISP process is put into a
hibernation
state
wuntil
the
subprocess
completes

its

execution.

This function is equivalent
to
the
DCL
SPAWN
command.
For
information on the SPAWN command, see the VAX/VMS DCL Dictionary.

Format
SPAWN

&KEY

:COMMAND-STRING
: LOGICAL-NAMES

:DCL-SYMBOLS
:OUTPUT-FILE

:INPUT-FILE
:PARALLEL

: PROCESS-NAME
Arguments

: COMMAND~-STRING

A string that specifies a DCL command the specified subprocess is
to
process.
The
value must be a DCL command.
By default, the
SPAWN function does not process a

command.

:DCL-SYMBOLS

Specifies whether
the
spawned
subprocess
is
to
acquire
the
currently
defined
CLI symbols from the LISP process.
The value
can be either T
or
NIL.
If
you
specify
T,
the
subprocess

acquires

the

CLI

symbols.

does not acquire the CLI

If you specify NIL, the subprocess

symbols.

The default value

1s T.

: INPUT-FILE

A pathname, namestring, symbol, or stream that specifies an input
file
containing
one
or more DCL commands to be associated with
the logical name SYSSINPUT and to
be
executed
by
the
spawned
subprocess.
If
you
specify both a command string and an input
file, the command string is processed before the commands in
the
input
file.
The
subprocess
1is
terminated when processing 1is
complete.

112

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

SPAWN Function (cont.)
: LOGICAL-NAMES

Specifies

whether

currently

NIL.

the

defined

you

specify

names;

logical

names.

you

spawned

1logical

the

default

The

the

1is

value

subprocess

specify NIL,
The

subprocess

names.

acquire

acquires

subprocess

value

can

does

the

either

the

not

logical

acquire

the

:OUTPUT-FILE

"Specifies

pathname,

the

output

file

and

to which

the

namestring,

symbol,

associated with

results

the

stream

logical

spawned

that

name

subprocess

names

SYS$SOUTPUT
are

written.
: PARALLEL

Specifies
created
or

whether

NIL.

subprocess
remains

the

subprocess

completes

execution

are

you

specify T,

are

parallel.

hibernation

the

vyou

execution and

the

name

system

value

the

The

and

can be
system

specify NIL,

wuntil

exits.

LISP

The

execution

state

its

the

parallel.

the

default value

and

LISP

created

the

either

the

system

subprocess

NIL.

: PROCESS-NAME

Specifies

this

keyword,

the

the subprocess

system generates

unique

created.

you

omit

name.

Return Value

Undefined.
Examples

Lisp>

(SPAWN)

$
Creates

a uniquely named

1it.

The

commands

the

subprocess until

subprocess
typed

the

and

the

subprocess

attaches

terminal

are

the

terminal

directed

exits.

Lisp> (SPAWN :INPUT-FILE "START.COM

"START.LO

:OUTPUT-FILE
:PARALLEL

L1sSp>
Cvx@fmi—acn

i'cacLtces

c~11hfihr\r~ass

oulprocce

vilado

START.COM.

113

w1 11

W. L4

avaoariidao

caclCULC

+ha

Lil€

Cf\fl‘l”fifi‘i"c“

LQIlLCiil o

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

SPAWN Function (cont.)
3.

Lisp>

(DEFUN

SPAWN-IN-WINDOW
(&OPTIONAL

(LET

(PROCESS-NAME

NIL))

((DEVICE-STRING

(UIS:CREATE-TERMINAL
c:BANNER-TITLE

(OR PROCESS-NAME
(SPAWN

:INPUT-FILE

"Subprocess"))))

DEVICE-STRING

cOQUTPUT-FILE

DEVICE-STRING

:PROCESS~-NAME

PROCESS-NAME

: PARALLEL

T)))

SPAWN-IN-WINDOW

Lisp>

(SPAWN-IN-WINDOW

"Smith_1")

Lisp>

This example works
only
on
a
VAXstation.
It
defines
a
function
named
SPAWN-IN-WINDOW
that creates a process 1in a
VAXstation
terminal
emulator
window.
The
function

UIS:CREATE-TERMINAL

creates

returns

device name.

the window'’s

terminal

emulator window and

By supplying

this

return

value
with
the
: INPUT-FILE
and
:OUTPUT-FILE
keyword
arguments, SPAWN-IN-WINDOW arranges for input to
and
output
from
the
subprocess
to
be
directed
through the terminal
emulator
window.
SPAWN-IN-WINDOW
accepts
an
optional
argument
that
becomes
the
name
of the subprocess and the
title

the window.

When the SPAWN-IN-WINDOW function is called, a subprocess and
a
terminal emulator window named "Smith_1" are created.
The
cursor switches to the terminal
emulator
window.
However,
the
wuser
can
switch the cursor back to the LISP prompt and
continue to use LISP without logging out of the subprocess.
See

the

VAX

LISP/VMS

information about

Graphics

Programming

the UIS:CREATE-TERMINAL

114

Guide

function.

for

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

STEP Macro
Invokes

The

the

STEP

what

macro

the

through

stepper

stepper.

evaluates

the

returns.

evaluation

surround
VAX

LISP

form

the

response

the

VAX

the

command

form

In
the

that

the

prompt

oriented

rather

displays

than

stepper,

see

Chapter

argument

you

Entering

commands with parentheses.
LISP

1ts

process,

form.

stepper

i1s

can

and

interactively

question mark

helpful

expression

For

further

the

function

returns

(?2)

information.

oriented

information

step
1in
The

not

on using

Format

STEP

form

Argument

form

evaluated.

Return Value

The

value

returned

form.

Example

Lisp>

#9:
Step

(STEP

(FACTORIAL

3))

Invokes

the VAX LISP

stepper

for

115

call

(FACTORIAL

3).

VAX LISP/VMS FUNCTION,

*STEP-ENVIRONMENT*
The

Variable

*STEP-ENVIRONMENT*

lexical

MACRO, AND VARIABLE DESCRIPTIONS

environment

variable,

which

debugging

*STEP-FORM*

default in the stepper, the lexical
EVALUATE command.
See COMMON LISP:
dynamic

and

lexical

environment

stepped

1is

being

environment is used
The Language for a

Dbound

the

evaluated.

if you use

the
of

description

variables.

Some COMMON LISP functions
(for
example,
MACROEXPAND)
take
an optional environment

to the
these

tool,

EVALHOOK,
argument.

APPLYHOOK,
and
The value bound

*STEP-ENVIRONMENT* variable can be passed as an environment
functions
to
allow
evaluaton
of forms in the context of

to
the

form.

Example
Step>

EVAL

(FUNCTION-X
Step>

*STEP-FORM*

(EVALHOOK

1))
'(-

NIL

*STEP-ENVIRONMENT*
)

The use of the *STEP-ENVIRONMENT* variable
EVALHOOK
function
causes the local value

evaluation of the form (- X 1).
stepper

sessions

from which

this

116

See

in this
of X to

Chapter

excerpt

taken.

call
to
be used in

for

the

the
the

full

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*STEP-FORM*

Variable

The *STEP-FORM* variable,
evaluated while stepping.
(STEP

a debugging tool, is bound to the
For example, while executing the

form being
form

(FUNCTION-Z ARGl ARG2))

the value of *STEP-FORM* is the list
stepping, the value is undefined.

(FUNCTION-Z ARGl ARGZ2).

When not

Example
Step>

STEP

Step>

#35:

#34:

(+ FUNCTION-X

(- X 1))

(FUNCTION-X

(- X 1))

STEP

#38:

S
Step>

X =>
=> NIL

#39:

EVAL

(FUNCTION-X

(- X 2)))

*STEP-FORM*

(FUNCTION-X

See Chapter
excerpt
1is

5 for
the
full
stepper session
from
which
this
taken.
In
this
case, the *STEP-FORM* variable 1is

bound

1))

(FUNCTION-X

(- X 1)).

117

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

SUSPEND Function
Writes
to

information

resume

the

the current
function is

about

LISP

system at

system,
invoked

system
later

file,

time.

The

making

function

but copies the state of the LISP
to the specified file.
When you

©possible

does

not

stop

system
when
reinvoke the

LISP

the

system with the /RESUME qualifier and the file name that was specified
the SUSPEND function, program execution continues from the point

with

where

Only

the

static

written

the

SUSPEND

function

and

the

read-only

dynamic

sections

system

called.

portions

specified

LISPSSYSTEM:LISPSUS. SUS.
able

was

file.

When

the

LISP

resume

environment

suspended

not,

you

will

are

system,

of
the
LISP
environment
are
taken
You
must make sure that your original

LISP$SSYSTEM:LISPSUS.SUS;

resume

the

you

not

from
LISP

system.

When a suspended system is resumed, the LISP environment is
identical
to
the
environment that existed when the suspend operation occurred,
with

the

following

exceptions:

All

streams

except

the

standard

The

*DEFAULT-PATHNAME-DEFAULTS*

streams

are

variable

closed.
set

the

current

directory.

Call-out

state might

LISP/VMS

System Acess

Programming Guide).

Any interrupt
VAX
LISP/VMS
automatically

For

action

the

that

action

Chapter

functions

reset

you

have

reestablished

upon

resuming.

Some

state

Editor

(see

o0f

the

functions are uninstated (see Chapter 4
of
System Access Programming Guide).
They are
reinstated upon resuming.

all workstation-related

argument,

1lost

the

established

changed

that

take

system default

(see

1is

not

the

VAX

the
not

action

state.

automatically

VAX

LISP

Editor

Programming Guide).

On
a workstation,

windows,

displays,

lost.
Format

SUSPEND pathname

118

and

display

1lists

are

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
SUSPEND Function (cont.)
Argument

pathname

file

name

T, when the LISP system is resumed at a later time and NIL,
execution continues after a suspend operation.

when

or symbol that represents the

namestring,

A pathname,

to which the

function writes the LISP-system state.

Return Value

Example
Lisp>

(DEFUN

PROGRAM-MAIN-LOOP

(PRINC

(LOOP

NIL

"Enter number>

(SETF X
(FORMAT

*STANDARD-INPUT*))
*STANDARD-OUTPUT*
(READ

"“%The square

root of "F is

"F.

(SQRT X)) ))

PROGRAM~-MAIN-LOOP

Lisp>

(DEFUN

DUMP-PROGRAM NIL

(SUSPEND

"MYPROG.SUS")

(FRESH-LINE)

"Welcome to my program!")

(PRINC

(TERPRI)

)
(PROGRAM-MAIN-LOOP)
DUMP-PROGRAM

Lisp>

;
:
:
;

(DUMP-PROGRAM)

Starting
Finished
Starting
Finished

Welcome

Enter

The

Enter

due
due
due
due

root of 5.0

is 2.236038.

number>

Lisp>

(EXIT)

S LISP/RESUME=MYPROG.SUS
Welcome

Enter

to
to
to
to

is 5.0.

root of 25.0

number>

square

collection
collection
collection
collection

my program

number>

square

Enter

The

garbage
garbage
garbage
garbage

my program

number>

119

GC function.
GC function.
SUSPEND function.
SUSPEND function.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
SUSPEND Function (cont.)
The

first

call

the

DEFUN macro

defines

function

named

defines

function

named

PROGRAM-MAIN-LOOP.

The

second

call

the

DEFUN macro

DUMP-PROGRAM.

The

call

the

LISP

the

DUMP-PROGRAM

environment

function

the

copies

file

the

current

MYPROG.SUS.

The

state

LISP

system continues to run, displaying the message "Welcome to my
program” and then executes the PROGRAM-MAIN-LOOP function.
The

call

the

EXIT

function

The

LISP/RESUME=MYPROG.SUS
system,
displays
the

PROGRAM-MAIN-LOOP

exits

the

specification

function.

120

message,

LISP

system.

reinvokes
the
and
executes

LISP

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
THROW-TO-COMMAND-LEVEL Function
Transfers control.
This function exists only for
compatibility
with
VAX
LISP/VMS
V1.x,
in
which
it
transferred control to a numbered
command level.
VAX LISP V2 does not have numbered command levels.
1In
VAX
LISP
V2,
THROW-TO-COMMAND-LEVEL
either
throws
to
the
CANCEL-CHARACTER-TAG tag or does nothing.

Format

level

THROW-TO-COMMAND-LEVEL
Argument

level

Either an integer or

keyword.

Depending

THROW-TO-COMMAND-LEVEL takes the following action:

the

argument,

No action
Throw to CANCEL-CHARACTER-TAG
No action
Throw to CANCEL-CHARACTER-TAG

integer
: CURRENT
: PREVIOUS
: TOP
Return Value

Undefined.
Example

Lisp>

(FACTORIAL

Fatal error in function SYSTEM::%EVAL
has

Symbol
Control
Frame

Debug>

no value:

(signaled with ERROR).

Stack Debugger

#3:

(EVAL

(FACTORIAL M))

(THROW-TO-COMMAND-LEVEL

:TOP)

Lisp>

The debugger is invoked, because an error

The

was

signaled

when

the FACTORIAL function was called.

call

control

to the

the

THROW-TO-COMMAND-LEVEL

top-level

loop.

121

function

returns

VAX LISP/VMS FUNCTION,

TIME

MACRO,

AND VARIABLE DESCRIPTIONS

Macro

Evaluates
returns

form,

the

displays

values

the

form

form’s

CPU

time

and

real

time,

and

returns.

The time information 1is displayed in the following format:
CPU Time:
I1f

garbage

sec.,

collections

TIME

macro,

line

includes

garbage

0.03

the

macro

Real

occur

Time:

during

displays

information

0.23
the

another

about

the

CPU

sec.

evaluation
line

time

and

collector.

Format

TIME

form

Argument

form

The

form

that

evaluated.

Return Value

The

form’s

return

values

are

returned.

Example

Lisp>

(TIME

CPU Time:

(TEST))

0.03

sec.,

Real

Time:

122

0.23

time

sec.

call

information.

real

time

used

the
This

the

VAX

LISP/VMS

FUNCTION,

*TOP-LEVEL-PROMPT*
Lets

you

change

the

MACRO,

AND VARIABLE

DESCRIPTIONS

Variable
top-level

prompt.

The

value

this

variable

be:

®@

string

function

NIL

you

specify

NIL,

the

arguments

default

that

prompt

returns

"Lisp>"

string

used.

Example
Lisp>

"TOP>

(SETF

*TOP-LEVEL-PROMPT*

"TOP>

TOP>

Sets

the

value

the

wvariable

123

*TQOP-LEVEL-PROMPT*

"TOP>

can

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRACE Macro

Enables tracing

for one or more

functions and macros.

VAX LISP allows you to specify a number of options that
suppress
the
TRACE macro’s displayed output or that cause additional information to
be displayed.
The options are specified as keyword-value pairs.
The
keyword-word value pairs you can specify are listed in Table 7.
NOTE

The arguments

to the

specified in a call

TRACE

macro

not evaluated when the call to TRACE is executed.
are
described
as
repeatedly,
evaluated
are
Some forms

below.

Format

TRACE

&REST

trace-description

Argument

trace-description

If an argument is not specified,
One or more optional arguments.
TRACE
macro returns a list of the functions and macros that
the
be
can
Trace-description arguments
are currently being traced.
specified

three

formats:

One or more function and/or macro names can be specified which
enables

tracing for that function(s)

name-1

and/or macro(s).

name-2

with
specified
be
can
macro
or
The name of each function
the
specify
pairs
keyword-value
The
pairs.
keyword-value
the
traces
it
operations the TRACE macro is to perform when
The name and the keyword-value
or macro.
function
specified
pairs must be specified as a list whose first element
1is
the
function

(name

macro

name.

keyword-1

value-1

keyword-2

value-2

...)

with
specified
be
A list of function and/or macro names can
specify the
pairs
keyword-value
The
pairs.
keyword-value
each
traces
operations the TRACE macro is to perform when it
The list of names and the
in the list.
and/or macro
function
first
whose
1list
keyword-value pairs must be specified as a
element

the

list of names.

124

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE

DESCRIPTIONS

TRACE Macro (cont.)
((name-1

Table

forms

lists
that

evaluated

name-2

the

keywords

are

the

keyword-1

value-1

keyword-2

value-2

and

values
in

referred

null

lexical

that

the

...)

can

wvalue

environment

and

specified.

The

descriptions

are

the

current

dynamic

environment.

Table 7:

TRACE Options

Keyword-Value

:DEBUG-IF

Description

Pair

form

Specifies

evaluated
call

the

macro.

other

than

that

and

after

specified
the

debugger
after

form
before
form

NIL,
is

the

function

returns

the

1invoked

function

be
each

value

VAX

LISP

before

and

macro

1is

called.

:PRE-DEBUG-IF

form

Specifies

form

that

evaluated

before

each

specified

function

macro.

I1f

value

other

than

debugger

the

form

NIL,

returns

VAX

LISP

the

invoked

:POST-DEBUG-IF

form

before

function

Specifies

evaluated

specified
the

form

NIL,

form-list

are

displayed
indented

displayed

the

TRACE

argument,
(see

125

called.

a list

<call
per
match

the

Chapter

5).

the

If
than

debugger

macro.

other

specified

called.

forms

that

and whose

displayed

macro

the

macro

1is
call

macro.

LISP

one

the

VAX

value

each

function

call

that

function

specified

each

evaluated

after

form

Specifies
to

after

function

+:PRINT

macro

returns

the

after

invoked

1is

before

the

The

and

other

evaluate
is

are

output

TRACE macro.

debugger

and

specified

values

1line

cannot

are

values

the

invoked

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRACE

Macro (cont.)

Table

(cont.)

Keyword-Value

Pair

:PRE-PRINT

form-list

Description

are
Specifies a list of forms that
to
be
evaluated
and whose values
each
before
displayed
be
are to
the specified function or
to
call

macro.
The
wvalues
are
displayed
one
per
line
and are indented to
match other output displayed by the
TRACE

macro.

the

TRACE macro

the
argument,
cannot evaluate the
Chapter
(see
invoked
1is
debugger
5).

:POST-PRINT

form-list

are
Specifies a list of forms that
and whose values
evaluated
be
to
are to be displayed after each call
to the specified function or macro.
per
one
displayed
The values are
match
to
indented
are
and
line
other output displayed by the TRACE
macro.

the

TRACE macro

cannot

evaluate the argument, the debugger
is invoked (see Chapter 5).
+STEP-IF

form

be
to
1is
that
form
Specifies a
each call to the
before
evaluated
If
macro.
or
specified function
a value other than
the form returns
NIL, the stepper is invoked and the
function
or
macro
is
stepped
for
5
Chapter
See
through.
information

: SUPPRESS-IF form

name

the

stepper.

be
to
1is
that
form
Specifies a
each call to the
before
evaluated
I1f
macro.
or
specified function
the form returns a value other than
not
does
macro
TRACE
the
NIL,
the
and
arguments
the
display
specified
the
of
value
return
function

:DURING

macro.

name
Specifies a function or macroc
function and macro
of
1list
a
or
macro
or
function
The
names.
by the TRACE function 1is
specified
called
1is
1t
when
only
traced

126

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRACE Macro (cont.)
Table

(cont.)

Description

Keyword-Value Pair

(directly
within
one
macros

or
indirectly)
from
of
the
functions
or
specified
by
the
:DURING

keyword.

Return Value

A list of the functions currently being traced.
Examples

Lisp>

(TRACE FACTORIAL COUNT1 COUNT2)

(FACTORIAL COUNT1

COUNT2)

COUNT1l,

Fnables the tracer for the functions FACTORIAL,

and

COUNTZ2.
Lisp>

(TRACE)

(FACTORIAL COUNT1 COUNTZ2)

functions

Returns a list of the

which

for

the

tracer

enabled.

Lisp>

(DEFUN REVERSE-COUNT (N)
(DECLARE (SPECIAL *GO-INTO-DEBUGGER*))
(IF

(SETQ

*GO~-INTO~-DEBUGGER*

(SETQ

*GO-INTO-DEBUGGER*

NIL))

((= N 0) 0)
(T (PRINT N) (+ 1 (REVERSE-COUNT
DEBUGGER* NIL)
*GO-INTO(SETQ
(COND

Lisp>
NIL

Lisp>

(TRACE

(REVERSE-COUNT

(REVERSE-COUNT)

Lisp>
#4:

(REVERSE-COUNT 3)

(REVERSE-COUNT

#16:

(- N 1))))})

(REVERSE-COUNT 3)

(REVERSE-COUNT

#28:

(REVERSE-COUNT

127

:DEBUG-IF *GO-INTO-DEBUGGER*))

VAX LISP/VMS FUNCTION,

TRACE

Macro

MACRO, AND VARIABLE DESCRIPTIONS

(cont.)

#40: (REVERSE-COUNT
#40=> 0
.

#28=>

$#16=>
$#4=> 3
3

Lisp>

#4:

(REVERSE-COUNT

. #16:

(REVERSE-COUNT

Control

Stack

Frame

#17:

Debug

Debugger

(DEBUG)

CONTINUE

(REVERSE-COUNT

#28:

#40:

(REVERSE-COUNT

#52:

(REVERSE-COUNT

#52=>
.

#40=>

$#28=>
$#16=> 3
#d4=> 4

Lisp>

The recursive function REVERSE-COUNT is defined to count down
from
the
number it is given and to return that number after
the function is evaluated.
1If, however, the number given
1is
greater
than 3 (set low to simplify the example), the global
variable *GO-INTO-DEBUGGER* (preset to NIL) 1is set to T.

The first time the REVERSE-COUNT function is traced using the
DEBUG-IF
keyword,
the
argument
1is 3.
The second time the
function is traced, the argument is over 3.
This
sets
the
global
variable
*GO-INTO-DEBUGGER*
to
T, which causes the
debugger to be invoked during a trace
of
the
REVERSE-COUNT
function.
The
debugger
is
invoked
after
the function’s
argument is evaluated.
To reset the global variable *GO-INTO-DEBUGGER* to
NIL,
the
REVERSE~-COUNT function must be completed.
So, the evaluation
of
the
function
was
continued
with
the
Debug
command

CONTINUE.

Lisp>

(TRACE

(RE\

(REVERSE-COUNT)

128

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRACE Macro (cont.)
Lisp>

#4:

(REVERSE-COUNT

#16: (REVERSE-COUNT 3)
Control Stack Debugger
Frame

$#17:

Debug

the
function causes
the REVERSE-COUNT
to
The 4 argument
turn
in
which
T,
to
set
be
to
variable
*GO-INTO-DEBUGGER*
recursive
causes the debugger to be invoked before the first
call to the REVERSE-COUNT function.

Lisp>

(TRACE

(REVERSE-COUNT

: POST-DEBUG-IF

)
*GO-INTO-DEBUGGER*)

(REVERSE-COUNT)

Lisp> (REVERSE-COUNT 4)
#4: (REVERSE-COUNT 4)
4

(REVERSE-COUNT 3)

#16:

(REVERSE-COUNT 2)

#28:

:
2

#40:

(REVERSE-COUNT 1)

#52:
#52=>
$#40=> 1
#28=> 2
.

(REVERSE-COUNT

$#16=>
$4=> 4
4

Lisp>

(TRACE

(REVERSE-COUNT
(NOT

(REVERSE-COUNT)

Lisp>

#4:

(REVERSE-COUNT

(REVERSE-COUNT 4)

(REVERSE-COUNT 3)

#16:

#28:

(REVERSE-COUNT 2)

)

#40:

(REVERSE-COUNT 1)

#52:

.
Control

(REVERSE-COUNT 0)

Stack Debugger

Frame

#53:

Debug

(

CON

129

*GO-INTO-DEBUGGER*)))

VAX

TRACE

LISP/VMS

Macro

FUNCTION,

MACRO,

AND

VARIABLE

DESCRIPTIONS

(cont.)

Control

Stack

Frame

#41:

Debug

CONTINUE

#40=>
Control

Stack

Frame

#29:

Debug

Debugger

(DEBUG)

CONTINUE

$28=>
Control

Debugger

(DEBUG)

Stack

Frame

#17:

Debug

Debugger

(DEBUG)

CONTINUE

#16=>
Control

Stack

Debugger

Frame

#5:

(DEBUG)

Debug

CONTINUE

the

first

#d4=>
4

Lisp>
Here,

the

debugger

time

1is

keyword,

because

condition

1is

after

the

not
the

met

keyword

after

function

variable

REVERSE-COUNT

invoked
the

reset

the

function,

reset

NIL,

The

second

form

(NOT

its

time

the

argument
a

invoking

the

this

were

the

debugger

the

Here,

evaluate

all

the

example

where

after

the

Debug

the
the

CONTINUE

Lisp>

(SETF

*L*

Lisp>

(TRACE

:PRINT

*L*

%Mk

(*)

Lisp>

*Mx

*xN%

(*L*

*M*

*N*)

130

*N*)))

been

invoked,

the

value

:POST-DEBUG-IF
the

condition

evaluated.
causes

must

example

command

(SETQ

have

since

command

This

its

invoked.

the
is

form
not

1is

command

repeated.

been

fulfills

CONTINUE

However,

definition

would

have

function

calls.

the

gives

turn

CONTINUE

recursive

from

function

This

wvalue, which

debugger

situation,

evaluation.

NIL.

only

*GO-INTO-DEBUGGER*
If

evaluates

evaluated,

evaluated.

the

would

:POST-DEBUG-IF

debugger

variable

REVERSE-COUNT

1is

the

NIL.

removed

*GO-INTO-DEBUGGER*)

keyword

and

the

evaluated,

NIL)

REVERSE-COUNT

invokes
function

back

*GO-INTO-DEBUGGER*

function

despite

did

only

differs
not

one

repeated
have

from
to

VAX LISP/VMS

TRACE Macro

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

(cont.)

Lisp>

*L*

function

#4:

*L*x

$#4

*M*

*N*

kM*

KN*
)

1260

$#4

*L*

*M*

1is

#4=>

*N*

1260

The

values

displayed

not

the

before

and

traced,

but

global

variables

after

the

call

function

traced.

*L*,

*M*,

and

*N*

are

the

function

1is

evaluated.
(*L*

*N*

*M*x

*N#*)))

1260

#d4=>
1260

The

values

displayed
8.

Lisp>

the

before

(TRACE

global

the

variables

call

:POST-PRINT

the

(*L*

*L*,

#*M*,

function

#*M*

and

*N*

are

evaluated.

*N%)))

(*)

Lisp>
#d:

#4=>

*L*

*M*

*N*)

1260

*L*

*M*

*N*

1260

The

values

displayed

the

after

global

the

(SQUARE

5.0)

variables

call

the

(SQRT

25))

*L*,

*M*,

function

and

*N*

evaluated.

are

VAX LISP/VMS FUNCTION. MACRO, AND VARIABLE DESCRIPTIONS
TRACE Macro (cont.)
T

Lisp>

(+)

Lisp>

(TRACE

(SQUARE

:SUPPRESS-IF

*STOP-TRACING¥*))

(SQRT

25))

26.0

In the first example, the call to the + function
1is
traced.
In
the
second
example,
the
<call to the + function is not
traced because

10.

Lisp>

(TRACE

form

the

(FACTORIAL

:SUPPRESS-IF

:STEP-IF

*STOP-TRACING*).

T))

(FACTORIAL)

Lisp>

#5:

£#9:

(FACTORIAL

Step>

(IF

(* N

2 N)

(* N

2 N)

(IF

(BLOCK FACTORIAL

#16:

(FACTORIAL

(1- N)))))

(1- N))))

Step>

#22:

Step>

The call to the FACTORIAL function invokes the stepper.

11.

Lisp>

(TRACE

(LIST-LENGTH

:DURING

PRINT-LENGTH))

(LIST-LENGTH
Lisp>

(PRINT-LENGTH

#13: (LIST-LENGTH
$#13=> 3

The

’(CAT

DOG

(CAT DOG PONY)

length of

PONY))

(CAT DOG PONY))

1is

NIL

The PRINT-LENGTH function has been defined to find the length
The
LIST-LENGTH.
function
the
with
argument
its
of
the
to
<call
the
traced during
1is
function
LIST-LENGTH
PRINT-LENGTH
Lisp>

(DEFUN

(IF

FUNCTION-X

(X)

(FUNCTION-X

(- X 1))

FUNCTION-X

FUNCTION-X
: PRE-DEBUG-IF
27
:g?
: SUPPRESS-1

(FUNCTION-X)
Lisp>

(FUNCTION-X

132

(
T)

R
N

Lisp>

12.

function.

(FUNCTION-X

(- X 2)))))

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRACE Macro (cont.)
Control

Stack Debugger

Frame

#26:

Debug

Frame

#21:

(DEBUG)

DOWN

(BLOCK
(IF

FUNCTION-X
(< X 3) 1

(+
Debug

Frame

#19:

Debug

(FUNCTION-X

1))

(FUNCTION-X

2)))))

DOWN

(FUNCTION-X

(CADR

(DEBUG-CALL))

3
Debug

Control

CONTINUE

Debugger

Stack

Frame

#19:

Debug

(DEBUG)

CONTINUE

FUNCTION-X is first defined.

In this example,

1is
TRACE
Then the TRACE macro is called for FUNCTION-X.
to invoke the debugger if the first argument to
specified
FUNCTION-X (the function call being traced) is
1less
than
2.
Since
the
PRE-DEBUG-IF
option
1is
specified,
the
the
As
FUNCTION-X.
to
call
the
before
invoked
is
debugger
: SUPPRESS-IF
option has
a value of T, calls to FUNCTION-X
do not

cause

any trace

output.

@ The DOWN command moves the pointer down the control stack.

The DEBUG-CALL function returns a

list

representing

the

evaluation

1In this case, the CADR
current debug frame function call.
of the list is 3.
This accesses the first argument to the
function in the

current

stack

frame.

Finally the CONTINUE command continues the

FUNCTION-X.

13.

Lisp>

(TRACE

(FUNCTION-X

: POST-DEBUG-IF
(FUNCTION-X)

Lisp>

#4:

(FUNCTION-X

(FUNCTION-X 5)

#11: (FUNCTION-X 4)
#18: (FUNCTION-X 3)

#25:
#25=>

#25:

$#25=>
$#18=> 2

(FUNCTION-X 2)
1

(FUNCTION-X

133

(FIRST

*TRACE-VALUES#*)

2)))

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRACE Macro (cont.)
(FUNCTION-X 2)

#18:

#18=> 1
Control Stack Debugger
Frame

#12:

Debug

(DEBUG)

BACKTRACE

Backtrace

Frame

#12:

Frame

#7:

start

(DEBUG)
(BLOCK
(IF

FUNCTION-X
(<

(FUNCTION-X

Frame
Frame
~--

#5:
#1:

1))
2)))))

(FUNCTION-X 5)
(EVAL (FUNCTION-X 5))

Backtrace

Frame

#12:

Debug

#11=>

((-

ends

(DEBUG)

CONTINUE

#11:

(FUNCTION-X 3)
#18: (FUNCTION-X 2)

$#18=>
#18:

1
(FUNCTION-X

#18=> 1
#11=> 2
Control Stack Debugger
Frame

#5:

(DEBUG)

Debug

CONTINUE

$d4=>

the
1in
TRACE is called for FUNCTION-X (the same function as
previous example) to start the debugger if the value returned
once when
The value returned exceeds 2 twice -exceeds 2.
it returns 3 and at the end when it returns 5.

134

VAX LISP/VMS FUNCTION,

*TRACE-CALLTM*
The
Or

Variable

*TRACE-CALL*
macro

call

MACRO, AND VARIABLE DESCRIPTIONS

variable,

being

debugging

tool,

bound

the

function

traced.

Examples
1.

Lisp>

(TRACE

(FUNCTION-X

: SUPPRESS-IF

This

causes

arqgument
Lisp>

(TRACE

FUNCTION-X
1

(SECOND

traced

: SUPPRESS-IF

(<=

(LENGTH

*TRACE-CALL*)

only

1)))

1its

first

less

(FUNCTION-X

*TRACE-CALL*)

2)))

This causes FUNCTION-X to be traced if it is called with more
than

Lisp>

argument.
(TRACE

(FUNCTION-X

: PREDEBUG-IF

(SECOND

*TRACE-CALL*)

: SUPPRESS-IF

(SECOND

*TRACE-CALL*)

2)))

FUNCTION-X

In this case, the TRACE macro is enabled for FUNCTION-X.
The
debugger
will be invoked and tracing suppressed i1f the first
argument to FUNCTION-X
(the
SECOND
of
the
wvalue
of
the
*TRACE-CALL*
variable)
1is
1less than 2.
So for example, if
FUNCTION-X is called with the arguments 3 and 5, *TRACE-CALL*
is
bound
to the form (FUNCTION-X 3 5); as 3 is greater than
2, the call is traced and the debugger not entered.
See
the
description
of
the
TRACE macro for further examples of the
use

*TRACE-CALL%*,

135

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

*TRACE-VALUESTM*

Variable

The *TRACE-VALUES* variable, a debugging tool, is bound to the list of
values
returned
by the traced function.
You can use the value bound
to this variable in the forms used with the trace option keywords such
as

:DEBUG-1IF.

Example

Lisp

(FACTORIAL

#4: (FACTORIAL 4)
#11: (FACTORIAL 3)
#18: (FACTORIAL 2)
#25: (FACTORIAL 1)
$#25=> 1
#25=> *TRACE-VALUES* is (1)
$#18=> 2
#18=> *TRACE-VALUES* is (2)
$#11=> 6
. #11=> *TRACE-VALUES* is (6)
#4=> 24
#4=>

*TRACE-VALUES*

(24)

In this case, the values returned by the FACTORIAL
function
and
(2),
(1),
as
displayed
are
variable
*TRACE-VALUES*
the
to
bound
Since the *TRACE-VALUES* variable is bound to the
(6), and (24).
list of values returned by a function, it can be used only in the
the
to
bound
being
Before
:POST- options to the TRACE macro.
return
values, it returns NIL.
See the description of the TRACE
macro

for

further examples

variable.

136

the

wuse

the

*TRACE-VALUES*

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
TRANSLATE-LOGICAL-NAME Function

Searches a logical name table for a logical name,
returns

The

list

TRANSLATE-LOGICAL-NAME

logical-name

translates

1it,

and

level

strings.

function

performs

only

one

translation.

This function is equivalent to the
DCL
SHOW
LOGICAL
command.
For
additional
information
about the SHOW LOGICAL command or about using
logical names, see the VAX/VMS DCL Dictionary.
Format

TRANSLATE-LOGICAL-NAME

string &KEY

:TABLE

:CASE-SENSITIVE

Arguments

string

The

logical name

for which the

function is to search.

: TABLE

The logical name table that the function is to search.
1If you do
not
specify
a
table
name, the process, group, and system name
tables are searched in that order.
The values
you
can
specify
with the

:TABLE

:PROCESS

Process name

: GROUP

Group name table (LNMS$GROUP)

: SYSTEM

System name

+ALL

Search all
(the

keyword are

table

the

following:

(LNMSPROCESS_TABLE)

(LNM$SYSTEM_TABLE)

three tables

(LNM$DCL_LOGICAL)

default)

:CASE-SENSITIVE

Used to restrict the search to a
case-sensitive
search.
vValid
values
are
T
(for
case-sensitive
search)
or
NIL
(for
T
Use a value of
The default is NIL.
case-insensitive search).
if you have multiple logical names that differ only in case.

Return Value

If the logical name has any translations, they are returned as
list of strings.
If is match found, NIL is returned.

137

VAX LISP/VMS FUNCTION,

MACRO, AND VARIABLE DESCRIPTIONS

TRANSLATE-LOGICAL-NAME Function (cont.)
Example
LiSp>

(DEFUN

SHOW-WHERE-I-AM

(&OPTIONAL
(STREAM

(FORMAT

*STANDARD-OUTPUT*)
)

STREAM

"Y&Current host is "A 7
“%Current device is A 7
“%Current directory is "A "%
(CAR (TRANSLATE-LOGICAL-NAME "SYSSNODE"))
(CAR (TRANSLATE-LOGICAL-NAME "SYSSDISK"))
]

(CONCATENATE

'STRING
Wg?@

(PATHNAME-DIRECTORY
(DEFAULT-DIRECTORY)
)
W}W}}

(VALUES))
SHOW-WHERE-I-AM

Lisp>

(SHOW-WHERE-I-AM)

Current

host

Current

device

Current

directory

Lisp>

(SETF

MIAMI::
1is

DBAl:
1s

[VAXLISP]

(DEFAULT-DIRECTORY)

"SYSSLIBR ARY")

"SYSSLIBRARY"
Lisp>

(SHOW-WHERE-I-AM)

Current
Current

host i1s MIAMI::
device is SYSSSYSROOT:

Current

directory

[SYSLIB]

The
<call
to
the
DEFUN
macro
defines
a
function
named
SHOW-WHERE-I-AM,
which displays the current host, device, and
directory.

The

first call

current

call

host,

to the
device,

the

function

SHOW-WHERE-I-AM

displays

the

and directory.

The

SETF macro changes

The second call to the function SHOW-WHERE-I-AM
1includes
new directory in the output the function displays.

138

the directory to SYSLIB.

the

VAX

LISP/VMS

FUNCTION,

UNBIND-KEYBOARD-FUNCTION

MACRO,

AND VARIABLE

DESCRIPTIONS

Function

Removes the binding of a function from a contrdl character.
Format

UNBIND-KEYBOARD-FUNCTION

control-character

Argument

control-character
The

control

character

from which

function’s

binding

not

removed.
Return

Value

bound

binding

removed.

NIL,

the

control

character

function.

Example

Lisp>

(BIND-KEYBOARD-FUNCTION

#\"B

#’BR

Lisp>

(UNBIND-KEYB

~-FUNCTION

#\"B

The
to

The

call
the

call

binding

the

BREAK

to
of

BIND-KEYBOARD-FUNCTION

function

binds

CTRL/B

function.

the
the

UNBIND-KEYBOARD-FUNCTION
function

that

139

bound

function
CTRL/B.

removes

the

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

UNCOMPILE Function
Restores the interpreted function
definition
of
a
symbol,
1if
the
symbol’s definition was compiled with a call to the COMPILE function.

The UNCOMPILE function is useful for editing function definitions
and
debugging.
For example, if you are not satisfied with the results of
a function compilation, you can uncompile the function, edit
it,
and
then

recompile

1it.

NOTE

You cannot uncompile system functions
and
macros
or
functions
and macros that were loaded from files that
were compiled by the COMPILE-FILE function or the
DCL
/COMPILE qualifier of the LISP command.

Format

UNCOMPILE symbol
Argument

symbol

The symbol that

represents the function that is to be uncompiled.

Return Value

The name of the function, if the specifed
symbol
represents
an
existing
compiled
lambda
expression
and
has
an
interpreted
definition;

NIL,

it does

not.

Example

Lisp>
ADD2

Lisp>

ADD2

Lisp>

(DEFUN ADD2

(FIRST

SECOND)

(+ FIRST SE

(COMPILE ’ADD2)
compiled.

(UNCOMPILE

'ADD2)

ADD2

The call to the DEFUN macro defines the function ADD2.

The call to the COMPILE function compiles the function ADDZ.

the
restores
The call to the UNCOMPILE function successfully
interpreted
definition
of
the
function
ADD2,
because the
function

1is

defined

and

function.
140

was

compiled

with

the

COMPILE

VAX

LISP/VMS

FUNCTION,

MACRO,

AND VARIABLE

DESCRIPTIONS

UNDEFINE-LIST-PRINT-FUNCTION Macro
Disables

the

list-print

function

undefined,

the

list-print

function

See

Chapter

older

for

function

was

function
exists

defined

superseded
1is

for

the

symbol.

reenabled.

another

1list-print
Otherwise,

the

given

symbol.

information

about

list-print

function
no

functions.

Format

UNDEFINE-LIST-PRINT-FUNCTION

symbol

Argument

symbol

The

name

the

list-print

function

the

list-print

function

that

disabled.

Return Value

The

name

has

been

Example
Lisp>

(UNDEFINE-LIST-PRINT-FUNCTION

MY-SETQ)

MY-SETQ

Undefines

the

list-print

function

141

named MY-SETQ.

disabled.

other

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS

UNIVE RSAL-ERROR-HANDLER

Function

The function to which the VAX LISP system sends all
errors
that
are
signaled
during
program
execution.
By
default,
the
VAX LISP
*UNIVERSAL-ERROR-HANDLER* variable is bound to this function.
The VAX LISP error handler

is described in Chapter

Format

UNIVERSAL-ERROR-HANDLER function-name
error-signaling-function &REST args
Arguments

function-name

The name of

the

function that produced or

signaled the error.

@rror~signaling~function
The name of an error-signaling function.
CERROR,

Valid

function

names

and WARN.

are

ERROR,

The

specified error-signaling

args

Return

function’s arguments.

Value

Invokes

the VAX LISP debugger,

exits

the

LISP

system,

returns

NIL.

Example

Lisp>

(DEFUN

CRITICAL-ERROR-

&REST AR@S}
Q

ERROR-SIGNALING-FUNCTION

ASH-ALARM-LIGHT)
)

'ERROR)
’CERROR ) )

%figfi& ERROR-HANDLER

%”@%}}

CRITICAL-ERROR-HANDLER

or
fatal
a
whether
checks
that
handler
error
an
Defines
of error 1is
type
either
If
signaled.
1is
error
continuable
the
signaled, the handler flashes an alarm light and then passes
For
the universal error handler.
to
information
signal
error
information on how to create an error handler, see Chapter 4.

142

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIO
*UNIVERSAL-ERROR-HANDLERTM* Variable
By default, this variable is bound to the VAX LISP error handler,
UNIVERSAL-ERROR-HANDLER function.
If you create an error handler,
must bind

the

*UNIVERSAL-ERROR-HANDLER*

the
you

1t.

Example

Lisp>

(DEFUN CRITICAL-ERROR-HANDLER

(FUNCTION-NAME
ERROR-SIGNALING~-FUNCTION

&REST
(OR

(WHEN

ARGS)

ERROR~-SIGNALING-FUNCTION

ERROR-SIGNALING-FUNCTION

'ERROR)
’CERROR))

)
(FLASH-ALARM-LIGHT)

(APPLY

#'UNIVERSAL-ERROR-HANDLER
FUNCTION-NAME

ERROR-SIGNALING-FUNCTION
ARGS))

CRITICAL-ERROR-HANDLER

Lisp>

(LET

((*UNIVERSAL-E]

$#"CRITICAL-ERROR

(PERFORM-CRITICAL-OPERATION)
)

The call to the DEFUN macro defines

error

handler

named

CRITICAL-ERROR-HANDLER.

the
binds
LET
form
special
the
to
call
The
variable to the error handler named
*UNIVERSAL-ERROR-HANDLER*
CRITICAL-ERROR-HANDLER,
function

while

evaluated.

143

the

PERFORM-CRITICAL-OPERATION

VAX LISP/VMS

WARN

FUNCTION,

AND VARIABLE

DESCRIPTIONS

Function

Invokes

the

VAX

LISP

error

message

and

variable.

value

not

the

error

value

NIL,

variable.

:EXIT

the

handler

the

handler

For

causes

invokes

The

the

information

the

VAX

handler

the

functions

checks

the

returns

the

1If

exit;

the
1f

value

the

NIL;

wvalue

*ERROR-ACTION*

keyword.
to

displays

*BREAK-ON-WARNINGS*

WARN

system

LISP

handler

value

:DEBUG

LISP

error

wvalue

=error

the

The

the

NIL,

the

*ERROR-ACTION*

either

handler.

checks

error

MACRO,

the

variable

value

can

:EXIT,
is

the

:DEBUG,

debugger.

warnings,

see

Chapter

Format

WARN

format-string

&REST

args

characters

that

passed

the

Arguments

format-string
The

string

create

warning

the

FORMAT

function

message.

args

The

arguments

for

the

that

format

are

FORMAT

function

arguments

string.

Return Value
NIL.

Example
Lisp>

(DEFUN

LOG-ERROR-STATUS

(DECLARE

(LET
(IF

(SPECIAL

( (MESSAGE

(VMS-STATUS)

*ERROR-LOG*))

(GET-VMS-MESSAGE

VMS-STATUS

#*1111)))

MESSAGE
*ERR OR-~-L

OG*)

"There

message

for VMS

status

#X 8,’0X."

error-logging

facility.

VMS-STATUS)
))
LOG-ERROR-STATUS

Defines

function

system

logs

the

service

returns

warning

message

error

that
VMS

status
is

status

RTL

an
that

routine.

that

has

displayed,

and

144

no
no

returned

from

<call-out

the

corresponding
log

entry

The

call-out

message

facility
text,

produced.

VAX LISP/VMS FUNCTION, MACRO, AND VARIABLE DESCRIPTIONS
WITH-GENERALIZED-PRINT-FUNCTION Macro

the
evaluates
it
Locally enables a generalized print function when
for more information about using
6
See Chapter
forms.
specified
generalized print

functions.

Format

WITH-GENERALIZED-PRINT-FUNCTION name &BODY forms
Arguments
name

A symbol
enabled.

function to be
generalized print
the
identifying
supersedes any
function
print
generalized
enabled
The

previously enabled generalized print function for name.

forms

A call

calls

to print

functions.

Return Value

Output generated by the call or calls to print functions.
Example

Lisp>

(DEFINE-GENERALIZED-PRINT-FUNCTION PRINT-NIL-AS-LIST
(OBJECT

(NULL

(PRINC

STREAM)

OBJECT)

STREAM))

PRINT-NIL-AS-LIST

Lisp>

(WITH-GENERALIZED-PRINT-FUNCTION
(PPRINT

'PRINT-NIL-AS-LIST

NIL))

()

the generalized print
because
),
(
The PPRINT call prints
function is enabled locally and pretty printing is enabled.

145

APPENDIXES

APPENDIX A

PERFORMANCE

HINTS

LISP code normally does much type checking at runtime.
You can reduce
execution
time and amount of memory required by using data structures
more efficiently
and
by
wusing
certain
programming
and
debugging
techniques.
This appendix lists what you can do to optimize the speed of execution
of
your
LISP
code
and the amount of memory required.
The sections
also give the

following information:

Number of instructions executed by certain functions

Relative speed of certain functions compared with others

Explanations of why certain functions and

can be used to achieve the

so much

time

same

that

result

operations

require

and memory

Data structure

representation

This information can help you choose the most efficient way to code

program.

Some VAX instructions are mentioned in this appendix.
Refer
to
the
VAX Architecture Handbook for more information on the VAX instruction
set.

A.1

DATA STRUCTURES

This section describes how to optimize the use of data
your

code.

structures

1in

PERFORMANCE

A.1.1

Integers

Fixnum

arithmetic

possible

integers
in

use

half:

-2**28
in

argument

generate

arithmetic

are

not

Keep

Fixnums

are

never

manipulated

this

than

require
the

bignums

likely

in mind when

placing

function

and

for

result

VAX

fixnum,
be

instructions.

and

even

though

all

the

result

may not

arithmetic

which

each
of
need

allocated

CMPL
not

(they

rather

fixnum

are

less

memory
bignums.

for

two’s

much more

and

and division
and

the

an
1is,

each)

and

operation.
appropriate

they

are

pointers).

less

header

complement
time

instruction

immediate:

with

consumes

one

through

requires

for

(That

declared.

than

longwords

values

be.

arithmetic
takes
two
operation
(except

instruction

arithmetic

number

subtraction

require

must

operations).

multiplication
a

input

for

as well

result

fixnums,

under

type

the
The

of
cut

fixnum

arithmetic

and

format.

time

enough

garbage

space

Therefore,

than working with

always

Therefore,

for

working

fixnums.

example, to print 1000 factorial takes much longer than to
Much
more
garbage
1is
produced
while
calculating
representation than in calculating the result.

A.1.2

range
to

declarations

in-line

two

1is

fixnum

directly,

fixnum arithmetic

versions

Therefore,

(The

use

for

result’s

with

future

2**29-1.

must

consist

the

arithmetic.

You

and decrementing,

branch;

represent

2**28-1.

closed

comparisons

Bignums

bignum

-2*%%29

programs.)

type

instructions

collection

than

range

declarations
are
wused,
for
each
addition
or

incrementing
Fixnum

the

fixnums

function may

~When
fixnum
instructions
four

your

faster

fixnum-only

declared
fixnums

much

represented

declarations

each

1is

numbers

HINTS

For

compute 1it.
the
print

Floating-Point Numbers

When using

floating-point arithmetic, the system allocates
new
space
for
the
results.
1In-line code is generated only when both arguments
to
an
arithmetic
function
are
declared
to
be
of
the
same
floating-point
type.
In-line conversions (CVTxx) are not done.
The
VMS math library routines are used for complicated functions, such
as
trigonometric

functions.

Floating-point

numbers

A.1.3

always

have

l-longword header.

Ratios

When working with ratios, the system calls the GCD function after each
ratio
1is
created,
and
stores the ratio in canonical form.
Use the
TRUNCATE or REM function when you do not need exact
answers
or
when
PR

A-2

PERFORMANCE HINTS

you want
a
remainder.
The TRUNCATE function executes faster if you
can declare the result to be a fixnum.
The TRUNCATE and REM functions
are faster than the FLOOR and MOD functions.
These in turn are faster
than

the

ROUND

function.

Ratios occupy two longwords;

A.1.4

they do not have headers.

Characters

specify
to
When representing characters, it is usually not necessary
bit and font attributes.
String characters utilize an 8-bit code that
is compatible with the ASCII and DIGITAL multinational standards,
and
with

the

VAX

architecture.

The CHAR= function used without type checking is the same
as
the
EQ
the
generate
functions
CHAR>=
and
CHAR>,
CHAR<=,
CHAR<,
The
function.
required
same code as the fixnum comparisons when no type checking is
CMPL
a
of
consists
code
This
wused.
were
declarations
because
instruction
followed
by
the
appropriate
branch.
Like
fixnums,
characters are never allocated (they are immediate), thereby requiring
less memory and less

A.1.5

time

for garbage collection.

Symbols

are
Symbols
name.
a
with
data
associate
symbols let you easily
interned
when
read
by
the READ function, and remain interned until
they are uninterned from all packages using them.
So, when you create
use uninterned symbols (created
functions,
and
variables
anonymous

using the MAKE-SYMBOL or GENSYM function).

several
require
may
dynamic variable
a
accessing
LISP,
For VAX
used.
optimizations
and
declarations
the
on
depending
instructions,
local
accessing
than
slower
is
variable
Normally, accessing a dynamic
A
variables.
lexical
but faster than accessing closed-over
variables
local variable can be accessed quickly because it
is
stored
on the
1is stored in a vector and passed to
variable
A closed-over
stack.
closed-over
a
access
to
Therefore,
other functions that use them.
To reduce the overhead of
may require several instructions.
variable
optimization
the
set
instruction,
one
to
dynamic variable access
variable
unbound
eliminating
0,
to
SAFETY
and
3
to
SPEED
declaration
checking,

and thus

reducing execution time.

When a special variable is bound to a new value, LISP saves the symbol
and its old value on the binding stack and stores the new value in the
four or five
either
requires
This
symbol.
the
of
cell
value
Unbinding a special variable requires one instruction.
instructions.
Accessing the parts of a symbol, such
as
its
name,
property list,
requires only one instruction each, if you have
and value,
package,
A-3

PERFORMANCE

used the
However,
Symbols

A.1.6

HINTS

appropriate declarations to declare the variable
setting a symbol’s function cell is very slow.
occupy

five

longwords

symbol.

each.

Lists and Vectors

Use lists when the number of elements changes often.
Typically,
vyou
push
elements
onto
and
pop
elements
off the front of the list to
simulate a stack.
Conses are convenient for creating tree structures,
especially
when
vyou
need
values
only
at the leaves.
If you must
access many values at each internal node of
a
tree,
wuse
structures
rather than lists.
Conses require two longwords.

Use vectors when you must
access
elements
often
at
any
position.
Vectors
wuse
half
as
much space as lists, and can cause less paging
when accessed because vector elements are stored
in
adjacent
memory
locations.
A simple-vector has a single-longword header.
Use the noncopying (or destructive) versions of the sequence and
1list
functions
whenever
possible.
For
example,
the
NCONC function 1s
faster than the APPEND function and
the
NSTRING-UPCASE
function
1is
faster
than
the
STRING-UPCASE
function.
You
can
use
the
form
(NREVERSE (THE LIST x)) rather than the copying version
(the
REVERSE
function) to get elements back to their original order 1f you are just
gathering the results in a list.
To copy input lists or strings
once
and
then
do
destructive operations is more efficient than to always
use

copying versions

functions.

Copying vectors by using the COERCE
or
SUBSEQ
function
results
1in
simple
vectors
(of
the
type
SIMPLE-VECTOR,
SIMPLE-STRING,
SIMPLE-BIT-VECTOR,
or
SIMPLE-ARRAY)
which
<can
be
manipulated
by
simpler,
faster
operations.
Therefore,
you
can
copy a vector to
manipulate it quickly thereafter.
However, to avoid numerous
garbage
collections, do not use copying versions of functions unless you must.

NOTE
Use destructive versions of functions
shared data may be modified.

with

care,

CAR, CDR, and the other list-manipulating functions by default
always
check
their
arguments to make sure they are lists and not atoms.
To
increase the speed of list-intensive
applications,
properly
declare
all
1lists and use the optimization declaration SPEED = 2 or use SPEED
= 3 and SAFETY = (0.
The CAR, CDR, RPLACA, and RPLACD
functions
each
require one instruction when used with these declarations.

PERFORMANCE

HINTS

the
to
pointer
If you frequently splice or concatenate lists, use a
NTHCDR,
the
using
than
This is faster
1list.
the
of
end
or
middle
MEMBER, APPEND, and NCONC functions on the entire list, as they always
process
from
the
beginning
of the list.
The fastest (and default)
tests for the MEMBER, ASSOC, and RASSOC functions are EQ and EQL.

1in
global
to be
keys
for
Use property lists when you want values
fairly
is
keys
of
number
the
if
lists
property
use
not
Do
scope.
a
Instead, use structures and include
constant and known in advance.
for
list
property
a
like
used
be
to
list
a
the structure for
in
slot
the

keys

that

change.

1in
Use association lists when you want values for keys to be dynamic
onto the front of an association list
entries
pushing
since
scope,
You can use dynamic variables as pointers 1into
shadows later entries.
association lists to help you recall additions to the lists.

A.1.7

Strings, General Vectors, and Bit Vectors

(vectors
vectors
Simple-vectors are processed faster than nonsimple
displaced vectors).
or
vectors,
adjustable
pointers,
fill
with
array
separate
Simple-vectors take less space since they do not have
headers and they are

created

faster.

(that
names
Avoid using lists of characters when manipulating symbol
supported
fully
are
Strings
IMPLODE).
or
never implement EXPLODE
is,
common
Some
LISP.
of
wversions
older
in this language, unlike in
operations on simple strings use the VAX character instructions.

be
can
1lists
Many data structures that used to be implemented with
default
(the
simple-vectors
with
implemented
efficiently
more
set
and
fixed
If the domain of a set is
DEFSTRUCT representation).
than
faster
much
is
vectors
bit
simple
using
frequent,
are
operations
structure
a declared
of
slots
Accessing or updating
using lists.
declarations.
appropriate
the
instruction given
only one
takes
1in a
bits
or
string
simple
Accessing or updating characters in a
vector is slower than accessing or updating elements of a
simple bit

simple
simple-vector; when accessing or wupdating characters 1in a
string or bits in a simple bit vector, data must be converted between
For both
representation.
LISP
the internal representation and the
instruction.
ASHL
an
least
at
involves
this
fixnums,
and
characters
strings
simple
handling
However, there are specialized routines for
BIT-AND
and
STRING-UPCASE
the
example,
(for
bit vectors
simple
and
functions with the proper declarations).

These representations take less space than simple
characters

bits.

vectors

that

hold

PERFORMANCE

A.1.8
Hash

Hash Tables
tables

provide

objects.

Although

the

total

time

objects.

You

can

hash

are

faster.

must

tables

code

can

are

faster

than

single

compile

anonymous

FUNCTION
inform

chains

the

that

and

use

bit

large

store,
numbers

collisions.

functions
the

and

for

1large

resolve

EQL

arbitrary

access

for

garbage

vectors
and

each

because

the

each

accessing

even

function,

and

faster

comparisons

EQL

functions

collection.

Hash

representing

sets,

extremely

variable.

the

DECLARATIONS

This

section

and

for

many

describes
most

other
type.

Whether

the

extent

(COMPILE

interpreted

any

time

without

vyou

have

just

NIL

stored

specifier

about

operations
Therefore,

compiler

values

type

how

standard

does,

generated,

such

attributes.

simple

correct

the

when

code

the

“(LAMBDA

and

types

executed

()

the

files.

you

,...)

later.

declaration

using

defined,

arguments

you

You

For

can use
want

can

use

proclamation
and

the

return

LISP

code.

function.

default,

type

code;

functions.

function

type

compiler

interpreted

occurs.

functions

code

FTYPE

A.2

for

after

regular

’'FUNCTION-NAME)

create

may

than

slower

type

use
EQUAL

tables

objects

required

use

that

lists

and

reasonable

the

rehashed

consing

(COMPILE

tables

hash
to

usually

use

much

compile

example,

the

storing

Functions

Closures

overhead

tables

preferable
of

way

hash

that

However,

evaluated,

You

LISP

hash

number

Compiled

VAX

tables

are

good

some

completely

the

A.1.9

required

access

than

when

HINTS

given

takes

use

declarations

VAX

LISP

functions

The

compiler

assuming

the

declarations

use

advantage

controlled

the

optimization

the

presence

declarations.

the

can

optimize

check

their

generate

qualities,
type

arguments
supply

faster

are

this

declarations,

OPTIMIZE

arguments

much

different
or

the

information.

and

declaration.

declarations

for

code

code
the

what

Depending

may

assumption

PERFORMANCE

HINTS

NOTE
Currently,

the

COMPILATION-SPEED

quality

ignored.

The format fbr using the OPTIMIZE declaration and its qualities with
the

PROCLAIM

and

(PROCLAIM

DECLARE

functions

' (OPTIMIZE

(SPEED

follows:

(SAFETY

(SPACE

z)))

(DECLARE

The

possible

x=1,y=1,z=1

(OPTIMIZE

switch
(the

values

(SAFETY

(SPACE

2z)))

are:

default)

particular

done

(SPEED

optimizations

all

arguments

done.

LISP

Generally,

type

checking

will

functions.

x=2,y<2

Observes
are

user

supplied

guaranteed

but when not
guaranteed
DOLIST)

all
to

declarations.
of

the

variables
be

expand

(such

correct.

into

code

Useful

declared
as

macros
these

when
and

function

Some
with

type

some

speed

variables
is

argquments)
(such

desired,
can

DOTIMES

and

declarations

already

supplied.

X>1,y=0
Skips

bounds

checking

for vector

and

array

references.

x=3,y=0

Assumes

correct

SYMBOL-NAME,
debugged

argument

and

types

SCHAR.

functions.

many

Useful

Special

functions,

for

variable

such

guaranteed

references

correct
not

check

CAR,

and
for

unbound values.
X>y

Does

tail

recursion

removal,

can.

y=3
The

THE

type.
bignums.

function

Useful

generates

for

tests

for

objects

fixnum declarations

being

to detect

the

specified

overflows

into

PERFORMANCE

HINTS

X>2

Tries

to open-code

some

sequence

functions.

Observes

1in-line

declarations.

Explicit type checking code, such as (IF (CONSP
X)
...),
1s
always
executed
regardless
of a type declaration for X and the optimization
settings.
Therefore, you can retain type checking and still
increase
the
speed
of
execution
by
wusing
declarations.
In the following
example, faster code is generated for
incrementing
X
by
wusing
the
appropriate
optimization
settings
without
having
to
rebind
X.
Meanwhile, type checking is retained at the start of the
function
by
using the

explicit

(DEFUN

FOO

(DECLARE
(IF

checking

code

(IF

(FIXNUMP X).

(X)

(FIXNUM

X))

(FIXNUMP

(LET

(INCF

...

(ERROR

Another
that
a

type

...)

...)))

function that always executes is COERCE, since it
1s
assumed
type
check will be executed, even if no coercion needs to be

done.

Use fixnum and floating-point declarations for fast
arithmetic.
The
compiler
needs
to
know
the
types
of
all
the arguments (and for
fixnums, the result type,
too)
before
it
can
generate
the
fast,
type-specific code available on a VAX.
Floating-point operations with
operands (and therefore results) of the same type can
also
generate
fast

code.

Use simple-vector and similar array declarations for fast sequence and
array operations.

Declaring

structures

is equally helpful.

The PROCLAIM and DECLARE functions are used to
declare
arguments
and
results whenever the function is called.
when

the

proclamation

(PROCLAIM

"{FTYPE

function’s
For example,

( FUNCTION

(FIXNUM)

SINGLE-FLOAT) MYFUNCTION)) is used, each time MYFUNCTION is called the
arguments are automatically declared to be fixnums and its
result
1is
automatically
declared
to
be
a single-float.
An FTYPE declaration
does not automatically provide declaration of the LAMBDA-LIST variable
in

the

function definition.

It is important to
provide
type
declarations,
especially
for
the
SIMPLE-VECTOR,
SIMPLE-STRING,
and
SIMPLE-BIT-VECTOR
types, for the
arguments to sequence functions.
The compiler can generate fast
code
for many common cases such as calls without any keyword arguments.

Multidimensional array operations also need declarations.
Unlike
the
vector
operations,
multidimensional
arrays need the actual (fixnum)
bounds for each dimension at compile-time, to generate efficient array
indexing
code.
In these cases it is helpful to use the DEFTYPE macro
or a macro that expands into a call to the DECLARE function.
A-8

PERFORMANCE

HINTS

The functions defined in the following examples will be compiled
with
either
(1)
type-checking
code
if
SPEED
1is
1less
than
2, or (2)
non-type-checking
code
if
SPEED
equals
3
and
SAFETY
equals
0.
However, the second example produces code that does not check the type
of X but does check the type of (CDR
X),
when
SPEED
equals
2
and
SAFETY
1is
1less
than
2.
This
1is
because
there is a declaration
allowing the optimization of the CDR operation, but no declaration for
the

CAR

operation.

(DEFUN
(CADR

(DEFUN

EXAMPLE1l

EXAMPLE2

(DECLARE
(CADR

(X)

X))

(LIST

(X)
X))

X))

In the following examples, a call to EXAMPLE3 always produces
generic
code,
since
it
is
not
known
that the result of the addition will
necessarily be a fixnum.
The declaration in
EXAMPLE4
provides
that
information, and all the arithmetic operations are fixnum-specific.
(DEFUN

EXAMPLE3

(DECLARE
(+

(DEFUN

(FIXNUM

Y))

EXAMPLE4

(DECLARE

(THE

(FIXNUM

FIXNUM

Y))

Y)))

The next example returns a
list
of
the
first,
indexed,
and
last
characters.
With SPEED greater than or equal to 2 and SAFETY equal to
very
be
will
0, all the character fetching from the STRING argument
fast.
The LENGTH operation will also be very fast, since it need not
function
check for the type of the argument like the generic sequence
normally would.

(This also means executing the

form

(LENGTH

(THE LIST

X)) is faster than executing
the
form
(LENGTH X).)
If
SAFETY
is
greater
than
0, bounds checking is still done, but type checking (of
optimizations
the string, for example) may not be, depending on what
are

used.

(DEFUN EXAMPLES5

(STRING

INDEX)

(DECLARE

(SIMPLE-STRING
(FIXNUM

(LIST

Array access

STRING)

INDEX))

(AREF

STRING

(CHAR

STRING

INDEX)

(LENGTH STRING)))))

(SCHAR STRING

(1-

following code:

fast

in the

PERFORMANCE HINTS

(COMPILE LOAD EVAL)
I-SIZE 3)

(EVAL-WHEN

(DEFCONSTANT

(DEFCONSTANT J-SIZE 4)
(DEFCONSTANT K-SIZE 5)
(DEFTYPE FOOARRAY (&OPTIONAL ELEMENT-TYPE)

,ELEMENT-TYPE

“\(SIMPLE-ARRAY

(DEFUN

FOO

(DECLARE

(FOOARRAY STRING-CHAR)

A.3

Y))

I-SIZE)

(DOTIMES

(FOO

,K-SIZE))))

(FOOARRAY T)

(TYPE

(DOTIMES

(SETF

,J-SIZE

()

(TYPE

(DOTIMES

(,I-SIZE

J-SIZE)

K-SIZE)

(AREF

K)))))))

PROGRAM STRUCTURE

1in
Avoid using closed-over variables (that is, lexical variables used
References to closed-over
scope).
their
created within
functions
(which
local variables
variables are slower than references to true
allocated), because closed-over variables must be found in
stack
are
that may take
simple vectors that represent the lexical environment
several

instructions.

than
rather
functions
in-line
or
In tight inner loops, use macros
in-line,
Always compile macros, functions declared
functions.
called
and calls to the DEFSTRUCT macro before compiling code that uses them.
function in-line just before defining it.
you proclaim a
Normally,
any calls to that function will then have the body expanded in-line at
If you
unless you use the NOTINLINE declaration.
site,
calling
the
without
declaration
INLINE
the
using
function
a
proclaim
or
declare
providing a definition, a compiler error will result because no
later
definition was provided for an in-line function.

functions
to
<calls
than
The FUNCALL and APPLY functions are slower
This is because the LISP
time.
compile
at
known
are
names
whose
system must check the

following:

Whether the object is a function

What

kind

interpreted

function

compiled)

(by

symbol

function

object,

PERFORMANCE

@
The

The

number

FUNCALL

than

and

HINTS

arguments

the

function takes

APPLY

functions

are

usually

compiled

call

fixed

two

function

three

with

times

fixed

slower

number

arguments.

The

CATCH

special

mechanism

are

form

slower

and

operations

than

calling

that

wuse

the

function,

catch-throw

wusing

the

APPLY

function.
No

penalty

&OPTIONAL

than

for

variable

the

causes

required

they

have

code

and

the

inflicted

created

&OPTIONAL

parse

wusing

required

list

consing

for

wusing

that

for

arguments.

overhead

1list

and

the

lambda-list

arguments.

those

&KEY

&REST

assign

arguments

keyword,

the

keyword

However,

proper

&REST

passed

are

the

plus

the

values

for

after

slowest;
run-time

the

given

keywords.

Using
or

multiple

vector

single
The

values.

(Consing

requires

function

READ

has

the

and

intern

symbols.

FORMAT,
and

object
The

the

function
The

for

compiler

file

READ-CHAR

the

current

The

due

list

function,

LISP

READ-CHAR

the

returning

later.)

functions

for

getting

faster

than

wusing

the

stream

functions

same

general

reader

function

overhead

(DEFUN

are

function

The

faster

the

representation

WITH-OUTPUT-TO-STRING

must

functions.
than

string

create

stream and

READ-FROM-STRING

and

WITH-INPUT-FROM-STRING

reason.

compiles

surrounding

(PROGN

function,

WITH-OUTPUT-TO-STRING

the

just

functions.

1is

usual

PARSE-INTEGER

consing

than

and PPRINT functions are slower than explicit calls

PRIN1

xxx-TO-STRING

function.

use

READ-LINE

than

READ-LINE

numbers,

the

LISP

the

space
slower

collections

according

and RMS.

garbage

input

streams

Using

than

and
are

the

than

PRINC

slower

time

methods

parse

slower

The WRITE,

create

the

less

Both

syntax,

requires

results.

READ

since

values

each

top-level

arbitrary

forms

form
in

the

#:TOP-LEVEL-FUNCTION

file

when

following

()

compiles

manner:

arbitrary-top-level-form)

(# :TOP-LEVEL-FUNCTION))
An

arbitrary-top-level-form

EVAL-WHEN

PROCLAIM

dumping,
wise

and
gather

Typically,

(such

function

PROGN

function,

such

(SETF

definition

initialization

from

these

...)

can

the

form,

forms
be

the

other

DEFUN

functions

data

have

desirable

program without
A-11

than

call

DEFMACRO

Creating,

functions

into

calls

form

function.

temporary

...)).

anyway

LISP

package

arbitrary

forms

(GET

any

special
or

1loading
many

takes
of

the

macro,

the

compiling,

time,

initialization

these

function

you

that

having

reasonable

calls

can

relocad

do
the

size.

functions

inside

selective
file.

PERFORMANCE HINTS

A.4

COMPILER REQUIREMENTS

The PROCLAIM,

PROVIDE,

and package functions like USE-PACKAGE

REQUIRE,

for the compiler to
"top 1level"
IN-PACKAGE must be used at
and
form without
a
as
defined
is
form
top-level
A
them.
recognize
a call to
within
level
top
at
form
a
or
surrounding parentheses,
either the EVAL-WHEN or PROGN special form.

Uses of the

DEFUN

macro

and anonymous lambdas that would get evaluated in code get compiled as
This
separate functions (closures if they use closed-over variables).
is

true in the following call to the DEFUN macro and to the anonymous

lambda

that

follows.

(LET

((COUNTER 0))

(DEFUN NEXT

(TRY

#’ (LAMBDA

(X)

(PRINT X)))

()

(INCF COUNTER)))

structures
data
1in
is,
If you want functions as data objects (that
you must
evaluation),
normal
they would not be processed during
where

compile them

between

the

(LIST

explicitly.

This

exemplified

the

difference

following:
#’' (LAMBDA

()

(FO0O0))

#’ (LAMBDA

()

(BAR))

)

and
'(

#'(LAMBDA

()

(F00))

#’ (LAMBDA

()

(BAR))

)

creates
In the first case, the compiler recognizes the functions and
In the second case, the compiler
compiled-function objects for them.
does not notice the fucntions since the entire form is quoted.

to
If you leave the code in the list at run time, the explicit calls
code
the
run
would
list
the
of
element
each
on
FUNCALL function
the
So, to have compiled code in the list, you must fill
interpretively.
You can do this at run time by using the
it with compiled functions.
COMPILE function with NIL as the first argument, or you can fill the
Or, you can compile
list with compiled functions once, when loading.
a file, using macros that expand into definitions of functions with
Then, have an initialization
names created using the GENSYM function.
function fill up the list with those compiled functions at load time.

APPENDIX B

USING THE "EMACS” EDITOR STYLE

This appendix provides information on the "EMACS" Editor
style.
The
"EMACS"
style consists of a collection of key bindings that cause the
Editor to behave like the EMACS editor.
This
appendix
1lists
these
bindings and explains how to activate the "EMACS" style in the Editor,
but does not provide any tutorial information on using EMACS.
This

appendix

organized

Section B.1

explains

follows:

to a new user

Editor.

Section B.2 describes how to activate the
minor
or
major
style,
thus making the
available

B.1

how

learn

about

the

"EMACS"
"EMACS"

style
as
a
key bindings

you.

Section B.3 lists the key bindings in the "EMACS“ style.

INTRODUCTION TO THE EDITOR

To learn about the Editor, read Chapter 3 of this manual.
Most of the
information
in
Chapter 3 is also true when you are using the "EMACS"
style.
The chief difference when you are using the "EMACS" style lies
in
the
key
bindings.
1In many instances, keys or key sequences that
invoke one command when you are not using the "EMACS" style
1invoke
a
different
command
when
the
"EMACS"
style
1s
active.
Table B-1
compares default Editor key bindings with EMACS key bindings,
showing
where
differences
exist.
Wwhen reading in Chapter 3, keep these key
binding differences in mind.
Table B-1 is arranged in the approximate
order
that
the key bindings and commands are presented in Chapter 3.
(Table B-1 lists only those commands listed in Chapter
3.
The
full
set of "EMACS" style key bindings is presented in Section B.3.)

S ection 3.2, which concerns ed iting operations,
contains
information
on
editing
wusing
(among other things) the numeric keypad.
Keys and
key sequences on the numeric keypad are set
up
to
emulate
the
EDT

B-1

USING THE

editor.
keypad

If
keys

active).

are
to

However,

similar

produce

confusion

Tablie

B-1:

EMACS

using

editing

(as

the
a

Differences

the
long

Between

style,

the

you

"EDT

may

EMACS

still

can

Emulation"

performed

operations,

seasoned

EDITOR STYLE

"EMACS"

operations

editing
in

"EMACS”

these

Binding

"EMACS"

CTRL/Z

ESCAPE
CTRL/Z

"EMACS”

Binding

different

Key Bindings and

Commands
Execute
Pause

Named

Command

Editor

None

CTRL/X

Write

Current

None

CTRL/X

CTRL/M

Write

Modified

None

CTRL/X

CTRL/W

Write

Named
Window

CTRL /X

CTRL /N

CTRL/X

CTRL/R

CTRL/X

Remove

None

CTRL/X

CTRL /W

CTRL/L

Remove Other

Windows

Commands

CTRL/X

CTRL/I

Insert

File

None

ESCAPE

Query

None

ESCAPE

CTRL/G

Exit

Recursive

None

ESCAPE

Upcase

None

ESCAPE

Downcase

None

ESCAPE

Capitalize

None

CTRL /X

Select

CTRL /X

CTRL/B

List

None

CTRL /X

CTRL/D

Delete

Word
Word

Buffer

Buffers
Current

CTRL /X

CTRL/E

None

CTRL /X

CTRL/V

Edit

None

CTRL /X

Grow Window

None

CTRL /X

CTRL/Z

Shrink Window

None

CTRL /X

Split Window

Customizing
CTRL /X

Edit

Word

None

CTRL/E

Replace

and Window Commands

None

CTRL/X

Window

Screen

None

Buffer

Buffers

File

Current

Redisplay

Editing

Buffer

File

Commands
Execute

Keyboard

Macro

while

enough

Default

Command

CTRL /G

user.

General-Purpose

CTRL /X

the

keys,

Bindings
Default

use

style

USING THE "EMACS” EDITOR STYLE

B.2

ACTIVATING THE "EMACS”

STYLE

By default, the Editor has "EDT Emulation" as its major style and "VAX
LISP" as its only minor style.
(If you are not editing LISP code, the
"VAX LISP"
style
will
not
be
active.)
Section
3.5.1.4
contains
information
about
styles.
To summarize:
Whenever you press a key,
the Editor looks in various places to see if that key is
bound
to
a
command.
The Editor first checks the current buffer; then checks the
minor styles, looking at
the
most
recently
activated
minor
style
first;
then
checks the major style; and finally checks to see if the
key is bound globally.
This means that key bindings in
minor
styles

precedence over, or "shadow," key bindings in the major style or

take

global

key bindings.

You can activate the "EMACS"

style as either

minor

the

major

style:

and activate
If you leave "EDT Emulation" as the major style
between "EDT
conflicts
binding
key
style,
minor
a
as
"EMACS"
be
will
CTRL/W)
and
CTRL/U
as
(such
"EMACS"
Emulation" and

settled

favor of

"EMACS".

"EDT
and activate
style
major
the
"EMACS"
If you make
style, key binding conflicts will be
minor
a
as
Emulation”

settled in favor of

"EDT Emulation”.

"EDT
activate
If you make "EMACS" the major style and do not
the
to
access
have
not
will
you
style,
minor
a
as
Emulation"

(However, you
any commands you like in the

keypad editing capabilities of "EDT Emulation".

can

bind

"EMACS"

B.2.1

the

style;

keypad

see

keys

Section

3.5.1.)

Activating "EMACS” as a Minor Style

Editor by
the
You can activate "EMACS" as a minor style from within
a
activates
command
This
"Activate Minor Style" command.
the
using
command
this
of
use
However,
minor style for the current buffer only.
cause problems if you are editing LISP code, because "EMACS" will
may
key bindings
become the most recently activated style; thus, "EMACS"
will take precedence over conflicting "VAX LISP" key bindings.

A better approach is to make "EMACS" a default minor style, which will
activated before the "VAX LISP" style when you
to be
"EMACS"
cause
call
To make "EMACS" a default minor style,
start editing LISP code.
LISP
your
in
or
interpreter
LISP
the
from
function
following
the
initialization
{ DTIC

file:

USING THE "EMACS” EDITOR STYLE
B.2.2z
To

Making

make

from

"EMACS"

the

LISP

(SETF
This

"EMACS"”

call

the

the Major Style

Editor’'s

interpreter

major

your

(EDITOR:VARIABLE-VALUE
causes

"EMACS"

style.

you

wish

minor

styles,

call

the

following:

"EDT

"EMACS”

Table

B-2

STYLE

lists

the

key

the

key

1in

Appendix

conflicts;
or

Key

contains

that

Major

"EDT

function

file:

Style")

Emulation"

"EMACS")

the

Emulation”"

especially

the
in

containing

alphabetic

Use

CTRL/[

generate

possessing

Table B-2:

"EMACS”

ESCAPE

same

key

different

alphabetic

the

supplied with
1is

where

enter

Key(s)

Editor’s
one

the

Styles"))

character
an

the

Movement

Forward

ESCAPE

Forward

ESCAPE

Character

Character
Word

Backward

Word

CTRL/A

Beginning

CTRL/E

End

CTRL/N

Line

ESCAPE

Beginning

ESCAPE

End

Paragraph

ESCAPE

Paragraph

Previous
Next

Line

CTRL/P

Screen

for

style.

commands,

The

finding

sequence

are

case

character

Style Key Bindings

Backward

Editor.

key

"EMACS"

table
key
bound

and

key

binding
to

two

case- sen51t1ve,

you

contexts.

key.

CTRL/F

the

available

characters

#\ESCAPE

CTRL/B

the

useful

Command
Cursor

Minor

supplied

descriptions

commands

must

CTRL/V

1initialization

"Default

bindings

short

bindings

is,

different

sequences

following

KEY BINDINGS

list

"EDT

the

Emulation"

Appendix

bindings

LISP

reinstate

(EDITOR:VARIABLE-VALUE

B.3

call

"Default

replace

major

(PUSH

style,

shown.
from

keyboards

not

USING THE "EMACS” EDITOR STYLE
Table

B-2

(cont.)

Command

Key(s)

ESCAPE
ESCAPE
ESCAPE
ESCAPE
CTRL/Z
ESCAPE
ESCAPE

Beginning of Buffer
End of Buffer
Beginning of Window
End of Window
Scroll Window Down
Scroll Window Up
Line to Top of Window

Searching

EMACS Forward Search
EMACS Backward Search

CTRL,/\,
CTRL/R

Deleting

DELETE
CTRL/D
ESCAPE DELETE
ESCAPE d

ESCAPE CTRL/D

Delete
Delete
Delete
Delete

Previous Character
Next Character
Previous Word
Next Word

Delete Whitespace

Killing, Yanking, and Regions
Kill

Line

Kill

Paragraph

CTRL /W

Kill

Region

CTRL /Y

Yank

CTRL /K
ESCAPE

ESCAPE

Y
CTRL/Y

ESCAPE

CTRL /W

CTRL/SPACE
ESCAPE

CTRL/SPACE

CTRL /X

Text

CTRL /0O
CTRL /X

CTRL /X
ESCAPE

ESCAPE

CTRL /T
ESCAPE
ESCAPE

Yank

Yank Replace Previous
Undo Previous Yank
Set Select Mark
Unset Select Mark

Exchange Point and Select Mark

Insertion and Modification
Open Line
Quoted Insert
Insert File

Capitalize Word

Downcase Word
Upcase Word

Transpose Previous Characters
Transpose Previous Words
Query Search Replace

USING THE

Table

B-2

Command

Multiple Windows

CTRL /X

Buffers

Window

Remove

Current

Remove

Other

Grow Window

CTRL /X
CTRL /X

CTRL/Z

Shrink Window

ESCAPE

CTRL/V

Page

CTRL /X

Split

CTRL /X

Select

CTRL /X

CTRL /B

List

CTRL /X

CTRL /D

Delete

Starting

and

Window

Window
Buffer

Buffers
Current

CTRL/E

CTRL /X

CTRL /V

Edit

File

CTRL /X

CTRL /R

Read

File

CTRL /X

CTRL/F

View

File

CTRL /X

Write

Current

CTRL /X

CTRL /M

Write

Modified

CTRL /X

CTRL /W

Write

Named

Editor
X

CTRL /G
ESCAPE

CTRL/G

Buffer

Buffers

File

Control
Execute

Named

Command

Pause

Editor

Exit

Recursive

Redisplay

CTRL /L

Buffer

Saving Work

CTRL /X

ESCAPE

Window

Windows

CTRL /X

and

- QT
O

CTRL /X

EDITOR

(cont.)

Key(s)

CTRL /X

"EMACS”

Edit

Screen

CTRL,/U

Supply

Prefix Argqument

Supply

EMACS

CTRL /X

Execute

CTRL /X

CTRL /T

ESCAPE

CTRL /U

CTRL /X

Prefix

Keyboard Macro

Show Time
What

Cursor

Position

B-6

STYLE

APPENDIX C

EDITOR COMMANDS AND KEY BINDINGS

This appendix briefly describes the Editor commands and lists the key
bindings that are supplied with the Editor. The appendix is organized
as

follows:

along with each
Section C.1 1lists the Editor commands,
command’s key bindings and a brief description of the command.

Section C.2 lists the keys and key sequences that are bound to
commands and explains how to determine to which command a key

or key sequence is bound in a given context.

C.1

EDITOR COMMAND DESCRIPTIONS

The second column
Table C-1 alphabetically lists the Editor commands.
are bound to that
that
sequences
key
or
keys
the
1lists
table
of the
The third
bound.
are
they
which
in
context
the
and
command (if any)
For a full
command.
the
of
n
descriptio
brief
column contains a
Editor
LISP/VMS
VAX
the
to
refer
description of each command,
Programming Guide.

EDITOR

Table

C-1:

COMMANDS AND

Editor Commands And

Name

Binding(s)1

Activate Minor Style

None

KEY

BINDINGS

Key Bindings

Description
Prompts for the name of a minor style and then

activates that style as a minor style in the current

buffer
Apropos

None

Prompts for a string, then displays the names of

Apropos Word

(:STYLE "VAX LISP")

Displays the result of evaluating the APROPOS

|ESCAPE| ?

function with the word at the cursor location as the

objects of a specified type containing that string

argument

Backward Character

Backward Kill Ring

:GLOBAL

Moves the cursor backward one character, or by the

(:STYLE "EMAGS")

number of characters specified by the prefix argument

None

Rotates the kill ring backward by one element, or

by the number of elements specified by the prefix
argument

Backward Page

None

Moves the cursor to the previous page break, or to the
preceding page break specified by the prefix argument

Backward Search

None

Prompts for a search string, then moves the cursor to
the beginning of the first preceding occurrence of that

string, or to the preceding occurrence specified by the

prefix argument
Backward Word

(:STYLE "EMACS")

Moves the cursor to the end of the previous word,

|[ESCAPE| b

or to the end of the preceding word specified by the

Beginning of Buffer

prefix argument

(:STYLE "EDT Emulation")

Moves the cursor to the beginning of the buffer

(:STYLE "EMACS")

[ESCAPE]
<
Beginning of Line

(:STYLE "EMACS")

Moves the cursor to the beginning of the current line,
or to the beginning of the following line specified by

the prefix argument
Beginning of

(:STYLE "VAX LISP")

Outermost Form

Moves the cursor to the beginning of the outermost

form currently containing it, or, if the cursor is not
currently contained in a form, to the beginning of the
preceding outermost form

Beginning of

(:STYLE "EMACS")

Moves the cursor to the beginning of the current

Paragraph

|ESCAPE| A

paragraph

(:STYLE "EMACS")

Moves the cursor to the top of the current window

Beginning of Window

|ESCAPE]
Bind Command

None

Prompts for a command name, a key sequence to

bind to the command, and a context in which to bind

the key sequence, then binds the key sequence to the

command

Capitalize Region

None

Capitalizes the first letter of each word in the current
select region

1] indicates nonprinting characters or pointer activity.

] Numeric keypad keys.

Hold down

while typing letter. [PF1][0]

[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down;

| button pressed; 1button released; [cec|— pointer movement with buttons
invoke command only when pointer cursor is in the current window.

in specified state. Pointer buttons

EDITOR COMMANDS AND KEY BINDINGS
Table

C-1

(cont.)

Name

Biruding(s:)1

Description

Capitalize Word

(:STYLE "EMACS")
|ESCAPE| ¢

Capitalizes the first letter of the word at the cursor
location

(:STYLE "VAX LISP")

Completes the outermost LISP form by inserting
close-parentheses characters at the cursor position

Close Qutermost
Form

|ESCAPE| |

Deactivate Minor

None

Style

Prompts for the name of a minor style, then

deactivates that minor style in the current buffer

(:STYLE "EMACS")

Deletes the current buffer: for modified buffers, asks if
the contents of the buffer should first be saved

Delete Line

None

Deletes everything between the cursor and the end
of the current line, or to the end of the following line
specified by the prefix argument

Delete Named Buffer

None

Delete Current Buffer

|CTRL/X| [CTRL/D|

Prompts for the name of a buffer, then deletes that

buffer; if the buffer is modified, asks if the contents of
the butfer should first be saved

Delete Next

(:STYLE "EMACS")

Character

Deletes the character following the cursor, or the
number of following characters specified by the prefix
argument

Delete Next Word

(:STYLE "EMACS")

Deletes everything from the cursor position to the end

[ESCAPE]
d

of the current word, or the number of following words

Delete Previous

:GLOBAL

Character

(:STYLE "EMACS")

Deletes the character preceding the cursor position, or
the number of preceding characters specified by the

Delete Previous
Word

Delete Whitespace

Delete Word

(:STYLE "EMACS")

specified by the prefix argument

prefix argument

Deletes everything from the cursor position to the

[ESCAPE| [DELETE|

beginning of the current word, or the number of

(:STYLE "EMACS")

Deletes whitespace characters following the cursor
location up to the next nonwhitespace character

[ESCAPE||CTRL/D|
None

preceding words specified by the prefix argument

Deletes everything from the cursor position to the
beginning of the next word, including whitespace, or
deletes the number of following words specified by the
prefix argument

Describe

None

Describe Word

(:STYLE "VAX LISP")

Describe Word at

(:STYLE "VAX LISP")

Downcase Region

None

Pointer2

Prompts for the name and type of an object, then
displays a description of that object

Calls the DESCRIBE function with the word at the
cursor position as the argument

Calls the DESCRIBE function with the word at the
pointer position as the argument

Makes all alphabetic characters in the current select
region lower case

Downcase Word

(:STYLE "EMACS")

Makes all alphabetic characters in the word at the

|[ESCAPE]||

cursor position lower case

1] indicates nonprinting characters or pointer activity. [CTRL/D| Hold down [CTRL] while typing letter.

[0]

[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down;
] Numeric keypad keys.
| button pressed; Tbutton released; [oeo]— pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the curr ent window.

2 Available only on VAXstation.

EDITOR

Table

C-1

COMMANDS

AND

KEY

BINDINGS

(cont.)

Name
Ed

Binding(s)1

Description

(:STYLE "EMACS")

Prompts for a LISP object to edit and, if the object is

|CTRL/X] | CTRLI/E]

a symbol, whether to edit its function definition or its
value

Edit File

(:STYLE "EMACS")

Prompts for the specification of a file to edit; |

ICTRL/X||[CTRL/V|

completion and alternatives are available during

(:STYLE "EDT EmulationTM)

Appends the current select region to the contents of

your response to the prompt

EDT Append

the paste buffer
EDT Back to Start of

(:STYLE "EDT Emulation")

Moves the cursor to the beginning of the current line,

and [BACKSPACE]*

or to the beginning of the previous line if the cursor is

Line

and [F12]3

already at the beginning of a line; or moves back the
number of lines specified by the prefix argument

EDT Beginning of

(:STYLE "EDT Emulation")

Line

Moves the cursor to the beginning of the next line, if

the current direction is forward, or to the beginning of
the current or previous line, if the current direction is
backward; moves by the number of lines specified by
the prefix argument

EDT Change Case

(:STYLE "EDT Emulation")

Changes the case (lower to upper and vice versa) of all
characters in the select region, or, if no select region
is defined, of the character at the cursor position

EDT Cut

(:STYLE "EDT Emulation")

6] and [REMOVE]| 3
‘O

EDT Delete

and

Deletes the current select region and replaces the

contents of the paste buffer with it

(:STYLE "EDT Emulation")

Character

Deletes the character at the cursor position and stores

it in the deleted character area; deletes the number of

characters specified by the prefix argument
EDT Delete Line

(:STYLE "EDT Emulation")

Deletes from the cursor position to the beginning of
the next line and stores the deleted line in the deleted
line area,; deletes the number of lines specified by the

prefix argument
EDT Delete Previous

(STYLE "EDT Emulation")

Character

Deletes the character preceding the cursor and stores
it in the deleted character area; deletes the number of

characters specified by the prefix argument
EDT Delete Previous

(:STYLE "EDT Emulation")

Line

Deletes from the cursor position to the beginning of
the current line or, if the cursor is at the beginning of

a line, to the beginning of the previous line; stores the
result in the deleted line area; deletes the number of

lines specified by the prefix argument
EDT Delete Previous
Word

(:STYLE "EDT Emulation")

and [LINEFEED]*

and [F133

Deletes from the cursor position to the beginning of
the current word or, if the cursor is between words, to

the beginning of the previous word; stores the result
in the deleted word area; deletes the number of lines

specified by the prefix argument

![] indicates nonprinting characters or pointer activity.
Hold down
while typing letter.
[0]
[.] Numeric keypad keys.
[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down:;
| button pressed; 1 button released:; —-+ pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.

3Key available only on LK201 keyboard.
“Key available only on VT100 terminal.

EDITOR COMMANDS AND KEY BINDINGS
Table

C-1

(cont.)

Name

Bindinrug(s)1

Description

EDT Delete to End

(STYLE "EDT Emulation")

Deletes from the cursor position to the end of the
current line or, if the cursor is at the end of a line,

of Line

to the end of the next line; stores the result in the

deleted line area; deletes the number of lines specified
by the prefix argument
EDT Delete Word

(:STYLE "EDT Emulation")

Deletes from the cursor position to the beginning of
the next word; stores the result in the deleted word
area; deletes the number of words specified by the
prefix argument

EDT Deselect

EDT End of Line

(:STYLE "EDT Emulation®)

]

Cancels the current select region; equivalent to *‘Unset
Select Mark”

(:STYLE "EDT Emulation")

Moves the cursor to the end of the current, next, or
previous line, depending on starting cursor position
and current direction; moves by the number of lines
specified by the prefix argument

EDT Move Character

(:STYLE "EDT Emulation")

Moves the cursor forward or backward by one
character, according to the current direction; moves
the number of characters specified by the prefix
argument

(:STYLE "EDT Emulation")

Moves the cursor to the preceding or following page
break, depending on the current direction; moves the
number of pages specified by the prefix argument

EDT Move Word

(:STYLE "EDT Emulation")

Moves the cursor to the beginning of the next, current,
or preceding word, depending on current direction and
cursor starting position; moves the number of words
specified by the prefix argument

EDT Move Page

(:STYLE "EDT

EDT Paste

Emulation")

[INSERT HERE[°
EDT Paste at

Pointer2

(6] an

Inserts the contents of the paste buffer at the cursor
|
location

(:STYLE "EDT Emulation")

Inserts the contents of the paste buffer at the pointer
cursor location

EDT Query Search

EDT Replace

EDT Scroll Window

(:STYLE "EDT Emulation")

[PF1] [PF3] and [FINDP3

(:STYLE "EDT Emulation")

9]
(:STYLE "EDT Emulation")

Prompts for a search string and moves the cursor to
the following or preceding occurrence of the string,

depending on the current direction; moves to the
occurrence specified by the prefix argument
Replaces the current select region with the contents
of the paste buffer

Scrolls the window in the direction indicated by the
current direction

EDT Search Again

(:STYLE "EDT Emulation")

[PF3]

Searches for the next or previous occurrence of the
search string that was last entered, according to the
current direction

Hold down

1] indicates nonprinting characters or pointer activity.

while typing letter.

[0]

[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down;
[] Numeric keypad keys.
| button pressed; {button released; [oeo|— pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.
?

wa fo2 om oum

HP Y

<Available only on VAXstation.

3Key available only on LK201 keyboard.

C-5

EDlTORCOMMANDS AND KEY BINDINGS
Table

C-1

(cont.)

Name
EDT Select

Binding(s)1

Description

(:STYLE "EDT Emulation")

[.] and [SELECT]3

Places a mark at the cursor position to indicate one

end of a select region; equivalent to “Set Select
Mark”

EDT Set Direction

(:STYLE "EDT Emulation")

Backward

(5]

EDT Set Direction

(:STYLE "EDT Emulation")

Sets the current direction to backward
Sets the current direction to forward

Forward

EDT Special Insert

(:STYLE "EDT Emulation")

Inserts the character whose ASCII code is specified by

the prefix argument at the cursor position
EDT Substitute

(:STYLE "EDT Emulation")

If the cursor is located at the beginning of the current

[PF1] [ENTER]

search string, replaces the search string with the

contents of the paste buffer, then finds the next

occurrence of the search string
EDT Undelete

Character
EDT Undelete Line

EDT Undelete Word

(:STYLE "EDT Emulation")

]

(:STYLE "EDT Emulation")

Inserts the contents of the deleted line area at the

|PF1||PF4]

cursor location

(:STYLE "EDT Emulation")

[PF]
[
EMACS Backward

Inserts the contents of the deleted character area at

the cursor location

Inserts the contents of the deleted word area at the

cursor location

(:STYLE "EMACS")

Searches backward for the first occurrence of the

search string specified in the previous command;
prompts for a search string if the previous command
was not a searching command; searches for the

occurrence of the search string specified by the prefix
argument

EMACS Forward

(:STYLE "EMACS")

Searches forward for the first occurrence of the search

string specified in the previous command; prompts for

a search string if the previous command was not a
searching command; searches for the occurrence of
the search string specified by the prefix argument
End Keyboard Macro

:GLOBAL

)

End of Buffer

(:STYLE "EDT Emulation")

Ends the collection of keystrokes for a keyboard macro
Moves the cursor to the end of the buffer

(:STYLE "EMACS")

|ESCAPE| >
End of Line

(:STYLE "EMACS")

Moves the cursor to the end of the current line, or
forward by the number of lines specified by the prefix

argument and then to the end of the line
End of Outermost
Form

(:STYLE "VAX LISP")

Moves the cursor to the outermost form currently

surrounding the cursor, or, if the cursor is between
outermost forms, to the end of the following outermost
form

'['] indicates nonprinting characters or pointer activity. [CTRL/D] Hold down [CTRL] while typing letter. [PF1][0]
[,] Numeric keypad keys.
[T] Arrow keys. [o]e|Pointer button transition: obutton up; ebutton held down;
| button pressed; 1button released; [oeo]— pointer movement with buttons in specified state. Pointer buttons
H
WYY
%Y
o
£
H
e
o varivndnaag
invoke
command only
when pointer
cursor
is Hin $hn
the current
window.

3Key available only on LK201 keyboard.

C-6

EDITOR COMMANDS AND KEY BINDINGS

Table

C-1

(cont.)

Name

Binding(a&s)*I

Description

End of Paragraph

(:STYLE "EMACS")

Moves the cursor to the end of the current paragraph

End of Window

e
|ESCAPE|

Moves the cursor to the end of the text in the current

(:STYLE "EMACS")

|[ESCAPE|.

window

Evaluate LISP
Region

(:STYLE "VAX LISP")
[CTRL/X| [ CTRL/A]

Exchange Point and
Select Mark

(:STYLE "EMACS")
[CTRL/X| [CTRL/X|

Evaluates the select region as LISP code; displays the
result of the evaluation in the information area
Moves the cursor to the other end of the current select
region, and the mark delimiting the select region to
the old cursor position; in other words, preserves the

select region but places the cursor at the other end of
,

Execute Keyboard
Macro

:GLOBAL [CTRL/X||CTRLIE]
(:STYLE "EMACS")

Executes the current keyboard macro once, or the
number of times specified by the prefix argument

CTRL/X] e

Execute Named

Command

:GLOBAL |CTRL/Z| and

[DOJ3

Prompts for the name of a command to execute; input

completion and alternatives are available during your

(STYLE "EDT Emulationn) ~ '®SPOnse to the prompt

(:STYLE "EMACS")
|[ESCAPE|
x

Exit Editor

Returns control to the LISP interpreter, discarding the

None

current Editor state; asks if modified buffers should
first be saved

Exit Recursive Edit
Forward Character

(:STYLE "EMACS")

Terminates a recursive edit, or pauses the Editor if not

[ESCAPE||CTRL/G|

doing a recursive edit

:GLOBAL

Moves the cursor forward one character

(:STYLE "EMACS")

Forward Kill Ring

None

Forward Page

None

Forward Search

None

Rotates the kill ring forward by one element, or by the
number of elements specified by the prefix argument

Moves the cursor to the next page break, or to the

following page break specified by the prefix argument

Prompts for a search string, then moves the cursor

forward to the end of the first occurrence of the string;
moves the cursor to the occurrence of the string
specified by the prefix argument

Forward Word

Grow Window

Moves the cursor to the beginning of the next word,

(:STYLE "EMACSH")

or the beginning of the word specified by the prefix
|
argument

|ESCAPE] {

Increases the height of the current window by one

(:STYLE "EMACS")

row, or by the number of rows specified by the prefix

[CTRL/X] z

argument

Help

:GLOBAL

and [HELP]3

Displays help on your current situation

'[] indicates nonprinting characters or pointer activity. [CTRL/D| Hold down [CTRL| while typing letter.

[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down;
[] Numeric keypad keys.
[oeo]— pointer movement with buttons in specified state. Pointer buttons
reieased;
{button
pressed;
button
|
U

invoke command only when pointer cursor is in the current window.

3Key available only on LK201 keyboard.

ifinAd

atat

EDITOR

Table

C-1

COMMANDS AND

KEY BINDINGS

(cont.)

Name

Binding(s)1

Help on Editor Error

:GLOBAL

Description
?

Displays information on the last Editor error that
occurred

lllegal Operation

None

Signals an Editor error; use to disable a key binding
locally within a style or buffer

Indent LISP Line

(:STYLE "VAX LISP")

Adjusts the current LISP line so that it is indented
properly in the context of the program

Indent LISP Region

None

Adjusts the indentation of the LISP code in the current
select region

Indent Qutermost

(:STYLE "VAX LISP")

Indents each line in the outermost LISP form

Form

|CTRL/X|
| TAB]

containing the cursor

Insert Buffer

None

Prompts for a buffer name, then inserts the contents
of the specified buffer at the cursor location

insert Close Paren

(:STYLE "VAX LISP") )

and Match

Inserts a close-parenthesis character at the cursor

location and highlights the corresponding open-

parenthesis character
Insert File

(:STYLE "EMACS")

Prompts for a file specification, then inserts the

[CTRL/X]||[CTRL]

contents of the file at the cursor location; input

completion and alternatives are available during your
response to the prompt
Kill Enclosing List

None

Deletes the LISP list that encloses the cursor and

adds it to the current kill-ring region if the previous
command was a kill-ring command, or creates a new
kill-ring region to hold the deleted list; deletes the

number of enclosing lists specified by the prefix
argument

Kill Line

(:STYLE "EMACS")

Deletes the rest of the current line and adds it to the

current kill-ring region if the previous command was
a kill-ring command, or creates a new Kkill-ring region

to hold the deleted line; deletes the number of lines
specified by the prefix argument
Kill Next Form

None

Deletes the LISP form immediately following the cursor

and adds it to the current kill-ring region if the previous
command was a kill-ring command, or creates a new
kill-ring region to hold the deleted form; deletes the
number of following forms specified by the prefix

argument within the current parentheses nesting level
Kill Paragraph

(:STYLE "EMACS")

|ESCAPE|
k

Deletes the rest of the current paragraph and adds it
to the current kill-ring region if the previous command
was a kill-ring command, or creates a new Kkill-ring
region to hold the deleted paragraph; deletes the
number of paragraphs specified by the prefix argument

[] indicates nonprinting characters or pointer activity.
Hold down
while typing letter.
[0]
[] Numeric keypad keys.
[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down;
| button pressed; Tbutton released; _-+ pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.

EDITOR COMMANDS AND KEY BINDINGS

Table

C-1

(cont.)

Name

Binding(s)1

Kill Previous Form

None

Description
Deletes the LISP form immediately preceding the

cursor and adds it to the current kili-ring region if the
previous command was a Kill-ring command, or creates

a new kill-ring region to hold the deleted form; deletes
the number of preceding forms specified by the prefix

argument within the current parentheses nesting level
Kill Region

(:STYLE "EMACS")

[CTRL/W]
and [ o]

Deletes the current select region and adds it to the
current kill-ring region if the previous command was a
kill-ring command, or creates a new kill-ring region to
hold the deleted region

Kill Rest of List

Deletes the rest of the enclosing list and adds it to the

None

current kill-ring region if the previous command was a
kitl-ring command, or creates a new kill-ring region to

hold the deleted list fragment
Line to Top of
Window

List Buffers
List Key Bindings

(:STYLE "EMACS")

Moves the line containing the cursor to the top of the

IESCAPE] |

window

(:STYLE "EMACS")

Displays a list of all buffers

None

Displays a list of all visible key bindings or of all keys

[CTRL/X|[CTRL/B]

bound in a specified context
Maybe Reset Select

:GLOBAL

at Pointer?
Move Point and

Select Region2

:GLOBAL [eco]—

If the pointer cursor has not moved, cancels the select

region that was started with [[ool; if the pointer cursor
has moved since [[oo], does nothing

Moves the text cursor with the pbinter cursor, marking
a select region

Move Point to

:GLOBAL

Move to LISP

(:STYLE "VAX LISP")

F’ointer2

Comment

;

Moves the text cursor to the pointer cursor
If there is no comment on the current line, moves
the cursor to the comment column and inserts a

semicolon and space; if there is a comment, moves
the cursor to the comment
New Line

GLOBAL |RETURN|
(:BUFFER "General

Breaks a line at the cursor position, leaving the cursor
-at the start of the new line

Prompting") [LINEFEED)|
(:STYLE "EMACS")

[RETURN]
New LISP Line

(:STYLE "VAX LISP")

[LINEFEED]

Breaks a line at the cursor position, and indents the
new line by the appropriate amount
in the context of
the program

Next Form

(:STYLE "VAX LISP")

Moves the cursor to the end of the next form, or

to the end of the following form specified by the
prefix argument; does not move outside the current

parentheses nesting level

1] indicates nonprinting characters or pointer activity.

Hold down [CTRL] while typing letter.

[] Numeric keypad keys.
[T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton held down;
| button pressed; tbutton released; [oeo]— pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.

2 Available only on VAXstation.

Cc-9

EDITOR COMMANDS AND

Table

C-1

KEY BINDINGS

(cont.)

Name

Binding(s)1

Description

Next Line

:GLOBAL [] |

Moves the cursor to the next line or down by the

(
Next Paragraph

.STYLE "EMACS") [CTRL/N]

)

number of lines specified by the prefix argument,

keeping the cursor in the same column if possible

(:STYLE "EMACS")

Moves the cursor to the beginning of the next

|[ESCAPE|
n

paragraph, or to the following paragraph specified
by the prefix argument

‘GLOBAL [NEXT SCREEN]3

Next Screen

Moves the window down in the buffer by one screenful,
or by as many screenfuls as are specified by the prefix
argument

Next Window

-GLOBAL [CTRL/X| [CTRL/N|

Selects another window on the screen to be the

(:STYLE "EMACS")

current window; eventually circulates through all the

CTRL/X 0

Open Line

windows on the screen

(:STYLE "EDT Emulation")

[0]

Breaks a line at the cursor location, leaving the cursor

at the end of the old line

(:STYLE "EMACS")

Page Next Window

Scrolls the next window on the screen down one page;

(:STYLE "EMACS")

|[ESCAPE|[CTRL/V|

or, if a prefix argument is supplied, scrolls the next
window by that many rows

Pause Editor

:GLOBAL |CTRL/X| |CTRL/Z|

Saves the Editor state and returns control to the LISP

(:STYLE "EMACS")

interpreter

(:STYLE "VAX LISP")

Previous Form

Moves the cursor to the beginning of the previous

form, or to the beginning of the preceding form
specified by the prefix argument; does not move
outside the current parentheses nesting level

Previous Line

:GLOBAL [T ]

(
Previous Paragraph

Moves the cursor to the previous line, or up by the

.STYLE "EMACS") [CTRL/P]

)

number of lines specified by the prefix argument;

keeps the cursor in the same column if possible

(:STYLE "EMACS")

Moves the cursor to the end of the previous

|ESCAPE|
p

paragraph, or to the end of the preceding paragraph
specified by the prefix argument

Previous Screen

Previous Window

-GLOBAL [PREV SCREEN]3

Moves the cursor up in the buffer by one screenful, or

(:STYLE "EMACS")
'ESCAPEl v

argument

by as many screenfuls as are specified by the prefix

(:STYLE "EMACS")

Makes another window on the screen into the current

CTRL/X| n

window; eventually circulates through all windows on
the screen

Prompt Complete

(:BUFFER "General

String

Prompting")

Prompt Help

Attempts to complete your response to a prompt,

based on what you have typed aiready and the
choices available in the situation

(:BUFFER "General

Displays information on whatever is being prompted

Prompting")

for

[] indicates nonprinting characters or pointer activity. |[CTRL/D| Hold down

while typing letter.

[,] Numeric keypad keys.
[T] Arrow keys. [o]e|Pointer button transition: obutton up; ebutton held down;
| button pressed; 1button released; [oso|— pointer m ovement with buttons in specified state. Pointer buttons
|

Iner#d

invoke command only when pointer cursor is in the current window.

3Key available only on LK201 keyboard.

EDITOR COMMANDS AND KEY BINDINGS
Table

C-1

(cont.)

Name

Prompt Read and
Validate

Binding(s)"

Description

(:BUFFER " General

Used to terminate prompt input

Prompting") [RETURN]
and

Prompt Scroll Help

(:BUFFER "General

Window

Prompting")

Prompt Show

(:BUFFER "General

window while responding to a prompt

Alternatives

Prompting") |[PF1]||PF2]

Query Search

(:STYLE "EMACS")

Replace

|[ESCAPE]| g

Quoted Insert

:GLOBAL

(:STYLE "EMACS")

[CTALKXg
Read File

Redisplay Screen

Scrolls the Help window down while another buffer
is current; supplied to allow you to scroll the Help
Displays a list of alternatives that can be entered in
response to the current prompt, based on what you
have typed already

Prompts for a search string and a replacement; offers
a number of options at each replacement opportunity
Inserts the next character typed at the cursor location
without Editor interpretation

[CTRL/X] [CTRL/R]

Prompts for a file specification, then replaces the
contents of the current buffer with the file; it the
current buffer is modified, prompts for confirmation

(:STYLE "EDT Emulation")

Erases and redisplays everything on the screen

(:STYLE "EMACS")

(:STYLE "EMACS")
Remove Current

:GLOBAL [CTRL/X][CTRL/R|

Window

(:STYLE "EMACS")

Removes the current window from the screen; does
not delete the associated buffer

d
Remove Other

(:STYLE "EMACS")

Windows

Scroll Window Down

(:STYLE "EMACS")

Removes all windows but the current window from the
screen

Scrolls the current window down in the buffer by one
row, or by the number of rows specified by the prefix
argument

Scroll Window Up

(:STYLE "EMACS")
|[ESCAPE| z

Scrolls the current window up in the buffer by one
row, or by the number of rows specified by the prefix
argument

Select Buffer
Select Enclosing

(:STYLE "EMACS")

[CTRLX]b

(:STYLE "VAX LISP")

Form at Pointer

Prompts for a buffer name, then makes that buffer the
current buffer; creates a new buffer if necessary
Places the form enclosing the cursor in a select
region; if the cursor is already in a select region,
expands the region to the next outermost form

(:STYLE "VAX LISP")

Makes the outermost LISP form containing the cursor

Form

[CTRL/X| [CTRL/ |

into a select region

Self Insert

:GLOBAL All graphic

Inserts the last character typed at the cursor location

Select Qutermost

characters

Set Screen Height

None

Sets the screen height to the number of rows specified
by the prefix argument; prompts for height if no prefix
argument is defined

Hold down

1] indicates nonprinting characters or pointer activity.

while typing letter.

[0]

[ Numeric keypad keys. [—] [T] Arrow keys. [o]e]Pointer button transition: obutton up; ebutton heid down;
| button pressed; fbutton released:; ——> pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.

c-11

EDITOR COMMANDS AND KEY BINDINGS

Table

C-1

(cont.)

Name

Binding(s)1

Descriptionr

Set Screen Width

None

Sets the screen width to the number of columns
specified by the prefix argument; prompts for the width
if no prefix argument is defined

Set Select Mark

(:STYLE "EDT Emulation")

Places a mark at the cursor position to indicate one

end of a select region
(:STYLE "EMAGCS")

Show Time

(:STYLE "EMACS")

|CTRL/X|[CTRL/T|
Shrink Window

(:STYLE "EMACS")

|CTRL/X| |CTRL/Z]|
Split Window

Shrinks the current window by one row, or by the
number of rows specified by the prefix argument

(:STYLE "EMACS")

Splits the current window into two identical windows

:GLOBAL [CTRL/X] (

Starts collecting keystrokes for a keyboard macro,

[CTRL/X] 2
Start Keyboard

Displays the time and date in the information area

Macro

replacing any unnamed keyboard macro that already

exists

Start Named

None

Keyboard Macro

Prompts for a name, then starts collecting keystrokes

for a keyboard macro; the resulting keyboard macro

is catalogued under the name you give and can be
treated as a command

Supply EMACS

(:STYLE "EMACSH")

Prefix

Sets the prefix argument to four, if no prefix argument
was defined, or to four times its former value, if a

prefix argument was defined
Supply Prefix

(:STYLE "EDT Emulation")

Argument

|PF1]{PF1|

Prompts for a prefix argument; if a prefix argument is

already defined, multiplies it by the number you enter

(:STYLE "EMACS")

[ESCAPE|[CTRL/U]
Transpose Previous

(:STYLE "EMACS")

Transposes the two characters preceding the cursor

Transpose Previous

(:STYLE "EMACS")

Transposes the words at and preceding the cursor

Words

|ESCAPE]|
t

Characters

~Undo Previous Yank

(:STYLE "EMACS")

Deletes the previously yanked region without pushing

|ESCAPE||CTRL/W)|

it onto the kill ring; more generally, deletes the select

region without pushing it onto the kill ring

Unset Select Mark

(:STYLE "EDT Emulation")

[PFA]
(]

Cancels the current select region

(:STYLE "EMACS")

|ESCAPE|[CTRL/ |
Upcase Region

None

Changes all alphabetic characters in the current select
region to upper case

Upcase Word

(:STYLE "EMACS")

|ESCAPE|
u
View File

(:STYLE "EMACS")

|CTRL/X| [CTRL/F]

Changes all alphabetic characters in the word at the
cursor location to upper case

Prompts for a file specification, then reads the

specified file into a read-only buffer

'] indicates nonprinting characters or pointer activity.
Hold down
while typing letter.
[0]
L] Numeric keypad keys. [—| [T | Arrow keys. [o]e]Pointer button transition: obutton up; sbutton held down:
| button pressed; 1button released; [oeo]— pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.

EDITOR COMMANDS AND KEY BINDINGS

Table

C-1

(cont.)

Name

Binding(s)1

Description

What Cursor Position

(:STYLE "EMACS")

Displays information about the cursor location

Write Current Buffer

(:STYLE "EMACS")

Writes out the current buffer; creates a new file

CTRL/X| s

version, or updates the LISP symbol whose function or

value slot is being edited

Write Modified

Buffers

|CTRL/X||CTRL/M|

(:STYLE "EMACS")

Performs the ‘“‘Write Current Buffer’”’ operation for each

Write Named File

(:STYLE "EMACS")
ICTRL/X| [CTRL/W|

Prompts for a file specification, then creates a file
having that specification from the contents of the

buffer that has been modified

current buffer

Yank

(:STYLE "EMACS")

Inserts the current kill-ring region at the cursor
location; inserts as many copies as are specified
by the prefix argument

Yank at Pointer?

(:STYLE "EMACS")

Inserts the current kill-ring region at the pointer cursor
location

Yank Previous

(:STYLE "EMACS")
|ESCAPE| y

Yank Replace

Rotates the kill ring forward, then inserts the new
current kill-ring region at the cursor location; inserts as
many copies as are specified by the prefix argument

(:STYLE "EMACS")

|[ESCAPE||CTRL/Y|

Deletes the previously yanked region, rotates the kill

ring forward, and inserts the new current kill-ring region
at the cursor location; inserts as many copies as are
specified by the prefix argument

'[] indicates nonprinting characters or pointer activity.

Hold down

while typing letter.

[] Numeric keypad keys.
[T] Arrow keys. [o[e]Pointer button transition: obutton up; ebutton held down;
| button pressed; 1button released; [ceo]— pointer movement with buttons in specified state. Pointer buttons
invoke command only when pointer cursor is in the current window.

2 Available only on VAXstation.

EDITOR COMMANDS AND KEY BINDINGS
C.2

EDITOR KEY BINDINGS

Table

C-2

lists

the

and

the

commands,
sequences

command

are

keys

bound

and

key

context

than

key

your

current

sequences

which

they

one

sequence

that

are

bound

bound.

Some

keys

find

out

command.

will

invoke,

use

the

Editor

key

which

following

procedure:
1.

are

typing

sequence

"General
that

bound

invokes

the

activated

most

strip.

The

with

the

label

the

Prompting"

prompt)

the

key

(that

and

the

is,

key

context

key

bound

the

key

the

styles.

(If

the

omitted.)

the

sequence

styles,

which

You
by

command.

i1f

key

(:BUFFER

sequence

bound

can

tell

which

contains

key

list

to
or

the

invokes

command

key

sequence

most

minor

the

activated

You

list

then

can

recently

style

window’s

the

style

minor

context,

key

bound
key

styles

the

command.

the

precedes

sequence

then

is
the

identify

strip;

key

sequence

style,

1label

the

:GLOBAL

was

1label

active

minor

the

front

key

to
or

command

key

sequence

major

the

too

bound

key

style

list

long,

the

sequence

minor
major

command
invokes

Otherwise,

the

key

results

error.

then

examining

recently

major

style

Otherwise,

key

strip

key

current
the

key

sequence

unbound;

typing

Editor Key Bindings
Context

and

Command

Single Keys
CTRL/SPACE

vyou

Key(s)

most

that

recently

invokes

Table C-2:

then

style.

looking

that

command

minor

list.

Otherwise,

"General

key

command

styles,
the

the
more

minor

activated

Prompting"),

one

response

command.

Otherwise,
in

buffer

(:BUFFER

"General

Prompting")

String

Prompt

(:STYLE

"EMACS")

Set

Select

CTRL/A

(:STYLE

"EMACS")

Beginning

CTRL/B

(:STYLE

"EMACS")

Backward

Mark
of

Line

Character

Complete

EDITOR COMMANDS AND KEY BINDINGS

Table

C-2

(cont.)

Kef(s)

Context and Command

CTRL/D

(:STYLE "EMACS")

Delete Next Character

CTRL/E

(:STYLE "EMACS")

End of Line

CTRL/F

(¢:STYLE "EMACS")

Forward Character

CTRL/G

(¢:STYLE "EMACS")

Pause Editor

CTRL/H or

(:STYLE "EDT Emulation") EDT Back to Start of Line

BACKSPACE

TAB or

(¢:STYLE "VAX LISP")

Indent LISP Line

CTRL/I

CTRL/J or

( :BUFFER "General Prompting") New Line

LINEFEED

(:STYLE "VAX LISP") New LISP Line
(:STYLE "EDT Emulation") EDT Delete Previous Word

CTRL /K

(:STYLE "EMACS")

Kill Line

CTRL/L

(¢:STYLE "EMACS")

Redisplay Screen

RETURN

( :BUFFER "General Prompting") Prompt Read and

or CTRL/M

Validate
(:STYLE "EMACS")

New Line

:GLOBAL New Line

CTRL/N

(:STYLE "EMACS") Next Line

CTRL/0

(:STYLE "EMACS") Open Line

CTRL /P

(:STYLE "EMACS") Previous Line

CTRL /R

(:STYLE "EMACS") Backward Search

CTRL/T

(:STYLE "EMACS") Transpose Previous Characters

CTRL/U

(:STYLE "EMACS") Supply EMACS Prefix
(:STYLE "EDT Emulation") EDT Delete Previous Line

CTRL/V

(:BUFFER "General Prompting") Prompt Scroll Help

CTRL/W
CTRL/Y

Wwindow
(:STYLE "EMACS")

Screen

(:STYLE "EMACS") Kill Region

(:STYLE "EDT Emulation")

(:STYLE "EMACS")

C-15

Yank

Redisplay Screen

EDITOR

Table

C-2

COMMANDS AND

KEY BINDINGS

(cont.)

Key(s)

Context

and

Command

CTRL/Z

(:STYLE "EMACS") Scroll Window Down
:GLOBAL

Execute

Named

CTRL /\

(:STYLE

"EMACS")

CTRL/?

(:STYLE

"VAX

EMACS

LISP")

DELETE

(:STYLE

"EMACS")

(¢:STYLE

"EDT

:GLOBAL

Delete

(:STYLE

"VAX

LISP")

<X]

)

Command
Forward

Describe

Delete

Emulation")

Word

Previous
Delete

Character
Previous

Character

Insert

Paren

and

keypad

(:STYLE

"EDT

Emulation")

EDT

Beginning

keypad

(:STYLE

"EDT

Emulation")

EDT

Move

keypad

(¢:STYLE

"EDT

Emulation”)

EDT

End

keypad

(:STYLE

"EDT

Emuiation")

EDT Move

keypad

(:STYLE

"EDT

Emulation")

EDT

Set

Direction

keypad

(:STYLE

"EDT

Emulation")

EDT

Set

Direction

Cut

Match

Line

Word

Line

Character
Forward

Backward
keypad

(:STYLE

"EDT

Emulation”)

EDT

keypad

(:STYLE

"EDT

Emulation”)

EDT Move

keypad

(:STYLE

"EDT

Emulation")

EDT

keypad

(:STYLE

"EDT

Emulation")

EDT Append

keypad

(:STYLE

"EDT

Emulation”)

Set

keypad

ENTER

(¢:BUFFER

"General

Prompting")

Page

Scroll

Select

Prompt

Window

Mark

Read

and

Validate
keypad

(¢:STYLE

"EDT

Emulation”)

EDT

Delete

Character

keypad

(:STYLE

"EDT

Emulation")

EDT

Delete

Word

keypad

PF2

(:BUFFER

(:STYLE

"General

"EDT

Prompting")

Emulation")

Help

Emulation")

EDT

Prompt

Help

:GLOBAL Help
keypad

PF3

(:STYLE

"EDT

C-16

Search Again

EDITOR COMMANDS AND KEY BINDINGS

Table

C-2

(cont.)

Key(s)

Context and Command

keypad PF4

(¢:STYLE "EDT Emulation")

Up arrow

:GLOBAL Previous Line

Down

: GLOBAL

+:GLOBAL

Forward

arrow

Right

arrow

EDT Delete Line

Line

Left

arrow

:GLOBAL

Backward

All

graphics

:GLOBAL

Self

Character

Insert

characters

Single Keys

LK201 Keyboard Only

F12

( +STYLE

"EDT Emulation")

EDT Back

F13

( +:STYLE

"EDT Emulation")

EDT Delete Previous Word

HELP

: GLOBAL

Help

+GLOBAL

Execute Named

FIND

( +cSTYLE

"EDT Emulation")

INSERT

( : STYLE "EDT

HERE

Start

Command

EDT Query Search

Emulation") EDT Paste

REMOVE

( :STYLE

"EDT

Emulation”")

EDT

Cut

SELECT

( +:STYLE

"EDT

Emulation")

EDT

Select

SCREEN

c:GLOBAL

SCREEN

: GLOBAL

Screen

Two-Key Sequences Starting with CTRL/X
CTRL/X

CTRL/SPACE

( +STYLE

"VAX LISP")

Select Outermost

CTRL/X

CTRL /A

( +STYLE

"VAX LISP")

Evaluate

CTRL/X

CTRL/B

( +:STYLE

"EMACS")

List

CTRL/X

( : STYLE

"EMACS")

Delete

CTRL/X

(: ST h gy & "EMACS") fal1 @}
Execute Keyboard Macro
: GLOBA
ST

Form

LISP Region

Buffers

Current Buffer

Line

EDITOR

Table

C-2

COMMANDS AND

KEY

BINDINGS

(cont.)

Key(s)

CTRL/X

CTRL/F

CTRL/X

TAB

or
CTRL/X

CTRL/I

CTRL/X

RETURN

Context

and

Command

(:STYLE

"EMACS")

(:STYLE
. "EMACS")
(¢:STYLE

"VAX

(¢:STYLE

"EMACS")

View

File

Insert

LISP")

File

Indent

Write

Outermost

Modified

Form

Buffers

S;RL/X CTRL /M
CTRL/X

CTRL/N

:GLOBAL

Window

CTRL/X

CTRL/R

(:STYLE

"EMACS")

:GLOBAL

Remove

Read

File

Current Window

CTRL/X

CTRL/T

(:STYLE

"EMACS")

Show

Time

CTRL/X

CTRL/V

(:STYLE

"EMACS")

Edit

File

CTRL/X

CTRL/W

(:STYLE

"EMACS")

Write

Named

File

CTRL/X CTRL/X

(:STYLE "EMACS") Exchange Point and Select Mark

CTRL/X

(:STYLE

"EMACS")

:GLOBAL

Pause

Editor
Keyboard

CTRL/Z

Shrink

Window

CTRL/X

(

:GLOBAL

Start

CTRL/X

)

:GLOBAL

End

Keyboard

Macro

CTRL/X

(:STYLE

"VAX

LISP")

(¢:STYLE

"VAX

LISP")

CTRL /X

Macro

Form

CTRL/X

(:STYLE

"EMACS")

Remove

Other

CTRL/X

(:STYLE

"EMACS")

Split

Window

CTRL/X

(¢:STYLE

"VAX

CTRL/X <

(:STYLE "VAX LISP")'Beginning of Outermost Form

CTRL/X

(¢:STYLE

"VAX

CTRL/X

(¢:STYLE

"EMACS")

CTRL/X

: GLOBAL

Help

LISP")

Move

End

Windows

LISP

Comment

Outermost

What

Cursor

Editor

Error

Position

Form

EDITOR COMMANDS AND KEY BINDINGS

Table

C-2

(cont.)

Key(s)

Context and Command

CTRL/X \

:GLOBAL Quoted Insert

CTRL/X b

(+STYLE "EMACS")

Select Buffer

CTRL/X d

(:STYLE "EMACS")

Remove Current Window

CTRL/X e

:GLOBAL Execute Keyboard Macro

CTRL/X n

(:STYLE "EMACS")

Previous Window

CTRL/X p

(:STYLE "EMACS")

Next Window

CTRL/X g

(¢STYLE "EMACS")

Quoted Insert

(:STYLE "EMACS") Write Current Buffer

| CTRL/X s

(:STYLE "EMACS")

CTRL/X z

Grow Window

Two-Key Sequences Starting with ESCAPE

ESCAPE CTRL/SPACE

(¢:STYLE "EMACS")

Unset Select Mark

ESCAPE CTRL/D

(:STYLE "EMACS")

Delete Whitespace

ESCAPE CTRL/G

(:STYLE "EMACS")

Exit Recursive Edit

ESCAPE CTRL,/U

(:STYLE "EMACS")

Supply Prefix Argument

ESCAPE CTRL/V

(:STYLE "EMACS")

Page Next Window

ESCAPE CTRL/W

(:STYLE "EMACS") Undo Previous Yank

ESCAPE CTRL/Y

(:STYLE "EMACS")

Yank Previous Replace

(:STYLE "EMACS")

Line to Top of Window

ESCAPE

ESCAPE ,

(¢:STYLE "EMACS") Beginning of Window

ESCAPE

(:STYLE "EMACS")

End of Window

ESCAPE <

(:STYLE "EMACS")

Beginning of Buffer

ESCAPE >

(:STYLE "EMACS")

End of Buffer

ESCAPE ?

(:STYLE "VAX LISP") Apropos Word

ESCAPE

]

(:STYLE "VAX LISP")

Close Outermost Form

EDITOR

Table

C-2

COMMANDS AND

KEY BINDINGS

(cont.)

Key(s)

Context

and

Command

ESCAPE

(:STYLE

"EMACS")

Beginning

ESCAPE

(:STYLE

"EMACS")

Backward

Word

ESCAPE

(:STYLE

"EMACS")

Capitalize

ESCAPE

(:STYLE

"EMACS")

Delete

ESCAPE

(:STYLE

"EMACS")

End

Paragraph

ESCAPE

(:STYLE

"EMACS")

Forward

ESCAPE

(:STYLE

"EMACS")

Kill

ESCAPE

(:STYLE

"EMACS")

Downcase

Paragraph

Word

Paragraph
Word

ESCAPE n

(:STYLE "EMACS") Next Pafagraph

ESCAPE

(:STYLE

"EMACS")

ESCAPE

(:STYLE

"EMACS")

Query

ESCAPE

(:STYLE

"EMACS")

Transpose

ESCAPE

(:STYLE

"EMACS")

Upcase

ESCAPE

(:STYLE

"EMACS")

ESCAPE

(:STYLE

"EMACS")

Execute

ESCAPE

(:STYLE

"EMACS")

Yank

ESCAPE

(:STYLE

"EMACS")

Scroll

Window

ESCAPE

DELETE

(:STYLE

"EMACS")

Delete

Paragraph

Replace

Words

Word
Screen

Named

Command

Previous
Up
Word

ESCAPE

<X]

Two-Key

Sequences

Starting with Keypad PF1

keypad

PF1

(:STYLE

"EDT

Emulation")

Open

Line

keypad

PF1

(:STYLE

"EDT

Emulation")

EDT

Change

Case

keypad

PF1

(:STYLE

"EDT

Emulation”)

EDT

Delete

keypad

PF1

(:STYLE

"EDT

Emulation”")

EDT

Special

End

Insert

Line

EDITOR COMMANDS AND KEY BINDINGS

Table

C-2

(cont.)

Key(s)

Context and Command

keypad PF1

(:STYLE

"EDT

keypad

PF1

(¢:STYLE

"EDT Emulation”)

Beginning of Buffer

keypad

PF1l

(:STYLE

"EDT

EDT Paste

keypad

PF1

(¢:STYLE

"EDT Emulation")

Execute Named

keypad

PF1

(:STYLE

"EDT

EDT Replace

keypad PF1

(:STYLE

"EDT Emulation")

Unset Select Mark

keypad

ENTER

(¢:STYLE

"EDT Emulation")

EDT

keypad PF1

(:STYLE

"EDT Emulation")

EDT Undelete

keypad PF1

(¢:STYLE

"EDT Emulation")

EDT Undelete Word

keypad PF1l

PF1

(¢:STYLE

"EDT Emulation")

Supply Prefix Argument

keypad PF1

PF3

(:BUFFER "General
Alternatives

keypad PF1

PF3

(:STYLE

"EDT Emulation")

EDT Query Search

keypad PF1

PF4

(:STYLE

"EDT Emulation")

EDT Undelete

PF1

Emulation")

Emulation”")

End of Buffer

Prompting")

Command

Substitute

Prompt

Character

Show

Line

INDEX

Page

numbers

page

1in

Part

page

the

Index
Page

Part

the

numbers

form
in

the

c-n

(for

form n

example,
(for

: ALLOCATION
description,

(table),
stepper

Editor

prompt

Anchored

...A...

APROPOS
output

output

depth,

Abbreviating

output

length,

Abbreviating

printed

: ACCOUNT

6-23

string,

7-9,

"Apropos"
using,

7-14

function,

(table),

keyword

function,

ARGUMENTS

keyword

GET-DEVICE-INFORMATION

function,

"Activate

Minor

Style"

frame,

with

SHOW

5-12

command,

5-16

command,

5-17

keyword

Arrays,

structure

facility,

command

Arrow

with

BOTTOM

with

DOWN

with

TOP
UP

command,

command,
command,

command,

function,

:AST-ACTIVE

5-15

7-6,

3-17

BIND-COMMAND
3-40

keyword

GET-PROCESS-INFORMATION

function,

5-16

keyword

usage,

specifying

5-17

5-15

7-6

keys

Editor

BACKTRACE

7-6

constant,

specialized,

1-5

modifier,

5-12

with

constant,

7-6

constants,
creating,

debugger

constant,

7-6

5-4

function,

with

:ALL

SET

ARRAY-RANK-LIMIT

GET-PROCESS~-INFORMATION

ALL

with

command

ARRAY-TOTAL-SIZE-LIMIT

B-3

:ACTIVE-PAGE-TABLE-COUNT

Alien

7-29
debugger

7-6

Editor

command
stack

5-1

ARRAY-DIMENSION-LIMIT

Active

function

information,

‘modifier,

51
:ACP-TYPE

3-13

command,

3-7

description,

GET-DEVICE-INFORMATION

using,

7-29

debugging

5-1

Editor

APROPOS-LIST

keyword

GET-PROCESS-INFORMATION

:ACP-PID

information,

1-7

(table),

6-24

3-31

windows,

description,

output,

3-9

function

help,

6-24

input,

3-9

debugging

lines,

6-25

control

function,

Alternatives

5-25

files,

Access

description,
5-26

Abbreviating

7-18,

keyword

GET-FILE-INFORMATION

command

Abbreviating

function,

:ALLOCATION-QUANTITY

5-13

5-10

(table),

refer

keyword

MAKE-ARRAY

command

:AST-COUNT

keyword

GET-PROCESS-INFORMATION

TRANSLATE-LOGICAL-NAM

function,

137

Index-1

25)

II.

debugger

refer

2-13)

example,

INDEX

:AST-ENABLED

"Bind Command"

keyword

function,
:AST-QUOTA

specifying

using,

keyword

GET-PROCESS-INFORMATION

function,
ATTACH

function

context,

specifying

keys,

using,
keyword

3-40

and

ED,

3-6

BIND-KEYBOARD-FUNCTION

description,

garbage

invoking

BACKTRACE

command

description,
(table),
stepper

Binding

5-17

(table),
: BACKUP-DATE

5-24

keyword
66

function,
function,

:BIO-COUNT

7-22,

keyword

GET~-PROCESS-INFORMATION

style

"Backward

Word"

Editor

"EMACS"

style

binding,

B-4

command
B-4

function,

:BIO-QUOTA

keyword

Bits

command,

7-5

style

BOTTOM debugger

description,

binding,

Line"

B-5

Editor

(table),
BREAK

style

"Beginning

binding,

Outermost

command,
of

Form"

3-27

Paragraph"

Editor

"Beginning

binding,

Window"

B-4

Editor

the

break

(table),

7-29

style

binding,

Editor

1-5,

5-5,

invoking,

B-5

prompt,

command,

using,

5-5,
5-5

5-5

5-6

variables,

3-46

specifying

loop,

message,

Command"

context,

3-40

Index-2

character

information,

invoking

exiting,

command

control

description,

Break

style

command

5-10

debugging

B-4

command
"EMACS"

function,

5-15

function,

binding

command
"EMACS"

keyword

55
Editor

3-26

"EMACS"

"Beginning

GET-FILE-INFORMATION

Buffer"

"Beginning

Editor

function,
attribute,

:BLOCK-SIZE

GET-PROCESS-INFORMATION

"Beginning

keyword

GET-PROCESS-INFORMATION

keyword
function,

keyword

GET-PROCESS-INFORMATION

function,

:BIO-OPERATIONS

3-25

:BASE-PRIORITY

function,

Editor

"EMACS"

5-5

GET-PROCESS-INFORMATION

keyword

Character"”"

command,

"Bind

7-24

loop,

105

function,

:BATCH

stack,

break

:BIO-BYTE-QUOTA keyword

5-27

GET-FILE-INFORMATION
"Backward

the

GET-PROCESS-INFORMATION

command

description,

7-18

functions,

:BIO-BYTE-COUNT

5-10

function

collector,

interrupt

debugger

3-42

3-40

BIND-KEYBOARD-FUNCTION

GET-PROCESS-INFORMATION

function,

3-39

specifying

:AUTHORIZED-PRIVILEGES

keys,

3-39

BIND-COMMAND

function

description,

Editor command

(Cont.)

GET-PROCESS-INFORMATION

5-7

5-4

9,
9

loop,
to

to,

5-1

5-7

5-5

INDEX

*BREAK-ON-WARNINGS*

Code

variable,

defining
WARN

attribute,

Command

5-14

error

function,

: BROADCAST

(CLI)

4-6

handler,

Command

144

keyword

GET-TERMINAL-MODES
SET-TERMINAL-MODES

function,

:BUFFER-SIZE

5-8

stepper,

5-27

See

keyword

GET-DEVICE-INFORMATION

levels,

debugger,

Command

108

function,

112

121

5-34

modifiers

Debugger

: COMMAND-STRING
SPAWN

Interpreter

commands,

tracer,

function,

7-5

Language

keyword

function,

112

Commands

Buffers

Editor

see

Editor

see

buffers

Editor

commands

Comments
LISP

Inserting with

CALL debugger

COMMON LISP,

command modifier,

COMPILE

5-12

with

SHOW

Call-out
Cancel

command,

facility,

character,

description,

/COMPILE

tag

style

binding,

function,

CHAR-FONT-LIMIT

constant,

CHAR-NAME-TABLE

function,

~J ~J

changing

names,

2-16

with /LIST

2-19

editor,

with /OPTIMIZE qualifier,

3-21

2-21

7-5

with /VERBOSE qualifier,

with /WARNINGS
3-16

inserting with Editor,

3-16

specifying

COMPILE-FILE
compiler

"Bind Command”,

compiling

Outermost

command,

:CLUSTER-SIZE

function,

(table),

Editor

2-23

2-24
17,

files,

7-26

2-7

7-29

*COMPILE-VERBOSE* variable
default for :VERBOSE keyword,

3-24

keyword

GET-DEVICE-INFORMATION

1-4,

restrictions,

description,

3-37

Form"

qualifier,

3-39

file,

2-20

with /OUTPUT_FILE qualifier,

7-5

representation,

"Close

|
qualifier,

2-21

7-5

Checkpoint

2-18

qualifier,

with /NOOUTPUT_FILE

nongraphic

Editor

qualifier,

with /MACHINE_CODE

case with

constants,

7-26

2-15

7-5

comparisons,

compiler,

2-10

with /INITIALIZE qualifier,

constant,

2-14

with /ERROR_ACTION qualifier,

4-7

CHAR-CODE-LIMIT

constant,

attributes,

and macros,

2-13

(table),

CHAR-BITS-LIMIT

description,

140

7-25

2-17

files,

optimizing

B-5

142

defining an error handler,
error messages, 4-3

Characters,

13,

1-3

qualifier,

description,

command,

modes,

"EMACS"

functions

compiling

Editor

3-29

CERROR

3-16

2-17

"Capitalize Word"

1-4,

restrictions,

compiling

1-5
10

CANCEL-CHARACTER-TAG

function,

compiler

5-17

Editor,

1-2

function,

15
description,

Index-3

INDEX

*COMPILE-WARNINGS*
default

for

wvariable

:WARNINGS

Controlling where

keyword,

description,

COMPILEDP

garbage

function

Compiler,

1-3,

7-25

7-29,

7-29

2-20,

7-26

- function,

code,

7-27

safe

code,

7-27

restrictions,

COMPILE

:CPU-TIME

function,

7-25

function,

COMPILE-FILE

: CREATION-DATE

7-25

function,

prompt

GET-FILE-INFORMATION

7-26

input,

3-8

and

new

line

binding,

Constructor

recovering

function

allocating

static

space,

7-18

CONTINUE

command,

debugger

1-10

(table),

2-4

CTRL/Q,

2-4

5-10

exiting

the

CTRL/R,

2-4

CTRL/S,

2-4

break

loop,

5-5,

CTRL/T,

2-4

characters

CTRL/U,

1-10,

CTRL/X,

2-4

Editor

functions,

7-24,
6

1-10,

information

about

Editor,

"Bind

Command",

key

2-4

direction

: CURRENT

3-7

Editor

CTRL/Y,

command,

3-43

Current

specifying

2-4

3-17

keyword

THROW-TO-COMMAND-LEVEL

function,

121

3-39

specifying

function,
(table),

BIND-COMMAND

Current

package,

3-40

Current

stack

from

functions,

7-25,

function,

stack,

debugger,

5-7

overflow,

7-18,

frame

See

Stack

keyword

GET-PROCESS-INFORMATION

function,

7-19

: CYLINDERS

105

indentation,

Controlling margins,

keyword

GET-DEVICE-INFORMATION

frame

allocation,

Controlling

: CURRENT-PRIVILEGES

5-3

5-7

keyword

GET-PROCESS-INFORMATION

139

stack

frame,

: CURRENT-PRIORITY

2-4

unbinding

storage

3-16

7-25,

2-4

Editor

3-16

bindings,

error,

3-43

Editor,

representation,

inserting with
returning

binding,

Editor

prohibition

key

3-43

binding,

function

Editor

from

prohibition

5-14

description,

cancel

CTRL/0O,
command

description,

Control

CANCEL-CHARACTER-TAG,

prohibition

directives,

6-8

binding

function,

CTRL/C

3-9

Conditional

Control

keyword

files,

DCL

keyword

GET-PROCESS-INFORMATION

Completion
Editor

keyword

GET-PROCESS-INFORMATION

fast

:CPU-LIMIT

122

collector,

getting,

optimizations,

begin,

time

displaying,

description,

lines

6-11

CPU

new

6-13

6-4

Index-4

function,

INDEX

-D-

*DEBUG-PRINT-LENGTH*

variable

controlling output,

Data

description,

representation,

7-2

7-6

*DEBUG-PRINT-LEVEL*

structure, 1-1
Data types
arrays, 7-6, 86

STOP,

1-10

7-3

DECnet -VAX

2-1

network
Default

:DCL-SYMBOLS keyword
SPAWN function, 112
DEBUG

See

7-13

also
*DEFAULT-PATHNAME-DEFAULTS*

debugging information,
‘description, 21
invoking the debugger,
stepper command
description, 5-26

5-1

variable
description, 25
: DEFAULT-EXTENSION keyword
GET-FILE-INFORMATION function,
55

5-8

(table), 5-24
DEBUG function
control

: DEFAULT-PAGE-FAULT-CLUSTER
keyword
character

to,

GET-PROCESS-INFORMATION

:DEBUG keyword

function,

See *ERROR-ACTION*
DEBUG-CALL

function,

variable

5-18

default directory,

TRACE macro, 5-36,
*DEBUG-IO* variable
debugger, 5-8

5-20

*DEFAULT-PATHNAME-DEFAULTS*
variable

description, 22
:DEBUG-IF keyword

stepper,

operations,

directory

changing, 25
DEFAULT-DIRECTORY function,

function

binding

5-20

descriptions, 5-13 to 5-17
modifiers (table), 5-12
(table), 5-10
controlling output, 23, 24
error handler, 4-2 to 4-4
exiting, 5-9, 5-14
invoking, 5-8, 5-26, 5-36, 21,
125
prompt, 5-8
sample sessions, 5-18
using, 5-10
Debugging facilities, 1-5
See also Break loop, Debugger,
Stepper, Tracer, Editor
Debugging functions and macros
(table), 5-1
Declarations, 7-27

1-10

1-3,

5-3

commands
arguments, 5-11
entering, 5-11

attributes, 7-5
comparisons, 7-5
constants, 7-5
names, 11
floating-point numbers,
constants, 7-4
integers, 7-2
constants, 7-2
numbers, 7-2
package, 3
packages, 1
pathnames, 37
See Pathnames
strings, 7-6, 86
vectors, 86
DCL commands
CONTINUE, 1-10
LISp,

variable

controlling output,
description, 24
Debugger, 1-5, 5-7 to

constants, 7-6
specialized, 7-6
characters, 7-5

entering,

5-3

DIRECTORY function, 7-15, 37
filling file specification
125

components, 14
resuming a suspended
118

using,

Index-5

7-15,

7-16

system,
|

INDEX

:DEFAULT-PRIVILEGES

keyword

DESCRIBE

GET-PROCESS-INFORMATION

function,

DEFINE-ALIEN-STRUCTURE

allocating

DEFINE-FORMAT-DIRECTIVE

description,

using,
Device,

FUNCTION
macro

using,

2-5

programs,

2-5

:DEVICE~-NAME

binding,

:DEVICE-TYPE

2-4

Buffer"

:DIO-COUNT
Editor

"EMACS"
"Delete

binding,

Word"

style

binding,

command

function,

:DIO-QUOTA

command

Word"

B-5

Editor

function,

:DIRECTION
OPEN

binding,

Whitespace”

B-5

Editor

command
"EMACS"

style

binding,

DESCRIBE

function

debugging

information,

description,
help,

1-7

5-1

7-23

6-6

directive,

6-11

“&

directive,

6-11

directive,

6-6

directive,

6-11

@ directive,

6-11

keyword

function,

directive,

function

B-5

DELETE-PACKAGE

description,

keyword

GET-PROCESS-INFORMATION

binding,

style

keyword

GET-PROCESS-INFORMATION

B-5

Character”

:DIO-OPERATIONS

command
"Delete

keyword

GET-PROCESS-INFORMATION

B-5

Editor

style

"EMACS"

function,

Character"

Editor

keyword

function,

GET-DEVICE-INFORMATION

Editor

3-36

style

"EMACS"
"Delete

keyword

command
"Delete

function,

GET-DEVICE-INFORMATION

B-6

3-34

"EMACS"

keyword

Editor

3-36

Named

function,

GET-DEVICE-INFORMATION

3-34

using,

keyword

:DEVICE-DEPENDENT-1

Buffer"

style

command,

function,

key,

function,

GET-DEVICE-INFORMATION

programs,

command,
"EMACS"

keyword

: DEVICE-DEPENDENT-0

Current

"Delete

7-9

functions,

macro

creating

GET-DEVICE-INFORMATION

macro

"Delete

field,

:DEVICE-CLASS

list-print

creating

3-13

6-19

DELETE

information,

GET-DEVICE-INFORMATION

6-19

description,

"Delete

command,

:DEVICE-CHARACTERISTICS

DEFINE-LIST-PRINT-FUNCTION

DEFUN

Editor

keyword

pathname

macro

DEFINE-LIST-PRINT-

DEFMACRO

command,

1-8

:DEVICE

DEFINE-GENERALIZED-PRINT-

Defining

Editor

3-7

getting

description,

3-8

3-49

7-29
Word"

"Describe"

6-21

macro,

pointer,

(Cont.)

Editor,

3-13

macro

-FUNCTION

FUNCTION

using
"Describe

7-18

DEFINE-GENERALIZED-PRINT

macro,

from

(table),

macro

static -space,

function

invoking

directive,

6-28

__directive,

6-6,

Directives

for

6-16

Directory,

Index-6

1-8

6-11

handling

lists,

INDEX

DIRECTORY

"Edit

function

description, 37
pathnames, 7-15
(table), 7-29
:DIRECTORY keyword

using,
Editing

pathname field, 7-9

DO-SYMBOLS macro, 1, 3
Documentation string, 35

file

7-4

DOUBLE-FLOAT-NEGATIVE-EPSILON
constant, 7-4

debugger command modifier, 5-12
with SEARCH command, 5-15
"Downcase Region" Editor command,
3-29

Editor

searching, 3-18
using pointer, 3-48
|
customizing, 3-38

debugging facility,
errors while using,
exiting,

style binding,

function

3-47

5-2

information

invoking,

TRACE macro, 5-37, 126
Dynamic memory, 2-19, 105,

7-17,

118
7-18

: ECHO keyword

GET-TERMINAL-MODES function,
SET-TERMINAL-MODES function,

3-5

character,

keyboard macros,

3-45

label strip, 3-4
loading files, 2-6
modifying function and macro
definitions, 2-7
moving text, 3-20
using pointer, 3-48

overview of operation,

108

function

and BIND-KEYBOARD-FUNCTION, 3-6
binding control character to, 6
debugging information, 5-2

description, 41
resuming Editor with, 3-5
starting Editor with, 3-3
(table), 7-29
:
1]
EQ" 1] Editor command, 3-36

style binding,

area,

3-3,

invoking with control

using,

3-11

getting help, 3-7
help window, 3-7
removing, 3-7
scrolling, 3-7

B-5

description, 40
(table), 7-29
:DURING keyword

"EMACS"

5-39
3-9

by deleting VAXstation window,

command,

debugging information,

3-17

moving by words,

debugger command
description, 5-15
(table), 5-10

garbage collector,

3-17

moving by lines,

DOWN

DRIBBLE

1-9

type,

copying text, 3-20, 3-21
creating programs, 2-5
cursor movement, 3-17
by LISP entities, 3-18
current direction, 3-17

7-3

3-29

3-40

1-4

checkpointing, 3-37
checkpointing file

DOUBLE-FLOAT-EPSILON constant,

"EMACS"

in BIND-COMMAND

function,

Editor,

floating-point numbers,

"Downcase Word"

3-33
keys

specifying

DO-ALL-SYMBOLS macro,

Double

Editor command, 3-37
style binding, B-6

File"

"EMACS"

)
3-47
protection against work

pausing, 3-10
on VAXstation,

refreshing the screen, 3-9
repeating operations, 3-23
restoring deleted text, 3-20
3-5

saving work, 3-10
searching, 3-18

substituting in text,

3-33

Index-7

loss,

3-37

resuming,

B-6

3-3

3-22

INDEX

Editor

(Cont.)

table
text

deletion,

characters,

lines,

3-20

by words,

3-19

LISP

undeleting
using
Editor

summary,

code,

with

3-15

creating,

3-46

changing,
deleting,

order

3-33

"General

Editor

two,

Prompting",

C-14

inserting

maintained

into

other

3-35

by,

buffers,

moving

between,

3-36

endpoints,

3-18

conflicts,

selecting,

binding

keys

conflicts

3-44
3-44

search,

windows,

changing

size,

style,

floating

3-40

shadowing,

3-44

table

bindings,

C-2

with

table

bindings

key,

3-39

3-7

capturing

sequences

Macro",

Named
3-45

customizing
summary,

Start

3-45

Keyboard

C-2

command,

3-26

Change

Case"

command,
of

command,

Beginning

"EDT

Cut"

"EDT

Delete

"EDT

editing
summary,

3-28

Line"

3-26

Line"

Editor

command,

3-29

3-46

descriptions,

Back

3-18

3-35

Editor

"EDT

"Start

3-48
in,

"EDT

Editor

creating

with

text

"EDT Append"

"EDT
of,

cursor,

3-32

splitting,

and window

3-33

by pointer

pointer,

scrolling

C-14

3-36

3-48

cursor,

3-47
removing,

summary,

pointer

window

indicated

C-14

cancelling,

pointer,

windows,

bindings,

Editor,

3-47

"EMACS"

multiple

within

3-30

3-31

indicated

interpreter,

key binding

buffer

3-30

window,

changing,

3-38

3-31

3-35

changing with

to,

3-45

3-30

anchored

noncurrent

LISP

3-44

style,

3-34

3-40

3-44

style,

current

B-2

from

styles,

major

3-6

Command",

minor

3-32

commands,

3-45

3-44

creating,

3-34

saving contents,
Editor

"Bind

order

3-31

text

3-46

search,

context,

Editor

listing,

name

3-33

3-23
moving

than

3-44

styles,

3-34

information

bindings,

specifying

3-30

key

execution,

global,

3-31

displaying

3-44
on

effect on keyboard macro

3-47

3-30

buffer,

3-23

context

effect

3-30

Editor,

3-6

buffer,

3-44

from within
current

Editor

3-20

keys,

3-6

typing,

pointer,

buffers,

context,

3-11

repeating,
3-14

text,

(Cont.)

invoking with

issuing,

on VAXstation,

editing

commands

general-purpose

3-19

insertion,

typing

C-2

3-19

text

Editor

commands,

Index-8

command,

Character"

command,

3-27

Delete

Line"

3-27
3-24

Editor

3-28

Editor

command,

INDEX

"EDT Delete Previous Character”
Editor command, 3-27
"EDT Delete Previous Line" Editor
command,

3-28

command,

3-27

"EDT Delete Previous Word"

Editor

"EDT Delete to End of Line"
Editor command, 3-28
"EDT Delete Word" Editor command,
3-27

"EDT Emulation"

Editor

3-26

"EDT Move Character" Editor
command, 3-25
"EDT Move Page" Editor command,
3-26

"EDT Move Word"

Editor command,

3-25

"EDT Paste" Editor command, 3-28
"EDT Query Search" Editor command,
3-26

"EDT Replace"

Editor command,

Scroll Window"
3-26

command,

"EDT Search Again"

Editor

:END-OF-FILE-BLOCK keyword
GET-FILE-INFORMATION function,

7-23

Editor command,

: ENQUEUE-COUNT keyword
GET-PROCESS-INFORMATION
function, 67
|

: ENQUEUE-QUOTA keyword
GET-PROCESS-INFORMATION

function, 67
EQ function, 7-2
EQUAL function, 7-12

3-25

Editor command,

3-29

"EDT Undelete Character"

ERROR

debugger command
description, 5-16
(table), 5-10
function, 142
defining an error handler,

Editor

command, 3-28
"EDT Undelete Line" Editor
command, 3-28
"EDT Undelete Word" Editor
command, 3-28
:ELEMENT-TYPE keyword
OPEN function, 7-23
"EMACS Backward Search" Editor

4-7

error messages,
listing

file

command

"EMACS"

style binding,

4-2

Error

type,

1-9

messages

compiler, 18
debugger, 5-16
error handler,

"EMACS" style binding, B-5
"EMACS Forward Search" Editor
command

command,

"EDT Set Direction Backward"
Editor command, 3-25
"EDT Set Direction Forward"
Editor command, 3-25
"EDT Special Insert" Editor
command,

Editor

"EMACS" style binding, B-5
"End of Line" Editor command
"EMACS" style binding, B-4
"End of Outermost Form" Editor
command, 3-27
"End of Paragraph" Editor command
"EMACS" style binding, B-4
"End of Window" Editor command
"EMACS" style binding, B-5
End-of-file operations, 7-21

3-27

"EDT Substitute"”

3-46

END-OF-FILE-BLOCK keyword
GET-FILE-INFORMATION function,

3-29

"EDT

command,

"End of Buffer"
3-26

Editor command,

"EDT End of Line"

key binding conflicts, B-2
key bindings, B-4
Enabling pretty printing, 6-3
"End Keyboard Macro" Editor

style,

3-44

Editor style, B-1
activating, B-3
as major style, B-4
as minor style, B-3

"EMACS"

100

error-handler definition,

B-5

format,

Index-9

4-2

4-6

INDEX

ESCAPE

Error

messages

warnings,
types,

4-2

2-24,
to

fatal,

4-3
144

1-4,

function,

creating,

143

debugging

information,

5-1

defining,

4-5

description,

stepper

100

"Evaluate
-

142
44

"Exchange
"EMACS"

variable,

"Execute

also /ERROR_ACTION

defining

error
43

fatal

error,

4-3

WARN

function,

4-3

"Execute

handler,

4-6
EXIT

GET-DEVICE-INFORMATION

function,

52
PRINT-SIGNALED-ERROR

function,

(table),

142

4-7

/ERROR_ACTION

also

functions,

2-15

*ERROR-ACTION*

variable
description,

2-14

fatal

error,

4-3

modes,

2-13

(table),
with

B-6
Editor

binding,

B-6

See

LISP,

2-2

*ERROR-ACTION*

Recursive

"EMACS"

Editor

3-29

style

Editor

using,

wvariable

Edit"

binding,

B-6

command

3-11,

3-34

:EXPIRATION-DATE
qualifier,

Editor

keyword

"Exit"

Error-signaling

B-5

3-11

command,

100

See

:EXIT

variable

Mark"

function

"Exit

*ERROR-OUTPUT*

binding,

style

exiting

Macro"

Command"

description,

keyword

binding,

style

command,

144

Select

3-46

Named

"EMACS"

4-4

: ERROR-COUNT

style

Keyboard

"EMACS"

error,

and

command

command,

qualifier
continuable

keyword

Point

Editor

description,

Editor

3-12

GET-PROCESS-INFORMATION

3-9

warning,

LISP Region"

:EVENT-FLAG-WAIT-MASK

messages

See

5-26

5-24

function,

Editor,

5-10

command,

keyword

*ERROR-ACTION*

5-13

command

(table),

144

function,

Error

command

description,
4-1

UNIVERSAL-ERROR-HANDLER

EXIT

keyword

GET-FILE-INFORMATION

function,

Extendgg attribute block (XAB),
Exteizions to the FORMAT function,
6-5

6-17

2-10

/INITIALIZE

qualifier,

~F-

2-15
'..J

Edi

Fast-loading

¢t

Er ro r

&
ot

loss,
while

file

B
&

using

1-1

description,
(table),

message,

invoking,

function,

debugger

4-7

:ERROR

function,

SET-TERMINAL-MODES

EVALUATE

variable,

GET-TERMINAL-MODES

EVAL

*UNIVERSAL-ERROR-

HANDLER*

error

3-43

keyword

108

4-4,

handler,

binding

:ESCAPE

4-2

warning,

Error

4-5

continuable,

character

transmitting,

(Cont.)

Editor,

loading,

3-9

locating,

Index-10

file,

type,

1-9

81
81

2-8,

2-14

INDEX

Fast-loading

producing,

file

14,

Font

File

compiling,

getting
name,

function,

FORMAT

2-6

organization,

7-8

VAX

Pathnames,

components,
format,

type,

FORMAT

(table),

1-8
1-9

1-7

number,

File

access

File

name

(FAB),

LISP,

Provided with

function

"Forward Character" Editor
command, 3-25
"EMACS" style binding, B-4

1-8

block

6-17

break-loop messages, 9
error messages, 4-7
warning messages, 144

1-8

version

See

1-7

Format Directives

Namestrings

defaults

6-5

directives

6-6

7-22

specification

also

7-5

user defined, 6-18
FORMAT directives i1n VAX LISP,

1-8

representation,

See

attribute,

FORMAT

2-7

information,

loading,

(Cont.)

Floating-point numbers
(table), 7-3

(Cont.)

"Forward Word" Editor command
"EMACS" style binding, B-4
: FREE-BLOCKS keyword
GET-DEVICE-INFORMATION function,

representation

File

FILE-LENGTH

function, 7-23
FILE-POSITION function, 7-23

Files

Fresh

creating

from Editor,

compiled,

file,

3-10

defining,

checkpoint

Editor
Editor

input completion, 3-9
protection against loss,

3-37

Editor

buffer,

“/FILL

directive,

FINISH

stepper

editing, 140
pretty printing, 90
implementation-dependent

7-29

GET-PROCESS-INFORMATION

keyword

creating,

modifying,

2-7

FUNCTION debugger command
modifier, 5-12
with SET command, 5-16
with SHOW command, 5-17
Function

GET-PROCESS-INFORMATION

keys

specifying

: FIXED-CONTROL-SIZE keyword
GET-FILE-INFORMATION function,
56
Floating windows,

7-24
7-25

keyboard

keyword

:FIRST-FREE-P1-PAGE

7-24

garbage collector,
suspended systems,

5-27

GET-FILE-INFORMATION function,
7-23, 56
:FIRST-FREE-PO-PAGE keyword

function,

definition

interpreted, 13
interrupt, 7-18,

6-6

command

(table), 5-25
:FIRST-FREE-BYTE

function,

2-7
2-5

(table),

3-23

description,

compiling,

Editor

6-11

Function

3-10

editing with Editor, 3-4
saving edited version,

inserting

line directive,

3-33

Floating-point numbers, 7-3
constants (table), 7-4

in "Bind Command", 3-39
specifying in BIND-COMMAND
function, 3-40
: FUNCTION keyword
ED function, 42

Index-11

INDEX

Functions

GET-FILE-INFORMATION

editing

definition,

moving

back

3-3

LISP,

evaluating
in

3-10

number

Editor,

function

(Cont.)

bytes

GET-GC-REAL-TIME

3-10

description,

collector,

7-17

available

space,

changing

messages,

control

stack

7-19

(table),

7-18

overflow,

function

returning

displaying

time,

122

elapsed

time,

failure,

7-19

frequency

interrupt

functions,

invoking,

7-18

keywords
record

7-17

static

*POST-GC
variable

7-18,

systems,

function

variables,

7-18

Graphics

: GROUP

Editor

buffer,

command
5-15

5-10

interface,

1-6

keyword

GET-FILE-INFORMATION

function,

56
print

functions,

6-21

GET-PROCESS-INFORMATION

function,

6-21

ENABLED-P

description,

"EMACS"
to

description,

A’T‘TfiN

(table),

Editor

command,

3-37

(table),

GET—FIT FaTNENDR

"Grow Window"

function

function,

137

GET-DEVICE-INFORMATION

description,

TRANSLATE-LOGICAL-NAME

GENERALIZED-PRINT-FUNCTION-

keywords

2-17

keyword

debugger

(table),

ENABLED-P

keywords

function

5-7

description,

collector

GENERALIZED-PRINT-FUNCTION-

function,

75
73

GET-PROCESS-INFORMATION

C-14
Generalized

function

2-22

:GLOBAL-PAGES

2-25

GOTO

Prompting"

5-7

function,

messages,

installing,

7-17

variable

description,

(table),

deleting,

garbage

function

sections

*GC-VERBOSE*

key

7-22

definitions,

-MESSAGE*

memory,

about

Global

*PRE-GC-MESSAGE*

description,

"General

variable,

changing

description,

efficiency,

(table),

GET-VMS-MESSAGE

49,

suspended

length,

keywords

*POST-GC-MESSAGE*

also

run-time

7-24

7-25

GET-TERMINAL-MODES

7-18,

variable
messages,

See

description,

also

information

GET-PROCESS-INFORMATION

7-17,

use,

function,

bindings,

memory,

message,

7-29

description,

dynamic

function

GET-KEYBOARD-FUNCTION

7-18,

7-19

CPU time,

See

description,

7-18

7-23

GET-INTERNAL-RUN-TIME

Garbage

file,

GET-GC-RUN-TIME
...G..

function

using,

style

binding,

B-6

3-35

54
51

o J

'Fn'nnticn

58
55

: HALF-DUPLEX

keyword

GET-TERMINAL-MODES

Index-12

function,

INDEX

: HALF-DUPLEX keyword
SET-TERMINAL-MODES

(Cont.)
function,

Hash

lists,

keyword

GET-PROCESS-INFORMATION

6-16

function,

table

keyword

comparing keys, 80
initial size, 79

: IMAGE-PRIVILEGES

rehash

function, 68
Implementation notes, 7-1 to 7-30
Improperly formed argument lists,

size,

GET-PROCESS-INFORMATION

threshold, 78
HASH-TABLE-REHASH-SIZE
rehash

function

description, 77
HASH-TABLE-REHASH-THRESHOLD

6-28

"Indent

3-24

function

description,

HASH-TABLE-TEST

79
function

description,
HELP

debugger command
description, 5-13
(table), 5-10

modes,

3-7

facilities

DCL,

1-7

5-13

debugger,
LISpP,

1-7

stepper,

command,

"Help"

Error"

Editor

3-13

Editor

HERE debugger

3-12
command modifier,

command,

5-12

with BACKTRACE command,
with SHOW command, 5-17
Hibernation state, 112
:HOST

keyword

pathname

field,

7-9

5-17

"Insert Buffer" Editor command,
3-25, 3-37
using, 3-23, 3-36
"Insert Close Paren and Match"”
Editor command, 3-24
"Insert

6-6

LOAD

function,

:IF-EXISTS

OPEN

File"

Editor

command,

3-25

: IF-DOES-NOT-EXIST keyword
OPEN

function, 7-23
FILE-POSITION function, 7-23
functions, 7-22, 7-23
#$\NEWLINE character, 7-19
record length, 7-22
terminal input, 7-20
WRITE-CHAR function, 7-24

= B

directive,

2-11

FILE-LENGTH

5-26

"Help on Editor

command,

with /COMPILE qualifier, 2-14
with /RESUME qualifier, 2-22
with /VERBOSE qualifier, 2-23
: INPUT-FILE keyword
SPAWN function, 112
Input/Output, 7-19 to 7-24
end-of-file operations, 7-21
file organization, 7-22

Help
Editor,

Editor

2-13

(table),

stepper command
description, 5-26
(table), 5-25

Help

LISP Line"

"Indent Outermost Form" Editor
command, 3-24
Indentation, 6-13
preserving, 6-9
Information area, 3-5
pointer cursor in, 3-48
JINITIALIZE qualifier
description, 2-15

description, 78
HASH-TABLE-SIZE function

directive,

6-11

: IMAGE-NAME

109

Handling

If-needed new line

81
7-23

keyword
function, 7-23

"EMACS" style binding, B-5
using, 3-23
Insignificant stack frame, 5-4
/INSTALL qualifier
description, 2-17
modes,

2-13

(table),

Index-13

2-11

INDEX

Integers,

7-2

constants,

Keys

7-2

/INTERACTIVE

description,
modes,

binding

qualifier,

1-3

2-17

2-13

(table),

2-11

Interpreted

59,

61,

function

restoring,

140

Interpreter,

1-3

creating

function

functions,

garbage

collector,

bindings,

bindings

input,

C-14
by

command,

Editor,

3-39

function

2-5

see

"Kill

facility,

7-18,

Function

Line"

"Kill

keys

Editor

style
style

Region"

"EMACS"

command

binding,

Paragraph"

"EMACS"

1-6

7-24

systems,

terminal

Interrupt

"EMACS"

Interrupt

suspended

table

"Kill

Interrupt

commands

table
within

63
definition

programs,

Editor

C-2

INTERNAL-TIME-UNITS-PER-SECOND

constant,

(Cont.)

Editor

B-5
command

binding,

Editor

style

B-5

command

binding,

B-5

7-25

7-21

levels

keyboard

functions,

Label

strip,

3-4

LEAST-NEGATIVE-DOQUBLE-FLOAT
o

] -

constant,

: JOB-SUBPROCESS-COUNT

keyword

GET-PROCESS-INFORMATION

function,

7-4

LEAST-NEGATIVE-LONG-FLOAT

constant,

7-4

LEAST-NEGATIVE-SHORT-FLOAT

constant,

7-4

LEAST-NEGATIVE-SINGLE-FLOAT
-

Keyboard

constant,

functions

creating,

interrupt

level,

specifying,
passing
Keyboard
named,

constant,

arguments

constant,

to,

constant,

3-45

constant,

: LEVEL
keypad

Lexical

binding

commands,

binding

Editor
in

3-38

commands

"EMACS"

Limiting

style,

key binding

shadowing,

bindings,

selecting

key

3-40

3-44

:LINES

WRITE

"Bind

BIND-COMMAND

Top

Window"

Editor

binding,

B-5

6-4,

style

Command",

6-6

keyword

and

WRITE-TO-STRING,

6-3

LISP

command,

function,

lines,

" /LINEAR/ directive,

sequence,

3-39
specifying

"EMACS"

C-14

7-26

command

3-43
specifying

restrictions,

output

6-25
"Line

interpreter,

environment

compiler

B-2

LISP

function,

Keys

conflicts

7-4

keyword

BIND-KEYBOARD-FUNCTION

Numeric

multiple

7-4

LEAST-POSITIVE-SINGLE-FLOAT

numeric

from

7-4

LEAST-POSITIVE-SHORT-FLOAT

Keypad

see

7-4

LEAST-POSITIVE-LONG-FLOAT

macros,

7-4

LEAST~-POSITIVE-DOUBLE-FLOAT

1-3,

qualifier

3-40

Index-14

2-1

descriptions,

2-25

2-10

INDEX

LISP

(Cont.)

command

qualifier modes (table), 2-13

qualifiers (table),
exiting, 2-2, 44
implementation notes,

2-10
7-1

2-1

processing during garbage
collection, 7-18
program, 1-1
compiling, 2-7
creating, 2-5
loading

File

programming language,
storage allocation,
See
LISP

1-1

2-1

prompt,

SPAWN

function,

: LOGICAL-VOLUME-NAME keyword
GET-DEVICE-INFORMATION function,

7- 3
7- 4

LONG-FLOAT-NEGATIVE-EPSILON
constant, 7-4

LONG-SITE-NAME function
description, 83
(table), 7-30

: LONGEST-RECORD-LENGTH keyword
GET-FILE-INFORMATION function,
56

1-1

also Memory

indenting with Editor, 3-15
typing and formatting with
Editor,

3-15

"List Buffers" Editor command,
3-36

style binding,

"EMACS"

3-31

"List Key Bindings"

B-6

Editor

command, 3-11
using, 3-7
/LIST qualifier

description,
modes,

Long floating-point numbers,
LONG-FLOAT-EPSILON constant,

code

using,

113

GET-PROCESS-INFORMATION
function, 68

Input/Output

See

: LOGICAL-NAMES keyword

:LOGIN-TIME keyword

input/output

See

1-10, 137
83, 84

7-30

invoking,

Logical names,
translating,

2-11

file, 2-18
producing, 14
:LISTING keyword

COMPILE-FILE function,
L.OAD function, 2-6, 2-16

description, 81
(table), 7-30

*LOAD-VERBOSE* variable
81

: LOCAL-EVENT-FLAGS keyword
GET-PROCESS-INFORMATION
fFiinecto ol
1 WAL
An P

2-18

2-13
2-11

(table),

Listing

de CALEAXr

description, 84
(table), 7-30
MACHINE-VERSION function
description, 85
(table), 7-30
modes,

with /COMPILE qualifier, 2-14
List-print functions, 6-19

load message,

:MACHINE-CODE keyword
COMPILE-FILE function, 14
Machine-code listing, 2-18
MACHINE-INSTANCE function

/MACHINE_CODE qualifier,

2-18

2-13

(table),

-M-

Logical block, 6-5
Logical name table,

2-14

with /COMPILE qualifier,
Macro

compiling, 2-7
defining, 2-5

implementation-dependent
(table), 7-29

modifying, 2-7
Major style, 3-44
default, B-4

establishing default,

B-4

MAKE-ARRAY function

allocating static space,

7-18

MAKE-HASH-TABLE function,

77 to

description, 86
(table), 7-30
80

137

Index-15

INDEX

MAKE-PATHNAME

function

constructing
creating

setting

pathnames,

: MAX-BLOCKS

MOST-NEGATIVE-FIXNUM

7-11

MOST-NEGATIVE-LONG-FLOAT

keyword

MOST-NEGATIVE-SHORT-FLOAT

constant,

function,

constant,

keyword

GET-DEVICE-INFORMATION

function,

constant,

: MAX-RECORD-SIZE

keyword

GET-FILE-INFORMATION

7-4

MOST-POSITIVE-FIXNUM

constant,

7-2

function,

MOST-POSITIVE-LONG-FLOAT

function,

MOST-POSITIVE-SHORT-FLOAT

constant,

56
function,

constant,

: MOUNT-COUNT

105

stack,

5-3

2-19,

105,

static,

2-19,

garbage

7-17,

105,

86,

7-18

118

105,

collector,

: MOUNTED-VOLUMES

garbage
modes,

118

function,

"Move

7-18

2-19

LISP

7-17

Comment"

Editor

3-24

Multiline

mode,

Multiline

mode

6-8

new

line

directive,

6-11

2-13

(table),

command,

collector,

keyword

GET-PROCESS-INFORMATION

qualifier

description,

function,

118

collector,
2-19,

7-4

keyword

GET-DEVICE-INFORMATION

control
dynamic,

garbage

7-4

MOST-POSITIVE-SINGLE-FLOAT

GET-PROCESS-INFORMATION

read-only,

constant,

7-4

keyword

GET-FILE-INFORMATION

Minor

7-4

MOST-POSITIVE-DOUBLE-FLOAT

/MEMORY

7-4

MOST-NEGATIVE-SINGLE-FLOAT

:MAX-FILES

Memory,

constant,

7-4

7-12

GET-DEVICE-INFORMATION

: MEMBER

constant,

7-2

7-11

pathnames,

2-11

style,

3-44

o\
K

activating
from

Editor,

from

LISP

activation,
default,

B-3

interpreter,

B-3

mode,

6-26,

6-5,

:NAME

recently

C-14

new

line

6-3

description,

7-9,

7-13
7-13

7-13
6-11

"New LISP

Line"

Editor

command,

3-24
variable,

103

using,
:NEWEST
See

MOST-NEGATIVE-DOUBLE-FLOAT

constant,

7-7,

lines,

103

*MODULE-DIRECTORY*

Modules,

namestrings,

creating,
New

Debugger

Module,

7-10

DIRECTORY

fields,

function,

7-9,

(table),
"Pause
Packages,

current,

"Page

"EMACS"

3
3,

style

binding,

command
B-6

function,

"EMACS"

:PID

keyword

function,

keyword

determining
bound

Pointer

function,

setting

Editor,

3-15

using

function

: POST-DEBUG-IF

pathnames,

7-11

TRACE

7-11

7-12

SET-TERMINAL-MODES

function,

: POST-PRINT

109

PPRINT

109

function,

SET-TERMINAL-MODES

function,

7-21,

109

Pass-through

Pathnames,

also

3-21

function,

7-14

7-11

126

6-2
6-2
function

6-2
function

description,

: PRE-DEBUG-IF
TRACE

File

constructing,

5-36,

PPRINT-DEFINITION

PPRINT-PLIST

pathnames,

pathnames,
7-6

7-18

PPRINT-PLIST

to,

function

creating

collector

keyword

description,

108

3-21

text

constructing

125

PPRINT-DEFINITION

mode,

buffer,

appending

See

description,

function,

keyword

GET-TERMINAL-MODES

3-47

wvariable,

garbage

TRACE macro,

: PASS-THROUGH

PATHNAME

5-36,

messages,

7-21,

3-47

keyword

macro,

changing

keyword

mode,

Editor,

*POST-GC-MESSAGE*

function,

Paste

VAXstation

GET-TERMINAL-MODES

Pass-all

commands

3-49

device

3-49

pathnames,

:PASS-ALL

Editor

to,

appearance

113

pointer,

creating

cursor

Pointing

constructing

function,

VAXstation

Parentheses

PARSE-NAMESTRING

6-9

Pointer

keyword

with

6-15

prefixes

GET-PROCESS~-INFORMATION

using

B-6

function,

binding,

GET-DEVICE-INFORMATION

GET-PROCESS-INFORMATION

: PAGES-AVAILABLE

style

3-34

keyword

function,

buffers,

preserving,

keyword

:PAGE-FILE-QUOTA

matching

command,

3-10

Per-line

GET-PROCESS-INFORMATION

SPAWN

Editor

Per-line prefix,

function,

using,

keyword

:PAGE-FILE-COUNT

: PARALLEL

Editor"

effect

Editor

GET-PROCESS-INFORMATION

7-15

3-11

Window"

: PAGE-FAULTS

7-10

7-9

functions,

-pP-

7-9

7-11

Index-18

macro,

keyword
5-36,

125

INDEX

PRINT-SIGNALED-ERROR function
defining an error handler, 4-6
description, 100

*PRE-GC-MESSAGE* variable, 49
changing garbage collector
7-18

messages,

description, 95
: PRE-PRINT keyword
TRACE macro, 5-36,

*PRINT-SLOT-NAMES-AS-KEYWORDS*
variable

description,

126

6-14

Prefix,

per-line,

connecting to, 4
getting information, 65
identification, 4
: PROCESS keyword
TRANSLATE-LOGICAL-NAME function,

6-15

3-23

Prefix argument,
entering, 3-23
negative, 3-23

Preserving indentation, 6-9
Preserving per-line prefixes,
Pretty printer,

1-5

controlling margins,
miser

mode,

6-9

137

: PROCESS-NAME keyword
GET-PROCESS-INFORMATION

function,

Prompt

3-27

break loop, 5-5
debugger, 5-8

: PREVIOUS keyword
See :VERSION keyword

THROW-TO-COMMAND-LEVEL

function,

Editor

completing input, 3-8
displaying alternative
choices, 3-9

121

Editor

Line"

command,

3-25

"EMACS" style binding, B-4
"Previous Paragraph" Editor

help

LISpP,

style binding, B-4
Screen" Editor command,

3-26

"EMACS" style binding, B-4
"Previous Window" Editor command
"EMACS" style binding, B-6
Print control variables, 6-3
: PRINT

keyword

LOAD function, 81
TRACE macro, 5-36,
*PRINT-LENGTH*, 6-24

125

~ variable, 6-5
*PRINT-MISER-WIDTH* variable
description,

*PRINT-RIGHT-MARGIN*,

6-26

AL TN
L TINLAILL
T DWVAIN

description,

var

5-20

2-1

changing,

123

"Prompt Complete
command,

3-13

command,

3-13

String"

Editor

"Prompt Scroll Help Window"
Editor command, 3-12
"Prompt Show Alternatives" Editor

list

pretty-print, 92
: PROTECTION keyword

GET-FILE-INFORMATION function,
56

_Q_

"Query Search Replace"
command,

"EMACS"
using,

6-4

*DDTmmfiDTflum_MADGIN*

3-7

top-level,

Property

*PRINT-LEVEL*, 6-24
*PRINT-LINES*, 6-4, 6-25
*PRINT-LINES* variable
description, 96
*PRINT-MISER-WIDTH*, 6-26

variable,

on,

2-1

stepper,

command

"EMACS"
"Previous

function, 113
PROCLAIM function, 7-26
SPAWN

Pretty printing, 6-1 to 6-28
"Previous Form" Editor command,

"Previous

102

Process

Editor

3-29

style binding,

3-22

B-5

QUICK debugger command modifier
5-12

with BACKTRACE command,

Index-19

INDEX

QUIT

"Remove

debugger

command,

description,

(table),
stepper

5-14

using,
/REMOVE

command

exiting

5-21

3-32

Editor

command,

2-12

function,

description,

3-25

(table),

"EMACS"

style

binding,

2-22

2-13

(table),
REQUIRE

B-5

/RESUME

103

qualifier,

modes,

File"

"EMACS"

Editor

style

READ-CHAR

binding,

with

B-6

terminal

input,

7-19

7-20

debugger
105,

2-19,

118

garbage

122

length,

Record

Management

7-22

input/output,

Services

stepper

terminal

function,

stepper
keyword

GET-FILE-INFORMATION

keyword

(table),

7-20

5-28

5-25

keyword

:REVISION-DATE

Screen"

Editor

command,

5-10
5-24

function,

keyword

GET-FILE-INFORMATION

3-13

function,

"EMACS"

style

debugger

(table),

binding,

B-6

:RIGHT-MARGIN

command

description,

WRITE

5-14

ROOM

5-10

and

function,

53
tabbing,

Current

command,

"EMACS"

command,

"EMACS"

6-16

Editor

]

Run-time

Editor

3-12

style

2-19

keyword

binding,
s

Windows

memory,

7-30

GET-DEVICE-INFORMATION

3-12

binding,

B-6

Index-20

5-2

105

:ROOT-DEVICE-NAME

Window"

style

Other

information,

specifying
(table),

Relative

6-3

function

description,

keyword

GET-DEVICE-INFORMATION

keyword

WRITE-TO-STRING,

debugging

:REFERENCE-COUNT

Remove

input,

GET-FILE-INFORMATION

GET-DEVICE-INFORMATION

commands,

command

:REVISION

"Redisplay

5-28

arguments,

commands,

description,
function,

56
:RECORD-SIZE

command

debugger

keyword

56
:RECORD-FORMAT

command,

5-11

GET-FILE-INFORMATION

"Remove

stepper

debugger

(RMS)

7-22

:RECORD-ATTRIBUTES

REDO

entering

7-19

length,

5-14

5-10

key

collector,

Record

2-19

command

description,
(table),

displaying,

qualifier,

RETURN

time

record

2-12

/INITIALIZE

with /MEMORY qualifier,

character,

Read-only memory,

118

2-16

function

#\NEWLINE

Real

command

2-26,

2-22

2-13

(table),
"Read

7-30

description,
o

Editor

qualifier

modes,

5-25

Insert"

Windows"

(Cont.)

description,

5-27

stepper,

(table),

Other

command

5-10

description,

"Quoted

5-9

efficiency,

7-17

function,

INDEX

SHORT-SITE-NAME

..S..

(table),
Screen

"Scroll

Window

Editor,

Down"

debugger

3-9

"EMACS"

"Scroll

(table),

style

binding,

Window Up"

"EMACS"

binding,

debugger

command

description,
:SECTORS

stepper

B-5

"Show Time"
"EMACS"

5-15

"Shrink

5-10

Editor

Single

using,

binding,

B-6

Form"

3-12,

3-28

case

of,

3-22

Editor,

outermost

with

form,
paste

”

3-21

Source

3-48
buffer,

function,

"Set

Mark"

Editor

command,

SPAWN

binding,

"EMACS"
Stack

B-5

input

current,

mode,

default

5-3

5-4
5-7

debugger
5-12

directory,

stepper

pathnames,

floating-point

SHORT-FLOAT-EPSILON

description,

tracer

7-12

numbers,
constant,

SHORT-FLOAT-NEGATIVE-EPSILON

constant,

B-6

5-4

number

108

7-4

SHORT-SITE-NAME

command,

binding,

insignificant,

the

7-6

Editor

3-35

frame,

active,

macro

setting

112

arrays,

style

function

terminal

description,

Short

function

using,
style

7-21

changing

3-37

SET-TERMINAL-MODES

SETF

1-9

type,

"Split Window"

5-16

3-28

changing

file

5-11

Select

"EMACS"

Specialized

command

compiling,

description,

(table),

file

locating,

keyword

GET-DEVICE-INFORMATION

description,

constant,

keyword

function,

loading,

: SERIAL-NUMBER

5-4

GET-PROCESS-INFORMATION

3-21

pointer,

with

debugger

frame,

7-4

:SITE-SPECIFIC

3-21

SET

stack

floating-point numbers,

constant,

changing

B-6

SINGLE-FLOAT-NEGATIVE-EPSILON

3-21

defining,

replacing

binding,

7-4

Editor

region

marking

style

SINGLE-FLOAT-EPSILON

cancelling,

B-6

command,

7-3

3-32
Outermost

command,

Editor

3-35

Significant

command,

3-36

"Select

command

binding,

Window"

using,

style

5-25
Editor

style

"EMACS"

function,

"EMACS"

5-27

3-37

keyword

Buffer"

command

(table),

B-5

GET-DEVICE-INFORMATION
"Select

5-17

5-11

description,

Editor.command

style

(table),

command

description,

Editor

command

from

(Cont.)

SHOW

refreshing,

Select

function

7-30

function

7- 3
7- &

command argument,
output,

output,

significant,

5-4

*STANDARD-QUTPUT*
LOAD

function,

variable
81

PPRINT-DEFINITION
PPRINT-PLIST

111

Index-21

5-22
5-34

function,

INDEX

"Start

Keyboard

command,

"Start

Named

Editor

using,
:STATE

Macro"

Editor

Keyboard

command,

Macro"

allocation,

See

Memory

3-45

with
69

creating,

garbage

2-19,

86,

collector,

code,

:STATUS

keyword

105,

118

function,

: SUCCESS

EXIT

STEP

command

description,
5-11

invoking

"Supply

EMACS

"EMACS"

"Supply

stepper,

5-20

Prefix"

style

Editor

"EMACS"

5-28

binding,

style

TRACE

macro,

creating

Editor

binding,

B-6

keyword
5-37,

VSUSPEND function

5-25

B-6

3-29

: SUPPRESS-IF

Step

suspended

126

systems,

2-25

macro

description,

115

description,

*STEP-ENVIRONMENT
*

variable,

Suspended

5-28

description,

116

file

5-28

description,
:STEP-IF

117

TRACE

macro,

Stepper,

1-5,

5-36,

5-20

126

Symbolic

7-25

59
2-22,

2-26

expressions,

1-1

Symbols

arguments,

5-25

descriptions,
(table),

exiting,

editing

5-26

5-28

moving

5-27

5-14,

editing

5-20,

126

5-36,

115,

moving

System
5-21

back

23,

5-20

value,

definition,

back

LISP,

:SYSTEM

LISP,

sessions,

using,

5-24

5-31

keyword

137

1-10

Index-22

3-10

(SID)

TRANSLATE-LOGICAL-NAME

sample

3-10

3-3

identification

controlling,

command,

function

3-3

5-24

5-21,

invoking,

prompt,

2-25

functions,

time,

resuming,

5-32

commands

output,

time,

interrupt

real

1-9

collector,

Internal

keyword

118

2-25

type,

garbage

variable,

118

systems,

creating,

*STEP-FORM*

STOP

Prefix Argument"

command,

command

(table),

function,

6-14

information,
5-2

description,

command
|

stepper

keyword

Suffix,

5-14

macro

debugging

GET-PROCESS-INFORMATION

function,

(table),

keyword

: SUBPROCESS~-QUOTA

keyword

debugger

112

GET-PROCESS-INFORMATION

7-18

return,

: SUBPROCESS-COUNT

GET-PROCESS-INFORMATION
sStatus

3-18

7-6

Subprocess,

memory,

Status

for

Editor,

Strings,

keyword

:ALLOCATION

Static

118

searching

function,

1-1

String

keyword

:STATIC

also

Streams,

3-46

GET-PROCESS-INFORMATION

See

Storage

3-46

function,

INDEX

TOP

=
=

debugger
T

directive,

Tab

6-15

directive,

Tabs,

debugger command modifier, 5-13
with BACKTRACE command, 5-17

6-15

~ /JTABULAR/ directive,

6-6

: TOP

Terminal

getting
input,

information,

changing

modes,

mode,

Top-level

7-21

prompt,

7-21

function,

TRACE

BIND-KEYBOARD-FUNCTION

function,

operations,

GET-TERMINAL-MODES
SET-TERMINAL-MODES

2-2

*TOP-LEVEL-PROMPT*
description, 123

*TERMINAL-IO* variable

end-of-file

loop

2-1

variables,

keyword

GET-PROCESS-INFORMATION

7-21

function,
function,

variable

macro

debugging

information,

description,

124

enabling

the

tracer,

options,

5-35

(table),

7-30

5-2

5-33

*TRACE-CALL*

108

: TERMINATION-MAILBOX

Variable

keyword

description,

GET-PROCESS-INFORMATION

function,

variable,

tracer,

variable

5-20

stepper,

7-20

135

5-37

*TRACE-OUTPUT*

function

#\NEWLINE character,
record length, 7-22

5-32

*TRACE-VALUES*

Text

changing

case

variable,

characters,

3-21

copying with

Editor,

3-20,

cutting and pasting,

3-20

deleting with

Editor,

restoring deleted,

3-21

3-19

moving between
3-36
moving with

disabling,

5-33

enabling,

5-33,

adding

function,

debugging information,
description, 122

5-37

keyword

GET-PROCESS-INFORMATION

(table), 125
5-34
controlling, 23, 24

5-2

7-30

function,

5-36
trace

options
output,

121

:TIMER-QUEUE-COUNT

invoking the debugger, 5-36
invoking the stepper, 5-36
removing information from
output, 5-37

3-20

macro

(table),

124

to output,

defining when

substituting in, 3-22
THROW-TO-COMMAND-LEVEL function
description,

5-39

options

3-20

Editor buffers,

Editor,

5-38

description, 136
Tracer, 1-5, 5-32 to

inserting with Editor, 3-14
starting new line, 3-15

TIME

function,

121

pass-all

TERPRI

keyword

THROW-TO-COMMAND-LEVEL

7-20

: TERMINAL

command

description, 5-15
(table), 5-11

6-15

: TRACKS

keyword

GET-DEVICE-INFORMATION

function,

: TRANSACTION-COUNT keyword
GET-DEVICE-INFORMATION function,
53

GET-PROCESS-INFORMATION

function,

TRANSLATE-LOGICAL-NAME
description, 137

Index-23

function

INDEX

TRANSLATE-LOGICAL-NAME

"Unset

function

(Cont.)

using,

7-13

"Transpose

"EMACS"

Editor

"EMACS"

Characters"

UNTRACE

command

style

"Transpose

binding,

B-5

Words"

Editor

command
"EMACS"
:TYPE

binding,

disabling

the

SEARCH
function,

function,

stepper

5-16

5-11

command modifier,

5-13

debugger

5-15

(table),

"Upcase

Region"

"Upcase
keyword

5-28

5-25

Editor
|

3-29

-={J
-

command,

command

description,

109

Word"

Editor

command,

3-29

GET-FILE-INFORMATION

function,

"EMACS"

User

GET-PROCESS-INFORMATION

function,

style

defined

binding,

FORMAT

:USERNAME
function,

keyword

GET-PROCESS-INFORMATION

function,

description,

B-5

directives,

6-18

UNBIND-KEYBOARD-FUNCTION

unbinding

5-33

command

debugger

keyword

SET-TERMINAL-MODES

5-2

tracer,

description,

7-10

B-5

(table),

field,

binding,

information,

B-5

GET-TERMINAL-MODES

:UIC

style

debugging

keyword

: TYPE-AHEAD

Editor

3-28

macro

debugger

style

pathname

Select Mark"

command,

139

control

characters,

7-25
UNCOMPILE

function

description,
retrieving

:VALUE

140

interpreted

definitions,
Unconditional

new

directive,

6-11

See

141

Editor

using

command

"EMACS"

3-44
3-44

specification

device

Editor,

Editor

on,

3-47

3-46

Vectors

style

binding,

B-5

creating,

keyword

VERBOSE

GET-DEVICE-INFORMATION

with

UNIVERSAL-ERROR-HANDLER

function,

4-1

debugger

command

BACKTRACE

command,

: VERBOSE

description,

error

handler,

142
4-5,

description,

143

LOAD

142

loading
/VERBOSE

Qqualifier

files,

2-6

qualifier

description,

Index-24

function,

/VERBOSE

*UNIVERSAL-ERROR-HANDLER*

variable,

4-6

5-17

keyword

COMPILE-FILE

modifier,

5-13

function,

defining

file

using

Yank"

style,

activation,

File

pointing

description,

6-3

Editor

VAXstation

macro

:UNIT

control,

LISP"

VAX/VMS

6-20

UNDEFINE-LIST-PRINT-FUNCTION

"Undo

"VAX

automatic

UNDEFINE-LIST-PRINT-FUNCTION

macro,

Variable

2-7
line

keyword

function,

2-23

15,

17
“

INDEX

/VERBOSE
modes,

qualifier

"What Cursor Position”

(Cont.)

2-13

(table),

2-12

with /COMPILE qualifier,

"EMACS" style binding,
WHERE debugger command
description, 5-16

2-14

with /INITIALIZE qualifier,
2-16

with /LIST qualifier,

Editor

command

B-6

(table), 5-11
:WILD keyword

2-18

See

:VERSION keyword
pathname field, 7-10
Version number, 1-8

:VERSION keyword

windows
Editor

see Editor windows
WITH-GENERALIZED-PRINT~-FUNCTION
macro, 6-22
WITH-GENERALIZED-PRINT-FUNCTION

: VERSION-LIMIT keyword

GET-FILE-INFORMATION function,
57

"View File" Editor command
"EMACS" style binding, B-6
:VIRTUAL-ADDRESS-PEAK keyword

macro

description, 145
s WORKING-SET-AUTHORIZED-EXTENT

GET-PROCESS-INFORMATION
function, 70

VMS

hibernation state, 4
: VOLUME-COUNT keyword

GET-DEVICE-INFORMATION function,
53

: VOLUME-NAME keyword

GET-DEVICE-INFORMATION function,
54

¢+ VOLUME -NUMBER keyword

GET-DEVICE-INFORMATION function,
54

: VOLUME-PROTECTION keyword
GET-DEVICE-INFORMATION function,
54

keyword
GET-PROCESS-INFORMATION
function, 70
s WORKING-SET-AUTHORIZED-QUOTA

keyword
GET-PROCESS-INFORMATION
function, 70

: WORKING-SET-COUNT keyword
GET-PROCESS-INFORMATION
function, 70

:WORKING-SET-DEFAULT keywcrd
GET-PROCESS-INFORMATION
function, 71

sWORKING-SET-EXTENT keyword
GET-PROCESS-INFORMATION
function, 71

:WORKING-SET-PEAK keyword
o Y

GET-PROCESS-INFORMATION
function, 71

: WORKING-SET-QUOTA keyword

"W directive, 6-6
WARN function, 142
description, 144
error messages, 4-4
(table), 7-30
WARNING function

GET-PROCESS-INFORMATION
function, 71

:WORKING-SET-SIZE keyword

defining an error handler,

:WARNING keyword
EXIT function, 44
: WARNINGS keyword

COMPILE-FILE function,

/WARNINGS qualifier
description, 2-24
modes, 2-13
‘table), 2-12

4-7

GET-PROCESS-INFORMATION
function, 71
:WRAP keyword

WRITE

GET-TERMINAL-MODES function, 75
SET-TERMINAL-MODES function,
109

15,

.th /COMPILE qualifier,

FORMAT directive,

6-7

"Write Current Buffer" Editor
command,

3-12

"EMACS" style binding, B-6

2-14

using,

Index-25

3-10,

3-34

INDEX

WRITE

WRITE-STRING

function

pretty-printing
keywords,

"Write

command,
"EMACS"
using,
"Write

WRITE-TO-STRING

control

Buffers"

3-10,

binding,

B-6

Editor

command,

"Yank

Previous"

"EMACS"

style

binding,

B-6

"Yank

#\NEWLINE

function,

7-24

character,

length,

style

Replace

Editor

command

binding,

Previous"

B-5

Editor

command

3-10

WRITE-CHAR
record

=Y
-

3-34

File"

3-12

"EMACS"

control

6-3

3-12

style

Named

using,

keywords,

Editor

7-20

function

pretty-printing

6-3

Modified

function,

7-22

7-20

"EMACS"
"Yank"

"EMACS"

Index-26

style

Editor

binding,

B-5

command

style

binding,

B-5

HOW TO ORDER
ADDITIONAL DOCUMENTATION

From

Call

Chicago

Write

312—640-5612

Digital Equipment Corporation

8:15am to 500 pm CT

Accessories & Supplies Center
1050 East Remington Road

Schaumburg, IL 60195

San Francisco

408-734—-4915

Digital Equipment Corporation

8:15aM to 5:00pm PT

Accessories & Supplies Center

603—-884-6660

Alaska, Hawaii

8:30am to 6:00 PMm ET
or

632 Caribbean Drive
Sunnyvale, CA 94086

408-734—-4915
8:15aM to 500 pm PT

New Hampshire

603-884—-6660

Digital Equipment Corporation

830 am to6:00pPmMm ET

Accessories & Supplies Center

Rest of U.S.A.,

1-800-258-1710

Puerto Rico”

830 AM to6:00pmMm ET

P.O. Box CS2008
Nashua, NH 03061

*Prepaid orders from Puerto Rico must be placed with the local DIGITAL subsidiary (call 809-754-7575)

Canada
British Columbia

Ottawa—Hull

1-800—-267-6146

Digital Equipment of Canada Ltd

8:00 AM. to 5:00 Pm ET

940 Belfast Road

613—-234-7726
8:00 Am to 5:00 PMm. ET

Elsewhere

Ottawa, Ontario K1G 4C2
Attn: A&SG Business Manager

112-800-267-6146
8:00 Am t0 5:00pmMm ET

Elsewhere

Digital Equipment Corporation
A&SG Business Manager”
*c/o DIGITAL's local subsidiary or approved distributor

VAX LISP/VMS User’'s Guide
AA-Y921B-TE

READER’S

COMMENTS

Note: This form is for document comments only. DIGITAL will use comments

submitted on this form at the company’s discretion. If you require a written reply and

are eligible to receive one under Software Performance Report (SPR) service, submit

your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
Assembly language programmer

Higher-level language programmer

Occasional programmer (experienced)
User with little programming experience
Student programmer

Other (please specify)

Name

Date

Organization

Street

City

State

Zip Code
or Country

Do Not Tear — Fold Here and Tape

dligliltall

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.

POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION

CORPORATE USER PUBLICATIONS
MLO5-5/E45
146 MAIN STREET
MAYNARD, MA 01754-2571

comce

comeee

0 opeawms

000

Gommeme

cSmmmoe

eemoey

aomcss

oSDRms

cosmmos

couweme

CODMSRE

oeiiRes

CRTGONS

COSWEG

GOoooie

woQome

oOOORWD

maows

Swmeems

Cut Along Dotted Line

Do Not Tear — Fold Here