Digital PDFs

AA-MK72A-TE

July 1989

174 pages

Original

75MB

Document:	VAX LISP/VMS Object Reference Manual
Order Number:	AA-MK72A-TE
Revision:	000
Pages:	174
Original Filename:

OCR Text

VAX LISP/VMS Object Reference Manual
Order Number: AA-MK72A-TE

This document contains reference information on all VAX LISP objects that are in the
v a x - l i s p : package but are not fully described in Common LISP: The Language.

Revision/Update Information:

This is a new manual.

Operating System and Version: VMS Version 5.1
Software Version:

digital equipment corporation
maynard, massachusetts

VAX LISP Version 3.0

First Printing, July 1989
The information in this document is subject to change without notice and should not be
construed as a commitment by Digital Equipment Corporation.
Digital Equipment Corporation assumes no responsibility for any errors that may appear in
this document.
The software, if any, 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 or equipment that is not supplied by Digital Equipment
Corporation or its affiliated companies.
© Digital Equipment Corporation 1989.
All rights reserved.
Printed in U.S.A.
The postpaid Reader’s Comments form at the end of this document requests your critical
evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
AI VAXstation
DEC
DECnet
DECUS
MicroVAX
MicroVAX II
MicroVMS

PDP
ULTRIX
ULTRIX-11
ULTRIX-32
UNIBUS
VAX
VAX LISP

VAX LISP/ULTRIX
VAX LISP/VMS
VAXstation
VAXstation II
VMS

This document was prepared using VAX DOCUMENT, Version 1.1.

ML-S839

Preface

vii
ABORT F U N C T IO N .....................................................
ALIEN-DATA FUNCTION..............................................
ALIEN-FIELD F U N C T IO N ...........................................
ALIEN-STRUCTURE-LENGTH FUNCTION...............
APROPOS FUNCTION................................................
APROPOS-LIST F U N C T IO N ......................................
AREA-SEGMENT-LIMIT FU N C TIO N .........................
AREA-SEGMENTS F U N C T IO N .................................
ATTACH FUNCTION ...................................................
BIND-KEYBOARD-FUNCTION FUNCTION...............
BREAK F U N C T IO N .....................................................
CALL-BACK-ROUTINE TYPE SP E C IF IE R ...............
CALL-OUT M A C R O .....................................................
CATCH-ABORT M AC R O ..............................................
CHAR-NAME-TABLE FU N C TIO N ..............................
COMMAND-LINE-ENTITY-P F U N C T IO N ..................
COMMAND-LINE-ENTITY-VALUE FUNCTION . . . .
COMMON-AST-ADDRESS PARAMETER..................
COMPILEDP FUNCTION ...........................................
COMPILE-FILE FUNCTION........................................
‘ COMPILE-VERBOSE* V A R IA B LE ............................
*COMPILE-WARNINGS* V A R IA B LE .........................
CONTINUE FUNCTION ..............................................
CRITICAL-SECTION M A C R O ....................................
DEBUG FU NC TIO N .....................................................
DEBUG-CALL FUNCTION...........................................
‘ DEBUG-PRINT-LENGTH* VARIABLE.......................
‘ DEBUG-PRINT-LEVEL* V A R IA B LE .........................
DEFAULT-DIRECTORY FUNCTION .........................
DEFINE-ALIEN-FIELD-TYPE M A C R O .......................
DEFINE-ALIEN-STRUCTURE M A C R O ....................
DEFINE-EXTERNAL-ROUTINE M A C R O ..................
DEFINE-FORMAT-DIRECTIVE M AC R O ....................
DEFINE-GENERALIZED-PRINT-FUNCTION MACRO
DEFINE-LIST-PRINT-FUNCTION M A C R O ...............
DELETE-PACKAGE FUNCTION.................................
DESCRIBE FUNCTION................................................
DIRECTORY FUNCTION ...........................................
DRIBBLE FUNCTION...................................................
DYNAMIC-SPACE-RATIO FU NC TIO N .......................
ED F U N C T IO N .............................................................
ENLARGE-BINDING-STACK FU NC TIO N ..................
ENLARGE-LISP-MEMORY F U N C T IO N ....................
‘ ERROR-ACTION* V A R IA B LE ...................................

1
2
3
4

6
8
9
9
10

12
13
14
14
16
17
18
19

20
20
21
23
24
25
26
27
27
28
29
30
32
34
37
41
43
44
46
46
48
50
51
51
53
53
54

iii

EXIT FU NC TIO N ................................................................................................................
FORCE-INTERRUPT-FUNCTION FUNCTION................................................................
FORMAT DIRECTIVES PROVIDED WITH VAX L IS P ...................................................
GC FU N C TIO N ..................................................................................................................
GC-COUNT F U N C T IO N ...................................................................................................
GC-MODE FU N C TIO N ......................................................................................................
‘ GC-VERBOSE* VARIABLE..............................................................................................
GENERALIZED-PRINT-FUNCTION-ENABLED-P FUNCTION ....................................
GET-DEVICE-INFORMATION F U N C T IO N .....................................................................
GET-FILE-INFORMATION FUNCTION............................................................................
GET-GC-REAL-TIME FU N C TIO N ....................................................................................
GET-GC-RUN-TIME FUNCTION.......................................................................................
GET-INTERNAL-RUN-TIME FUNCTION .......................................................................
GET-INTERRUPT-FUNCTION FU N C TIO N .....................................................................
GET-KEYBOARD-FUNCTION F U N C T IO N .....................................................................
GET-PROCESS-INFORMATION FUNCTION ................................................................
GET-TERMINAL-MODES F U N C T IO N ............................................................................
GET-VMS-MESSAGE FUNCTION....................................................................................
HASH-TABLE-REHASH-SIZE F U N C T IO N .....................................................................
HASH-TABLE-REHASH-THRESHOLD FUNCTION ......................................................
HASH-TABLE-SIZE F U N C T IO N .......................................................................................
HASH-TABLE-TEST FUNCTION.......................................................................................
IMMEDIATE-OUTPUT-P FU NC TIO N ...............................................................................
INSPECT FUNCTION........................................................................................................
INSTATE-INTERRUPT-FUNCTION FU NC TIO N .............................................................
LINE-POSITION F U N C T IO N ............................................................................................
LISTEN2 F U N C T IO N ...........................................
LOAD F U N C T IO N .............................................................................................................
LONG-SITE-NAME FUNCTION .......................................................................................
MACHINE-INSTANCE FUNCTION ..................................................................................
MACHINE-VERSION F U N C T IO N ....................................................................................
MAKE-ARRAY FUNCTION ..............................................................................................
MAKE-CALL-BACK-ROUTINE FU NC TIO N .....................................................................
MEMORY-ALLOCATION-EXTENT FUNCTION .............................................................
‘ MODULE-DIRECTORY* VAR IABLE...............................................................................
NREAD-LINE F U N C T IO N .................................................................................................
OPEN-STREAM-P FUNCTION.........................................................................................
‘ POST-GC-MESSAGE* VAR IABLE.................................................................................
PPRINT-DEFINITION FUNCTION....................................................................................
PPRINT-PLIST F U N C T IO N ..............................................................................................
‘ PRE-GC-MESSAGE* VARIABLE....................................................................................
‘ PRINT-LINES* V A R IA B L E ..............................................................................................
‘ PRINT-MISER-WIDTH* VARIABLE ...............................................................................
‘ PRINT-RIGHT-MARGIN* VARIABLE...............................................................................
PRINT-SIGNALED-ERROR FUNCTION..........................................................................
‘ PRINT-SLOT-NAMES-AS-KEYWORDS* V A R IA B L E ...................................................
REQUIRE FUNCTION ......................................................................................................
RIGHT-MARGIN F U N C T IO N ............................................................................................
ROOM FUNCTION.............................................................................................................
ROOM-ALLOCATION FUNCTION....................................................................................
SET-TERMINAL-MODES FUNCTION ............................................................................
SHORT-SITE-NAME FUNCTION ....................................................................................
SOFTWARE-VERSION-NUMBER FUNCTION................................................................
SOURCE-CODE FU N C TIO N ............................................................................................
SPAWN FU NC TIO N ...........................................................................................................
STEP MACRO ..................................................................................................................
‘ STEP-ENVIRONMENT* V A R IA B LE ...............................................................................

55
56
56
58
59
60
61
62
63
65
67
69
70
71
72
73
78
80
81
82
83
84
85
85
86
90
91
91
93
93
94
95
96
99
99
100
100
101
102
103
105
106
107
108
109
110
Ill
112
113
115
116
118
119
120
120
123
123

'STEP-FORM* VARIABLE.................................................................................................
SUSPEND FU N C TIO N ......................................................................................................
TIME M A C R O .....................................................................................................................
'TOP-LEVEL-PROMPT* VARIABLE ...............................................................................
TRACE M A C R O ................................................................................................................
'TRACE-CALL* V A R IA B L E ..............................................................................................
'TRACE-VALUES* V A R IA B LE .........................................................................................
TRANSLATE-LOGICAL-NAME FUNCTION.....................................................................
UNBIND-KEYBOARD-FUNCTION FUNCTION .............................................................
UNCOMPILE FUNCTION .................................................................................................
UNDEFINE-LIST-PRINT-FUNCTION M A C R O ................................................................
UNINSTATE-INTERRUPT-FUNCTION FUNCTION........................................................
UNIVERSAL-ERROR-HANDLER F U N C T IO N ................................................................
'UNIVERSAL-ERROR-HANDLER* VARIABLE .............................................................
VMS-DEBUG F U N C T IO N .................................................................................................
WAIT FUNCTION................................................................................................................
WARN FUNCTION.............................................................................................................
WITH-GENERALIZED-PRINT-FUNCTION M A C R O .....................................................

124
124
127
127
128
137
137
138
140
140
142
142
143
144
145
146
148
149

Index

Tables
1

DEFINE-ALIEN-STRUCTURE O ptions............................................................................

DEFINE-ALIEN-STRUCTURE Field O p tio n s ..................................................................

DEFINE-EXTERNAL-ROUTINE O ptions..........................................................................

DEFINE-EXTERNAL-ROUTINE Argument O ptions........................................................

Format Directives Provided with VAX LISP

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

GET-DEVICE-INFORMATION Keywords .......................................................................

GET-FILE-INFORMATION Keywords

GET-PROCESS-INFORMATION Keywords

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

GET-TERMINAL-MODES K e y w o rd s ...............................................................................

Specialized Array Element T y p e s ....................................................................................

ROOM Function Data Type H e a d in g s ............................................................................

113

TRACE Options

129

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

Preface
This manual contains reference information on VAX LISP objects that are de
scribed in the VAX LISP /VMS Program Development Guide, VAX LISP/VMS
System Access Guide, and VAX LISP Implementation and Extensions to Common
LISP manuals, and that are contained in the v a x -l i s p : package. Reference in
formation for VAX LISP objects contained in the w i n d o w - s t r e a m : package may be
found in the VAX LISP Implementation and Extensions to Common LISP manual.

Intended Audience
This manual is intended for programmers with a good knowledge of both LISP
and the programming interface to the VMS operating system.

Document Structure
This manual contains full descriptions of the functions, macros, variables, and
constants in VAX LISP. Each function or macro description explains the function’
s
or macro’
s use and shows its format, applicable arguments, return value, and
examples of use. Each variable or constant description explains the variable’
s or
constant’
s use and provides examples of its use. The descriptions are organized
alphabetically.

Associated Documents
The following documents are relevant to VAX LISP/VMS programming:
• VAX LISP/VMS Program Development Guide
• VAX LISP/VMS System Access Guide
• VAX LISP Implementation and Extensions to Common LISP
• VAX LISP/VMS System-Building Guide
• VAX LISP/VMS DECwindows Programming Guide
• VAX LISP Interface to VWS Graphics
• Common LISP: The Language
• VAX Architecture Handbook
• VMS DCL Dictionary
• VMS System Messages and Recovery Procedures Reference Manual
• VMS Record Management Services Manual
VII

• VMS Utility Routines Manual
• VMS Command Definition Utility Manual
• VMS System Services Reference Manual
• VMS I/O U ser’
s Reference Manual: Part I
For a complete list of VMS software documents, see the Overview of VMS
Documentation.

Conventions
The following conventions are used in this manual:
Convention

Meaning

UPPERCASE

DCL commands and qualifiers and VMS file names are printed in
uppercase characters; however, you can enter them in uppercase,
lowercase, or a combination of uppercase and lowercase characters.
For example:
The examples directory (SYS$SYSROOT:[VAXLISP.EXAMPLES] by
default) contains sample LISP source files.

UPPERCASE
TYPEWRITER

Defined LISP functions, macros, variables, constants, and other
symbol names are printed in uppercase TYPEWRITER charac
ters; however, you can enter them in uppercase, lowercase, or a
combination of uppercase and lowercase characters. For example:
The CALL-OUT macro calls a defined external routine ....

lowercase
typewriter

LISP forms are printed in the text in lowercase typewriter
characters; however, you can enter them in uppercase, lowercase, or
a combination of uppercase and lowercase characters. For example:
(setf example-1 (make-space))

SANS SERIF

Format specifications of LISP functions and macros are printed in a
sans serif typeface. For example:
CALL-OUT external-routine &REST routine-arguments

italics

Lowercase italics in format specifications and in text indicate argu
ments that you supply; however, you can enter them in lowercase,
uppercase, or a combination of lowercase and uppercase characters.
For example:
The routine-arguments must be compatible with the arguments
defined in the call to the DEFINE-EXTERNAL-ROUTINE macro.

()

Parentheses used in examples of LISP code and in format spec
ifications indicate the beginning and end of a LISP form. For
example:
(setq name lisp)

C on v en tion

M eaning

[]

Square brackets in format specifications enclose optional elements.
For example:
[doc-string]
Square brackets do not indicate optional elements when they are
used in the syntax of a directory name in a VMS file specification.
Here, the square bracket characters must be included in the syntax.
For example:
(pathname "MIAMI::DBA1:[SMITH]LOGIN.COM;4")

{}

In function and macro format specifications, braces enclose elements
that are considered one unit of code. For example:
{keyword value}

{}*

In function and macro format specifications, braces followed by
an asterisk enclose elements that are considered one unit of code,
which can be repeated zero or more times. For example:
{keyword value}*

&OPTIONAL

In function and macro format specifications, the word &OPTIONAL
indicates that the arguments that follow it are optional. For exam
ple:
PPRINT object &OPTIONAL stream
Do not specify &OPTIONAL when you invoke a function or macro
whose definition includes &OPTIONAL.

&REST

In function and macro format specifications, the word &REST
indicates that an indefinite number of arguments may appear. For
example:
CALL-OUT external-routine &REST routine-arguments
Do not specify &REST when you invoke a function or macro whose
definition includes &REST.

&KEY

In function and macro format specifications, the word &KEY indi
cates that keyword arguments are accepted. For example:
COMPILE-FILE input-pathname
&KEY :LISTING :MACHINE-CODE OPTIMIZE
:OUTPUT-FILE :VERBOSE WARNINGS
Do not specify &KEY when you invoke a function or macro whose
definition includes &KEY.
A horizontal ellipsis in a format specification means that the ele
ment preceding the ellipsis can be repeated. For example:
function-name . . .
A vertical ellipsis in a code example indicates that all the informa
tion that the system would display in response to the function call
is not shown; or, that all the information a user is to enter is not
shown.

Convention

Meaning

1Return |

A word inside a box indicates that you press a key on the keyboard.
For example:
1Return |or |Tab|

In code examples, carriage returns are implied at the end of each
line. However, 1Return |is used in some examples to emphasize carriage returns.
|CtrI/JC|

Two key names enclosed in a box indicate a control key sequence in
which you hold down Ctrl while you press another key. For example:
|ctrl/c| or ICtrl/S|

EE3S

A sequence such as [p f T] [x j indicates that you must first press and
release the key labeled PF1, then press and release another key.

mouse

The term mouse refers to any pointing device, such as a mouse, a
puck, or a stylus.

MB1, MB2, MB3

By default, MB1 indicates the left mouse button, MB2 indicates the
middle mouse button, and MB3 indicates the right mouse button.
You can rebind the mouse buttons.

Red print

In interactive examples, user input is shown in red. For example:
L isp >
(B

L is p >

(cdr

(a b c ) )

ABORT Function

ABORT Function
Unwinds the stack to the most recent c a t c h -a b o r t .The a b o r t function is invoked
whenever the cancel character (Ctrl/C) is typed at the keyboard. The VAX LISP top
level uses the c a t c h -a b o r t macro, so that typing Ctrl/C puts you back at the top
level.
Thus, you can use a b o r t to cause an exit to the VAX LISP read-eval-print loop.
In this way, you can partially simulate the action of the cancel character from
within your code. (The cancel character also invokes the c l e a r -i n p u t function on
the *t e r m i n a l -i o * stream.)
NOTE

This function takes the place of a t h r o w to the c a n c e l -c h a r a c t e r -t a g
tag in previous versions of VAX LISP.

Format
ABORT
Argument
None.

Return Value
Does not return.

Examples
1.

Lisp> (bind-keyboard-function #\~g
#'(lambda ()
(clear-input *query-io*)
(when (y-or-n-p "Are you sure? ")
(abort)))
:level 5)
T
Lisp> (loop)
[Ctri/Gl

Are you sure? y
Lisp>

• The call to the b i n d -k e y b o a r d -f u n c t i o n function binds a function to the
key Ctrl/G.
• The user types Ctrl/G. (This is not echoed on the screen.)
• When the user types Y, the a b o r t function returns control to the VAX
LISP top level.

ABORT Function
2.

Lisp>(setf *foo* nil)
NIL
Lisp>(defun foo ()
(catch-abort (unwind-protect (unless *foo* (abort))
(setf *foo* 3)))
(+ *foo* 10))
FOO

Lisp>(foo)
13

The unwind-protect cleanup form, (setf *foo* 3), i s executed after abort i s
invoked.

ALIEN-DATA Function
Either dereferences a pointer to an alien structure’
s data vector or returns its
address. For more information about alien structures, see Chapter 5 in the VAX
LISP/VMS System Access Guide.

Format
ALIEN-DATA alien-structure
Argument
alien-structure
The alien structure for which you want to access the data vector.

Return Value
The data vector or an integer if the vector is in non-LISP space

Examples
1.

Lisp> (setf y (make-text-string))
#<Alien Structure TEXT-STRING #<Vector #x21C511>>
Lisp> (setf (text-string-a y) "abc")
"abc"
Lisp> (alien-data y)
#(97 98 99 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32 32
32 32)
Lisp> (text-string-a y)
"abc
Lisp>

In this example, the alien structure is not constructed with the :d a t a
keyword. The accessor function is used to initialize the field. When a l i e n d a t a is used to access the data vector, it returns the unformatted contents
of the vector. When the accessor function is used, it returns the field as a
24-byte string, according to the field description. This is the default.

ALIEN-DATA Function
2.

Lisp> (define-alien-structure text-string (a :string 0 24))
TEXT-STRING
Lisp> (setf x (make-text-string :data "this string is going to be very
long, longer than the 24 bytes allocated for the alien structure"))
#<Alien Structure TEXT-STRING this string is going to be very long,
longer than the 24 bytes allocated for the alien structure>
Lisp> (alien-data x)
"this string is going to be very long, longer than the 24 bytes
allocated for the alien structure"
Lisp> (text-string-a x)
"this string is going to "
Lisp>

This example defines an alien structure consisting of a single 24-byte text
field. An instance of this structure is created with the :d a t a keyword, making
the pointer to the data vector point directly to a string rather than allocating
a new vector. When you use a l i e n -d a t a to access the data, it returns the
entire string. When you use an accessor function to access the data, it returns
only the first 24 bytes of the string according to the alien structure definition.

ALIEN-FIELD Function
Accesses the value of a field of a specified type from an alien structure. The
function ignores the alien structure’
s predefined fields.
You can modify alien structures if you use the a l i e n -f i e l d function with the
s e t f macro. This function is most useful for debugging a program that uses alien
structures. The function can also be used to write your own accessor functions,
for example, to access unnamed gaps in an alien structure.
For more information about alien structures, see Chapter 5 in the VAX
LISP/VMS System Access Guide.

Format
ALIEN-FIELD alien-structure field-type start end
Arguments
alien-structure
The alien structure from which a field value is to be accessed.
field-type
The type of the field from which a value is to be accessed. It tells a l i e n -f i e l d
how to interpret the data. This argument can be either a keyword that names a
built-in alien structure field type, a symbol (for a user-defined field type), or a list
whose first element names the field type.
start
A rational number that specifies the start position (in 8-bit bytes) of a field in the
alien structure’
s data area. This value is inclusive and zero-based.

ALIEN-FIELD Function
end
A rational number that specifies the end position (in 8-bit bytes) of a field in the
alien structure’
s data area. This value is exclusive.

Return Value
The value of the specified alien structure field.

Example
Lisp> (define-alien-structure space
(area-1 :unsigned-integer 0 4 :default 22)
(area-2 :unsigned-integer 4 8 rdefault 2764))
SPACE
Lisp> (setf space-record (make-space) )
#<Alien Structure SPACE #x45FA60>
Lisp> (space-area-1 space-record)
22

Lisp> (space-area-2 space-record)
2764
Lisp> (alien-field space-record :unsigned-integer 0 4)
22
Lisp> (alien-field space-record :unsigned-integer 4 8)
2764
Lisp> (alien-field space-record :unsigned-integer 0 8)
11871289606166

This example illustrates:
• If you specify the a l i e n -f i e l d function with the same field types and
positions that are in the definition of an alien structure, the data you access
is the same as if you had accessed it with that structure’
s default accessor
functions.
• If you specify the a l i e n -f i e l d function with field types and positions
different from those in a defined alien structure, the interpretation of the
data you access could be different, depending on the field type and field
positions you specify.

ALIEN-STRUCTURE-LENGTH Function
Returns the length of an alien structure in bytes.

Format
ALIEN-STRUCTURE-LENGTH alien-structure
Argument
alien-structure
The alien structure whose length is to be returned.

ALIEN-STRUCTURE-LENGTH Function

Return Value
The length of the alien structure in bytes.

Examples
The following examples illustrate the use of the a l i e n -s t r u c t u r e -l e n g t h
function. The diagram after each example illustrates why it returns a specific
value.
1.

Lisp> (define-alien-structure examplel
(name :string 0 20 :occurs 3 :offset 20))
EXAMPLEI
Lisp> (alien-structure-length (make-examplel))
60

name2

namel

name3

Offset=20

MLO-002987

2. Lisp> (define-alien-structure example2
(name :string 0 20 :occurs 3 :offset 10))
EXAMPLE2
Lisp> (alien-structure-length (make-example2))
40

namel
name2
i

•m
m

name3

Offset=10
MLO-002988

In e x a m p l e 2, the offset overlaps so that the last part of the information stored
in n a m e i becomes the first part of the information stored in n a m e 2, and so on.

ALIEN-STRUCTURE-LENGTH Function
3.

Lisp> (define-alien-structure example3
(name :string 0 20 :occurs 2 :offset 40))
EXAMPLE3
Lisp> (alien-structure-length (make-example3))
60

namel

name3

gap

Offset=40

MLO-002989

In e x a m p l e 3 and e x a m p l e 4, the gaps are counted as part of the length of the
structure.
4.

Lisp> (define-alien-structure example4 (name :string 20 40))
EXAMPLE4
Lisp> (alien-structure-length (make-example4))
40

0
•
•
i
■
i

gap
1____ _ —

namel
MLO-002990

APROPOS Function
Searches through packages for symbols whose print names contain a specified
string. The function is not sensitive to the case of characters. The string can be
either the print name or a substring of the symbol’
s print name.
The a p r o p o s function displays a message that shows the string that is being
searched for and the name of the package that is 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*, has a value

If the symbol has a function definition, the function displays the phrase “
has a
definition”after the symbol as follows:
MY—FUNCTION, has a definition

APROPOS Function
In VAX LISP, the a p r o p o s function uses the d o -s y m b o l s macro rather than the
d o -a l l -s y m b o l s 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 &OPTIONAL package
Arguments
string
The string to be sought 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. If you specify t , all packages are searched. If you do not
specify the argument, the symbols that are accessible in the current package are
searched.

Return Value
No value.

Example
Lisp> (apropos "*print")
Symbols in package USER containing the string "*PRINT":
*PRINT-CIRCLE*, has a value
*PRINT-SLOT-NAMES-AS-KEYWORDS*, has a value
*PRINT—RADIX*, has a value
*PRINT-ESCAPE*, has a value
*PRINT-ARRAY*, has a value
*PRINT-GENSYM*, has a value
*PRINT-LEVEL*, has a value
*PRINT-PRETTY*, has a value
*PRINT-LENGTH*, has a value
*PRINT-RIGHT-MARGIN*, has a value
*PRINT-MISER-WIDTH*, has a value
*PRINT-BASE*, has a value
*PRINT-CASE*, has a value
*PRINT-LINES*, has a value

Searches the package u s e r for the string "*p r i n t " and displays a list of the
symbols that contain the specified string.

APROPOS-LIST Function

APROPOS-LIST Function
Searches through packages for symbols whose print names contain a specified
string. The function is not sensitive to the case of characters. The string can be
either the print name or a substring of the symbol’
s print name.
When the function completes its search, it returns a list of the symbols whose
print names contain the string.
In VAX LISP, the a p r o p o s -l i s t function uses the d o -s y m b o l s macro rather than
the d o -a l l -s y m b o l s macro. As a result, the function includes by default only
symbols that are accessible from the current package in the list it returns. For
information on packages, see Common LISP: The Language.

Format
APROPOS-LIST string &OPTIONAL package
Arguments
string
The string to be sought 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. If you specify t , all packages are searched. If you do not
specify the argument, the symbols that are accessible in the current package are
searched.

Return Value
A list of the symbols whose print names contain the string.

Example
Lisp> (apropos-list "array")
(ARRAY-TOTAL-SIZE ARRAY-DIMENSION ARRAY-DIMENSIONS
SIMPLE-ARRAY ARRAY-DIMENSION-LIMIT ARRAY-ELEMENT-TYPE
ARRAYP *PRINT-ARRAY* ARRAY-RANK ARRAY-RANK-LIMIT
MAKE-ARRAY ARRAY-TOTAL-SIZE-LIMIT ARRAY-ROW-MAJOR-INDEX
ADJUST-ARRAY ARRAY ARRAY-IN-BOUNDS-P ADJUSTABLE-ARRAY-P
ARRAY-HAS—FILL-POINTER-P)

Searches the symbols that are accessible in the current package for the string
"a r r a y " and returns a list of the symbols that contain the specified string.

AREA-SEGMENT-LIMIT Function

AREA-SEGMENT-LIMIT Function
Returns the maximum number of segments that the specified area may occupy
before being garbage collected. See the VAX LISP Implementation and Extensions
to Common LISP manual for details on garbage collection in VAX LISP.
This function may be used with the s e t f macro, but only on the ephemeral areas
(the area argument is 0, 1, or 2).

Format
AREA-SEGMENT-LIMIT &OPTIONAL area
Argument
area
A keyw ord or num ber in dicatin g the area o f m emory:
:DYNAMIC

Total dynamic space, including ephemeral areas. This is the default.

The most transient ephemeral area, E0.

The second ephemeral area, E l .

The least transient ephemeral area, E2.

Values of t , n i l , or : d e f a u l t are in terpreted as : d y n a m i c .

Return Value
An integer.

Example
Lisp> (area-segment-limit 0)
10
Lisp> (area-segment-limit t)
22

AREA-SEGMENTS Function
Returns the number of segments that are currently allocated to the specified
area of dynamic memory. See the VAX LISP Implementation and Extensions to
Common LISP manual for details on VAX LISP memory management and the
garbage collector.

AREA-SEGMENTS Function

Format
AREA-SEGMENTS area
Argument
area
A keyw ord or n um ber in dicatin g the area o f m emory:
:DYNAMIC

Total dynamic space, excluding ephemeral areas. This is the default.

:READ-ONLY

Read-only space contains much of the LISP system and is never garbage
collected.

:STACK

Stack space contains several kinds of stacks, and is scanned as part of
garbage collection.

:STATIC

Static space contains user-allocated objects that are guaranteed not to be
moved by the garbage collector.

The most transient ephemeral area, E0.

The second ephemeral area, El.

The least transient ephemeral area, E2.

Values o f t , n i l , or : d e f a u l t are in terpreted as : d y n a m i c .

Return Value
An integer.

Example
Lisp> (area-segments :read-only)
79
Lisp> (area-segments t)
4

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 but can become
active at a later time. You can use this function to switch terminal control from
one process to another.
The a t t a c h function is similar to the DCL ATTACH command. For information
on the ATTACH command, see the VMS DCL Dictionary.
NOTES

The a t t a c h function can be used only if LISP is invoked from DCL; it
cannot be used if LISP is invoked from another Command Language
Interpreter (CLI).

ATTACH Function
Be careful using this function under DECwindows, both in the develop
ment environment and in your programs. Since a t t a c h causes LISP to
hibernate, no events can be processed. If events are queued and LISP
does not respond within a server-defined timeout, the X server aborts
the connection to the LISP process.

Format
ATTACH process
Argument
p rocess
The name or identification (PID) of the process to which your terminal is to be
connected. To specify the process name, use a string or a symbol; to specify the
PID, use an integer.

Return Value
Unspecified.

Examples
1.

Lisp> (spawn)
$ attach smith
Lisp> (attach "SMITH_1")
%DCL-S-RETURNED, control returned to process SMITH_1
$

• The call to the s p a w n function creates a subprocess named SMITHJL.
• The DCL ATTACH command attaches your terminal back to the process
SMITH.
• The call to the VAX LISP a t t a c h function returns control to the process
SMITHJL.
2.

Lisp> (defun attach-main nil
(attach (second (get-process-information
nil
:owner-pid))))
a t t a c h -m a i n

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

BIND-KEYBOARD-FUNCTION Function

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
u n b i n d -k e y b o a r d -f u n c t i o n function. You can use the g e t -k e y b o a r d -f u n c t i o n
function to get information about a function that is bound to a control character.
You can specify an interrupt level (an integer in the range 0 through 7) for
a keyboard function by using the :l e v e l keyword. A keyboard function can
interrupt only code that is executing at an interrupt level below its 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 input; therefore, a
keyboard function executing at interrupt level 6 cannot receive input from the
keyboard. For this reason, be careful when using interrupt level 6.
• Interrupt level 7 can interrupt any code that is not in the body of a c r i t i c a l s e c t i o n macro. A keyboard function executing at interrupt level 7 must
terminate by executing a t h r o w function to a tag or by calling the a b o r t
function.
• If you bind a control character to the b r e a k or d e b u g 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 e d function, use the default interrupt
level (1) or a lower level.
The VAX LISP/VMS System Access Guide contains more information about using
interrupt levels, the c r i t i c a l -s e c t i o n macro, and interrupt functions.
NOTE

When you bind a control character to a function, the stream bound to
the *t e r m i n a l -i o * variable must be connected to your terminal.
See VAX LISP Implementation and Extensions to Common LISP for an explana
tion of calling functions asynchronously.

Format
BIND-KEYBOARD-FUNCTION control-character function
&KEY rARGUMENTS :LEVEL

BIND-KEYBOARD-FUNCTION Function

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 is to be bound.
ARGUMENTS

A list containing arguments to be passed to the specified function when it is
called. The arguments in the list are evaluated when the b i n d -k e y b o a r d f u n c t i o n function is called.
:LEVEL

An integer in the range 0 through 7, specifying the interrupt level for the
keyboard function. The default is 1.

Return Value
T.

Examples
L±sp> (bind-keyboard-function f\AB #'break)
T
Lisp> ICtrl/B|
Break>

Binds Ctrl/B to the b r e a k function. You can then invoke a break loop by typing
Ctrl/B.

2. Lisp> (bind-keyboard-function #\~E #'ed)
T
Lisp> IOWE |
(now in the Editor)

Binds ctrl/E to the e d function. You can then invoke the Editor by typing Ctrl/E.

BREAK Function
Invokes a break loop. A break loop is a nested read-eval-print loop. For more
information about break loops, see Chapter 4 of the VAX LISP/VMS Program
Development Guide.

Format
BREAK &OPTIONAL format-string &REST args

BREAK Function

Arguments
formatstring
The string of characters that is passed to the f o r m a t function to create the
break-loop message.
args
The arguments that are passed to the f o r m a t function as arguments for the
format string.

Return Value
When the c o n t i n u e function is called to exit the break loop, the b r e a k function
returns n i l ; otherwise, no value is returned.

Example
(when (unusual-situation-p status)
(break "Unusual situation ~D encountered. Please investigate"
status))

Calls the b r e a k function if the value of the u n u s u a l -s i t u a t i o n -p function is not

n i l .The break message contains the condition code.

CALL-BACK-ROUTINE Type Specifier
An alien structure that can be passed to an external routine during callout. See
Chapter 4 in the VAX LISP/VMS System Access Guide for more information
about the callback facility.

Format
CALL-BACK-ROUTINE

CALL-OUT Macro
Calls a defined external routine. If you specify an external routine that has not
been defined with the d e f i n e -e x t e r n a l -r o u t i n e macro, the LISP system signals
an error.
For information about how to use the VAX LISP callout facility, see Chapter 4 in
VAX LISP/VMS System Access Guide.

CALL-OUT Macro

Format
CALL-OUT GXternal-routine &REST args
Arguments
external-routine
The name of a defined external routine.
args
Arguments to be passed to the external routine. The arguments correspond by
position to the arguments defined for the routine. The LISP system evaluates
the argument expressions before the external routine is called. You can omit
an optional argument by specifying an expression whose value is n i l . The
corresponding position in the argument list will contain a 0 to coincide with
the VAX Procedure Calling Standard. If you specify fewer arguments than
were specified in the definition, the argument list will contain only the number of
arguments actually supplied. LISP signals an error if you supply more arguments
than were specified in the definition.

Return Value
If the :r e s u l t option of the d e f i n e -e x t e r n a l -r o u t i n e macro was specified, the
external routine’
s result is returned; otherwise, no value is returned.

Example
Lisp> (define-external-routine (smg$create_pasteboard
:file "SMGSHR"
:result integer)
(new-pasteboard-id :lisp-type integer
:vax-type :unsigned-longword
:access :in-out)
(output-device :lisp-type string)
(pb-rows :lisp-type integer :access :in-out)
(pb-columns :lisp-type integer :access :in-out)
(preserve-screen-flag :lisp-type integer
:vax-type :unsigned-longword))
SMG$CREATE_PASTEBOARD
Lisp> (defvar *pasteboard-id* -1)
*PASTEBOARD-ID*
Lisp> (call-out smg$create_pasteboard *pasteboard-id*
nil nil nil 1)

• The call to the d e f i n e -e x t e r n a l -r o u t i n e macro defines the VMS Screen
Management Facility (SMG$) routine called s m g $c r e a t e _ p a s t e b o a r d .
• The call to the d e f v a r macro defines a special variable which contains the
pasteboard ID returned by the external routine.

CALL-OUT Macro
• The call to the c a l l -o u t macro invokes the external routine s m g $c r e a t e _
p a s t e b o a r d , specifying the special variable to receive the pasteboard ID.
Three arguments are omitted, and a preserve-screen-flag of l is given. The
result status is returned.

CATCH-ABORT Macro
Catches the throw to the VAX LISP top level generated by the a b o r t function.
(For example, the a b o r t function is invoked when the cancel character (Ctrl/C)
is typed at the keyboard.) Thus, you can use c a t c h -a b o r t to alter the behavior
whenever a b o r t is called.
NOTE

This macro takes the place of (catch 'cancel-character-tag (...))
forms in previous versions of VAX LISP.

Format
CATCH-ABORT {body}*
Argument
body
One or more LISP forms.

Return Value
Unspecified.

Example
Lisp> (defun trapper ()
(catch-abort (loop))
(princ "Execution came through here"))
TRAPPER
Lisp> (TRAPPER)
[CWCl

Execution came through here
"Execution came through here"
Lisp>

• The t r a p p e r function sets up a catcher for the cancel character, then enters
an infinite loop.
• The user types Ctrl/C.
• The p r i n c function prints a string, indicating that execution continued after
the c a t c h -a b o r t form rather than returning directly to the Lisp> prompt.

CHAR-NAME-TABLE Function

CHAR-NAME-TABLE Function
Displays a formatted list of the VAX LISP character names.

Format
CHAR-NAME-TABLE
Argument
None.

Return Value
No value.

Example
Lisp> (char-name-table)
Hex Code
00
01
02
03
04
05
06
07
08
09
0A
0B
oc
0D
0E
OF
10
11
12
13
14
15
16
17
18
19
1A
IB
1C
ID
IE
IF
20

Preferred Name

Other Names

NULL
AA
AB
AC
AD
AE

NUL
SOH
STX
ETX
EOT
ENQ
ACK
AG BEL
AH BS
AI HT
AJ LF
VT
AL FORMFEED
AM CR
SO
SI
DLE
XON DC1
DC2
XOFF DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC ALTMODE

BELL
BACKSPACE
TAB
LINEFEED
AK
PAGE
RETURN
AN
A0
AP
AQ
AR
AS
AT
AU
AV
AW
AX
AY
AZ
ESCAPE
FS
GS
RS
US
SPACE

CHAR-NAME-TABLE Function
7F
84
85
86
87
88
89
8A
8B
8C
8D
8E
8F
90
91
92
93
94
95
96
97
9B
9C
9D
9E
9F
FF

RUBOUT
IND
NEL
SSA
ESA
HTS
HTJ
VTS
PLD
PLU
RI
SS2
SS3
DCS
PU1
PU2
STS
CCH
MW
SPA
EPA
CSI
ST
OSC
PM
APC
NEWLINE

COMMAND-LINE-ENTITY-P Function
Returns two values indicating the presence or absence of the specified entity
on the command line that invoked LISR This function provides an interface
to the CLI$PRESENT routine described in the VMS Utility Routines Manual.
Refer to that manual and to the VMS Command Definition Utility Manual for a
description of defining DCL commands and obtaining values from the command
line in your program.
The c o m m a n d -l i n e -ENTiTY-p function is especially useful in a user-built LISP
system that is invoked by a defined DCL command. See VAX LISP/VMS SystemBuilding Guide for information on user-built LISP systems.

Format
COMMAND-LINE-ENTITY-P entity-desc
Argument
entity-desc
A character string or symbol. If you supply a symbol, the print name of the
symbol is used. See the description of the entity-desc argument to CLI$PRESENT
in the VMS Utility Routines Manual for information about the meaning of this
argument.

COMMAND-LINE-ENTITY-P Function

Return Values
Two values. The meaning of these values is as follows:
First
Value

Second
Value

Meaning

Entity was explicitly specified as present.

NIL

Entity was present by default.

NIL

Entity was explicitly negated with NO.

NIL

Entity was absent by default.

COMMAND-LINE-ENTITY-VALUE Function
Returns the value of the specified entity on the command line that invoked LISR
This function provides an interface to the CLI$GET_VALUE routine described
in the VMS Utility Routines Manual. Refer to that manual and to the VMS
Command Definition Utility Manual for a description of defining DCL commands
and obtaining values from the command line in your program.
The c o m m a n d -l i n e -e n t i t y -v a l u e function is especially useful in a user-built LISP
system that is invoked by a defined DCL command. See the VAX LISP/VMS
System-Building Guide for information on user-built LISP systems.

Format
COMMAND-LINE-ENTITY-VALUE entity-desc
Argument
entity-desc
A character string or symbol. If you supply a symbol, the print name of the
symbol is used. See the description of the entity-desc argument to CLI$GET_
VALUE in the VMS Utility Routines Manual for information about the meaning
of this argument.

Return Values
Two values:
1. A string containing the first or next value of the specified entity, depending on
whether this is the first request for this entity or a subsequent request. If the
entity is not present, has no value, or if all values for this entity have been
obtained, n i l is returned.
2. A character that is the character delimiter that preceded the returned entity.
This is normally a comma (#\ , ) but may be a plus sign (#\ +) to indicate
concatenation.

COMMON-AST-ADDRESS Parameter

COMMON-AST-ADDRESS Parameter
Specifies the address of a routine, supplied by VAX LISP/VMS, that initially
handles all ASTs. This parameter must be given as the astadr argument to all
external routines that can cause an AST. No other object can be passed as the
astadr argument. Use the :v a l u e mechanism to pass this parameter.

Format
COMMON-AST-ADDRESS
Example
See the description of i n s t a t e - i n t e r r u p t -f u n c t i o n for an example of the use of
COMMON-AST-ADDRESS.

COMPILEDP Function
A predicate that checks whether an object is a symbol that has a compiled
function definition.

Format
COMPILEDP name
Argument
name
The symbol whose function or macro definition is to be checked.

Return Value
Returns the interpreted function or macro definition, if the symbol has an
interpreted definition that was compiled with the c o m p i l e function. Returns t ,
if the symbol has a compiled definition that was not compiled with the c o m p i l e
function. Returns n i l , if the symbol does not have a compiled function definition.

COMPILEDP Function

Example
Lisp> (defun add2 (x) (+ x 2))
ADD2
Lisp> (compiledp 'add2)
NIL
Lisp> (compile 'add2)
ADD2
ADD2
Lisp> (compiledp 'add2)
(LAMBDA (X) (BLOCK ADD2 (+ X 2)))

• The call to the d e f u n macro defines a function named ADD2.
• The first call to the c o m p i l e d p function returns n i l , because the function
ADD2 has not been compiled.
• The call to the c o m p i l e function compiles the function a d d 2.
• The second call to the c o m p i l e d p function returns the interpreted function
definition, because the function a d d 2 was previously compiled.

COMPILE-FILE Function
Compiles a specified LISP source file and writes the compiled code as a binary
fast-loading file (file type .FAS).

Format
COMPILE-FILE input-pathname &KEY :LISTING :MACHINE-CODE :OPTIMIZE
:OUTPUT-FILE :VERBOSE WARNINGS
Arguments
input-pathname
A pathname, namestring, symbol, or stream. The VAX LISP Compiler uses the
value of the *d e f a u l t -p a t h n a m e -d e f a u l t s * variable to fill in file specification
components that are not included in your input-pathname. The file type defaults
to .LSP.
:LISTING

Specifies whether the Compiler is to produce a listing file. The value can be t ,
n i l ,or a pathname, namestring, symbol, or stream. If you specify T, the Compiler
produces a listing file. The listing file is assigned the same name as the source
file with the file type .LIS, and is placed in the directory that contains the source
file.
If you specify n i l , no listing is produced. The default value is n i l .

COMPILE-FILE Function
If you specify a pathname, namestring, symbol, or stream, the Compiler uses the
value as the specification of the listing file. The Compiler uses the .LIS file type
and the value of the input-pathname to fill the components of the file specification
that are not included in your pathname, namestring, symbol, or stream.
:MACHINE-CODE

Specifies whether the Compiler is to include the machine code that it produces for
each function and macro that it compiles in the listing file. The value can be T or
n i l .If you specify t ,the listing file contains the machine code. If you specify n i l ,
the listing file does not contain the machine code. The default value is n i l .
:OPTIMIZE

Specifies the optimization qualities that the Compiler is to use during compila
tion. The value must be a list of sublists. Each sublist must contain a symbol
and a value, which specify the optimization qualities and corresponding values
that the Compiler is to use during compilation. For example:
' ((space 2) ( s a fe ty 1))

The default value for each quality is one. For a detailed discussion of Compiler
optimizations, see Chapter 2 of the VAX LISP/VMS Program Development Guide.
:OUTPUT-FILE

Specifies whether the Compiler is to produce a fast-loading file. The value can
be t , n i l , 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 n i l ,no fast-loading file is produced.
If you specify a pathname, namestring, symbol, or stream, the Compiler uses that
value as the specification of the output file. The Compiler uses the .FAS file type
and the value of the input-pathname to fill the components of the file specification
that are not included in your pathname, namestring, symbol, or stream.
:VERBOSE

Specifies whether the Compiler is to display the name of functions and macros
that it compiles. The value can be t or n i l .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. If you specify n i l , the names are not
displayed or included in the listing file. The default value is the value of the
*c o m p i l e -v e r b o s e * variable (by default, t ).
WARNINGS

Specifies whether the Compiler is to display warning messages. The value can be
t or n i l . If you specify t , the Compiler displays warning messages. If a listing
file exists, the Compiler also includes the messages in the listing file. If you
specify n i l , warning messages are not displayed or included in the listing file.
The default value is the value of the *c o m p i l e -w a r n i n g s * variable (by default, t ).

COMPILE-FILE Function

Return Value
If the Compiler generated an output file, a namestring is returned; otherwise, n i l
is returned.

Examples
1.

Lisp>

(compile-file "FACTORIAL" :verbose t)

Starting compilation of file DBA1:[SMITH]FACTORIAL.LSP;1
FACTORIAL compiled.
Finished compilation of file DBA1:[SMITH]FACTORIAL.LSP;1
0 Errors, 0 Warnings
"DBA1:[SMITH]FACTORIAL.FAS;1"

Compiles the file FACTORIAL.LSP, which is in the current directory. A fast
loading file named FACTORIAL.FAS is produced. The compilation is logged
to the terminal, because the :v e r b o s e keyword is specified with the value t .
2.

Lisp>

(compile-file "FACTORIAL" :output-file nil
:listing t
:warnings nil
:verbose nil)

NIL

Compiles the file FACTORIAL.LSP, which is in the current directory. A fast
loading file is not produced, because the :o u t p u t -f i l e keyword is specified
with the value n i l . A listing file named FACTORIAL.LIS is produced.
Warning messages are suppressed, because the :w a r n i n g s keyword is
specified with the value n i l .

*COMPILE-VERBOSE* Variable
Controls the amount of information that the Compiler displays.
The c o m p i l e -f i l e function binds the *c o m p i l e -v e r b o s e * variable to the value
supplied by the :v e r b o s e keyword. If the :v e r b o s e keyword is not specified, the
function uses the existing value of the *c o m p i l e -v e r b o s e * variable. If the value
is not n i l , the Compiler displays the name of each function as it is compiled; if
the value is n i l , the Compiler does not display the function names. The default
value is t .

Example
Lisp> (compile-file 'math)
Starting compilation of file DBA1:[SMITH]MATH.LSP;1
FACTORIAL compiled.
FIBONACCI compiled.

*COMPILE-VERBOSE* Variable
Finished compilation of file DBA1:[SMITH]MATH.LSP;1
0 Errors, 0 Warnings
" D B A l :[S M I T H ] M A T H . F A S ;1"

Lisp> (SETF *COMPILE—VERBOSE* NIL)
NIL
Lisp> (compile-file 'math)
"DBAl:[SMITH]MATH.FAS;2"

• The first call to the c o m p i l e -f i l e function shows the output the Compiler
displays during the compilation of a file, when the *c o m p i l e -v e r b o s e *
variable is the default, t .
• The call to the s e t f macro sets the value of the variable to n i l .
• The second call to the c o m p i l e -f i l e function compiles the file without
displaying output, because the variable’
s value is n i l .

‘ COMPILE-WARNINGS* Variable
Controls whether the Compiler displays warning messages during a compilation.
The c o m p i l e -f i l e function binds the *c o m p i l e -w a r n i n g s * variable to the value
supplied with the :w a r n i n g s keyword. If the :w a r n i n g s keyword is not specified,
the function uses the existing value of the *c o m p i l e -w a r n i n g s * variable. If the
value is not n i l , the Compiler displays warning messages; if the value is n i l ,the
Compiler does not display warning messages. The default value is T.
NOTE

The Compiler always displays fatal and continuable error messages.

Example
Lisp> (compile-file 'math)
Starting compilation of file DBAl:[SMITH]MATH.LSP;2
Warning in FACTORIAL
N bound but value not used.
FACTORIAL compiled.
Warning in FIBONACCI
N bound but value not used.
FIBONACCI compiled.
Finished compilation of file DBAl:[SMITH]MATH.LSP;2
0 Errors, 2 Warnings
"DBAl:[SMITH]MATH.FAS;3"
Lisp> (setf *compile-warnings* nil)
NIL
Lisp> (compile-file 'math)
Starting compilation of file DBAl:[SMITH]MATH.LSP;2
FACTORIAL compiled.
FIBONACCI compiled.
Finished compilation of file DBAl:[SMITH]MATH.LSP;2
0 Errors, 2 Warnings
"DBAl:[SMITH]MATH.FAS;4"

*COMPILE-WARNINGS* Variable

• The first call to the c o m p i l e -f i l e function shows the output that the
Compiler displays during the compilation of a file, when the *c o m p i l e w a r n i n g s * variable is the default, t .
• The call to the s e tf macro sets the value of the variable to n i l .
• The second call to the c o m p i l e -f i l e function compiles the file without
displaying warning messages in the output, because the variable’
s value is
NIL.

CONTINUE Function
Enables you to exit the break loop. When you call this function, it causes the
b r e a k function to return n i l and the evaluation of your program to continue from
the point at which the break loop was entered.

Format
CONTINUE
Argument
None.

Return Value
NIL.

Example
Lisp> (bind-keyboard-function # \ AB #'break)
Lisp> (load "FILEB.LSP")
; Loading contents of file LISPW$:[SMI...
AB
Break> (load "FILEA.LSP")
; Loading contents of file LISPW$:[SMITH]FILEA.LSP;1
;
FUNCTION-A
; Finished loading LISPW$:[SMITH]FILEA.LSP;1
T
Break> (continue)
Continuing from break loop...
;
FUNCTION-B
; Finished loading LISPW$:[SMITH]FILEB.LSP;1
T
Lisp>

The b r e a k function is bound to Ctrl/B.
FILEB.LSP is loaded.

CONTINUE Function
• Realizing that FILEA.LSP, which is needed to initialize an environment for
FILEB.LSP, is not yet loaded, the programmer invokes the b r e a k loop.
• FILEA.LSP is then loaded.
• Finally, the call to the c o n t i n u e function continues the loading of FILEB.LSP
and then returns the programmer to the top-level loop.

CRITICAL-SECTION Macro
Executes the forms in its body as a “
critical section.”During the execution of a
critical section, all interrupt functions are blocked and queued for later execution.
Ctrl/C is also blocked, so a critical section must neither loop nor cause errors. It is
an error to perform I/O or to call the w a i t function in a critical section.
If an error occurs during a critical section, VAX LISP invokes the Debugger,
and temporarily removes the restrictions on interrupts so you can type to the
Debugger. If you continue from the Debugger, LISP restores the restrictions on
interrupts before continuing. However, LISP is open to interruptions while you
are debugging the code.

Format
CRITICAL-SECTION {form}*
Argument
form
Form(s) to be executed as a critical section.

Return Value
Value(s) of the last form that was executed.

Example
Lisp> (defun restore-to-free-list (cons-cell)
(critical-section
(setf (cdr cons-cell) *head-of-free-list*
*head-of-free-list* cons-cell)))
RESTORE-TO-FREE-LIST

This example defines a function that restores a cons cell to the head of a list of
free cells. During the call to s e t f , the list is in an inconsistent state, because
the special variable *h e a d -o f -f r e e -l i s t * does not point to the head of the
list. An interrupting function that used *h e a d -o f -f r e e -l i s t * to remove an
element from the list would break the list. Therefore, r e s t o r e -t o -f r e e -l i s t
uses the c r i t i c a l -s e c t i o n macro to ensure that the s e t f call completes without
interruption.

DEBUG Function

DEBUG Function
Invokes the VAX LISP Debugger. For information on how to use the VAX LISP
Debugger, see Chapter 4 of the VAX LISP/VMS Program Development Guide.

Format
DEBUG
Argument
None.

Return Value
Returns n i l . You can cause the Debugger to return other values. See Chapter 4
of the VAX LISP /VMS Program Development Guide.

Example
Lisp> (debug)
Control Stack Debugger
Apply #5: (DEBUG)
Debug 1>

Invokes the VAX LISP Debugger. When you invoke the Debugger, it displays an
identifying message, stack frame information, and the Debugger prompt.

DEBUG-CALL Function
Returns a list representing the current debug frame function call. This function
is a debugging tool and takes no arguments. The list returned by the d e b u g -c a l l
function can be used to access the values passed to the function in the current
stack frame.

Format
DEBUG-CALL
Argument
None.

DEBUG-CALL Function

Return Value
A list representing the current debug frame function call, n i l is returned if this
function is called outside the Debugger.

Example
Lisp> (defvar adjustable-string
(make-array 10 :element-type 'string-char
:initial-element #\space
:adjustable t))
ADJUSTABLE-STRING
Lisp> (schar adjustable-string 3)
Fatal error in function SCHAR (signaled with ERROR).
Argument must be a simple-string: "
"
Control Stack Debugger
Apply #4: (SCHAR "
” 3)
Debug 1> (type-of (second (debug-call)))
(STRING 10)
Debug 1> ret #\space
#\SPACE

In this case, the function in the current stack frame is s c h a r . The call to
(d e b u g -c a l l ) returns the list (s c h a r "
"3). The form (second
(debug-call)) returns the first argument to s c h a r in the current stack frame.
Calling t y p e -of with this LISP object determines that the first argument to
s c h a r is of type (s t r i n g 10) and not a simple string. See the t r a c e macro
description for another example of the use of the d e b u g -c a l l function.

*DEBUG-PRINT-LENGTH* Variable
Controls the output that the VAX LISP 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 value can be either a positive
integer or n i l . If the value is a positive integer, the integer indicates the number
of objects at each level of a nested object to be displayed. If the value is n i l , no
limit is on the number of objects that can be displayed. The default value is n i l .
The value of this variable might cause the printer to truncate output. An ellipsis
( . . . ) indicates truncation.
This variable is similar to the *p r i n t -l e n g t h * variable described in Common
LISP: The Language.

*DEBUG-PRINT-LENGTH* Variable

Example
Lisp> (setf alphabet ' ( a b o d e f g h i
( A B C D E F G H I J K )
Lisp> (setf *debug-print-length* 5)
5
Lisp> (+ 2 ALPHABET)

j k))

Fatal error in function + (signaled with ERROR).
Argument must be a number: ( A B C D E F G H I J K )
Control Stack Debugger
Apply #5:: (+ 2 (A B C D E ...))
Debug 1> (SETF *DEBUG-PRINT-LENGTH* 3)
O
o
Debug 1> WHERE
Apply #5:: (+ 2 ( A B C

...))

• The call to the s e tf macro sets the symbol a l p h a b e t to a list of single-letter
symbols.
• The value of the *d e b u g -p r i n t -l e n g t h * 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 value of the symbol a l p h a b e t the first time it displays the stack frame
numbered 5.
• The call to the s e t f macro within the Debugger sets the value of the *d e b u g p r i n t -l e n g t h * variable to 3.
• The Debugger displays three elements of the list, after you change the value
of the variable.

*DEBUG-PRINT-LEVEL* Variable
Controls the output that the VAX LISP Debugger, Stepper, and Tracer facilities
display. This variable controls the number of levels of a nested object these
facilities can display. The variable’
s value can be either a positive integer or n i l .
If the value is a positive integer, the integer indicates the number of levels of a
nested object to be displayed. If the value is n i l , no limit is on the number of
levels that can be displayed. The default value is n i l .
The value of this variable might cause the printer to truncate output. A number
sign (#) indicates truncation.
This variable is similar to the *p r i n t -l e v e l * variable described in Common
LISP: The Language.

*DEBUG-PRINT-LEVEL* Variable

Example
Lisp> (setf alphabet ' (a (b (c (d (e))))))
(A (B (C (D (E) ))))
Lisp> (setf *debug-print-level* 3)
3
Lisp> (+ 2 ALPHABET)
Fatal error in function + (signaled with ERROR).
Argument must be a number: (A (B (C (D (E)))))
Control Stack Debugger
Apply #5: (+2

(A (B #)))

Debug 1> (setf *debug-print-level* nil)
NIL
Debug 1> where
Apply #5: (+2

(A (B (C (D (E))) )))

• The call to the s e t f macro sets the symbol a l p h a b e t to a nested list.
• The value of the *d e b u g -p r i n t -l e v e l * variable is set to 3.
• 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
is the value of the symbol a l p h a b e t ) the first time it displays the stack frame
numbered 5.
• The call to the s e t f macro within the Debugger sets the value of the *d e b u g p r i n t -l e v e l * variable to n i l .
• The Debugger displays all the levels of the nested list, after you change the
value of the variable.

DEFAULT-DIRECTORY Function
Returns a pathname with the host, device, and directory fields filled with the
values of the current default directory.
The d e f a u l t -d i r e c t o r y function is similar to the DCL SHOW DEFAULT com
mand. For information about the SHOW DEFAULT command, see the VMS DCL
Dictionary.
You can change the default directory by using the s e t f macro. Setting your
default directory with this macro also resets the value of the *d e f a u l t -p a t h n a m e d e f a u l t s * variable. Performing this operation is similar to using the DCL SET
DEFAULT command. See VAX LISP Implementation and Extensions to Common
LISP and Common LISP: The Language for more information on pathnames and
the *d e f a u l t -p a t h n a m e -d e f a u l t s * variable.
Note that the directory must exist for the change of directory to succeed.

DEFAULT-DIRECTORY Function

Format
DEFAULT-DIRECTORY
Argument
None.

Return Value
The pathname that refers to the default directory.

Examples
1.

Lisp> (default-directory)
#S(PATHNAME :HOST "MIAMI" :DEVICE "DBA1"
:DIRECTORY "SMITH" :NAME NIL :TYPE NIL
:VERSION NIL)
Lisp> (setf (default-directory) "[.tests]")
" [.TESTS]"
Lisp> (default-directory)
#S(PATHNAME :HOST "MIAMI" :DEVICE "DBA1"
:DIRECTORY "SMITH.TESTS" :NAME NIL :TYPE NIL
:VERSION NIL)

• The first call to the d e f a u l t -d i r e c t o r y function returns the pathname
that points to the default directory.
• The call to the s e t f macro changes the value of the default directory to
SMITH.TESTS.
• The second call to the d e f a u l t -d i r e c t o r y function verifies the directory
change.
2.

Lisp> (default-directory)
#S(PATHNAME :HOST "MIAMI" :DEVICE "DBA1"
:DIRECTORY "SMITH.TESTS" :NAME NIL :TYPE NIL
:VERSION NIL)
Lisp> *default-pathname-defaults*
#S(PATHNAME :HOST "MIAMI" :DEVICE "DBA1"
:DIRECTORY "SMITH.TESTS" :NAME NIL :TYPE NIL
:VERSION NIL.)
Lisp> (namestring (default-directory))
"DBA1:[SMITH.TESTS]"
Lisp> (setf (default-directory) "[-]")

"[-]"
Lisp> (namestring (default-directory))
"DBA1:[SMITH]"
Lisp> (namestring *default-pathname-defaults*)
"DBA1:[SMITH]"

DEFAULT-DIRECTORY Function

• The first call to the d e f a u l t -d i r e c t o r y function returns the pathname
that points to the default directory.
• The call to the *d e f a u l t -p a t h n a m e -d e f a u l t s * variable shows that its
value is the same as the value returned by the d e f a u l t -d i r e c t o r y
function.
• The call to the n a m e s t r i n g function returns the pathname as a string.
• The call to the s e tf macro changes the value of the default directory to
DBA1: [SMITH],
• The last two calls to the n a m e s t r i n g function show that the return
values of the d e f a u l t -d i r e c t o r y function and the *d e f a u l t -p a t h n a m e d e f a u l t s * variable are still the same.

DEFINE-ALIEN-FIELD-TYPE Macro
Defines alien-structure field types.
For information about alien structures, see Chapter 5 in the VAX LISP/VMS
System Access Guide.

Format
DEFINE-ALIEN-FIELD-TYPE name lisp-type primitive-type access-function
setf-function
Arguments
name
The name of the alien-field type being defined.
lisp-type
A LISP data type indicating the type of LISP object to which the field is to be
mapped.
primitive-type
Either one of the predefined alien-field types or a type that was previously defined
with the d e f i n e -a l i e n -f i e l d -t y p e macro. A LISP object of type primitive-type
is extracted from the alien structure’
s data when the field is accessed. The object
is then passed to the specified access function. Predefined alien-field types are
listed in Table 5-1 in the VAX LISP/VMS System Access Guide.
access-function
A function of one argument (whose type is primitive-type) that returns an object
of type lisp-type.

DEFINE-ALIEN-FIELD-TYPE Macro
setf-function
A function of one argument (whose type is lisp-type) that returns an object
whose type is the type of the default s e t f form, as defined by the primitive-type
argument. When the object is returned, it is packed into the alien structure’
s
field data.

Return Value
The name of the alien-field type.
NOTE

Functions that access and set field values can take more than one
argument; additional arguments are optional. When the type argument
in the d e f i n e -a l i e n -s t r u c t u r e macro’
s field description is a list, the
first element of the list is the field type, and the remaining elements
are expressions that the LISP system evaluates when it evaluates
the access function. The resulting values are passed as additional
arguments to the functions that access or set the field.*•

Examples
1.

Lisp> (define-alien-field-type integer-string-8
' integer
:string
#'(lambda (x) (parse-integer x :junk-allowed t))
#'(lambda (x) (format nil "~s" x)))
INTEGER-STRING-8
Lisp> (define-alien-structure two-ascii-integers
(int-1 integer-string-8 0 8)
(int-2 integer-string-8 8 16))
TWO-ASCII-INTEGERS

• The call to the d e f i n e -a l i e n -f i e l d -t y p e macro defines a field type
named i n t e g e r - s t r i n g -8. The field type i n t e g e r -s t r i n g -8 causes an
alien structure to convert strings to integers.
• The call to the d e f i n e -a l i e n -s t r u c t u r e macro defines an alien structure
named t w o -a s c i i -i n t e g e r s that has two fields, each of type i n t e g e r 
s t r i n g -8.

Lisp> (define-alien-field-type selection
t
:unsigned-integer
#' (lambda (n) (nth n ' (ma ri ny) ))
#' (lambda (x) (position x ' (ma ri ny))))
SELECTION

This is an example of how the : s e l e c t i o n type could be implemented. The
example defines an alien-field type named s e l e c t i o n . This type defines
a relationship between unsigned integers in an alien field and LISP data
objects. In accessing the value of a field of this type, the access-function uses
the integer stored in the alien field as an index into a list. In setting the
value in this type of field, the position of a LISP object in that list is used to
define the integer value stored in the alien structure.
33

DEFINE-ALIEN-STRUCTURE Macro

DEFINE-ALIEN-STRUCTURE Macro
Defines alien structures. An alien structure is a collection of bytes containing
VAX data types.
The syntax of the d e f i n e -a l i e n -s t r u c t u r e macro is similar to the d e f s t r u c t
macro described in Common LISP: The Language.
For an explanation of how to define an alien structure, see Chapter 5 in the VAX
LISP /VMS System Access Guide.

Format
DEFINE-ALIEN-STRUCTURE name-and-options
[doc-string]
{field-description}*
Arguments
name-and-options
The name-and-options argument is the name and the options of a new LISP
data type. The name argument must be a symbol. The options define the
characteristics of the alien structure. If you do not specify options, you can
specify the name-and-options argument as a symbol:
nam e

If you specify options, specify the name-and-options argument as a list whose first
element is the name:
( n a m e { ( k ey w o rd value)}*)

Using the following format, specify options as a list of keyword-value pairs.
(keyword value)

Table 1 lists the keyword-value pairs that you can specify.
Table 1:

DEFINE-ALIEN-STRUCTURE O ptions

Keyword-Value P a ir

D escription

:CONC-NAME name

Names the access functions. The value can be a symbol or NIL.
If you specify a symbol, the symbol becomes a prefix in the
access function names. If you wish to include a hyphen (—) in
the access function names, specify it as part of the prefix. If
you specify NIL, the access function names are the same as the
field names. By default, the prefix is the alien structure name
followed by a hyphen.

(continued on next page)

DEFINE-ALIEN-STRUCTURE Macro

Table 1 (Cont.):

DEFINE-ALIEN-STRUCTURE O ptions

Keyword-Value P a ir

D escription

: CONSTRUCTOR name

Names the constructor function. The value can be a symbol
or NIL. If you specify a symbol, the symbol becomes the name
of the constructor function. If you specify NIL, the macro does
not define a constructor function. If you do not specify this
keyword, the constructor function’
s name is the prefix MAKEattached to the alien structure name.

: C O PIER name

Names the copier function. The value can be a symbol or
NIL. If you specify a symbol, the symbol becomes the name
of the copier function. If you specify NIL, the macro does not
create a copier function. If you do not specify this keyword, the
copier function’
s name is the prefix COPY- attached to the alien
structure name.

: PREDICATE name

Names the predicate function. The value can be a symbol or
NIL. If you specify a symbol, the symbol becomes the name
of the predicate function. If you specify NIL, the macro does
not define a predicate function. If you do not specify this
keyword, the macro names the predicate function by attaching
the structure name to the characters -P.

: PRINT-FUNCTION

Specifies the print function for the alien structure. The value
must be a function. If you do not specify this keyword, the
LISP system displays the alien structure in the following
format:

function-name

#<Alien Structure n a m e n u m b e r >
In the preceding format, name is the name of the alien struc
ture and number is a unique identification number, which
distinguishes alien structures that have the same name.

doc-string
The documentation string to be attached to the symbol that names the alien
structure. The documentation string is of type s t r u c t u r e . See Common LISP:
The Language for information on the d o c u m e n t a t i o n function.
field-description
A field description for the alien structure. Specify a field description in the
following format:
{ n a m e ty p e sta rt e n d op tio n s)

The name argument must be a symbol. It names functions that access and set
the value of the alien structure field.
The type argument determines the method by which the VAX data type stored in
a field is converted to a LISP object and vice versa. Valid types are:
: STRING
: VARYING-STRING
: SIGN ED-IN TEGER
: UNSIGNED-INTEGER
: BIT-V ECTOR
: F-FLOATING
: G-FLOATING

DEFINE-ALIEN-STRUCTURE Macro
: D-FLOATING
: H-FLOATING
: POINTER
: SELECTION
T V p e s d e f i n e d w i t h t h e VAX LISP d e f i n e - a l i e n - f i e l d - t y p e m a c r o

See Chapter 5 in the VAX LISP /VMS System Access Guide for more information
on field types.
As in Common LISP, the start and end arguments are zero-based, with start being
inclusive and end being exclusive.
The start argument must be a rational number or, in some cases, a fixnum (see
Section 5.4.3.1 in the VAX LISP/VMS System Access Guide) that specifies the
8-bit byte start position of the field in the alien structure’
s data area. Default:
none.
The end argument must be a rational number or, in some cases, a fixnum (see
Section 5.4.3.1 in the VAX LISP/VMS System Access Guide) that specifies the
8-bit byte end position of the field in the alien structure’
s data area. The last
position a field occupies is the position that precedes the field’
s end position value.
Default: none.
The options define the characteristics for the field. Specify each option with a
keyword-value pair:
keyword value

Table 2 lists the keyword-value pairs that you can specify.
Table 2:

DEFINE-ALIEN-STRUCTURE Field O ptions

Keyword-Value P a ir

D escription

: DEFAULT form,

Specifies the default initial value that is to occupy the field. If
the field ’
s initial value was not specified in a call to the alien
structure’
s constructor function, the form is evaluated when
the constructor function is called. The value that results from
the evaluation is the field ’
s default initial value. This value
defaults to NIL.

: READ-ONLY value

Specifies whether the field can be accessed or set. The value
can be T or NIL. If you specify T, the macro generates access
functions that are unacceptable place indicators in a call to the
SETF macro. If you specify NIL, the macro generates access
functions that are acceptable place indicators in a call to the
SETF macro. The default is n i l .

: OCCURS integer

Specifies the number of times the field is to be represented
within the alien structure. The value must be an integer. The
default value is 1 (which means no repeats).

(continued on next page)

DEFINE-ALIEN-STRUCTURE Macro

Table 2 (Cont.):

DEFINE-ALIEN-STRUCTURE Field O ptions

Keyword-Value P a ir

D escription

: OFFSET rational-

Specifies the distance in 8-bit bytes from the start of one
occurrence of the field to the start of the next occurrence
of the field. The value must be a rational number. If you
specify a value that is greater than the field ’
s length, the alien
structure contains gaps. You can access the gaps with other
field definitions.

number

Return Value
The name of the alien structure.

Example
Lisp> (define-alien-structure et
(space-ship
:string 0 10)
(phone-number :unsigned-integer 10 17)
(home
:string 17 32))
ET

Defines an alien structure named e t , which contains three fields named s p a c e 
s h i p , p h o n e -n u m b e r , and h o m e .The fields s p a c e -s h ip and h o m e are defined to be
strings of length 10 and 15, respectively. The field p h o n e -n u m b e r is defined to be
a 7-byte unsigned integer.
For more examples of how to define alien structures, see Chapter 5 in the VAX
LISP/VMS System Access Guide.

DEFINE-EXTERNAL-ROUTINE Macro
Defines an external routine that a LISP program is to call. You can call routines
defined with this macro with the VAX LISP c a l l -o u t macro. For informa
tion about how to use the VAX LISP callout facility, see Chapter 4 in the VAX
LISP/VMS System Access Guide.

Format
DEFINE-EXTERNAL-ROUTINE name-and-options
[doc-string]
{argument-description}*

DEFINE-EXTERNAL-ROUTINE Macro

Arguments
name-and-options
The name argument is the name of the external routine that is being defined. It
must be a symbol; it may not be the name of a LISP function. The options define
the characteristics of the routine. If you do not specify options, you can specify
the name-and-options argument as a symbol:
nam e

If you specify options, specify the name-and-options argument as a list whose first
element is the name:
(n a m e { k e y w o r d value}*)

Specify the options with keyword-value pairs:
k e y w o r d v a lu e

The option values are not evaluated.
Table 3 lists the keyword-value pairs that you can specify.
Table 3:

DEFINE-EXTERNAL-ROUTINE O ptions

Keyword-Value P a ir

D escription

:CHECK—STATUSRETURN value

Specifies whether the callout facility is to check the severity of
the value that an external routine returns in register RO. The
value you specify can be T, an integer, or NIL. If you specify
T, the callout facility checks the severity of the return value.
If the severity is warning, error, or severe, the LISP system
signals a continuable error. If you specify an integer, an error
is signaled if that value is returned by the routine. If you
specify NIL, the callout facility does not check the severity of
the return value, n i l is the default value. If you specify this
option, do not specify the : RESULT option.

ENTRY-POINT string

Names the external routin e’
s entry point. The value must be a
string. The macro converts the name to uppercase characters.
The default value is the print name of the external routine
name.

:FILE pathname

Specifies the shareable image that was created for the external
routine. This must be in uppercase characters and must be
a logical name or the name of an executable image in the
SYS$SHARE directory. The file specification is merged with
the file SYS$SHARE:.EXE. You must specify this option unless
you are calling a system service.

(continued on next page)

DEFINE-EXTERNAL-ROUTINE Macro

Table 3 (Cont.):

DEFINE-EXTERNAL-ROUTINE O ptions

Keyword-Value P a ir

D escription

:RESULT type

Specifies the type of LISP object that the external routine is to
return. The value can be a LISP type, a type-spec-list, or NIL.
A type-spec-list has the following format:
:RESULT (:LISP-TYPE lisp-type :VAX-TYPE vax-type)

See Table 4-2 in the VAX LISP /V M S System Access Guide for
a list ofLISP/VAX types. NIL specifies that the routine returns
no value. The default value is NIL. If you specify this option,
do not specify the : CHECK-STATUS-RETURN option.
:TYPE-CHECK value

Specifies whether the callout facility is to check the types of
the arguments passed to the external routine for compatibility
with the LISP types specified in the argument specification.
The value can be T or NIL. If you specify T, the facility checks
the types for compatibility; if you specify NIL, the facility does
not check the argument types. The default value is NIL.

doc-string
The documentation string for the symbol that names the external routine. The
documentation string is of type e x t e r n a l -r o u t i n e . See Common LISP: The
Language for information on the d o c u m e n t a t i o n function.
argument-description
An argument description that is to be passed to the external routine. Include as
many descriptions as the arguments you want to call. Specify the descriptions in
the following format:
(name options)

The name argument must be a unique symbol in the definition or n i l .The name
identifies the argument and is used in some error messages. If you do not specify
options, you can specify the argument-description argument as a symbol:
name

If you specify options, specify the argument as a list whose first element is the
name:
[name {keyword value}*)

The options arguments define the characteristics of an argument. Specify the
options with keyword-value pairs:
keyword value

The option values are not evaluated.
Table 4 lists the keyword-value pairs you can specify.

DEFINE-EXTERNAL-ROUTINE Macro

Table 4:

DEFINE-EXTERNAL-ROUTINE Argument O ptions

Keyword-Value P a ir

D escription

:ACCESS value

Specifies the type of access the external routine needs for
the argument. The value can be either : IN or : i n -OUT. The
default value is : IN. If you specify : IN, the argument can be
read but not modified by the external routine. If you specify
:IN-OUT, the argument can be both read and destructively
modified by the external routine.

:LISP-TYPE type

Specifies the LISP type of the argument value that the callout
facility is to pass to the external routine. See Table 4-2 in the
VAX L IS P / V M S System A ccess G u ide for the values you can
specify.

:MECHANISM value

Specifies the argument-passing mechanism the external
routine is to expect for the argument. The values you can
specify are :VALUE, :REFERENCE, and :DESCRIPTOR. The
default value is :DESCRIPTOR for :VAX-TYPE :TEXT and
:REFERENCE for other LISP data types.

:VAX-TYPE type

Specifies the VAX data type of the argument value that the
external routine is to return. See Table 4—2 in the VAX
L IS P / V M S System A ccess G uide for the values you can specify.

Return Value
The symbol that names the external routine.

Example
Lisp> (define-external-routine (mth$acosd
:file "MTHRTL"
:result (:lisp-type
single-float
:vax-type
:f-floating))
"This routine returns the arc cosine
of an angle in degrees."
(x :lisp-type single-float
:vax-type :f-floating))

Defines an RTL routine, called m t h $a c o s d , which returns the arc cosine of an
angle in degrees. The routine takes one read-only argument, which is an F_
floating number, and returns the result as an F_floating number.
For more examples of how to define external routines, see Chapter 4 in the VAX
LISP/VMS System Access Guide. These examples also show you how to call out
to defined external routines.

DEFINE-FORMAT-DIRECTIVE Macro

DEFINE-FORMAT-DIRECTIVE Macro
Defines a directive for use in a f o r m a t control string, supplementing the directives
supplied with VAX LISP. In a call to f o r m a t , specify a directive you have defined
in the form:
~/n a m e!

You can also specify colon and at sign modifiers:
~@Jnamel

You can also specify one or more parameters:
~ n ,n ln a m el

d e f i n e -f o r m a t -d i r e c t i v e provides means for the body of the format directive
you define to receive the value of parameters and the presence or absence of colon
and at sign modifiers. See VAX LISP Implementation and Extensions to Common
LISP for more information about defining format directives.

Format
DEFINE-FORMAT-DIRECTIVE name ( arg stream colon-p atsign-p
&OPTIONAL (parameterl default)
(param eter default)
...)
&BODY forms
Arguments
name
The name of the format directive defined with this macro.
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 f o r m a t directive looks in
the u s e r package for the directive definition.
arg
A symbol that is bound to the argument to be formatted by the directive.
stream
A symbol that is bound to the stream to which the printing is to be done.
colon-p
A symbol that is bound to t or n i l , indicating whether a colon was specified in
the directive.
atsign-p
A symbol that i s bound to t or n i l , indicating whether an at sign was specified in
the directive.
41

DEFINE-FORMAT-DIRECTIVE Macro
parameters
One optional argument is allowed for each prefix parameter 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 body can begin with
a declaration and/or documentation string.

Return Value
The name of the f o r m a t directive that has been defined.

Example
Lisp> (define-format-directive evaluation-error
(symbol stream colon-p atsign-p
soptional (severity 0))
(declare (ignore atsign-p))
(fresh-line stream)
(princ (case severity
(0
"Warning: ")
(1
"Error: ")
(2
"Severe Error: "))
stream)
(format stream "~:!The symbol ~S ~:_does not have an ~
integer value.~%Its value is:
symbol (symbol-value symbol))
(when colon-p
(write-char #\bell stream)))
EVALUATION-ERROR
Lisp> (setf process nil)
NIL
L is p >

(fo rm a t

" ~ 1 : / e v a l u a t i o n —e r r o r / "

'p r o c e s s )

Error: The symbol PROCESS does not have an integer value.
Its value is: NIL
|b e e p |

• This example shows the definition of a f o r m a t directive, a use of the directive,
and the printed output.
• The prefix parameter l in "~l: /e v a l u a t i o n -e r r o r /" indicates the severity of
the error being signaled. The colon produces a beep on the terminal.

DEFINE-GENERALIZED-PRINT-FUNCTION Macro

DEFINE-GENERALIZED-PRINT-FUNCTION Macro
Defines a function that specifies how any object is to be pretty-printed, regardless
of its form. Generalized print functions are effective only when they are enabled
(globally or locally) and when pretty-printing is enabled. You can enable a
generalized print function globally by using the g e n e r a l i z e d -p r i n t -f u n c t i o n e n a b l e d -p function, or you can enable it locally by using the w i t h -g e n e r a l i z e d p r i n t -f u n c t i o n macro. An enabled generalized print function is used if its
predicate evaluates to a non-NiL value.
See VAX LISP Implementation and Extensions to Common LISP for more infor
mation about generalized print functions.

Format
DEFINE-GENERALIZED-PRINT-FUNCTION name {object stream) predicate
&BODY forms
Arguments
name
The name of the generalized print function being defined.
object
A symbol that is bound to the object to be printed.
stream
A symbol that is bound to the stream to which output is to be 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. If
the form evaluates to non-NiL on the object to be pretty-printed, the generalized
print function will be 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 of the generalized print function that has been defined.

DEFINE-GENERALIZED-PRINT-FUNCTION Macro

Example
Lisp> (define-generalized-print-function print-nil-as-list
(object stream)
(null object)
(princ "( )" stream))
PRINT-NIL-AS-LIST
Lisp> (print nil)
NIL
NIL
Lisp> (pprint nil)
NIL
Lisp> (with-generalized-print-function 'print-nil-as-list
(print nil)
(pprint nil))
NIL
( )
Lisp> (setf (generalized-print-function-enabled-p
'print-nil-as-list)
t)
T
Lisp> (pprint nil)
( )

• The first p r i n t call prints n i l , because the generalized print function
p r i n t - n i l - a s - l i s t i s not enabled.
• The first p p r i n t call prints n i l , because p r i n t - n i l - a s - l i s t is still not
enabled.
• The second p r i n t call prints n i l , because pretty-printing is not enabled.
• The second p p r i n t call prints ( ), because the generalized print function is
enabled locally.
• The third p p r i n t call prints ( ), because the generalized print function is
en abled globally.

DEFINE-LIST-PRINT-FUNCTION Macro
Defines and enables a function to print lists that begin with a specified element.
Defined functions are effective only when pretty-printing is enabled. The system
checks the first element of each list to be printed for a match. If the first element
of a list matches the name of a list-print function, the list is printed according to
the format you have defined.
See VAX LISP Implementation and Extensions to Common LISP for more infor
mation about pretty-printing.

Format
DEFINE-LIST-PRINT-FUNCTION symbol (list stream)
&BODY forms

DEFINE-LIST-PRINT-FUNCTION Macro

Arguments
symbol
The first element of any list to be printed in the defined format.
list
A symbol that is bound to the list to be printed.
stream
A symbol that is bound to the stream on which printing is to be done.
forms
Forms to be evaluated. The forms refer to the list to be printed and the stream
by means of the symbols you supply for list and stream. The body can include
declarations. Calls to f o r m a t may also be included.

Return Value
The name of the list-print function that has been defined.

Example
Lisp> (define-list-print-function my-setq (list stream)
(format stream
"~1!~W~A ~ :1-0{~W~A
"
list))
MY-SETQ
Lisp> (setf base ' (my-setq hi 3 bye.4))
(MY-SETQ HI 3 BYE 4)
Lisp> (print base)
(MY-SETQ HI 3 BYE 4)
(MY-SETQ HI 3 BYE 4)
Lisp> (pprint base)
(MY-SETQ HI 3
BYE 4)

• The list-print function m y -s e t q is defined.
• The call to p r i n t does not use the list-print function m y -s e t q to print the
value of b a s e , because pretty-printing is not enabled.
• The call to p p r i n t does use the list-print function m y -s e t q to print the value
of BASE.

DELETE-PACKAGE Function

DELETE-PACKAGE Function
Uninterns all symbols interned in the package, unuses all packages the package
uses, and deletes the package. An error is signaled if any other package uses the
package.

Format
DELETE-PACKAGE package
Argument
package
A package, or a string or symbol naming a package.

Return Value
T.

Example
Lisp> (delete-package "test-package")
T
Lisp> (find-package "test-package")
NIL

DESCRIBE Function
Displays information about a specified object. If the specified object has a doc
umentation string, this function displays the string in addition to the other
information the function displays. The type of information the function displays
depends on the type of the object. For example, if a symbol is specified, the
function displays the symbol’
s value, definition, properties, and other types of
information. If a floating-point number is specified, the number’
s internal repre
sentation is displayed in a way that is useful for tracking such things as roundoff
errors.

Format
DESCRIBE object

DESCRIBE Function

Argument
object
The object about which information is to be displayed.

Return Value
No value.

Examples
1.

Lisp> (describe 'c)
It is the symbol C
Package: USER
Value:
unbound
Function: undefined

Lisp> (describe 'factorial)
It is the symbol FACTORIAL
Package: USER
Value:
unbound
Function: a compiled-function
FACTORIAL n

Lisp> (.describe pi)
It is the long-float 3.1415926535897932384626433832795L0
Sign:
+
Exponent:
2 (radix 2)
Significand: 0.78539816339744830961566084581988L0

Lisp> (describe '#(1 2 3 4 5))
It is a simple-vector
Dimensions:
(5)
Element type: t
Adjustable:
no
Fill Pointer: no
Displaced:
no

Displays information about the simple-vector #(1 2 3 4 5).

DIRECTORY Function

DIRECTORY Function
Converts its argument to a pathname and returns a list of the pathnames for the
files matching the specification. The d i r e c t o r y function is similar to the DCL
DIRECTORY command.

Format
DIRECTORY pathname
Argument
pathname
The pathname, namestring, stream, or symbol for which the list of file system
pathnames is to be returned. In VAX LISP/VMS, this argument is merged with
the following default file specification:
host:device\[directory]*.*:*

The host, device, and directory values are supplied b y the * d e f a u l t - p a t h n a m e d e f a u l t s * variable.
Specifying just a directory is equivalent to specifying a directory with wildcards
(*) in the name, type, and version fields of the argument. For example, the
following two expressions are equivalent:
(directory " [mydirectory]")
(directory " [mydirectory]*.*;*")

Both expressions return a list of pathnames that represent the files in the
directory MYDIRECTORY.
Specifying a directory with just a specified version field is equivalent to specifying
a directory and version with wildcards (*) 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 following equivalent expressions return the list of pathnames for files in your
default directory:
(directory "")
(directory (default-directory))

Return Value
A lis t o f p a th n a m e s, i f th e s p e c ifie d p a th n a m e is m a tc h e d , o r n i l , i f th e p a th n a m e
is not matched.

DIRECTORY Function

Example
Lisp> (defun my-directory (Soptional (filename ""))
(let ((pathname (pathname filename))
(directory (directory filename)))
(cond ((null directory)
(format t
"~%No files match ~A.~%"
(namestring filename)))
(t (format t
"~%The following
[files are ~;file is ~]~
in the directory ~A:[~A]
(equal (length directory) 1)
(pathname-device
(nth 0 directory))
(pathname-directory
(nth 0 directory)))
(dolist (x directory)
(format t "~&~2T~A" (file-namestring x)))
(terpri)))
(values)))
MY-DIRECTORY
Lisp> (my-directory)
The following files are in the directory DBA1:[SMITH.TESTS]:
TEST5.DRB;1
TEST1.LSP;7
TEST1.LSP;6
TEST1.LSP;5
EXAMPLE.TXT;2
TEST3.LSP;15
TEST6.LSP;1
Lisp> (my-directory ".lsp;")
The following files are in the directory DBA1:[SMITH.TESTS]:
TEST1.LSP;7
TEST3.LSP;15
TEST6.LSP;1

• The call to the d e f u n macro defines a function that formats the output of
the d i r e c t o r y function, making the output more readable. The function
is defined such that it accepts an optional argument and does not return a
value.
• The f i r s t c a l l t o t h e f u n c t i o n m y - d i r e c t o r y s h o w s h o w t h e f u n c t i o n f o r m a t s
t h e d i r e c t o r y o u t p u t w h e n a n a r g u m e n t i s n o t s p e c if i e d .

• The second call to the function m y - d i r e c t o r y includes an argument; the
output includes only the latest versions of file names of file type .LSP.

DRIBBLE Function

DRIBBLE Function
Echoes the input and output of an interactive LISP session to a specified file,
enabling you to save a record of what you do during the session in the form of a
file.
When you want to stop the d r i b b l e function from echoing input and output to
the pathname, close the file by calling the d r i b b l e function without an argument.
In VAX LISP/VMS, there are two restrictions on the use of the d r i b b l e function:
• When you are in the VAX LISP Editor, terminal I/O is not recorded in a
dribble file.
• In the DECwindows-based development environment, I/O to windows other
than the Listener is not recorded in a dribble file.

Format
DRIBBLE &OPTIONAL pathname
Argument
pathname
The pathname to which the input and output of the LISP session is to be sent.

Return Value
If an argument is specified with the function, no value is returned and dribbling
is turned on. If dribbling is on and the function is called with no arguments, t is
returned and dribbling is turned off. If dribbling is off and the function is called
without an argument, n i l is returned.

Examples
1.

Lisp> (dribble "newfunction.txt")
Dribbling to DBA1:[SMITH]NEWFUNCTION.TXT;1
Lisp>

Creates a dribble file named NEWFUNCTION.TXT. The LISP system sends
input and output to the file until you call the d r i b b l e function again (without
an argument) or exit LISP.
2.

Lisp> (dribble)
T

Closes the dribble file that was previously opened and turns dribbling off.

DYNAMIC-SPACE-RATIO Function

DYNAMIC-SPACE-RATIO Function
Returns the percentage of dynamic space that may be filled before a full garbage
collection is performed.
The ratio may be changed by using the s e t f macro. The new value must be
a floating-point number greater than 0 and less than or equal to 1. Setting
this ratio may help the memory management system make more efficient use
of memory. However, the ratio is only a guideline: it may be reset to more
appropriate values when the memory management system finds the current value
to be inappropriate for existing conditions.
The default dynamic space ratio is 0.5. Setting the dynamic space ratio to a
higher value decreases the frequency of garbage collections. Values less than 0.5
are probably wasteful of space.

Format
DYNAMIC-SPACE-RATIO
Argument
None.

Return Value
A floating-point number.

Example
Lisp> (dynamic-space-ratio)
0 .5

Lisp> (setf (dynamic-space-ratio)
0.75

.75)

ED Function
Invokes the VAX LISP Editor. This function can be specified with an optional
argument whose value can be a namestring, pathname, or symbol. In VAX LISP,
the argument’
s value can also be a list. In addition, you can specify a :t y p e
argument whose value can be the :f u n c t i o n or :v a l u e 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 :l e v e l keyword. Do not specify a higher interrupt level.

ED Function
See Chapter 3 of the VAX LISP /VMS Program Development Guide for informa
tion on using the VAX LISP Editor.

Format
ED &OPTIONAL x&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 s e t f macro. The list is evaluated, and a value that you can edit is returned.
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 invoked to edit the function or macro definition associated
with the specified symbol.

:VALUE

The Editor is invoked to edit the specified sym bol’
s value.

The default value for the :TYPE keyword i s the :f u n c t i o n keyword.

Return Value
No value.

Examples
1.

Lisp> (ed " [smith.lisp]newprog.lsp")

Invokes the Editor to edit the file NEWPROG.LSP in the directory
[SMITH.LISP].
2. Lisp> (ed 'factorial)
Invokes the Editor to edit a function named f a c t o r i a l .
3. Lisp> (ed 'gameboard-array :type :value)
Invokes the Editor to edit the value of the symbol g a m e b o a r d - a r r a y .

ED Function

4. Lisp> (defstruct room
doors
windows
outlets
color)
ROOM
Lisp> (setq room2 (make-room :doors 1
:windows 3
:outlets 4
:color 'blue))
#S(ROOM :DOORS 1 :WINDOWS 3 :OUTLETS 4 :COLOR BLUE)
Lisp> (ed ' (room-color room2))

• The call to the d e f s t r u c t macro defines a structure named r o o m .
• The call to the s e t q special form creates an instance of the structure r o o m .
• The call to the e d function invokes the Editor to edit the c o l o r slot of the
structure bound to ROOM2.

ENLARGE-BINDING-STACK Function
Enlarges the VAX LISP binding stack by the specified number of pages. Use this
function if the default size of the binding stack is too small to accommodate a
large or complex program.

Format
ENLARGE-BINDING-STACK number-of-pages
Argument
number-of-pages
The number of 512-byte pages by which to enlarge the binding stack.

Return Value
Unspecified.

ENLARGE-LISP-MEMORY Function
Increases the amount of virtual memory allocated to VAX LISP by asking the
operating system for a specified number of 64K-byte segments.

Format
ENLARGE-LISP-MEMORY segments

ENLARGE-LISP-MEMORY Function

Argument
segments
The number of 64K-byte segments by which to enlarge VAX LISP memory.

Return Value
The specified number of segments.

Example
Lisp> (area-segment-limit :dynamic)
100

Lisp>
50
Lisp>
150

(enlarge-lisp-memory 50)
(area-segment-limit :dynamic)

*ERROR-ACTION* Variable
Determines the action that the VAX LISP Error Handler is to take when an
unhandled error occurs. The value of this variable can be the :e x i t or the :d e b u g
keyword. If the value is :EXiT, the Error Handler causes the LISP system to exit;
if the value is :d e b u g , the Error Handler invokes the VAX LISP Debugger. The
default value is :d e b u g for interactive LISP sessions; otherwise, the default value
is :EXIT.
Besides setting this variable within a LISP form, you can also set it on LISP
initialization with the /ERROR_ACTION qualifier. See Chapter 2 of the VAX
LISP/VMS Program Development Guide.

Example
Lisp> (car 'a)
Error in CAR: Argument must be a list: A.
Control Stack Debugger
Apply #6: (CAR A)
Debug 1> quit
Lisp> (setf *error-action* :exit)
:EXIT
Lisp> (car 'a)
Error in CAR: Argument must be a list: A.
$

*ERROR-ACTION* Variable

• When the first error occurs, the LISP system invokes the VAX LISP Debugger
because the value of the *e r r o r -a c t i o n * variable is :d e b u g (the default).
• The call to the s e t f macro sets the value of the variable to :e x i t .
• The second time the error occurs, the LISP system exits and control returns
to the VMS command level.

EXIT Function
Invokes the VMS Exit system service, after unwinding the stack, causing the
LISP system to exit and to return control to the VMS command level.
You can pass the status of the LISP system to the VMS command level when you
exit the LISP system by specifying an optional argument. When the LISP system
exits, the argument’
s value is passed to the VMS command level.

Format
EXIT &OPTIONAL status
Argument
status
A fixnum or a keyword that indicates the status of the LISP system that is 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:
Error status
Success status
Warning status

:ERROR
:SUCCESS
:WARNING

Return Value
The e x i t function does not return to LISP.

Examples
1.

Lisp>

(e xit)

Exits the LISP system.
2. Lisp>

(e x it

terror)

$ show symbol Sstatus
$STATUS = "%X112D8012"

Exits the LISP system. When control returns to the VMS command level, the
VAX LISP exit status contains an error status.

FORCE-INTERRUPT-FUNCTION Function

FORCE-INTERRUPT-FUNCTION Function
F orces an A ST and th us the invocation o f the related in terrupt function specified
by its argument, f o r c e -i n t e r r u p t -f u n c t i o n is prim arily u sefu l for debugging.

Format
FORCE-INTERRUPT-FUNCTION iif-id
Argument
iif-id
An in terrupt function identifier previou sly return ed by an i n s t a t e -i n t e r r u p t f u n c t i o n function.

Return Value
U nspecified.

Example
Lisp> (defun timer-interrupt-handler ()
(princ "The timer has expired"))
TIMER-INTERRUPT-HANDLER
Lisp> (setf timer-iif (instate-interrupt-function
#'timer-interrupt-handler))
8454198
Lisp> (force-interrupt-function timer-iif)
The timer ’has expired
T

• T h e function t i m e r -i n t e r r u p t -h a n d l e r is in sta ted as an in terrupt function
w h ose iif-id is retained as the value of t i m e r -i i f .
• P a ssin g t i m e r -iif in a call to f o r c e -i n t e r r u p t -f u n c t i o n cau ses t i m e r i n t e r r u p t -h a n d l e r to execute.

Format Directives Provided with VAX LISP
VAX L ISP provides eigh t directives for th e f o r m a t function, in addition to th ose
described in Common LISP: The Language. Table 5 lists and describes th ese
directives. See VAX LISP Implementation and Extensions to Common LISP for
m ore inform ation about u sin g th ese directives.

Format Directives Provided with VAX LISP

Table 5:

Format Directives Provided with VAX LISP

D irective

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 modifier and four prefix parameters.
Use the colon modifier (~ :W) when you want to set *PRINT-PRETTY*
and *PRINT—ESCAPE* to T,but *PRINT-LENGTH*, *PRINT-LEVEL*, and
*PRINT-LINES* to NIL.
The four prefix parameters specify padding.
~ mincol, colinc, minpad,padcharSN

These parameters are identical to those used with the Common LISP ~A
directive:
mincol
Specifies the minimum width of the printed representation of
the object. FORMAT inserts padding characters on the right,
until the width is at least mincol columns. Use the at sign
modifier with minpad to insert the padding characters on the
left instead. The default for mincol is 0.

colinc

Specifies an increment: the number of padding characters
to be inserted at one time until the width is at least mincol
columns. The default is 1.

minpad

Specifies the minimum number of padding characters to be
inserted. The default is 0.

padchar

Preceded by a single quote, specifies the padding character.
The default is the space character.

Begins a logical block. A logical block is a hierarchical grouping of
FORMAT directives treated as a unit. FORMAT must be processing a logical
block with *PRINT-PRETTY* true to enable pretty-printing. Directives
inside a logical block refer to elements of a single list taken from the
argument list to FORMAT. (If the argument supplied to the logical block is
not a list, the logical block is skipped and the argument is printed as if
with ~W.) The logical block directive takes colon and at sign modifiers.
When the logical block directive is modified by a colon (~: !), the directive
sets *PRINT-PRETTY* and *PRINT-ESCAPE* to T but *PRINT-LENGTH*,
*PRINT-LEVEL*, and *PRINT-LINES* to NIL.
When the logical block directive is modified by an at sign (~@ !), direc
tives 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. 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 (~1!) 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.

(continued on next page)

Format Directives Provided with VAX LISP

Table 5 (Cont.):
D irective

Format Directives Provided with VAX LISP
Effect
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 (~: ), the directive starts a new line if not enough space is on the
line to print the next logical block section. When modified by an at sign
(~§ ), the directive starts a new line if miser mode is enabled.
The ~ directive and its variants are effective only when used within a
logical block with pretty-printing enabled.

~nl

Sets indentation for subsequent lines 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 ~ nl directive
and the ~ n : I variant are effective only when used within a logical block
with pretty-printing enabled.

~n/FILL/

Prints the elements of a fist with as many elements as possible on each
line. If n is 1, FORMAT encloses the printed list in parentheses. If pretty
printing is disabled, the directive causes FORMAT to print the output on a
single fine.

~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 list in parentheses. If pretty-printing is disabled,
this directive causes FORMAT to print the output on a single line.

~ n , m/TABULAR/ Prints the list in tabular form. If n is 1, FORMAT encloses the list
in parentheses; m specifies the column spacing. If pretty-printing is
disabled, this directive causes FORMAT to print the output on a single
line.

GC Function
Invokes a full garbage collection. The LISP system automatically initiates
garbage collection during normal system use whenever necessary. You might
want to use the g c function to invoke the garbage collector just before a timecritical part of a LISP program. Using the g c function this way reduces the
possibility of the LISP system initiating a garbage collection when a critical part
of the program is executing.
NOTE

The LISP system does not use the gc function to initiate garbage
collections. Therefore, redefining the g c function does not prevent
garbage collection. You can disable garbage collecting by using the
g c -m o d e function.
See VAX LISP Implementation and Extensions to Common LISP for a description
of the garbage collector.

GC Function

Format
GC
Argument
None.

Return Value
t , w hen ga rba ge collection is completed.

Example
Lisp> (gc)
; Starting full GC ...
; ... Full GC finished
T

Invokes the garbage collector. Whether the messages are printed when a garbage
collection occurs depends on the value of the * gc -v erbose * variable.

GC-COUNT Function
Returns the number of garbage collections performed since the LISP image was
invoked. You may specify the type of garbage collection to be counted.

Format
GC-COUNT &OPTIONAL type
Argument
type
Possible values are:
0, 1, or 2

Collections in the three ephemeral areas, respectively.
:FULL
Full collections.
:DEFAULT Both full and ephemeral collections. This is the default.
A type of t is the same as :d e f a u l t .

Return Value
An integer.

GC-COUNT Function

Example
Lisp> (gc-count 0)
12
Lisp> (gc-count :full)
1

The number of ephemeral collections is higher than the number of full garbage
collections in this session.

GC-MODE Function
Returns or sets the mode of garbage collection, depending on the value of the type
argument. You can use this function to control the collection algorithm used or to
prevent garbage collections. See the VAX LISP Implementation and Extensions to
Common LISP manual for details on VAX LISP garbage collection.

Format
GC-MODE &OPTIONAL type
Argument
type
D eterm in es w hether the function return s or sets th e garbage collection mode.
P ossib le valu es are:
:DEFAULT

The function returns the current mode. This is the default.

:NONE

Garbage collection is disabled.

:FULL

The full garbage collector is enabled.

:EPHEMERAL

The VAX LISP system attempts to enable the ephemeral garbage col
lector. The attempt may fail due to insufficient memory. :EPHEMERAL
always implies :FULL.

Values o f T or n i l for type are also valid and cau se the function to return the
current mode.

Return Value
One of three keywords indicating which type of garbage collection may occur:
:n o n e , if garbage collecting is disabled; :Fu l l , if full garbage collection only
is enabled; or :e p h e m e r a l , if both ephemeral and full garbage collections are
enabled.

GC-MODE Function

Examples
1.

Lisp>

(gc-mode)

: FULL

The ephemeral collector has been shut off; only the full collector is enabled
2.

Lisp> (enlarge-lisp-memory 40)
40
Lisp> (gc-mode :ephemeral)
:EPHEMERAL

With more memory allocated by the e n l a r g e - l i s p - m e m o r y function, both
ephemeral and full stop-and-copy garbage collections are enabled by this call
to the g c - m o d e function.

*GC-VERBOSE* Variable
A variable whose value is used as a flag to determine whether the LISP system
is to display messages when a full garbage collection occurs. If the flag is n i l ,
the system displays no messages. If the flag is not n i l , the system displays a
message before and after a garbage collection occurs. The default value is T.
The VAX LISP * p r e - g c - m e s s a g e * and * p o s t - g c - m e s s a g e * variables control the
contents of the messages displayed.
The ephemeral garbage collector does not display messages.
For more information on garbage collector messages, see the VAX LISP
Implementation and Extensions to Common LISP manual.

Examples
1.

Lisp> *gc-verbose*
T
L isp >

(gc)

; Starting full GC ...
; ... Full GC finished
T

In this example, * g c - v e r b o s e * has the default value t , so the LISP system
displays a message before and after a garbage collection occurs.
The text of the messages depends on the values of the * p r e - g c - m e s s a g e * and
* p o s t - g c - m e s s a g e * variables. These are the default messages.
2.

Lisp>

(setf *gc-verbose* nil)

N IL

Lisp>

(gc)

The second call to the g c function shows that the system does not display
messages when the value of * g c - v e r b o s e * is n i l .

GENERALIZED-PRINT-FUNCTION-ENABLED-P Function

GENERALIZED-PRINT-FUNCTION-ENABLED-P
Function
Used to enable globally a generalized print function or to test whether a gener
alized print function is enabled, g e n e r a l i z e d - p r i n t - f u n c t i o n - e n a b l e d - p is a
predicate, and it can be used as a place form with s e t f .
See VAX LISP Implementation and Extensions to Common LISP for more infor
mation about using generalized print functions.

Format
GENERALIZED-PRINT-FUNCTION-ENABLED-P name
Argument
name
A symbol identifying the generalized print function to be enabled or tested.

Return Value
T o r N IL.

Example
Lisp> (generalized-print-function-enabled-p 'print-nil-as-list)
NIL
Lisp> (define-generalized-print-function print-nil-as-list
(object 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 use of the g e n e r a l i z e d - p r i n t - f u n c t i o n - e n a b l e d - p function returns
n i l , because no generalized print function named p r i n t - n i l - a s - l i s t has
been defined.
• The call to the d e f i n e - g e n e r a l i z e d - p r i n t - f u n c t i o n macro defines the
generalized print function p r i n t - n i l - a s - l i s t .

GENERALIZED-PRINT-FUNCTION-ENABLED-P Function
• The call to s e tf globally enables the generalized print function p r i n t -n i l AS-LIST.

• The p p r i n t call prints ( ), because the generalized print function is enabled
globally and pretty-printing is enabled.

GET-DEVICE-INFORMATION Function
Returns information about a device. The keywords you specify with the function
determine the type of information the function returns.
This function is similar to the VMS system service $GETDVI. For more infor
mation on the $GETDVI system service, see the VMS System Services Reference
Manual and the VMS I/O U ser’
s Reference Manual: Part I.

Format
GET-DEVICE-INFORMATION device &REST keyword
Arguments
device
The string that names the device about which information is to be returned.
keyword
Optional keywords that specify types of information about the specified device.
Do not specify values with the keywords.
Table 6 lists the keywords that you can specify and the values they return.
Table 6:

GET-DEVICE-INFORMATION K eyw ords

Keyword

Return Value

:ACP-PID

An integer that specifies the ACP process ID.

:ACP-TYPE

An integer that specifies the ACP type code.

:BUFFER-SIZE

An integer that specifies the buffer size.

:CLUSTER-SIZE

An integer that specifies the volume cluster size.

:CYLINDERS

An integer that specifies the number of cylinders on the
device.

:DEVICE-CHARACTERISTICS

A vector of 32 bits that specifies the device characteristics.
See the VMS I/O User’s Reference Manual: Part I for
information about device characteristics.

:DEVICE-CLASS

An integer that specifies the device class.

:DEVICE-DEPENDENT-0

A bit vector that specifies device-dependent information.

:DEVICE-DEPENDENT-1

A bit vector that specifies device-dependent information.

(continued on next page)

GET-DEVICE-INFORMATION Function

Table 6 (Cont.):

GET-DEVICE-INFORMATION Keyw ords

Keyword

R etu rn Value

:DEVICE-NAME

A string that specifies the device name.

:DEVICE-TYPE

An integer that specifies the device type.

:ERROR-COUNT

An integer that specifies the number of errors that have
occurred on the device.

:FREE—BLOCKS

An integer that specifies the number of free blocks on the
device; otherwise, NIL.

:LOGICAL-VOLUME-NAME

A string that specifies the logical name associated with
the volume on the device. This keyword is valid only for
disks.

:MAX-BLOCKS

An integer that specifies the maximum number o f logical
blocks that can exist on the device.

:MAX-FILES

An integer that specifies the maximum number of files
that can exist on the device.

:MOUNT-COUNT

An integer that specifies the number of times the device
has been mounted.

:NEXT-DEVICE-NAME

A string that specifies the name of the next volume in the
volume set.

:OPERATION-COUNT

An integer that specifies the number of operations that
have been performed on the device.

:OWNER-UIC

An integer that specifies the UIC of the owner.

:PID

An integer that specifies the process ID of the owner.

:RECORD-SIZE

An integer that specifies the blocked record size.

:REFERENCE-COUNT

An integer that specifies the number of channels assigned
to the device.

:ROOT-DEVICE-NAME

A string that specifies the name of the root volume in the
volume set.

:SECTORS

An integer that specifies the number of sectors per track.

:SERIAL-NUMBER

An integer that specifies the serial number.

:TRACKS

An integer that specifies the number of tracks per cylin
der.

:TRANSACTION-COUNT

An integer that specifies the number of files open on the
device.

:UNIT

An integer that specifies the unit number.

:VOLUME-COUNT

An integer that specifies the number of volumes in the
volume set.

:VOLUME-NAME

A string that specifies the name of the volume on the
device.

:VOLUME-NUMBER

An integer that specifies the number of the volume on the
device.

:VOLUME-PROTECTION

A vector of 32 bits that specifies the volume protection
mask.

GET-DEVICE-INFORMATION Function

Return Value
The keywords and their values are returned as a property list in the following
format:
(:keyw ord-1 value-1 :k ey w ord -2 valu e-2 . . . )

The function preserves the order of the keyword-value pairs in the argument list.
If you do not specify keywords, the function returns a list of all the keyword-value
pairs. If the device does not exist, the function returns n i l .

Example
Lisp>

(get-device-information "dbal"
:device-name
:error-count
:mount-count)
(:DEVICE-NAME "_DBA1:" :ERROR-COUNT 0 :MOUNT-COUNT 1)

Returns the device name, the error count, and the mount count for the device
DBA1.

GET-FILE-INFORMATION Function
Returns information about a file. The keywords that you specify with the function
determine the type of information that the function returns. The keywords
correspond to VMS RMS file access block (FAB) and extended attribute block
(XAB) fields. See the VMS Record Management Services Manual for information
on FAB and XAB fields.

Format
GET-FILE-INFORMATION pathname &REST {keyword)*
Arguments
pathname
A pathname, namestring, symbol, or stream that represents the name of the file
about which information is to be returned.
keyword
Optional keywords that return specific types of information about the specified
file. Do not specify values with the keywords.
Table 7 lists the keywords that you can specify and the values they return.

GET-FILE-INFORMATION Function

Table 7:

GET-FILE-INFORMATION Keywords

Keyword

R etu rn Value

: AL L O CATIO N -QU ANT IT Y

An integer that specifies the number of blocks allocated
for the file.

: BACKUP-DATE

The last universal date and time the file was backed up.
If the file has not been backed up, the function returns
NIL.

: B L OC K -SIZE

An integer that specifies the block size.

: CRE ATIO N -DATE

The universal date and time the file was created.

: DEF A U LT -EX TEN SIO N

An integer that specifies the number of blocks added to
the file ’
s size when the file was extended.

: EN D-OF-FILE-BLOCK

An integer that specifies the block in which the file ends.

: E X P IR A T I O N - D A T E

The universal date and time the file expires. If an
expiration date is not recorded, the function returns NIL.

: FIR ST-FREE-BY TE

An integer that specifies the offset of the first byte in the
file ’
s end-of-file block.

: FIX E D -C O N T R O L -SIZE

An integer that specifies the fixed control area size.

: GROUP

An integer that specifies the owner group number.

: LONGES T-RECO RD -LENGTH

An integer that specifies the length of the longest record
in the file.

: M A X - R E C O R D - S IZ E

An integer that specifies the maximum size allowed for a
record.

: MEMBER

An integer that specifies the owner member number.

: O R G A N IZ A TIO N

An integer that specifies the organization.

: P R O T E C T IO N

A vector of 16 bits that specifies the protection code.

: R E C O R D - A T T R IB U T E S

An integer that specifies the record attributes.

: RECORD-FORMAT

An integer that specifies the record format.

: R E V ISIO N

An in teger that specifies the rev ision number.

: REV ISIO N -DATE

The last universal date and time the file was revised.

: U IC

An integer that specifies the owner UIC.

:V ER SIO N -LIM IT

An integer that specifies the maximum version number
the file can have.

Return Value
The keywords and their values are returned as a property list in the following
format:
(■.keyword-1 value-1 :keyword-2 value-2 . . . )

GET-FILE-INFORMATION Function

Examples
1.

Lisp> (get-file-information "important.dat"
:allocation-quantity
:backup-date)
(:ALLOCATION-QUANTITY 252 :BACKUP-DATE 2654202351)

Returns the allocation quantity and backup date for the file IMPORTANT.DAT.
2.

L isp >

(d efu n

sh o w - file - size

( file)

(let ((size-list
(get-file-information file
:allocation-quantity
:end-of-file-block)))
(format t
"~A ~%~
~3T Blocks allocated: ~D~%~
~3T Blocks used:
~d ~%"
( n a m estrin g

(truenam e

file ) )

(getf size-list :allocation-quantity)
(getf

siz e - list

: e n d - o f - f i l e - b l o c k ) ) ))

SH O W -FIL E-SIZE

Lisp> (show-file-size "myfile.txt")
DBA1:[SMITH]MYFILE.TXT;4
Blocks allocated: 240
Blocks used:
239
N IL

• The call to the d e f u n macro defines a function named s h o w - f i l e - s i z e ,
which displays the amount of space that is allocated for a specified file
and the amount of space the file uses.
• The call to s h o w - f i l e - s i z e displays the amount of space that is allocated
for the file MYFILE.TXT and the amount of space the file uses.

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 i n t e r n a l - t i m e - u n i t s - p e r s e c o n d constant. This value is cumulative. It includes the elapsed time used for
all the garbage collections that have occurred. For a description of the i n t e r n a l t i m e - u n i t s - p e r - s e c o n d constant, see Common LISP: The Language.
When a suspended system is resumed, the elapsed time is set to 0.
For more information on the garbage collector, see VAX LISP Implementation and
Extensions to Common LISP.

Format
GET-GC-REAL-TIME

GET-GC-REAL-TIME Function

Argument
None.

Return Value
The real time that has been used by the garbage collector.

Examples
1.

Lisp> (qet-gc-real-time)
3485700000
Lisp> (gc)
; Starting full GC ...
; ... Full GC finished
T
Lisp> (get-gc-real-time)
401210000

• The first call to the g e t -g c -r e a l -t i m e function returns the real time used
by the garbage collector.
• The call to the gc function invokes a garbage collection.
• The second call to the g e t -g c -r e a l -t i m e function returns the updated
real time that has been used by the garbage collector.
2. Lisp> (defmacro gc-elapsed-time (form)
' (let* ((start-gc (get-gc-real-time))
(value ,form)
(end-gc (get-gc-real-time)))
(format *trace-output*
"~ %GC e l a p s e d

tim e:

~D s e c o n d s ~ % "

(truncate
(- end-gc start-gc)
internal-time-units-per-second))))
GC-ELAPSED-TIME
Lisp> (gc-elapsed-time (suspend "myfile.sus"))
; Starting full GC ...
; ... Full GC finished
GC elapsed time: 54 seconds
NIL

• The call to the d e f m a c r o macro defines a macro named g c -e l a p s e d -t i m e ,
which evaluates a form and displays the amount of elapsed time that was
used by the garbage collector during a form’
s evaluation.
• The call to the g c -e l a p s e d -t i m e function displays the amount of elapsed
time the garbage collector used when the LISP system evaluated the form
(suspend "myfile.sus").

GET-GC-RUN-TIME Function

GET-GC-RUN-TIME Function
Lets you inspect the CPU 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 i n t e r n a l -t i m e -u n i t s -p e r s e c o n d constant. This value is cumulative. It includes the CPU time used for all
the garbage collections that have occurred. For a description of the i n t e r n a l t i m e -u n i t s -p e r -s e c o n d constant, see Common LISP: The Language.
When a suspended system is resumed, the CPU time is set to 0.
For more information on the garbage collector, see VAX LISP Implementation and
Extensions to Common LISP.

Format
GET-GC-RUN-TIME
Argument
None.

Return Value
The CPU time that has been used by the garbage collector.

Examples
1.

Lisp> (get-gc-run-time)
6933
Lisp> (gc)
; Starting full GC ...
; ... Full GC finished
T
Lisp> (get-gc-run-time)
8423

• The first call to the g e t -g c -r u n -t i m e function returns the CPU time used
by the garbage collector.
• The call to the g c function invokes a garbage collection.
• The second call to the g e t -g c -r u n -t i m e function returns the updated
CPU time that has been used by the garbage collector.

GET-GC-RUN-TIME Function
2.

Lisp> (defmacro gc-cpu-time (form)
' (let* ((start-gc (get-gc-run-time))
(value ,form)
(end-gc (get-gc-run-time)))
(format *trace-output*
"~%GC CPU time: ~D seconds~%"
(truncate
(- end-gc start-gc)
internal-time-units-per-second))))
GC-CPU-TIME
Lisp> (gc-cpu-time (suspend "myfile.sus"))
; Starting full GC ...
; ... Full GC finished
GC CPU time: 10 seconds
NIL

• The call to the d e f m a c r o macro defines a macro named g c -c p u -t i m e ,
which evaluates a form and displays the amount of CPU time that was
used by the garbage collector during a form’
s evaluation.
• The call to the g c -c p u -t i m e function displays the amount of CPU time
the garbage collector used when the LISP system evaluated the form
(suspend "myfile.sus").

GET-INTERNAL-RUN-TIME Function
Returns an integer that represents the elapsed CPU time used for the current
process. The function value is measured in terms of the i n t e r n a l -t i m e -u n i t s p e r -s e c o n d constant. For a description of the i n t e r n a l -t i m e -u n i t s -p e r -s e c o n d
constant, see Common LISP: The Language.

Format
GET-INTERNAL-RUN-TIME
Argument
None.

Return Value
The elapsed CPU time used for the current process.

GET-INTERNAL-RUN-TIME Function

Example
Lisp> (defmacro my-time (form)
' ( let*

MY-TIME

(( sta rt- re a l- tim e

( g e t- in te rn a l- re a l- tim e ) )

(start-run-time (get-internal-run-time))
(value ,form)
(end-run-time (get-internal-run-time))
(end-real-time (get-internal-real-time)))
(format *trace-output*
"~&Run Time: ~,2F sec., ~
Real Time: ~,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))

Defines a macro that displays timing information about the evaluation of a
specified form.

GET-INTERRUPT-FUNCTION Function
Returns information about the interrupt function specified by its argument.

Format
GET-INTERRUPT-FUNCTION iif-id
Argument
iif-id
An interrupt function identifier previously returned by in s t a t e - interru pt function .

Return Values
Four values:
• The function definition of the interrupt function
• The argument list
• The value of :l e v e l (an integer in the range 0 through 7)
• The value of :o n c e -o n l y -p (t or n i l )
If the interrupt function represented by iif-id has been uninstated, g e t i n t e r r u p t -f u n c t i o n returns four values of n i l .

GET-INTERRUPT-FUNCTION Function

Example
Lisp> (defun time-elapsed (n)
(format t
"~0(~R~) second~:P ~ : [have-;has~:;have~] ~
elapsed since setting the timer"
n) )
TIME-ELAPSED
Lisp> (setf t-e-iif (instate-interrupt-function
#'time-elapsed
:arguments (list 5)))
8388671
Lisp> (get-interrupt-function t-e-iif)
#<Interpreted Function (LAMBDA (N) (BLOCK TIME-ELAPSED (FORMAT T
(~R~) second~:P ~ : [have~;has~:;have~] ~
elapsed since setting the timer" N))) 4742880> ;
(5) ;
2 ;
NIL

• The function tim e - ela psed , which prints out the number of seconds since a
timer was set, is defined. It takes a single argument.
•

t i m e -e l a p s e d is instated as an interrupt function.

The :a r g u m e n t s keyword
specifies that t i m e -e l a p s e d is passed one argument, the number 5. The
iif-id returned by i n s t a t e - i n t e r r u p t -f o n c t i o n is retained as the value of
T-E-IIF.

• The call to get-interrupt-function returns four values. The first value is
the function definition of time-elapsed. The second value is a list of the
arguments specified with instate-interrupt-function. The third value is
the interrupt level (2 , the default for instate-interrupt-function). The
fourth value is nil, indicating that :ONCE-only-p was not specified with
instate-interrupt-function.

GET-KEYBOARD-FUNCTION Function
Returns information about the function that is bound to a control character.

Format
GET-KEYBOARD-FUNCTION control-character
Argument
control-character
The control character to which a function is bound.

GET-KEYBOARD-FUNCTION Function

Return Values
Three values:
• The function that is bound to the control character
• The function’
s argument list
• The function’
s interrupt level
If no function is bound to the specified control character, the g e t -k e y b o a r d f u n c t i o n returns n i l for all three values.

Examples
1.

Lisp> (bind-keyboard-function #\AB #'break)
T
Lisp> (get-keyboard-function #\AB)
#<Compiled Function BREAK #x261510> ;
NIL ;
1

• The call to the b i n d -k e y b o a r d -f u n c t i o n function binds Ctrl/B to the b r e a k
function.
• The call to the g e t -k e y b o a r d -f u n c t i o n function returns the function to
which Ctrl/B is bound; the function’
s argument list (which is n i l ); and the
function’
s interrupt level (which is 1).
2. Lisp> (get-keyboard-function #\AS)
NIL ;
NIL ;
NIL

All three values returned are n i l ,because Ctrl/S is not bound to any function.

GET-PROCESS-INFORMATION Function
Returns information about a process. If the process is nonexistent, this function
returns n i l . The keywords you specify with the function determine the type of
information the function returns.
This function is similar to the VMS system service $GETJPI. For more infor
mation on the $GETJPI system service, see the VMS System Services Reference
Manual.

Format
GET-PROCESS-INFORMATION process &REST {keyword}*

GET-PROCESS-INFORMATION Function

Arguments
process
The name or the identification of the process (PID) about which information is to
be returned. You can specify a string, an integer, or n il . If you specify a string,
the argument is the process name; if you specify an integer, the argument is the
PID; if you specify nil, the information the function returns corresponds to the
current process.
keyword
Optional keywords that return specific types of information about the process. Do
not specify values with the keywords.
Table 8 lists the keywords that you can specify and the values they return.
Table 8:

GET-PROCESS-INFORMATION Keyw ords

Keyword

R etu rn Value

:ACCOUNT

A strin g that sp ecifies th e account.

:ACTIVE-PAGE-TABLE-COUNT

A n in teg er th at specifies th e active p a g e table count.

:AST-ACTIVE

A vector o f fou r b its th at specifies the n u m ber o f
a ccess m od es that h ave active a syn ch ron ou s sy stem
traps (ASTs) for th e process.

:AST-COUNT

An in teg er th at specifies th e rem a in in g A S T quota.

:AST-ENABLED

A v ector o f fou r b its th at specifies th e n u m ber o f
a ccess m od es th at h ave en ab led A ST s for th e process.

:AST-QUOTA

An in teg er th at specifies th e A S T quota.

:AUTHORIZED-PRIVILEGES

A v ector o f 64 b its th at specifies th e p riv ileges the
p rocess is au th orized to enable.

:BASE-PRIORITY

An in teg er th at specifies th e b a se priority.

:BATCH

E ith er T or NIL. T he fu nction retu rn s T if the p rocess
is a batch job; otherw ise, retu rn s NIL.

:BIO-BYTE-COUNT

An in teg er th at specifies the rem a in in g bu ffered I/O
byte cou n t quota.

:BIO-BYTE-QUOTA

An in teg er th at specifies the b u ffered I/O byte coun t
quota.

:BIO-COUNT

A n in te g er th at specifies the rem a in in g bu ffered I/O
operation quota.

:BIO-OPERATIONS

A n in teg er th at specifies the n u m b er o f bu ffered I/O
opera tion s th e p rocess h a s perform ed.

:BIO-QUOTA

A n in teg er th at specifies th e bu ffered I/O operation
quota.

:CLI-TABLENAME

A strin g th at specifies th e file n am e o f th e current
com m an d la n gu a ge in terp reter table.

:CPU-LIMIT

An in teg er th at sp ecifies th e C P U tim e lim it o f the
p rocess in 10-m illisecond units.

(continued on next page)

GET-PROCESS-INFORMATION Function

Table 8 (Cont.):

GET-PROCESS-INFORMATION Keywords

Keyword

R eturn Value

:CPU-TIME

A n in teg er th at specifies th e accu m u la ted C P U tim e
o f the p rocess in 10-m illisecond units.

:CURRENT-PRIORITY

A n in teg er that specifies th e cu rren t priority.

:CURRENT-PRIVILEGES

A v ector o f 64 b its th at specifies th e cu rren t privi
leges.

:DEFAULT-PAGE-FAULT-CLUSTER

An in teg er th at specifies th e defau lt p a g e fault
clu ster size.

:DEFAULT-PRIVILEGES

A v ector o f 64 b its th at specifies th e defau lt privi
leges.

:DIO-COUNT

An in teg er th a t sp ecifies th e rem a in in g d irect I/O
operation quota.

:DIO-OPERATIONS

An in teger th at specifies th e n u m b er o f d irect I/O
operation s th e p rocess h as perform ed.

:DIO-QUOTA

A n in teg er th at specifies th e direct I/O operation
quota.

:ENQUEUE-COUNT

A n in teg er th at specifies th e n u m ber o f lock m an a ger
enqueues.

:ENQUEUE-QUOTA

A n in teger th at sp ecifies th e lock m an a ger en qu eu e
quota.

:EVENT-FLAG-WAIT-MASK

A v ector o f 32 b its th at specifies the even t flag w ait
mask.

:FIRST-FREE-PO-PAGE

An in teger th a t specifies th e first free p a ge at the
en d o f the progra m region.

:FIRST-FREE-P1-PAGE

An in te g er th at specifies th e first free p a g e at the
en d o f th e con trol region.

:GLOBAL-PAGES

A n in teg er th at specifies th e n u m b er o f glob a l p a g e s
in the w ork in g set.

:GROUP

A n in te g er th at specifies th e grou p field o f th e UIC.

:IMAGE-NAME

A strin g th at specifies th e cu rren t im a g e file name.

:IMAGE-PRIVILEGES

A v ector o f 64 b its th at specifies th e p riv ileges w ith
w hich th e cu rren t im a g e o f th e p ro cess w as installed.

:JOB-SUBPROCESS-COUNT

An in te g er th at specifies th e n u m b er o f su bprocesses.

:LOCAL-EVENT-FLAGS

A v ector o f 32 b its th at specifies th e loca l even t flags
th e pro cess h as in effect.

:LOGIN-TIME

A n in teg er in in tern al tim e th a t specifies th e tim e
th e process w a s created.

:MEMBER

An in teg er th a t specifies th e m em b er field o f the
UIC.

:MOUNTED-VOLUMES

A n in teg er th a t specifies th e n u m ber o f m oun ted
volum es.
( c o n t in u e d o n n e x t p a g e )

GET-PROCESS-INFORMATION Function

Table 8 (Cont.):

GET-PROCESS-INFORMATION Keywords

Keyword

R etu rn Value

: OPEN-FILE-COUNT

An in teger th at specifies th e rem a in in g open file
quota.

: OPEN-FILE-QUOTA

An in teger th at specifies th e op en file quota.

: OWNER-PID

An in teger th at specifies th e p ro cess ID o f th e owner.

: PAGE-FAULTS

An in teger th at specifies th e n u m ber o f p a g e faults.

: PAGE-FILE-COUNT

An in teger th at specifies the n u m b er o f p a g in g file
p a g e s rem a in in g to th e process.

: PAGE-FILE-QUOTA

An in teg er th at specifies th e p a g in g file quota.

:PAGES-AVAILABLE

An in teger th at specifies th e n u m b er o f virtual p a ges
available for expansion.

:PID

A n in teg er th at specifies the p ro cess ID.

:PID-OF-PARENT

An in teg er th at specifies th e P ID o f th e paren t
process. T h is in teger differs from : OWNER-PID in
that : PID-OF-PARENT refers to th e top-level process,
w hile : OWNER-PID refers to the p ro cess im m edia tely
above th e cu rren t p ro cess or subprocess.

: PROCESS-CREATION-FLAGS

A 32-bit bit-vector th at sp ecifies th e flags u sed to
create th e process.

: PROCESS-INDEX

An in teger th at specifies the in d ex n u m b er o f the
p rocess at a giv en instant. (Process in d ex n u m bers
are re a ssig n e d to different p ro ce sse s over time.)

: PROCESS-NAME

A strin g that specifies the n am e o f th e process.

: SITE-SPECIFIC

A lon gw ord th at specifies the con ten ts o f th e sitespecific longw ord.

: STATE

An in teg er th at specifies th e sta te o f th e process.

: STATUS

A vector o f 32 bits th at specifies th e sta tu s flags.

: SUBPROCESS-COUNT

An in teg er th at specifies th e n u m b er o f su b p rocesses
ow n ed b y th e process.

: SUBPROCESS-QUOTA

A n in teg er th at specifies th e su b p ro cess quota.

: TERMINAL

A strin g th at specifies th e n am e o f th e term in al w ith
w hich th e p rocess is interacting.

: TERMINATION-MAILBOX

An in teg er th at specifies th e term in a tion m ailbox
unit number.

: TIMER-QUEUE-COUNT

An in teg er th a t specifies th e rem a in in g tim er qu eu e
entry quota.

: TIMER-QUEUE-QUOTA

An in teg er that specifies th e tim er qu eu e entry
quota.

:UAF-FLAGS

A 12-bit bit-vector th at specifies th e U A F flags o f the
u ser w ho ow n s the process.

:UIC

An in teger th at specifies th e UIC.

: USERNAME

A strin g th a t specifies th e u ser name.

(continued on next page)

GET-PROCESS-INFORMATION Function

Table 8 (Com.):

GET-PROCESS-INFORMATION Keywords

Keyword

R eturn Value

:VIRTUAL-ADDRESS-PEAK

An in teg er th at specifies th e pea k virtual a dd ress
spa ce size.

:WORKING-SET-AUTHORIZEDEXTENT

An in teg er th at specifies th e m axim u m au th orized
w ork in g se t extent.

:WORKING-SET-AUTHORIZEDQUOTA

An in teger th at specifies th e a u th orized w ork in g set
quota.

:WORKING-SET-COUNT

A n in teg er th at specifies th e n u m ber o f p rocess p a ges
in th e w ork in g set.

:WORKING-SET-DEFAULT

An in teg er th at specifies th e defau lt w ork in g se t size,

:WORKING-SET-EXTENT

An in teger th at specifies th e cu rren t w ork in g se t siz e
extent.

:WORKING-SET-PEAK

An in teger th at specifies th e p ea k w ork in g se t size,

:WORKING-SET-QUOTA

An in teger th at specifies th e cu rren t w ork in g set
quota.

:WORKING-SET-SIZE

An in teger th at specifies th e cu rren t w ork in g set
size.

Return Value
The keywords and their values are returned as a list in the following format:
(:keyword-1 value-1 \keyword-2 value-2 . . . )

The function preserves the order of the keyword-value pairs in the argument list.
If you do not specify keywords, the function returns a list of all the keyword-value
pairs. If the specified process does not exist, the function returns n i l .

Examples
1.

Lisp> (get-process-information "smith"
:batch
:cpu-time
:base-priority
:global-pages)
(:BATCH NIL :CPU-TIME 45884 :BASE-PRIORITY 4 :GLOBAL-PAGES 68)

Returns the value of the batch setting, the CPU time, the base priority, and
the number of global pages used for the process SMITH.
2. Lisp> (defun parent nil
(let ((pid
(second (get-process-information
nil
:owner-pid))) )
(if (zerop pid) nil (attach pid))))
PARENT

GET-PROCESS-INFORMATION Function
Defines a function that just returns n i l if the LISP system is running in the
main process, and attaches your process to the parent process if the system is
running in a subprocess.

GET-TERMINAL-MODES Function
Returns information about the terminal characteristics of the device associated
with the *t e r m i n a l -io* variable when you invoke the LISP system. If the
specified stream is not connected to a terminal, the LISP system signals an error.
The keywords you specify with the function determine the type of information
that the function returns.
This function is similar to the DCL SHOW TERMINAL command. For more
information on the SHOW TERMINAL command, see the VMS DCL Dictionary.

Format
GET-TERMINAL-MODES &REST keyword
Argument
keyword
Optional keywords that return the terminal characteristics of the stream that is
bound to the *t e r m i n a l -i o * variable. Do not specify values with the keywords.
Table 9 lists the keywords that you can specify and the values they return.
Table 9:

GET-TERMINAL-MODES Keyw ords

Keyword

Return Value

:BROADCAST

E ith er T or NIL. T he fu n ction retu rn s T i f y ou r term in a l can
receiv e b roa d ca st m essa ges, su ch as M AIL n otification s an d REPLY
m essa ges; otherw ise, retu rn s NIL.

:ECHO

E ith er T or NIL. T he fu n ction retu rn s T i f the term in al displays
th e in pu t character th at it receives; otherw ise, retu rn s NIL. I f the
function retu rn s NIL, th e term in a l d ispla y s on ly data ou tp u t from
th e sy stem or a u ser app lica tion program .

:ESCAPE

E ith er T or NIL. T he fu n ction retu rn s T i f A N SI sta n d a rd esca p e
sequ en ces tra n sm itted from th e term in a l are h an d led as a sin gle
m ultich aracter term inator; otherw ise, retu rn s NIL. T he term in al
driver ch eck s th e esca p e seq u en ces for syn tax before p a ssin g th em
to the program . F or m ore in form ation on esca p e sequ en ces, se e the

VM S I/ O U ser’
s Reference Manual: Part I.

(continued on next page)

GET-TERMINAL-MODES Function

Table 9 (Cont.):

GET-TERMINAL-MODES K eyw ords

Keyword

R etu rn Value

:HALF-DUPLEX

E ith er T or NIL. T he fu nction retu rn s T i f th e term in a l’
s opera tin g
m ode is half-duplex, an d the fu n ction retu rn s NIL i f th e opera tin g
m ode is full-duplex. F or a d escrip tion o f term in al op era tin g m odes,
see th e VM S I/ O U ser’
s Reference Manual: Part I.

:PASS-ALL

E ith er T or NIL. T he function retu rn s T if th e sy stem d oes not
expan d tab ch aracters to blanks, fill carria ge retu rn or lin efeed
characters, recogn ize control characters, and receive b roa d ca st
m essages. The fu nction retu rn s NIL i f th e sy stem p a sse s all data to
an application progra m a s bin ary data.

:PASS-THROUGH

E ith er T or NIL. T h is m ode is the sa m e as the : PASS-ALL mode,
ex cep t th at “
T T SY N C ”protocol (Ctrl/S and Ctrl/Q) is still used.

:TYPE-AHEAD

E ith er T or NIL. T he function retu rn s T i f th e term in al accepts
in pu t th at is typed w h en th ere is no ou tsta n d in g read, and the
function retu rn s NIL i f the term in al driver is d ed ica ted and accepts
in pu t only w h en a p rogra m or th e sy stem issu e s a read.

:WRAP

E ith er T or NIL. T he function retu rn s T i f th e term in al gen er
ates a carria ge retu rn and a lin e feed w hen the en d o f a lin e is
reached. Otherw ise, the fu nction retu rn s NIL. The en d o f th e lin e is
d eterm in ed b y the term inal-w idth setting.

NOTE
:p a s s -a l l has been kept for the sake of compatibility with Version 1 of
VAX LISP, but it is not recommended that you use :p a s s -a l l .

Return Value
The keywords and their values are returned as a list in the following format:
( \keyword-1 value-1 \keyword-2 value-2 . . . )

The function preserves the order of the keyword-value pairs in the argument list.
If you do not specify keywords, the function returns a list of the keyword-value
pairs. The list is returned in a format such that the list can be specified as an
argument in a call to the s e t -t e r m i n a l -m o d e s function.

Example
Lisp> (get-terminal-modes)
(:BROADCAST T :ECHO T :ESCAPE NIL :HALF-DUPLEX NIL :PASS-ALL NIL
:TYPE-AHEAD T :WRAP T :PASS-THROUGH NIL)

Returns a list of all the keyword-value pairs.

GET-VMS-MESSAGE Function

GET-VMS-MESSAGE Function
Returns the system message associated with a specified VMS status.

Format
GET-VMS-MESSAGE status &OPTIONAL flags
Arguments
status
A fixnum that specifies the VMS status code of the message that is to be returned.
See the 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:
B it

Info rm atio n

Text

M essa ge ID

S everity

F acility

Return Value
Returns the message that corresponds to the specified status code as a string.
The function returns n il if you specify a status code that does not exist.

Examples
1.

Lisp> (get-vms-message 32)
"%SYSTEM-W-NOPRIV, no privilege for attempted operation"

Returns the VMS message text for message 32 with all flags set.
2.

Lisp> (get-vms-message 32 #*1001)
"%SYSTEM, no privilege for attempted operation"

Returns the VMS message text for message 32 with only the facility and text
flags set.

HASH-TABLE-REHASH-SIZE Function

HASH-TABLE-REHASH-SIZE Function
Returns the rehash size of a hash table. The rehash size indicates how much a
hash table is to increase when it is full. 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-SIZE hash-table
Argument
hash-table
The name of the hash table whose rehash size is 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 #'equal
:size 200
:rehash-size 1.5
:rehash-threshold .95) )
#<Hash Table #x503BA8>
Lisp> (hash-table-rehash-size table-1)
1.5

• The first call to the setf macro sets the value of the *pr in t -array* variable
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 to the hash- table- rehash- s iz e function returns the rehash size of
the hash table, table- i .

HASH-TABLE-REHASH-THRESHOLD Function

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 m a k e -h a s h -t a b l e 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 size or a floating
point number greater than 0 and less than 1.

Example
Lisp> (setf *print-array* nil)
NIL
Lisp> (setf table-1 (make-hash-table :test #'equal
:size 200
:rehash-size 1.5
:reh a sh - th resh o ld

•95) )

#<Hash Table #x503BA8>
Lisp> (hash-table-rehash-threshold table-1)
0.95

• The first call to the setf macro sets the value of the *pr in t -array* variable
to NIL.
• The second call to the s e t f macro sets t a b l e - i to the hash table created by
the call to the m a k e -h a s h -t a b l e function.
• The call to the h a s h -t a b l e -r e h a s h -t h r e s h o l d function returns the rehash
threshold of the hash table, t a b l e - l.

HASH-TABLE-SIZE Function

HASH-TABLE-SIZE Function
Returns the current size of a hash table. You specify that value when you create
a hash table with the m a k e -h a s h -t a b l e 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 is to be returned.

Return Value
An integer that indicates the initial size of the hash table.

• The first call to the s e t f macro sets the value of the *p r i n t -a r r a y * variable
to NIL.
• The second call to the s e t f macro sets t a b l e - i to the hash table created by
the call to the m a k e -h a s h -t a b l e function.
• The call to the h a s h -t a b l e -s i z e function returns the initial size of the hash
table, t a b l e -i .

HASH-TABLE-TEST Function

HASH-TABLE-TEST Function
Returns a symbol that indicates how a hash table’
s keys are compared. The value
is specified 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-TEST hash-table
Argument
hash-table
The hash table whose test value is to be returned.

Return Value
A symbol: (eq, eql , or equal), eql is the default when creating a hash table.

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 #x503BA8>
Lisp> (hash-table-test table-1)
EQUAL

• The first call to the setf macro sets the value of the *pr in t -array* variable
to NIL.
• The second call to the setf macro sets table- i to the hash table created by
the call to the make- hash- table function.
• The call to the hash- table- test function returns the test for the hash table,
TABLE-1.

IMMEDIATE-OUTPUT-P Function

IMMEDIATE-OUTPUT-P Function
Predicate indicates whether an output stream does not buffer its output. The VAX
LISP I/O system uses this function to improve output performance by buffering
output when the stream itself does not perform buffering.

Format
IMMEDIATE-OUTPUT-P &OPTIONAL output-stream
Argument
output-stream
An output stream. The default value is *s t a n d a r d -o u t p u t *. If you supply a
value of t ,the value of *t e r m i n a l - i o * is used.

Return Value
t , if output-stream does not buffer output; otherwise, n il .

INSPECT Function
Invokes the VAX LISP Inspector, a utility for examining and modifying objects in
your current LISP environment. The Inspector displays the components of the
LISP object you specify. You can inspect these components in turn and modify
their values.
NOTE

The VAX LISP Inspector is available only when LISP is running with
the DECwindows-based development environment.
You can run the Inspector either synchronously or asynchronously (the default).
In synchronous mode, you can specify which value the Inspector is to return. In
asynchronous mode, the Inspector immediately returns the object on which it was
invoked to the program (or other VAX LISP utility) from which it was invoked.
See Chapter 9 of the VAX LISP/VMS Program Development Guide for more
information on using the Inspector.

Format
INSPECT &OPTIONAL object &KEY PARALLEL

INSPECT Function

Arguments
object
Any LISP object.
PARALLEL

Specifies whether the Inspector runs asynchronously (: p a r a l l e l t ) or syn
chronously (: p a r a l l e l n i l ) with other programs in your LISP environment. The
default value is t .

Return Value
The returned value depends on the mode of operation. If the Inspector is running
asynchronously, it immediately returns the object on which it was invoked. If the
Inspector is running synchronously, there are two ways to return a value:
• You may specify an object whose value the Inspector will return by selecting
that object and choosing the Return item from the Operations menu.
• Otherwise, the Inspector returns the object on which it was invoked when you
exit the Inspector.

INSTATE-INTERRUPT-FUNCTION Function
Takes as its first argument a function that will later be invoked asynchronously
and returns an identification (iif-id) for this instance of the function. The iif-id is
intended to be passed to a routine that can cause an AST. When the AST occurs,
it invokes the interrupt function identified by the iif-id.
The :a r g u m e n t s keyword allows you to supply a list of zero or more arguments
that are passed to the interrupt function when it executes. This allows a single
function to take different actions, depending on the particular AST that invokes
it.
The :l e v e l keyword lets you specify the interrupt level for the interrupt function
as an integer in the range 0 through 7. See Chapter 7 in the VAX LISP/VMS
System Access Guide for more information about interrupt levels.
The :o n c e -o n l y -p keyword allows you to specify that this instance of the function
will be invoked only once and then discarded. Specifying :o n c e -o n l y -p t is
equivalent to using u n i n s t a t e - i n t e r r u p t -f u n c t i o n on the function after its
first invocation. However, :o n c e -o n l y -p does not disable further occurrences
of the AST after its first occurrence. If :o n c e -o n l y -p t is specified and the
corresponding AST occurs more than once, the second and subsequent ASTs are
ignored. (See u n i n s t a t e -i n t e r r u p t -f u n c t i o n for more details.)
For more information about interrupt functions, see Chapter 6 in the VAX
LISP/VMS System Access Guide.

INSTATE-INTERRUPT-FUNCTION Function

Format
INSTATE-INTERRUPT-FUNCTION function
&KEY ARGUMENTS :LEVEL :ONCE-ONLY-P
Arguments
fu n ction

A function to be invoked asynchronously at a later time.
ARGUMENTS

A list of zero or more arguments to be passed to the interrupt function when it is
invoked.
:LEVEL

An integer in the range 0 through 7, specifying the interrupt level for the
interrupt function. The default interrupt level is 2.
:ONCE-ONLY-P
t or n il (the default), specifying whether or not this instance of the function is to

be uninstated when it has been invoked once.

Return Value
An integer that identifies this instance of the interrupt function. This integer
becomes the iif-id argument to functions that require an iif-id and the astprm
argument to external routines that can cause an AST.

INSTATE-INTERRUPT-FUNCTION Function

Examples
i.

Lisp> (define-external-routine (sys$setimr
:check-status-return t)
(efn .'mechanism :value)
(daytim :vax-type :quadword)
(astadr imechanisra rvalue)
(astprm rmechanism rvalue))
SYS$SETIMR

Lisp> (define-external-routine (sys$bintim
rcheck-status-return t)
(timbuf rvax-type rtext rlisp-type string)
(timadr rvax-type rquadword raccess rin-out))
SYS$BINTIM
Lisp> (defun set-timer (delta-time)
(let ((iif-id (instate-interrupt-function
#'timer-interrupt-handler
ronce-only-p t)))
(call-out sys$setimr nil delta-time
common-ast-address iif-id))
t)
SET-TIMER
Lisp> (defun timer-interrupt-handler ()
(print "The timer has expired"))
TIMER-INTERRUPT-HANDLER
Lisp> (setq delta 0) ; delta must be bound before call-out

0
Lisp> (call-out sys$bintim "0 ::5" delta)

1
Lisp> (set-timer delta)
T
Lisp> ( f iv e s e c o n d s p a s s )

"The timer has expired"

• The external routine s y s $ s e t i m r is defined. s y s $ s e t i m r is a system
service that sets a timer and causes an AST when the timer expires. The
a s t a d r and a s t p r m arguments are both passed with :m e c h a n is m : v a l u e .
• The external routine s y s $b i n t i m is defined. s y s $b i n t i m is a system
service that converts a time specified as a string to a binary format
acceptable to s y s $ s e t i m r .
• The function s e t - t i m e r is defined, s e t - t i m e r ’
s argument is the binaryformatted time before a timer should expire, s e t - t i m e r calls i n s t a t e i n t e r r u p t - f u n c t i o n to instate t i m e r - i n t e r r u p t - h a n d l e r as an interrupt
function. The t value for :o n c e - o n l y - p requests that the interrupt
function be uninstated after it executes once, s e t - t i m e r then calls out to
s y s $ s e t i m r , passing the binary time as the second argument. The third
argument is (and must be) the co m m o n - a s t - a d d r e s s parameter; the fourth
argument is the iif-id returned by i n s t a t e - i n t e r r u p t - f u n c t i o n .
• The function t i m e r - i n t e r r u p t - h a n d l e r is defined. It simply prints a
message on the terminal.
• After the binary format for 5 seconds is stored in d e l t a , the call to
s e t - t i m e r sets a timer to expire in 5 seconds, s e t - t i m e r returns.
Five seconds later, the timer expires and the interrupt function t i m e r i n t e r r u p t - h a n d l e r executes, printing the message.

INSTATE-INTERRUPT-FUNCTION Function
2.

Lisp> (defun set-timer (seconds)
(let ((delta 0)
(iif (instate-interrupt-function
#'time-elapsed
:once-only-p t
:arguments (list seconds))))
(call-out sys$bintim (time-string seconds) delta)
(call-out sys$setimr nil delta
common-ast-address iif))
t)
SET-TIMER
Lisp> (defun time-string (n)
(format nil "0 :~d:~d" (truncate n 60) (mod n 60)))
TIME-STRING
Lisp> (defun time-elapsed (n)
(format t
"~@(~R~) second~:P ~ [ h a v e - ; h a s ~ h a v e - ] elapsed since setting the timer"
n) )
T IM E - E L A P S E D

Lisp> (set-timer 5)
T
Lisp> ( f iv e s e c o n d s e la p s e ) Five seconds have elapsed since
setting the timer

This example shows the use of arguments with interrupt functions. The
external routines s y s $s e t i m r and s y s $b i n t i m have the same definitions as
shown in Example 1.
• The new definition of s e t -t i m e r accepts an integer argument that is
the number of seconds to wait (not a binary-formatted time), s e t t i m e r instates a function called t i m e -e l a p s e d as an interrupt function,
requesting that one argument (the number of seconds) be passed to
t i m e -e l a p s e d , s e t -t i m e r then calls out to s y s $b i n t i m to convert the
seconds to binary format. (An auxiliary function, t i m e -s t r i n g , converts
the integer argument to a string acceptable to s y s $b i n t i m . t i m e -s t r i n g
cannot format an argument larger than 3599 seconds properly.) Finally,
s e t -t i m e r calls out to s y s $s e t i m r , passing the binary-formatted time (the
second argument) and the iif-icL for t i m e -e l a p s e d (the fourth argument).
• The function t i m e -e l a p s e d is defined. It accepts an integer argument and
uses f o r m a t to print the number of seconds represented by that argument.
•

s e t -t i m e r is called with the argument 5. s e t -t i m e r returns. After 5
seconds elapse, t i m e -e l a p s e d executes and prints the formatted message
on the terminal, including the number of seconds.

INSTATE-INTERRUPT-FUNCTION Function
3.

Lisp> (defun print-button (button transition)
(when transition
(case button
(#.uis:pointer-button-1
(princ "Left button pressed"))
(#.uis:pointer-button-2
(princ "Middle button pressed"))
(#.uis:pointer-button-3
(princ "Right button pressed")))))
PRINT-BUTTON
Lisp> (setf button-iif
(instate-interrupt-function #'print-button))
8454171
Lisp> (uis:set-button-action display window button-iif)
T
L isp>

This example shows the use of an interrupt function with a VAX LISPsupplied function. This example works only on a VAXstation running
UIS.
• The function p r i n t - b u t t o n is defined. Depending on its arguments, it
prints one of three lines on the terminal, or it does nothing.
•

p r in t -bu tton s

is instated as an interrupt function. The iif-id returned by

in s t a t e - in t e r r u p t - f u n c t io n

is r e t a in e d a s th e v a lu e o f b u tto n - i i f .

• The function s e t - b u t t o n - a c t i o n is called with b u t t o n - i i f as the third
argument, s e t - b u t t o n - a c t i o n specifies what should happen when a
workstation pointer button is pressed or released while the pointer cursor
is in a specified window. If an iif-id is passed as the third argument,
the associated interrupt function is invoked when a button is pressed or
released, s e t - b u t t o n - a c t i o n causes an interrupt function to be passed
two arguments: the button involved, and t or n i l to indicate whether the
button was pressed or released.
• After s e t - b u t t o n - a c t i o n returns, a button is pressed, p r i n t - b u t t o n
receives the two arguments passed to it and prints the message on the
screen.

LINE-POSITION Function
Returns the number of characters that have been output on the current line, if
that number can be determined; otherwise, n i l .

Format
LINE-POSITION &OPTIONAL output-stream
Argument
output-stream

An output stream. The default value is * s t a n d a r d - o u t p u t *. If you specify t , the
value of * t e r m i n a l - i o * is used.

LINE-POSITION Function

Return Value
A fixnum or n i l .

LISTEN2 Function
Returns two values instead of the one returned by the Common LISP l i s t e n
function, enabling you to find out if end-of-file was encountered on the input
stream. You can use this function wherever you would normally use l i s t e n .

Format
LISTEN2 &OPTIONAL input-stream
Arguments
input-stream

An input stream. The default value is *s t a n d a r d - i n p u t *. If you supply a value
of T, the value of *t e r m i n a l -i o * is used.

Return Values
Two values:
•

t ,if a character is immediately available from input-stream; otherwise, n i l .

•

T, if end-of-file was encountered on input-stream; otherwise, n i l .

LOAD Function
Reads and evaluates the contents of a file into the LISP environment.
In VAX LISP, if the specified file name does not specify an explicit file type, the
l o a d function locates the source file (type .LSP) or 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 or not the file is compiled.

Format
LOAD filename
&KEY :IF-DOES-NOT-EXIST :PRINT :VERBOSE
Arguments
filenam e
The nam e o f the file to be loaded.

LOAD Function
:IF-DOES-NOT-EXIST

Specifies whether the l o a d function signals an error if the file does not exist. The
value can be t or n i l .If you specify t ,the function signals an error if the file does
not exist. If you specify n i l , the function returns n i l if the file does not exist.
The default value is T.
:PRINT

Specifies whether the value of each form that is loaded is printed to the stream
bound to the *s t a n d a r d -o u t p u t * variable. The value can be T or n i l . If you
specify T, the value of each form in the file is printed to the stream. If you specify
n i l , no action is taken. The default value is n i l . This keyword is useful for
debugging.
:VERBOSE

Specifies whether the l o a d function is to print a message in the form of a
comment to the stream bound to the *s t a n d a r d -o u t p u t * variable. The value can
be T or n i l . 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 you specify n i l ,
the function uses the value of *l o a d -v e r b o s e * variable. The default is t .

Return Value
A value other than n il if the load operation is successful.

Example
Lisp> (compile-file "factorial")
Starting compilation of file DBA1:[SMITH]FACTORIAL.LSP;1
FACTORIAL compiled.
F in ish e d
0

E rro rs,

co m p ila tio n

file

DBA1: [SM IT H ]FA CT O R IA L . L S P ; 1

0 W a rn in g s

" DBA1: [SM ITH ]FA CTO RIA L .F A S ; 1 "

Lisp> (load "factorial")
; Loading contents of file DBA1:[SMITH]FACTORIAL.FAS;1
;
FACTORIAL
; Finished loading DBA1:[SMITH]FACTORIAL.FAS;1
T

• The call to the c o m p i l e -f i l e function produces a fast-loading file named
FACTORIAL.FAS.
• The call to the l o a d function locates the fast-loading file FACTORIAL.FAS
and loads the file into the LISP environment.

LONG-SITE-NAME Function

LONG-SITE-NAME Function
Translates the logical name LISP$LONG_SITE_NAME. If the first character of
the resulting string is an at sign (@), the rest of the string is assumed to be a
file specification. The file is read and its content is returned as a string that
represents the physical location of the computer hardware on which the VAX
LISP system is running. If the first character of the translation is not an at sign,
the translation itself is returned as the long-site name.

Format
LONG-SITE-NAME
Argument
None.

Return Value
The contents of a file or the translation of the logical name LISP$LONG_SITE.
NAME is returned as a string that represents the physical location of the
computer hardware on which the VAX LISP system is running. If a long-site
name is not defined, n i l is returned.

Example
Lisp> (long-site-name)
"Smith's Computer Company
Artificial Intelligence Group
22 Plum Road
Canterbury, Ohio 47190"

MACHINE-INSTANCE Function
Translates the logical name LISP$MACHINE_INSTANCE.

Format
MACHINE-INSTANCE

MACHINE-INSTANCE Function

Argument
None.

Return Value
The translation of the logical name LISP$MACHINE_INSTANCE is returned
as a string. If the logical name is not defined and DECnet-VAX is running, the
node name is returned. If the logical name is not defined and DECnet-VAX is not
running, n i l is returned.

Example
Lisp> (machine-instance)
"MIAMI"

MACHINE-VERSION Function
Returns the content of the system identification (SID) register as a string that
represents the version of computer hardware on which the VAX LISP system is
running. The contents of the SID register are determined by the type of CPU—for
example, 780, 750, or 730. For more information about CPU types, see the VAX
Architecture Handbook.

Format
MACHINE-VERSION
Argument
None.

Return Value
The contents of the SID register are returned as a string.

Example
Lisp> (machine-version)
"SID Register: #x01383550

MAKE-ARRAY Function

MAKE-ARRAY Function
Creates and returns an array. VAX LISP has added the :a l l o c a t i o n keyword to
this Common LISP function. When the function is used with the :a l l o c a t i o n
keyword and the value : s t a t i c , the function creates a statically allocated array.
During system usage, the garbage collector moves LISP objects. You can prevent
the garbage collector from moving an object by allocating it in static space.
Arrays, vectors, and strings can be statically allocated if you use the :a l l o c a t i o n
keyword and : s t a t i c value in a call to the m a k e -a r r a y function. Once an object
is statically allocated, its virtual address does not change. Note that such objects
are never garbage collected and their space cannot be reclaimed. By default,
LISP objects are allocated in dynamic space.
NOTE

A statically allocated object maintains its memory address even if a
s u s p e n d /r e s u m e operation is performed.
Calling the m a k e -a r r a y function with the :a l l o c a t i o n : s t a t i c keyword-value
pair is useful if you are creating a large array. Preventing the garbage collector
from moving the array causes the garbage collector to go faster.
The m a k e -a r r a y function has a number of other keywords that can be used. See
Common LISP: The Language for information on the other m a k e -a r r a y keywords.
VAX LISP creates a specialized array when the array’
s element type is any of the
types in Table 10.
Table 10:

Specialized Array Element Types

CHARACTER

BIT

(UNSIGNED-BYTE 2)

(UNSIGNED-BYTE 4)

(UNSIGNED-BYTE 8)

(UNSIGNED-BYTE 12)

(UNSIGNED-BYTE 16)

(UNSIGNED-BYTE 24)

(UNSIGNED-BYTE 32)

(UNSIGNED-BYTE 64)

(SIGNED-BYTE 8)

(SIGNED-BYTE 16)

(SIGNED-BYTE 32)

DOUBLE-FLOAT

LONG-FLOAT

(SIGNED-BYTE 64)
SINGLE-FLOAT

For subtypes of these types, VAX LISP creates a specialized array of the most
specific type possible. For example:
Lisp> (type-of (make-arry 3 :element-type '(signed-byte 5)))
(SIMPLE-ARRAY (SIGNED-BYTE 8) (3))

For all other element types, VAX LISP creates a generalized array, with the ele
ment type t . For compatibility of VAX types with LISP types in calls to external
routines, see the table on data conversion in Chapter 4 of the VAX LISP/VMS
System Access Guide.

MAKE-ARRAY Function

Format
MAKE-ARRAY dimensions
&KEY :ALLOCATION other-keywords
Arguments
d im e n s io n s

A list of positive integers that are to be the dimensions of the array.
:ALLOCATION
Specifies whether the LISP object is to be statically allocated. You can specify one
of the following values with the :a l l o c a t i o n keyword:
:DYNAMIC
:STATIC

The LISP object is not to be statically allocated. This is the default.
The LISP object is to be statically allocated.

oth er-k eyw ords

See Common LISP: The Language.

Return Value
The statically allocated object.

Example
Lisp> (defparameter bit-buffer
(make-array ' (1000 1000) : element-type 'bit
:allocation :static))
BIT-BUFFER

Creates a large array of bits named b i t -b u f f e r , which is not intended to be
removed from the system. The :e l e m e n t -t y p e keyword is one of the other
keywords (described in Common LISP: The Language) that this function accepts.

MAKE-CALL-BACK-ROUTINE Function
Returns an alien structure of type c a l l -b a c k -r o u t i n e , which can be passed to an
external routine during callout. Chapter 4 in the VAX LISP /VMS System Access
Guide contains more information on the callback facility.

Format
MAKE-CALL-BACK-ROUTINE function
&KEY ARGUMENTS argument-specifier
:RESULT result-specifier

MAKE-CALL-BACK-ROUTINE Function

Arguments
fu n ction

Specifies the LISP function that will be called by an external routine. This
argument may be a function object or a symbol that names a function. Symbols
are useful if the named function is later redefined, or if you have not defined the
function before the call to m a k e -c a l l -b a c k -r o u t i n e .
ARGUMENTS a rgu m en t-sp ecifier

Specifies the arguments to the callback routine. The argument-specifier can be
one of the following:
•

n i l indicates that the callback routine takes no arguments.

default.

•

This is the

:ap indicates that the actual VAX argument list is passed to the callback
routine as the only parameter. All arguments in the list must be accessed by
the callback routine using alien field references. When the callback routine is
invoked, it is passed a single argument that is an alien structure representing
the VAX call frame argument list.

• A list of argument descriptions having either the format:
(argument-name)

or
( argument-name keyword-1 value-1

...)

The argument-name must be a symbol. You may use the following keywordvalue pairs:
:ACCESS value

Specifies the type of access to use when passing an ar
gument. The value can be either : IN or : IN-OUT. Use
:IN-OUT when the callback routine returns multiple
values. The default value is : IN.

:MECHANISM value

Specifies the argument-passing mechanism used in passing
data to and from the callback routine. The value can be
:VALUE, :REFERENCE, or tDESCRIPTOR.
The default argument-passing mechanism for arguments
to a callback routine is : DESCRIPTOR when the :VAXTYPE is : TEXT. The default mechanism for all other LISP
data types is r e f e r e n c e .
The default argument-passing mechanism for values re
turned from a callback routine is :VALUE for all scalar
VAX data types except : H-FLOATING. The default mecha
nism for VAX type : H-FLOATING and all nonscalar types
is : REFERENCE.

:LISP-TYPE type

Specifies the LISP type of arguments or return values. For
arguments, the default : LISP-TYPE is INTEGER. When
no : VAX-TYPE option is given, the default for a given
:LISP-TYPE is used. Table 4—2 of your VAX L ISP /V M S
System Access Guide lists the default LISP type—VAX type
pairings.

MAKE-CALL-BACK-ROUTINE Function

The default : l i s p - t y p e for return values is i n t e g e r ; the
default : VAX-TYPE iS : SIGNED-LONGWORD.
Specifies the VAX type of arguments and return values.
When no : VAX-t y p e option is given, the default value of
its corresponding : L ISP -T Y P E is used. Table 4-2 of your
VAX L ISP /V M S System Access Guide lists default LISP
type—VAX type pairings.

: VAX-TYPE type

All : VAX-TYPE type values are keywords.

:RESULT resu lt-sp ecifier

Specifies the type of the value returned by the callback routine and conversion
mechanisms from LISP to VAX data types. The default value is n i l , which means
that the function returns no value. If it returns multiple values, the result must
be the first value in the v a l u e s list. Subsequent arguments are processed in the
order in which they are defined. The types of the returned values must match the
argument’
s :l i s p - t y p e .
The syntax for defining a result-specifier is similar to that for defining arguments.
However, for a result-specifier you supply only the :v a x - t y p e and :l i s p - t y p e
options; :ACCESS and :Me c h a n i s m keywords do not apply.

Return Value
An alien structure of type c a l l - b a c k - r o u t i n e .

Examples
1.

(defvar my-call-back (make-call-back-routine
#'integer-call-back
:arguments
' ((argl :lisp-type integer
:access :in
:mechanism :value
:vax-type runsigned-longword)
(arg2 :lisp-type integer
:access :in-out
:mechanism rreference))
:result
' (: l i s p - t y p e

in te g e r)))

defines the name of the callback function (i n t e g e r and the order of the arguments, as well as information about type
and access characteristics. The second argument is defined to have : i n - o u t
access; therefore, the callback routine will return multiple values.

m ake- c a l l - b a c k - r o u t in e
ca l l -back)

(let* ((lisp-call-back-routine
(make-call-back-routine
'integer-by-ap
:a rgument s :ap
:result '(:lisp-type integer)))

))

•

In this example, the callback function i n t e g e r - b y - a p is defined with the :AP
keyword. Thus, it takes a VAX argument list as its only argument.
98

MEMORY-ALLOCATION-EXTENT Function

MEMORY-ALLOCATION-EXTENT Function
Returns the “
allocation extent”currently used by the memory management
system. The allocation extent is the minimum number of 64K-byte segments
requested when it is necessary to enlarge LISP memory for internal reasons. The
actual number of requested segments may exceed the allocation extent, depending
on how much memory is required.
The allocation extent may be changed with the s e t f macro. The new value must
be a positive integer, representing a number of 64K-byte segments.

Format
MEMORY-ALLOCATION-EXTENT
Argument
None.

Return Value
An integer.

*MODULE-DIRECTORY* Variable
A variable whose value refers to the directory containing the module that is being
loaded into the LISP environment due to a call to the r e q u i r e function. The
value is a pathname.
This variable is useful to determine the location of a module if additional files
from the same directory must be loaded by the module. For example, consider the
following contents of a file called REQUIRED_FILE1.LSP:
(provide "required_filel")
(load (merge-pathnames "required_file2" *module-directory*))
(defun test

When you specify the preceding module with the r e q u i r e function, you do not
have to identify the module’
s directory if it is in one of the places the r e q u i r e
function searches (see the description of the r e q u i r e function later in this man
ual). Furthermore, using the * m o d u l e - d i r e c t o r y * variable, as in this example,
ensures that the file REQUIRED_FILE2 will be loaded from the same directory.
After the module is loaded, the * m o d u l e - d i r e c t o r y * variable is rebound to n i l .
NOTE

As this variable is bound during calls to the r e q u i r e function, nested
calls to the function cause its value to be updated appropriately.

NREAD-LINE Function

NREAD-LINE Function
a destructive version of the Common LISP r e a d - l i n e function,
places the characters that were read into the string supplied as its first argument.
n r e a d - l i n e returns the number of characters that were read, a flag indicating
whether end-of-file was encountered, and a string containing the line if the line
could not fit into the supplied string.
n read- l in e ,

Format
NREAD-LINE string &OPTIONAL input-stream eof-error-p eof-value-p recursive-p
Arguments
strin g

A character string, nread- l in e updates string with the line that was read. If
string has a fill pointer, the fill pointer is adjusted so that string appears to
contain exactly what was read from the stream. If string is adjustable and the
size of the line exceeds the size of string, then string is extended.
Since n r e a d - l i n e does not return string, you must maintain a pointer to string,
input-stream eof-error-p eof-value-p recu rsive-p

These arguments correspond to the arguments to r e a d - l i n e , which is documented
in Common LISP: The Language.

Return Values
Three values:
• A fixnum in dicatin g the n um ber o f characters that w ere in th e line.
•

T, i f t h e l i n e w a s t e r m i n a t e d b y e n d - o f- file ; o t h e r w i s e n i l .

•

n il , if th e

l i n e f it i n t o string-, o t h e r w i s e , a s t r i n g c o n t a i n i n g t h e lin e .

OPEN-STREAM-P Function
This predicate indicates whether a stream is open.

Format
OPEN-STREAM-P stream

100

OPEN-STREAM-P Function

Argument
stream
A stream.

Return Value
T, i f s t r e a m i s o p e n ; n i l , i f i t i s c lo s e d .

*POST-GC-MESSAGE* Variable
Controls the message that the LISP system displays after a garbage collection
occurs. The value of this variable can be n i l , a string of message text, or the
null string (""). If the value is n i l , the system displays a system message; if the
value is a string, the system displays the string; if the variable’
s value is the null
string (""), the system displays no output. The default value is n i l .
The system message is:
; ... Full GC finished

If y o u s e t t h e * p o s t - g c - m e s s a g e * v a r ia b l e , t h e m e s s a g e y o u e s t a b l i s h s u p e r s e d e s
t h e s y s t e m m e s s a g e d i s p l a y e d a f t e r a g a r b a g e c o ll e c t io n .

Example
Lisp> (gc)
; Starting full GC ...
; ... Full GC finished
T

Lisp>

(setf *post-gc-message* "")

II II

Lisp> (gc)
; Starting full GC ...
T

Lisp> (setf *post-gc-message* "GC —
"GC — finished"
Lisp> (gc)
; Starting full GC ...
GC — finished

finished")

• The first call to the g c function shows the garbage collection messages that
the LISP system displays by default.
• The first call to the s e t f macro sets the value of the * p o s t - g c - m e s s a g e *
variable to the null string ("").
• The second call to the g c function shows that, if the variable’
s value is the
null string, the system does not display a message when a garbage collection
is finished.

101

*POST-GC-MESSAGE* Variable
• The second call to the s e t f macro sets the value of the variable to the string
"GC —

finished".

• The third call to the gc function shows that, if the variable’
s value is a string,
the system displays the new message when a garbage collection is finished.

PPRINT-DEFINITION Function
Pretty-prints to a stream the function definition of a symbol.

Format
PPRINT-DEFINITION symbol &OPTIONAL stream
Arguments
symbol
The symbol whose function value is to be pretty-printed.
stream
The stream to which the code is to be pretty-printed. The default stream is the
stream bound to the ^s t a n d a r d -o u t p u t * variable.

Return Value
No value.

Examples
1.

Lisp> (defun factorial (n)
"Returns the factorial of an integer."
(cond ((<= n 1) 1) (t (* n (factorial (- n 1))))))
FACTORIAL
Lisp> (pprint-definition 'factorial)
(DEFUN FACTORIAL (N)
"Returns the factorial of an integer."
(COND ((<= N 1) 1) (T (* N (FACTORIAL (- N 1))))))

• The call to the d e f u n macro defines a function called f a c t o r i a l , which
returns the factorial of an integer.
• The call to the p p r i n t -d e f i n i t i o n function pretty-prints the function
value of the symbol f a c t o r i a l .

102

PPRINT-DEFINITION Function
2.

Lisp> (defun record-my-statistics
(name age siblings married?)
(unless (symbolp name)
(error "~S must be a symbol." name))
(setf (get name 'age) age
(get name 'number-of-siblings) siblings
(get name 'is-this-person-married?) married?) name)
RECORD-MY-STATISTICS
Lisp> (pprint-definition 'record-my-statistics)
(DEFÜN RECORD-MY-STATISTICS (NAME AGE SIBLINGS MARRIED?)
(UNLESS (SYMBOLP NAME)
(ERROR "~S must be a symbol." NAME))
(SETF (GET NAME 'AGE) AGE
(GET NAME 'NUMBER-OF-SIBLINGS) SIBLINGS
(GET NAME 'IS-THIS-PERSON-MARRIED?) MARRIED?)
NAME)

• The call to the d e f u n macro defines a function called r e c o r d -m y STATISTICS.

• The call to the p p r i n t -d e f i n i t i o n function pretty-prints the function
value of the symbol r e c o r d -m y -s t a t i s t i c s .

PPRINT-PLIST Function
Pretty-prints to a stream the property list of a symbol. A property list is a list
of symbol-value pairs; each symbol is associated with a value or an expression.
The p p r i n t -p l i s t function prints the property list in a way that emphasizes the
relationship between the symbols and their values.
p p r i n t -p l i s t prints only the symbol-value pairs for which a symbol is accessible
in the current package. (For information on packages, see Common LISP: The
Language.) On the other hand, s y m b o l -p l i s t returns all the symbol-value pairs
(the entire property list) of a symbol, even those not accessible in the current
package. So, the form (pprint-plist 'me) is not equivalent to the form (pprint
(symbol-plist 'me)). The following example shows the differences between the
two forms:

Lisp> (make-package 'planet)
Lisp> (setf (symbol-plist 'me)
' (girl "samantha" boy "daniel"
planet::inhabitant-of "earth"))
(GIRL "SAMANTHA" BOY "DANIEL" PLANET::INHABITANT-OF "EARTH")
Lisp> (pprint (symbol-plist 'me))
(GIRL "SAMANTHA" BOY "DANIEL" PLANET::INHABITANT-OF "EARTH")
Lisp> (pprint-plist 'me)
(GIRL "SAMANTHA"
BOY "DANIEL")

The call to p p r i n t prints the symbol-value pair p l a n e t ::i n h a b i t a n t -o f "e a r t h ",
but the call to p p r i n t -p l i s t does not. This is because the symbol i n h a b i t a n t -of
in the package p l a n e t is not accessible in the current package. (A symbol can be
in another package and still be accessible in the current package.) The symbol m e
in the current package is associated with the symbol-value pair i n h a b i t a n t -of
"e a r t h " in the p l a n e t package, but the p p r i n t -p l i s t function does not print
that symbol-value pair because it is not accessible in the current package.
103

PPRINT-PLIST Function

Format
PPRINT-PLIST symbol &OPTIONAL stream
Arguments
symbol
The symbol whose property list is to be pretty-printed.
stream
The stream to which the pretty-printed output is to be sent. The default stream
is the stream bound to the *s t a n d a r d -o u t p u t * variable.

Return Value
No value.

Examples
1.

Lisp> (setf (get 'children 'sons) ' (danny geoffrey))
(DANNY GEOFFREY)
Lisp> (setf (get 'children 'daughters) 'samantha)
SAMANTHA
Lisp> (pprint-plist 'children)
(DAUGHTERS SAMANTHA
SONS (DANNY GEOFFREY))

• The calls to the s e t f macro give the symbol c h i l d r e n the properties
s o n s and d a u g h t e r s . The property list of the symbol c h i l d r e n has two
properties: d a u g h t e r s whose value is s a m a n t h a and s o n s whose value is
the list (DANNY GEOFFREY) .
• The call to the p p r i n t -p l i s t function pretty-prints the property list of the
symbol c h i l d r e n .The pretty-printed output emphasizes the relationship
between each property and its value.

104

PPRINT-PLIST Function
2.

Lisp>

(defun record-my-statistics (name age siblings married?)
(unless (symbolp name)
(error "~S must be a symbol." name))
(setf (get name 'age) age
(get name 'number-of-siblings) siblings
(get name 'is-this-person-married?) married)
name)

RECORD-MY-STATISTICS
Lisp> (defun show-my-statistics

(name)
(unless (symbolp name)
(error "~S must be a symbol." name))
(pprint-plist name))

SHOW -MY-STATISTICS
Lis p > (record-my-statistics 'tom 29
TOM
Lisp> (show-my-statistics 'tom)
(IS-THIS-PERSON-MARRIED? NIL
NUMBER-OF-SIBLINGS 3
AGE 29)

3 nil)

• The first call to the d e f u n macro defines a function named r e c o r d - m y S T A T IS T IC S .

• The second call to the d e f u n macro defines a function named s h o w m y - s t a t i s t i c s . The definition includes a call to the p p r i n t - p l i s t
function.
• The call to the r e c o r d - m y - s t a t i s t i c s function supplies the properties for
the symbol t o m .
• The call to the s h o w - m y - s t a t i s t i c s function pretty-prints the property
list for the symbol t o m .

*PRE-GC-MESSAGE* 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 value is n i l , the system displays a system message; if the value is
a string of message text, the system displays the message text; if the variable’
s
value is the null string, the system displays no output. The default value is nil.
The system message is:
; Starting full GC ...

If y o u s e t t h e * p r e - g c - m e s s a g e * v a r ia b l e , t h e m e s s a g e y o u e s t a b l i s h s u p e r s e d e s
th e sy ste m m essa ge.

105

*PRE-GC-MESSAGE* Variable

Example
Lisp> (gc)
; Star t i n g full GC ...
; ... Full GC fini s h e d
T
Lisp> (setf *pr e - g c - m e s s a g e *

"")

II II

Lisp> (gc)
; ... Ful l GC fini s h e d
T
Lis p > (setf *pr e - g c - m e s s a g e *
"GC —
started"
Lis p > (gc)
GC —
started
; ... Ful l GC f i n i s h e d
T

"GC —

started")

• The first call to the g c function shows the garbage collection messages that
are printed by default.
• The first call to the s e t f macro sets the value of the * p r e - g c -m e s s a g e *
variable to the null string ("").
• The second call to the g c function causes the system not to display a message
when the garbage collection starts.
• The second call to the s e t f macro sets the value of the variable to the string
"GC —

started".

• The third call to the g c function causes the system to display the new
message text when the garbage collection starts.

*PRINT-LINES* Variable
Specifies the number of lines to be printed by an outermost logical block. The
default for this variable is n i l , which specifies no abbreviation. *p r i n t - l i n e s *
is effective only when pretty-printing is enabled. When the system limits output
to the number of lines specified by *p r i n t - l i n e s *, it indicates abbreviation by
replacing the last four characters on the last line printed with “. . . ”
.
The w r i t e and w r i t e - t o - s t r i n g functions have been extended in VAX LISP to
accept the :l i n e s keyword. If you specify this keyword, *p r i n t - l i n e s * is bound
to the value you supply with the keyword before any output is produced.
See VAX LISP Implementation and Extensions to Common LISP for more infor
mation on using the *p r i n t - l i n e s * variable.

106

*PRINT-LINES* Variable

Example
Lisp> (setf *print-pretty* t)
T
Lisp> (setf *print-lines* 4)
4
Lisp> (format t "Stars: ~ :!-/LINEAR/-."
' (polaris dubhe mira mirfak bellatrix capella algol
mirzam pollux canopus albireo castor alphecca
antares))
Stars: POLARIS
DUBHE
MIRA
MIRFAK .. .

With *p r i n t -l i n e s * set to 4, printing stops at the end of the fourth line.

*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 is less than the value of
this variable, the pretty-printer enables miser mode. When output is printed
in miser mode, all indentations are ignored. In addition, a new line is started
for every conditional new line directive (~_,
or
The default value for
*PRINT-MISER-WIDTH* is 40.
You can prevent the use of miser mode by setting the *p r i n t -m i s e r -w i d t h *
variable to n i l .
The w r i t e and w r i t e -t o -s t r i n g functions have been extended in VAX LISP to
accept the :m i s e r -w i d t h keyword. If you specify this keyword, *p r i n t -m i s e r w i d t h * is bound to the value you supply with the keyword before any output is
produced.
For more information about miser mode and the use of the *p r i n t -m i s e r -w i d t h *
variable, see VAX LISP Implementation and Extensions to Common LISP.

Example
Lisp> (setf *print-right-margin* 60)
60
Lisp> (setf *print-miser-width* 35)
35
Lisp> (format t "~!Stars with Arabic names: ~:@!~S ~:_~S ~
~27I~:_~S ~ :I~@_~S ~_~S ~1I~_~S~.~."
' (betelgeuse (deneb sirius vega)
aldeberan algol (castor pollux) bellatrix))
Stars with Arabic names: BETELGEUSE
(DENEB SIRIUS VEGA)
ALDEBERAN
ALGOL
(CASTOR POLLUX)
BELLATRIX

107

*PRINT-MISER-WIDTH* Variable
• The text, “
Stars with Arabic names:”
, in the outer logical block causes the
inner logical block to begin at column 26. With * p r i n t - m i s e r - w i d t h _ * set to
35, f o r m a t enables miser mode when the logical block begins past column 25.
•

form at

c o n s e r v e s s p a c e b y s t a r t in g a n e w lin e a t e v e r y m u lt ilin e m o d e n e w

l i n e d i r e c t i v e (~_) a n d e v e r y if - n e e d e d n e w l i n e d i r e c t i v e
•

f o r m a t starts a new line at the miser mode new line directive (~@
_) and
ignores the indentation directives (~ni).

*PRINT-RIGHT-MARGIN* Variable
Specifies the right margin for pretty-printing. Output may exceed this margin if
you print long symbol names or strings, or if your f o r m a t control string specifies
no new line directives of any type. If the value of * p r i n t - r i g h t - m a r g i n * is n i l ,
the print function uses a value appropriate to the output device.
The w r i t e and w r i t e - t o - s t r i n g functions have been extended in VAX LISP to
accept the :r i g h t - m a r g i n keyword. If you specify this keyword, * p r i n t - r i g h t m a r g i n * is bound to the value you supply with the keyword before any output is
produced.
See VAX LISP Implementation and Extensions to Common LISP for more infor
mation about using the * p r i n t - r i g h t - m a r g i n * variable.

Example
Lisp> (defun record-my-statistics
(name age siblings married?)
(unless (symbolp name)
(error "~S must be a symbol." name))
(setf (get name 'age) age
(get name 'number-of-siblings) siblings
(get name 'is-this-person-married?) married)
name)
RECORD-MY-STATISTICS
Lisp> (pprint-definition 'record-my-statistics)
(DEFUN RECORD-MY-STATISTICS (NAME AGE SIBLINGS MARRIED?)
(UNLESS (SYMBOLP NAME) (ERROR "~S must be a symbol." NAME))
(SETF (GET NAME' 'AGE) AGE
(GET NAME 'NUMBER-OF-SIBLINGS) SIBLINGS
(GET NAME 'IS-THIS-PERSON-MARRIED?) MARRIED)
NAME)

Lisp> (setf *print-right-margin* 40)
40
Lisp> (pprint-definition 'record-my-statistics)
(DEFUN
RECORD-MY-STATISTICS
(NAME AGE SIBLINGS MARRIED?)
(UNLESS
(SYMBOLP NAME)
(ERROR

"~S must be a symbol."
NAME))
(SETF

(GET NAME 'AGE) AGE
(GET NAME 'NUMBER-OF-SIBLINGS)
SIBLINGS
108

*PRINT-RIGHT-MARGIN* Variable
(GET
NAME
'IS-THIS-PERSON-MARRIED?)
MARRIED)
NAME)

• The call to the d e f u n macro defines a function named r e c o r d -m y -s t a t i s t i c s .
• The first call to the p p r i n t -d e f i n i t i o n function shows the default output.
• The call to the s e t f macro sets the value of the *p r i n t -r i g h t -m a r g i n *
variable to 40.
• The second call to the p p r i n t function shows what effect the variable’
s value
has on the pretty-printed output, p p r i n t -d e f i n i t i o n inserts new lines as
needed before reaching column 40.

PRINT-SIGNALED-ERROR Function
Used by the VAX LISP error handler to display a formatted error message when
an error is signaled. The function prints all output to the stream bound to the
*e r r o r -o u t p u t * variable. VAX LISP Implementation and Extensions to Common
LISP describes the error message formats.
You can include a call to this function in an error handler that you create. See
VAX LISP Implementation and Extensions to Common LISP.

Format
PRINT-SIGNALED-ERROR function-name error-signaling-function
&REST args
Arguments
function-name
The name of the function that is to call the specified error-signaling function.
error-signaling-function
The name of an error-signaling function. Valid function names are e r r o r , c e r r o r ,
and w a r n .
args
The specified error-signaling function’
s arguments.

Return Value
Unspecified.

109

PRINT-SIGNALED-ERROR Function

Example
Lisp> (defun continuing-error-handler (function-name
error-signaling-function
&rest args)
(if (eq error-signaling-function 'cerror)
(progn
(apply #'print-signaled-error
function-name
error-signaling-function
args)
(format *error-output*
"~&It will be continued automatically.~2%.")
nil)
(apply #'universal-error-handler
function-name
error-signaling-function
args)))
CONTINUING-ERROR-HANDLER

Defines an error handler that automatically continues from a continuable error
after displaying an error message. All other errors are passed to the system ’
s
error handler.

*PRINT-SLOT-NAMES-AS-KEYWORDS* Variable
Determines how the slot names of a structure are formatted when they are
displayed. The value can be t or n i l . If the value is T, slot names are preceded
with a colon (:). For example:
#S(SPACE :AREA 4 :COUNT 10)

If the value is n i l , slot names are not preceded with a colon. For example:
#S(SPACE AREA 4 COUNT 10)

The default value is T.

Example
Lisp> (defstruct house
rooms
floors)
HOUSE
Lisp> (make-house :rooms 8 :floors 2)
#S(HOUSE :ROOMS 8 :FLOORS 2)
Lisp> (setf *print-slot-names-as-keywords* nil)
NIL
Lisp> (make-house :rooms 8 :floors 2)
#S(HOUSE ROOMS 8 FLOORS 2)

• The call to the d e f s t r u c t macro defines a structure named h o u s e .
• The first call to the constructor function make-house creates a structure
named house. Colons are included in the output, because the value of the
* p r i n t - s l o t - n a m e s - a s - k e y w o r d s * v a r i a b l e i s T.

110

*PRINT-SLOT-NAMES-AS-KEYWORDS* Variable
• The call to the s e t f macro changes the value of the * p r i n t - s l o t - n a m e s - a s k e y w o r d s * variable to n i l .
• The second call to the constructor function m a k e - h o u s e creates a structure
named h o u s e . Colons are not included in the output, because the value of the
* p r in t - s l o t - n a m es- a s - k ey w o rd s* v a r ia b le i s n i l .

REQUIRE Function
Examines the * m o d u l e s * variable to determine if a specified module has been
loaded. If the module is not loaded, the function loads the files that you specify
for the module. If the module is loaded, its files are not reloaded.
When you call the r e q u i r e function in VAX LISP, the function checks whether
you explicitly specified pathnames that name the files it is to load. If you specify
pathnames, the function loads the files the pathnames represent. If you do not
specify pathnames, the function searches for the module’
s files in the following
order:
1. The function searches the current directory for a source file or a fast-loading
file with the specified module name. If the function finds such a file, it loads
the file into the LISP environment. This search forces the function to locate
a module you have created before the function locates a module of the same
name that is present in one of the public places (see following steps).
2. If the logical name LISP$MODULES is defined, the function searches the
directory to which this logical name refers for a source file or a fast-loading
file with the specified module name. This search enables the VAX LISP sites
to maintain a central directory of modules.
3. The function searches the directory to which the logical name LISP$SYSTEM
refers for a source file or a fast-loading file with the specified module name.
This search enables you to locate modules that are provided with the VAX
LISP system.
4. If the function does not find a file with the specified module name, an error is
signaled.
When you load a module, the pathname that refers to the directory that contains
the module is bound to the * m o d u l e - d i r e c t o r y * variable. A description of the
* m o d u l e - d i r e c t o r y * variable is provided earlier in this manual.
The r e q u i r e function checks the * m o d u l e s * variable to determine if a module has
already been loaded. However, when loading a module, the r e q u i r e function does
not update the * m o d u l e s * variable to indicate that the module has been loaded.
The p r o v i d e function (described in Common LISP: The Language) does update
the *m o d u l e s * variable. Use the p r o v i d e function in a file containing a module
to be loaded to indicate to the LISP system that the file contains a module of this
name.
If the loaded file does not contain a corresponding p r o v i d e , a subsequent r e q u i r e
of the module causes the file to be reloaded.

Ill

REQUIRE Function

Format
REQUIRE module-name &OPTIONAL pathname
Arguments
module-name
A string or a symbol that names the module whose files are to be 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
Unspecified.

Example
Lisp> *modules*
("C A L C U L U S " " N E W T O N I A N - M E C H A N I C S " )

Lisp> (require 'relative)
T
Lisp> *modules*
("RELATIVE" "CALCULUS"

"NEWTONIAN-MECHANICS")

• The first evaluation of the *m o d u l e s * variable shows that the modules
CALCULUS and NEWTONIAN-MECHANICS are loaded.
• The call to the r e q u i r e function checks whether the module RELATIVE is
loaded. The previous evaluation of the *m o d u l e s * variable indicated that the
module was not loaded; therefore, the function loaded the module RELATIVE.
• The second evaluation of the *m o d u l e s * variable shows that the module
RELATIVE was loaded.

RIGHT-MARGIN Function
Returns the default right margin used by the pretty printer when printing to
the stream. The current margin used by the pretty printer is controlled by the
variable *p r i n t -r i g h t -m a r g i n *.

Format
RIGHT-MARGIN &OPTIONAL output-stream

112

RIGHT-MARGIN Function

Argument
output-stream
An output stream. The default value is *STANDARD-OUTPUT*. If you specify a
value of t, the value of *terminal-io* is used.

Return Value
A non-negative fixnum indicating the default right margin for output-stream.

ROOM Function
Displays information about LISP memory. Information is displayed for the
following memory spaces:
• Stack space
• Read-only space
• Static space
• Dynamic space
• Ephemeral space
For each space, the function provides the number of bytes (and segments) in use.
For all spaces except stack, the function shows memory used by the data types
listed in Table 11.
Table 11:

ROOM Function Data Type H eadings

Heading

D ata Types

Cons
Boxed
Unboxed

Conses
Symbols, structures, arrays of element-type T
Strings, floats, bignums, arrays of element-type other than T, compiled
code
Functions, stacks

Mixed

For the ephemeral areas, the r o o m function also shows the maximum number of
segments that will be used for allocation. (See the description of a r e a - s e g m e n t l i m i t .)

The following additional information is provided:
• The status of the full garbage collector, and the number of full collections
since LISP image startup.
• The status of the ephemeral garbage collector, and the number of collections
in each ephemeral area.
• The number of times LISP memory has been enlarged, and the number of
segments that have been added.

113

ROOM-ALLOCATION Function

Example
Lisp> (room-allocation)
1276831 ;
7602176
Lisp> (room-allocation :static)
2660502 ;
2818048

SET-TERMINAL-MODES Function
Sets the terminal characteristics of the stream bound to the * t e r m i n a l - i o *
variable when you invoke the LISP system. Changes to the stream affect all
streams attached to the terminal.
Be careful when you change the settings of terminal modes. A change to terminal
modes affects all the streams that are open to the terminal. If you put a stream
into pass-through mode, for example, all the streams open to the terminal are put
into pass-through mode.
NOTE

Create an error handler to prevent your terminal from being placed in
a nonstandard state. See VAX LISP Implementation and Extensions to
Common LISP for information about how to create an error handler.

Format
SET-TERMINAL-MODES &KEY BROADCAST :ECHO :ESCAPE
:HALF-DUPLEX :PASS-ALL :PASS-THROUGH
:TYPE-AHEAD :WRAP
Arguments
:BROADCAST

Specifies whether the terminal can receive broadcast messages, such as MAIL
notifications and REPLY messages. The value can be either t or n i l . If you
specify t , the terminal can receive messages; if you specify n i l , the terminal
cannot receive messages.
:ECHO

Specifies whether the terminal displays the input characters that it receives.
The value can be either T or n i l . If you specify t , the terminal displays input
characters; if you specify n i l , the terminal displays only data output from the
system or from a user application program.

116

SET-TERMINAL-MODES Function
:ESCAPE

Specifies whether ANSI standard escape sequences that are transmitted from
the terminal are handled as a single multicharacter terminator. The value can
be either T or n i l . If you specify t , the escape sequences are handled as a single
multicharacter terminator. The terminal driver checks the escape sequences for
syntax before passing them to the program. For more information on escape
sequences, see the VMS I/O U ser’
s Reference Manual: Part I.
:HALF-DUPLEX

Specifies the terminal’
s operating mode. The value can be either t or n i l . If you
specify T, the terminal’
s operating mode is half-duplex. If you specify n i l , the
operating mode is full-duplex. For a description of terminal operating modes, see
the VMS I/O U ser’
s Reference Manual: Part I.
:PASS-ALL

Specifies whether the terminal is in pass-all mode. The value can be either T
or n i l . If you specify t , the system does not expand tab characters to blanks,
fill carriage return or line feed characters, recognize control characters, or
receive broadcast messages. If you specify n i l , the system passes all data to an
application program as binary data.
NOTE
: p a s s - a l l has been kept for compatibility with Version 1 of VAX LISP,

but it is not recommended that you use :p a s s - a l l .
:PASS-TH ROUGH

Specifies whether the terminal is in pass-through mode. The value can be either
t or n i l . This mode is the same as the :p a s s - a l l mode, except that “
TTSYNC”
protocol (Ctrl/S, Ctrl/Q) is still used.
:TYPE-AHEAD

Specifies whether the terminal accepts input that is typed when there is no
outstanding read. The value can be either T or n i l . If you specify t , the terminal
accepts input even if there is no outstanding read. If you specify n i l , the terminal
is dedicated and accepts input only when a program or the system issues a read.
:WRAP

Specifies whether the terminal driver generates a carriage return and a line feed
when the end of a line is reached. The value can be either T or n i l . If you specify
t , the terminal driver generates a carriage return and a fine feed when the end of
a line is reached. The end of the line is determined by the terminal width setting.

Return Value
Unspecified.

117

SET-TERMINAL-MODES Function

Example
L isp > (defv a r * o ld - te r m in a l- s ta te * )
* O L D -T E R M IN A L - S T A T E *
L is p > (d efu n p a s s - t h r o u g h - h a n d le r ( f u n c t io n e r r o r S r e s t a r g s)
( l e t ( ( c u r r e n t - s e t t i n g s ( g e t - t e r m i n a l - m o d e s ) ))
( a p p ly # ' s e t - t e r m i n a l - m o d e s * o l d - t e r m i n a l - s t a t e * )
( a p p ly # 'u n i v e r s a l - e r r o r - h a n d l e r f u n c t i o n e r r o r a r g s)
( a p p ly # ' s e t - t e r m i n a l - m o d e s c u r r e n t - s e t t i n g s ) ) )
PA SS-THROUGH-HANDLER
L isp >

(defu n
( let

u n u su a l- in p u t n i l
( ( * o ld - te r m in a l- sta te *
( g e t- te rm in a l- m o d e s) )
( * u n i v e r s a l - e r r o r - h a n d l e r * # ' p a s s - t h r o u g h - h a n d l e r ))
( u n w in d - p rotect (progn
( se t- te rm in a l- m od e s
:p a s s - t h r o u g h
t
:ech o
n il)
( get- in p u t) )
( a p p ly # ' s e t - t e r m i n a l - m o d e s
* o l d - t e r m i n a l - s t a t e * ) ) ))
UNUSUAL-INPUT

• The call to the d e f v a r macro informs the LISP system that * o l d - t e r m i n a l s t a t e * is a special variable.
• The first call to the d e f u n macro defines an error handler named p a s s 
t h r o u g h - h a n d l e r , which is used when the terminal is placed in an unusual
state. The handler assumes that the normal terminal modes are stored as the
value of the * o l d - t e r m i n a l - s t a t e * variable.
• The second call to the d e f u n macro defines a function named u n u s u a l - i n p u t ,
which causes the function p a s s - t h r o u g h - h a n d l e r to be the error handler
while the function g e t - i n p u t is being executed. The g e t - i n p u t function is
inside a call to the u n w i n d - p r o t e c t function, so an error or throw puts the
terminal back in its original state.

SHORT-SITE-NAME Function
Translates the logical name LISP$SHORT_SITE_NAME.

Format
SHORT-SITE-NAME
Argument
None.

118

SHORT-SITE-NAME Function

Return Value
The translation of the logical name LISP$SHORT_SITE_NAME is returned as a
string. If the logical name is not defined, n i l is returned.

Example
L is p > ( sh o rt- site- n a m e)
" S m it h ' s C om p u ter Com pany"

SOFTWARE-VERSION-NUMBER Function
Returns as multiple values the version number of the specified software compo
nent.

Format
SOFTWARE-VERSION-NUMBER component
Argument
com pon en t

A string indicating the software component. Possible values are " v a x l i s p " ,
" v m s " , and "uiS". See the VAX LISP/VMS DECwindows Programming Guide for
information on finding the version number of the X protocol.

Return Values
Multiple values. For a software version number in the form x.y:
1. A fixnum designating x
2. A fixnum designating y

Example
L isp >

( softw a re- v ersion - n u m b e r

"VAX L I S P " )

3 ;

L isp >

119

SOURCE-CODE Function

SOURCE-CODE Function
Returns a lambda expression that is the source code for an interpreted function.

Format
SOURCE-CODE function
Argument
fu nction

An interpreted function or a symbol designating an interpreted function.

Return Value
A lambda expression.

Example
L isp >
F
L isp >

( d e f u n f (x y)
(* (+ x y) (* x
( p p rin t

y) ) )

( sy m b ol- fu n ction

# < I n te r p r e t e d F u n ctio n
(LAMBDA (X Y) (BLOCK F

'f))
(+ X Y)

(* X Y ) )))

4980172>
L isp >

(source-code

(LAMBDA
L isp >

(X Y)

( sy m b ol- fu n ction

(BLOCK F

(+ X Y)

' f ))
(* X Y) ) ) >

SPAWN Function
Creates a subprocess for executing Command Language Interpreter (CLI) com
mands. This function causes the LISP system to interrupt execution of a LISP
process and optionally to execute the specified CLI command. If you specify the
: p a r a l l e l keyword with a value of t , the LISP process continues to execute while
the subprocess is executing. If you do not specify this keyword or if you specify
it with n i l , the LISP process is put into a hibernation state until the subprocess
completes its execution.
NOTE

Be careful using this function with :p a r a l l e l n i l under DECwindows,
both in the development environment and in your programs. Because
this causes LISP to hibernate, no events can be processed. If events
are queued and LISP does not respond within a server-defined timeout,
the X server aborts the connection to the LISP process.
120

SPAWN Function
No such restriction applies to :p a r a l l e l t , because that does not make
LISP hibernate.
This function is equivalent to the DCL SPAWN command. For more information
on the SPAWN command, see the VMS DCL Dictionary.

Format
SPAWN &KEY :COMMAND-STRING :DCL-SYMBOLS :INPUT-FILE
:LOGICAL-NAMES .OUTPUT-FILE PARALLEL
:PROCESS-NAME
Arguments
:COMMAND-STRING

A string specifying a DCL command that the specified subprocess is to process.
The value must be a DCL command. By default, the s p a w n 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 n i l .If you specify t ,
the subprocess acquires the CLI symbols; if you specify n i l ,the subprocess does
not acquire the CLI symbols. The default value is 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 SYS$INPUT
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 ends when processing is complete.
:LOGICAL-NAMES

Specifies whether the spawned subprocess is to acquire the currently defined
logical names. The value can be either t or n i l . If you specify t , the subprocess
acquires the logical names; if you specify n i l ,the subprocess does not acquire the
logical names. The default value is t .
:OUTPUT-FILE

Specifies a pathname, namestring, symbol, or stream that names the output file
to be associated with the logical name SYS$OUTPUT and to which the results of
the spawned subprocess are to be written.
:PARALLEL

Specifies whether the execution of the LISP system and the created subprocess
are to be parallel. The value can be either t or n i l . If you specify t ,the execution
of the system and the subprocess are parallel; if you specify n i l , the LISP
system remains in a hibernation state until the created subprocess completes its
execution and exits. The default value is n i l .

121

SPAWN Function
:PROCESS-NAME

Specifies the name of the subprocess to be created. If you omit this keyword, the
system generates a unique name.

Return Value
Unspecified.

Examples
1.

Lisp> (spawn)
$

Creates a uniquely named subprocess and attaches the terminal to it. The
commands typed at the terminal are directed to the subprocess until the
subprocess exits.
2. Lisp> (spawn :input-file "start.com"
.•output-file "start.log"
:parallel t)
Lisp>

Creates a subprocess that will execute the contents of START.COM.
3. Lisp> (defun spawn-in-window
(Soptional (process-name nil))
(let ((device-string
(uis:create-terminal
:banner-title
(or process-name "Subprocess"))))
(spawn :input-file device-string
:output-file device-string
:process-name process-name
.•parallel t) ))
SPAWN—IN—WINDOW
Lisp> (spawn-in-window "Smith_l")
Lisp>

This example works only on a VAXstation running UIS. It defines a function
named s p a w n - i n -w i n d o w that creates a process in a VAXstation terminal
emulator window. The function u is :c r e a t e -t e r m i n a l creates a terminal
emulator window and returns the window’
s device name. By supplying this
return value with the : i n p u t -f i l e and :o u t p u t -f i l e keyword arguments,
s p a w n - i n -w i n d o w arranges for input to and output from the subprocess to be
directed through the terminal emulator window, s p a w n - i n -w i n d o w accepts an
optional argument that becomes the name of the subprocess and the title of
the window.
When the s p a w n -i n -w i n d o w function is called, a subprocess and a terminal
emulator window named “
Smith_l”are created. The cursor switches to the
terminal emulator window. However, the user can switch the cursor back
to the LISP prompt and continue to use LISP without logging out of the
subprocess.
See the VAX LISP Interface to VWS Graphics manual for information about
the u i s :c r e a t e -t e r m i n a l function.

122

STEP Macro

STEP Macro
Invokes the VAX LISP Stepper.
The s t e p macro evaluates the form that is its argument and returns what the
form returns. In the process, you can interactively step through the evaluation
of the form. Entering a question mark (?) in response to the Stepper prompt
displays helpful information. The Stepper is command oriented rather than
expression oriented—do not enclose commands within parentheses.
For further information on using the VAX LISP Stepper, see Chapter 4 of the VAX
LISP/VMS Program Development Guide.

Format
STEP form
Argument
form

A form to be evaluated.

Return Value
The value returned by the form argument.

Example
Lisp> (step (factorial 3))
: #9: (FACTORIAL 3)
Step >

Invokes the VAX LISP Stepper for the function c a l l (f a c t o r i a l 3).

*STEP-ENVIRONMENT* Variable
The *s t e p - e n v i r o n m e n t * variable, a debugging tool, is bound to the lexical en
vironment in which *s t e p - f o r m * is being evaluated. By default in the Stepper,
the lexical environment is used if you use the e v a l u a t e command. See Common
LISP: The Language for a description of dynamic and lexical environment vari
ables.
Some Common LISP functions (for example, e v a l h o o k , a p p l y h o o k , and
take an optional environment argument. The value bound to the
* s t e p - e n v i r o n m e n t * variable can be passed as an environment to these functions
to allow evaluation of forms in the context of the stepped form.
m acroexpand)

123

*STEP-ENVIRONMENT* Variable

Example
Step> eval *step-form*
(FIBONACCI (- X 1))
Step> (evalhook 'x nil nil nil)
"Top level value of X"
Step> (evalhook 'x nil nil *step-environment*)
3

The *s t e p - e n v i r o n m e n t * variable in this call to the e v a l h o o k function causes the
local value of x to be used in the evaluation of the form (- x l) . See Chapter 4
of the VAX LISP/VMS Program Development Guide for the full Stepper sessions
from which this excerpt is taken.

*STEP-FORM* Variable
The * s t e p - f o r m * variable, a debugging tool, is bound to the form being evaluated
by the VAX LISP Stepper. For example, while executing the form:
(STEP (FUNCTION-Z ARG1 ARG2))

the value of * s t e p - f o r m * is the list (f u n c t i o n - z a r g i a r g 2) . When not stepping,
the value is undefined.

Example
Step> step
: : : : : : : : #39: X => 4
: : : : : : : #35: => NIL
: : : : : : : #34: (+ FIBONACCI (- X 1))
Step> step
: : : : : : : : #38: (FIBONACCI (- X 1))
Step> eval *step-form*
(FIBONACCI (- X 1))

(FIBONACCI (- X 2))

See Chapter 4 of the VAX LISP/VMS Program Development Guide for the full
Stepper session from which this excerpt is taken. In this case, the *s t e p - f o r m *
variable is bound to (F i b o n a c c i (- x i ) ).

SUSPEND Function
Writes information about a LISP system to a file, making it possible to resume the
LISP system at a later time. The function does not stop the current system, but
copies the state of the LISP system when the function is invoked to the specified
file. When you reinvoke the LISP system with the /RESUME qualifier and the file
name that was specified with the s u s p e n d function, program execution continues
from the point where the s u s p e n d function was called.
Only the static and dynamic portions of the LISP environment are written to the
specified file. When you resume a suspended system, the read-only sections of
the LISP environment are taken from LISP$SYSTEM:LISP.EXE. You must make
sure that your original LISP system is in LISP$SYSTEM:LISP.EXE; if it is not,
you will be unable to resume the system.
124

SUSPEND Function
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 and window streams are closed except the standard streams
(*STANDARD-INPUT*, *STANDARD-OUTPUT*, and SO On).
•

The * d e f a u l t - p a t h n a m e - d e f a u l t s * variable is set to the current directory.

• Callout state might be lost. (See Chapter 4 of the VAX LISP /VMS System
Access Guide.)
• Any interrupt functions are uninstated. (See Chapter 6 of the VAX
LISP /VMS System Access Guide.) They are not automatically reinstated
upon resuming.
• All state associated with the DECwindows-based development environment’
s
utilities is lost. On resuming the Listener will be reinitialized and brought up
using the last saved defaults. (See Chapter 7 of the VAX LISP/VMS Program
Development Guide.)
• For all workstation-related functions that take an action argument, the action
is reset to the system default state. An action that you have established is
not automatically reestablished upon resuming.
• Some Editor state is changed. (See the VAX LISP/VMS Editor Programming
Guide.)
• In a LISP with user-programmed CLX or XUI toolkit connections, all nonLISP state is lost. This includes displays, windows, and widgets. (See the
VAX LISP/VMS DECwindows Programming Guide.)
• On a VWS/UIS workstation, windows, displays, and display lists are lost.
Suspended systems must be resumed from the same LISP system that suspended
them. For LISP systems created with the System-Building Utility, the LISP
system that resumes a suspended system must be the same image as the LISP
system that suspended the system or a copy of that image. Two LISP systems
created at different times cannot resume systems suspended by the other, even if
the two LISP systems were created with identical calls to d e f i n e - l i s p - s y s t e m .
The s u s p e n d function should not be called during a call to l o a d ; the stream used
by l o a d cannot be re-created to finish the load on resuming the LISP.

Format
SUSPEND pathname
Argument
pathname
A pathname, namestring, or symbol that represents the file name to which the
function writes the LISP-system state.

125

SUSPEND Function

Return Value
t , when the LISP system is resumed at a later time; n i l , when execution
continues after a suspend operation.

Example
Lisp> (defun program-main-loop nil
(loop (princ "Enter number> ")
(setf x (read *standard-input*))
(format *standard-output*
"~%The square root of ~F is ~F. ~%"
x
(sqrt x))))
PROGRAM-MAIN-LOOP
Lisp> (defun dump-program nil
(suspend "myprog.sus")
(fresh-line)
(princ "Welcome to my program!")
(terpri)
(program-main-loop))
DUMP-PROGRAM
Lisp> (dump-program)
; Starting full GC ...
; ... Full GC finished
Welcome to my program!
Enter number> 25
The square root of 25.0 is 5.0.
Enter number> 5
The square root of 5.0 is 2.235038.
Enter number>

[c t r l /c |

Lisp> (exit)
$ lisp/resume=myprog.sus
Welcome to my program!
Enter number>

• The first call to the d e f u n macro defines a function named p r o g r a m -m a i n loop.

• The second call to the d e f u n macro defines a function named d u m p -p r o g r a m .
• The call to the d u m p -p r o g r a m function copies the current state of the LISP
environment to the file MYPROG.SUS. The LISP system continues to run,
displaying the message “
Welcome to my program!”and then executes the
p r o g r a m -m a i n -l o o p function.
• The call to the e x i t function exits the LISP system.
• The LISP/RESUME=MYPROG.SUS specification reinvokes the LISP system,
displays the message, and executes the p r o g r a m -m a i n -l o o p function.

126

TIME Macro

TIME Macro
Evaluates a form, displays the form’
s CPU time and real time, and returns the
values that the form returns.
The time information is displayed in the following format:
CPU Time: cpu-time sec., Real Time: real-time sec.

If garbage collections occur during the evaluation of a call to the t i m e macro, the
macro displays another line of time information. This line includes information
about the CPU time and real time used by the garbage collector.

Format
TIME form
Argument
form

The form that is to be evaluated.

Return Value
The form’
s return values are returned.

Example
Lisp> (time (test))
CPU Time: 0.03 sec.. Real Time: 0.23 sec.
6

*TOP-LEVEL-PROMPT* Variable
Lets you change the top-level prompt. The value of this variable can be:
• A string
• A function of no arguments that returns a string
•

N IL

If you specify n i l , the default prompt, Lisp>, is used.

127

*TOP-LEVEL-PROMPT* Variable

Example
L isp >
"T O P >
TOP>

(setf
■
'

* to p - le v e l- p r o m p t*

"TOP>

Sets the value of the variable * t o p - l e v e l - p r o m p t * to " t o p >

TRACE Macro
Enables tracing for one or more functions and macros.
VAX LISP allows you to specify a number of options that suppress the t r a c e
macro’
s displayed output or that cause additional information to be displayed.
The options are specified as keyword-value pairs. The keyword-value pairs you
can specify are listed in Table 12.
NOTE

The arguments specified in a call to the t r a c e macro are not evalu
ated when the call to t r a c e is executed. Some forms are evaluated
repeatedly, as described below.

Format
TRACE &REST trace-description
Argument
trace-description
Zero or more optional arguments. If no argument is specified, the t r a c e macro
returns a list of functions and macros that are currently being traced. Tracedescription arguments can be specified in three formats:
• One or more function and/or macro names can be specified, which enables
tracing for that function(s) and/or macro(s).
name-1 name-2 . . .

• The name of each function or macro can be specified with keyword-value
pairs. The keyword-value pairs specify the operations that the t r a c e macro
is to perform when it traces the specified function or macro. The name and
the keyword-value pairs must be specified as a list whose first element is the
function or macro name.
(name keyword-1 value-1 keyword-2 value-2 . . . )

• A list of function and/or macro names can be specified with keyword-value
pairs. The keyword-value pairs specify the operations that the t r a c e macro
is to perform when it traces each function and/or macro in the list. The list
of names and the keyword-value pairs must be specified as a list whose first
element is the list of names.

128

TRACE Macro
((name-1 name-2 . . . ) keyword-1 value-1
keyword-2 value-2 . . . )

Table 12 lists the keywords and values that can be specified. The forms that are
referred to in the value descriptions are evaluated in the null lexical environment
and the current dynamic environment.
Table 12:

TRACE O ptions

Keyword-Value P a ir

D escription

:D E B U G - I F form

Specifies a form that is to be evaluated before and after
each call to the specified function or macro. If the form
returns a value other than NIL, the VAX LISP Debugger
is invoked before and after the function or macro is called.

:P R E - D E B U G - I F form

Specifies a form that is to be evaluated before each call
to the specified function or macro. If the form returns a
value other than NIL, the VAX LISP Debugger is invoked
before the specified function or macro is called.

:P O S T - D E B U G - I F form

Specifies a form that is to be evaluated after each call
to the specified function or macro. If the form returns a
value other than NIL, the VAX LISP Debugger is invoked
after the specified function or macro is called.

:PRI N T form-list

Specifies a list of forms that are to be evaluated and
whose values are to be displayed before and after each
call to the specified function or macro. The values are
displayed one per line and are indented to match other
output displayed by the TRACE macro.

:P R E - P R I N T form-list

Specifies a list of forms that are to be evaluated and
whose values are to be displayed before each call to the
specified function or macro. The values are displayed one
per line and are indented to match other output displayed
by the TRACE macro.

:P O S T - P R I N T form-list

Specifies a list of forms that are to be evaluated and
whose values are to be displayed after each call to the
specified function or macro. The values are displayed one
per line and are indented to match other output displayed
by the TRACE macro.

:STEP-IF form

Specifies a form that is to be evaluated before each call
to the specified function or macro. If the form returns a
value other than NIL, the VAX LISP Stepper is invoked
and the function or macro is stepped through.

:S U P P R E S S - I F form

Specifies a form that is to be evaluated before each call
to the specified function or macro. If the form returns a
value other than NIL, the TRACE macro does not display
the arguments and the return value of the specified
function or macro.

(continued on next page)

129

TRACE Macro

Table 12 (Cont.):

TRACE O ptions

Keyword-Value Pair

Description

: DURING name

Specifies a function or macro name or a list of function
and macro names. The function or macro specified by the
TRACE function is traced only when it is called (directly
or indirectly) from within one of the functions or macros
specified by the : DURING keyword.

See the VAX LISP /VMS Program Development Guide for more information on the
VAX LISP Debugger, Stepper, and Tracer.

Return Value
A list of the functions currently being traced.

Examples
1.

Lisp> (trace factorial countl count2)
(FACTORIAL COUNT1 COUNT2)

Enables the VAX LISP Tracer for the functions factorial , counti, and
C0UNT2.
2.

Lisp> (trace)
(FACTORIAL COUNTI COUNT2)

Returns a list of the functions for which the Tracer is enabled.
3. Lisp> (defun reverse-count (n)
(declare (special *go-into-debugger*))
(if (> n 3)
(setq *go-into-debugger* t)
(setq *go-into-debugger* nil))
(cond ((= n 0) 0)
(t (print n) (+ 1 (reverse-count (- n 1))))))

REVERSE-COUNT
Lisp>
NIL
Lisp>
3

(setq *go-into-debugger* nil)
(reverse-count 3)

1
3
Lisp> (trace (reverse-count :debug-if *go-into-debugger*))
(REVERSE-COUNT)
Lisp> (reverse-count 3)
#4: (REVERSE-COUNT 3)
3
. #16: (REVERSE-COUNT 2)
2

. . #28: (REVERSE-COUNT 1)
1
. . . #40: (REVERSE-COUNT 0)
. . . #40=> 0
. . #28=> 1

. #16=> 2

130

TRACE Macro
#4=> 3
3
Lisp> (reverse-count 4)
#4:
4
. #16: (REVERSE-COUNT 3)
Control Stack Debugger
Apply #17: (DEBUG)
Debug 1> continue
3
. . #28: (REVERSE-COUNT 2)
2

. . . #40: (REVERSE-COUNT 1)
1
. . . . #52: (REVERSE-COUNT 0)
. . . . #52=> 0
. . . #40=> 1
. . #28=> 2
. #16=> 3
#4=> 4
4
Lisp>

The recursive function r e v e r s e -c o u n t is defined to count down from the
number it is given and to return that number after the function is evaluated.
However, if the given number is greater than 3 (set low to simplify the
example), the global variable *g o - i n t o -d e b u g g e r * (preset to n i l ) is set to T.
The first time the r e v e r s e -c o u n t function is traced by use of the :DEBUG-if
keyword, the argument is 3. The second time the function is traced, the
argument is over 3. This sets the global variable *g o -i n t o -d e b u g g e r * to t ,
which causes the Debugger to be invoked during a trace of the r e v e r s e -c o u n t
function. The Debugger is invoked after the function’
s argument is evaluated.
To reset the global variable *g o -i n t o -d e b u g g e r * to n i l , the r e v e r s e -c o u n t
function must be completed. So, the evaluation of the function was continued
with the Debugger CONTINUE command.
4.

Lisp> (trace (reverse-count
:pre-debug-if *go-into-debugger*))
(REVERSE-COUNT)
Lisp> (reverse-count 4)
#4: (REVERSE-COUNT 4)
4
. #16: (REVERSE-COUNT 3)
Control Stack Debugger
Apply #17:
Debug 1>

The 4 argument to the r e v e r s e -c o u n t function causes the *g o - i n t o d e b u g g e r * variable to be set to t , which in turn causes the Debugger to
be invoked before the first recursive call to the r e v e r s e -c o u n t function.

131

TRACE Macro
5. Lisp> (trace (reverse-count
:post-debug-if *go-into-debugger*))
(REVERSE-COUNT)
Lisp> (reverse-count 4)
#4: (REVERSE-COUNT 4)
4
. #16: (REVERSE-COUNT 3)
3
. . #28: (REVERSE-COUNT 2)
2

. . . #40: (REVERSE-COUNT 1)
1
. . . . #52: (REVERSE-COUNT 0)
. . . . #52=> 0
. . . #40=> 1
. . #28=> 2
. #16=> 3
#4=> 4
4
Lisp> (trace (reverse-count
:post-debug-if (not *go-into-debugger*)))
(REVERSE-COUNT)
Lisp> (reverse-count 4)
#4: (REVERSE-COUNT 4)
4
. #16: (REVERSE-COUNT 3)
3
. . #28: (REVERSE-COUNT 2)
2

. . . #40: (REVERSE-COUNT 1)
1
. . . . #52: (REVERSE-COUNT 0)
Control Stack Debugger
Apply #53: (DEBUG)
Debug 1> continue
. . . . #52=> 0
Control Stack Debugger
Apply #41: (DEBUG)
D ebug

co n tin u e

. . . #40=> 1
C on trol

Stack

D ebugger

Apply #29: (DEBUG)
Debug 1> continue
. . #28=> 2
Control Stack Debugger
Apply #17: (DEBUG)
Debug 1> continue
. #16=> 3
Control Stack Debugger
Apply #5: (DEBUG)
Debug 1> continue
#4=> 4
4
L isp >

Here, the first time the r e v e r s e -c o u n t function is evaluated, the Debugger
is not invoked despite the .-p o s t -d e b u g -if keyword, because the keyword
invokes the Debugger only if its condition is met after the function is
evaluated. However, after the function is evaluated, the *g o - i n t o -d e b u g g e r *
variable is reset to n i l . If the form (setq *go-into-debugger* nil) were
removed from the definition of the r e v e r s e -c o u n t function, the variable

132

TRACE Macro
would not have been reset to n i l , and the Debugger would have been
invoked.
The second time the r e v e r s e -c o u n t function is invoked, the form (not
* g o - i n t o - d e b u g g e r * ) evaluates to t , since the value of its argument is n i l .
This gives the : p o s t - d e b u g - i f keyword a t value, which in turn fulfills the
condition of invoking the Debugger after the function is evaluated.
In this situation, the Debugger CONTINUE command causes only one
evaluation. Here, the CONTINUE command must be repeated to evaluate
all the recursive calls. This example differs from Example 1, where the
CONTINUE command did not have to be repeated.
6.

Lisp> (setf *L* 5 *M* 6 *N* 7)
7
Lisp> (trace (* :print (*L* *M* *N*)))

(*)

Lisp> ( + 2 3 *L* *M* *N*)
23
Lisp> (* 2 3 *L* *M* *N*)
#4: ( * 2 3 5 6 7)
#4 *L* is 5
#4 *M* is 6
#4 *N* is 7
#4=> 1260
#4 *L* is 5
#4 *M* is 6
#4 *N* is 7
1260

The + function is not traced, but the * function is traced. The values of the
global variables *l *, *m *, and *n * are displayed before and after the call to
the * function is evaluated.
7. Lisp> (trace (* :pre-print (*L* *M* *N*)))
(*)
Lisp> (* 2 3 *L* *M* *N*)
#4: ( * 2 3 5 6 7)
#4 *L* is 5
#4 *M* is 6
#4 *N* is 7
#4=> 1260
1260

The values of the global variables *l *, *m *, and *N* are displayed before the
call to the * function is evaluated.
8.

Lisp> (trace (* :post-print (*L* *M* *N*)))

(*)

Lisp> ( * 2 3 *L* *M* *N*)
#4: ( * 2 3 5 6 7)
#4=> 1260
#4 *L* is 5
#4 *M* is 6
#4 *N* is 7
1260

The values of the global variables *L*, *m *, and *N* are displayed after the
call to the * function is evaluated.

133

TRACE Macro
9.

Lisp> (trace +)

(+)

Lisp> ( + 2 3 (square 4) (sqrt 25))
#4: (+ 2 3 15 5.0)
#4=> 25.0
26.0
Lisp> (setq *stop-tracing* t)
T
Lisp> (trace (+ :suppress-if *stop-tracing*))

(+)
Lisp> ( + 2 3
26.0

(square 4) (sqrt 25))

The first call to the + function is traced. The second call to the + function is
not traced because of the form (+ :suppress-if *stop-tracing*).
10. Lisp> (trace (factorial :step-if t))
(FACTORIAL.)
Lisp> (+ (factorial 2) 3)
#6: (FACTORIAL 2)
#10: (BLOCK FACTORIAL (IF (<= N 1) 1
(* N (FACTORIAL (- N 1)))))
Step>
: #15: (IF (<= N 1) 1 (* N (FACTORIAL (- N 1))))
Step>
: : #20: (<= N 1)
Step>

The call to the f a c t o r i a l function invokes the Stepper.
11.

L isp > ( tra ce ( lis t - le n g t h :d u rin g p r in t- le n g th ) )
( L IST-L EN G TH )
L isp > ( p r in t- le n g th ' (cat d og p o n y ) )

#13: (LIST-LENGTH (CAT DOG PONY))
#13=> 3
The length of (CAT DOG PONY) is 3.
N IL

The p r i n t - l e n g t h function has been defined to find the length of its argument
with the function l i s t - l e n g t h . The l i s t - l e n g t h function is traced during
the call to the p r i n t - l e n g t h function.

134

TRACE Macro
12. Lisp> (defun fibonacci (x)
(if (< x 3) 1
(+ (fibonacci (- x 1)) (fibonacci (- x 2)))))
FIBONACCI
Lisp> (trace (fibonacci
:pre-debug-if (< (second *trace-call*) 2)
:suppress-if t))
(FIBONACCI)
Lisp> (fibonacci 5)
Control Stack Debugger
Apply #30: (DEBUG)
Debug 1> down
Eval #27: (FIBONACCI (- X 2))
Debug 1> down
Eval #26: (+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2)))
Debug 1> down
Eval #25: (IF (< X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2))))
Debug 1> down
Eval #24: (BLOCK FIBONACCI
(IF (< X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2)))))
Debug 1> down
Apply #22: (FIBONACCI 3)
Debug 1> (cadr (debug-call))
3
Debug 1> continue
Control Stack Debugger
Apply #22:
Debug 1> continue
5

This example illustrates the following points:
• First, F i b o n a c c i is defined.
• Then the t r a c e macro is called for F i b o n a c c i , t r a c e is specified to invoke
the Debugger if the first argument to F i b o n a c c i (the second element
of *t r a c e -c a l l *) is less than 2. Since the .-p r e -d e b u g - if option is
specified, the Debugger is invoked before the call to F i b o n a c c i . A s the
: s u p p r e s s -if option has a value of t , calls to F i b o n a c c i cause no trace
output.
• The DOWN commands move the pointer down the control stack.
• The d e b u g -c a l l function returns a list representing the current debug
frame function call. In this case, the c a d r of the list is 3. This accesses
the first argument to the function in the current stack frame.
• Finally, the CONTINUE command continues the evaluation of F i b o n a c c i .

135

TRACE Macro
13. Lisp> (trace (fibonacci
:post-debug-if (> (first *trace-values*) 2)))
(FIBONACCI)
Lisp> (fibonacci 5)
#5: (FIBONACCI 5)
. #13: (FIBONACCI 4)
. . #21: (FIBONACCI 3)
. . . #29: (FIBONACCI 2)
. . . #2 9=> 1
. . . #29: (FIBONACCI 1)
. . . #29=> 1
.

. # 21= > 2

. . #21:

(FIBONACCI 2)

. . #21=> 1

Control Stack Debugger
Apply #14: (DEBUG)
Debug 1> backtrace
— Backtrace start —
Apply #14
(DEBUG)
Eval #11 (FIBONACCI (- X 1))
Eval #10 (+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2)))
Eval #9: (IF (< X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2))))
Eval #8: (BLOCK FIBONACCI
(IF (< X 3) 1
(+ (FIBONACCI (- X 1) )
(FIBONACCI (- X 2) )
Apply #6: (FIBONACCI 5)
Eval #3: (FIBONACCI 5)
Apply #1: (EVAL (FIBONACCI 5))
— Backtrace end —
Apply #14: (DEBUG)
Debug 1> continue
. #13=> 3
. #13: (FIBONACCI 3)
. . #21: (FIBONACCI 2)

. . #21=> 1

. . #21:

(FIBONACCI 1)

. . #21=> 1

. #13=> 2
Control Stack Debugger
A p p ly

#6:

(DEBUG)

Debug 1> continue
#5=> 5
5
t r a c e is called for F i b o n a c c i to start the Debugger if the returned value
(which is bound to *t r a c e -v a l u e s *) exceeds 2. The returned value exceeds 2
twice—once when it returns 3 and at the end when it returns 5.

136

*TRACE-CALL* Variable

*TRACE-CALL* Variable
The *t r a c e -c a l l * variable, a debugging tool, is bound to the function or macro
call being traced.

Examples
These examples assume that the function F i b o n a c c i has already been
defined. See the examples of the t r a c e macro for the definition.
1. Lisp> (trace (fibonacci
:suppress-if (> (second *trace-call*) 1)))
(FIBONACCI)

This causes F i b o n a c c i to be traced only if its first argument is 1 or less.
2. Lisp> (trace (fibonacci

:suppress-if (<= (length *trace-call*) 2)))

(FIBONACCI)

This causes F i b o n a c c i to be traced if it is called with more than one argu
ment.
3. Lisp> (trace (fibonacci
:predebug-if (< (second *trace-call*) 2)
: suppress-if (< (second *trace-call*) 2)))
(FIBONACCI)

The t r a c e macro is enabled for F i b o n a c c i . In this case, the Debugger is
invoked and tracing suppressed if the first argument to F i b o n a c c i (the
s e c o n d of the value of the *t r a c e -c a l l * variable) is less than 2. So, for
example, if F i b o n a c c i is called with the arguments 3 and 5, *t r a c e -c a l l * is
bound to the form (fibonacci 3 5); as 3 is greater than 2, the call is traced
and the Debugger not entered. See the description of the t r a c e macro for
further examples of the use of *t r a c e -c a l l *.

*TRACE-VALUES* Variable
The *t r a c e -v a l u e s * 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-i f .

Example
This example assumes that the f a c t o r i a l function has already been defined.

137

*TRACE-VALUES* Variable
Lisp> (trace (factorial :post-print *trace-values*))
Lisp> (FACTORIAL)
Lisp> (factorial 4)
#5: (FACTORIAL 4)
. #14: (FACTORIAL 3)
. . #23: (FACTORIAL 2)
. . . #32: (FACTORIAL 1)
. . . #32=> 1
. . . #32 *TRACE-VALUES* is (1)
. . #23=> 2
. . #23 *TRACE-VALUES* is (2)
. #14=> 6
. #14 *TRACE-VALUES* is (6)
#5=> 24
#5 *TRACE-VALUES* is (24)
24

The values returned by the f a c t o r i a l function are bound to the *t r a c e -v a l u e s *
variable and are displayed as (l), (2), (6), and (24). Since the *t r a c e -v a l u e s *
variable is bound to the list of values returned by a function, it can be used
only in the :p o s t - options to the t r a c e macro. Before being bound to the return
values, it returns n i l .See the description of the t r a c e macro for further examples
of the use of the *t r a c e -v a l u e s * variable.

TRANSLATE-LOGICAL-NAME Function
Searches a logical name table for a logical name, translates it, and returns it as a
list of strings.
The t r a n s l a t e -l o g i c a l -n a m e function performs only one level of logical name
translation.
This function is equivalent to the DCL SHOW LOGICAL command. For addi
tional information about the SHOW LOGICAL command or about using logical
names, see the VMS DCL Dictionary.

Format
TRANSLATE-LOGICAL-NAME string
&KEY :TABLE :CASE-SENSITIVE
Arguments
strin g

The logical name for which the function is to search.
:TABLE

The logical name table that the function is to search. If you do not specify a
table name, the process, group, system, and VMS DECwindows name tables are
searched in that order. The values you can specify with the :t a b l e keyword are
the following:

138

TRANSLATE-LOGICAL-NAME Function
Process name table (LNM$PROCESS_TABLE).
: GROUP
Group n a m e ta b le (LNM$GROUP).
:SYSTEM
System name table (LNM$SYSTEM_TABLE).
:DECWINDOWS
DECwindows name table (DECW$LOGICAL_NAMES).
:ALL
Search all four tables (LNM$DCL_LOGICAL).
This is the default.
You can also specify a string that names a table created with the DCL command
CREATE/NAME_TABLE.
:PROCESS

:CASE-SENSITIVE

Used to restrict the search to a case-sensitive search. Valid values are t for
case-sensitive search or n i l for case-insensitive search. The default is n i l . Use a
value of T if you have multiple logical names that differ only in case.

Return Value
If the logical name has any translations, they are returned as a list of strings. If
no match is found, n i l is returned.

Example
Lisp>

(defun show-where-i-am (Soptional
(stream *standard-output*))
(format stream
"-^Current host is ~A ~
~%Current device is ~A ~
~%Current directory is ~A ~%"
(car (translate-logical-name "sys$node"))
(car (translate-logical-name "sys$disk"))
(concatenate 'string
II £ II

(pathname-directory
(default-directory))

"1 ") )
(values))
SHOW-WHERE-I-AM
Lisp> (show-where-i-am)
Current host is MIAMI::
Current device is DBA1:
Current directory is [VAXLISP]
Lisp> (setf (default-directory) "SYS$LIBRARY")
"SYS$LIBRARY"
Lisp> (show-where-i-am)
Current host is MIAMI::
Current device is SYS5SYSR00T:
Current directory is [SYSLIB]

• The call to the d e f u n macro defines a function named s h o w -w h e r e - i -a m ,
which displays the current host, device, and directory.
• The first call to the function s h o w -w h e r e -i -a m displays the current host,
device, and directory.

139

TRANSLATE-LOGICAL-NAME Function
• The call to the s e t f macro changes the directory to s y s l i b .
• The second call to the function s h o w - w h e r e - i - am includes the new directory
in the output that the function displays.

UNBIND-KEYBOARD-FUNCTION Function
Removes the binding of a function from a control character.

Format
UNBIND-KEYBOARD-FUNCTION control-character
Argument
con trol-ch aracter

The control character from which a function’
s binding is to be removed.

Return Value
T, if a binding is removed; n il , if the control character is not bound to a function.

Example
L isp >

( b in d - k ey b oa rd - fu n ction

# \ AB # ' b r e a k )

T
L isp >

( u n b in d - k e y b oa rd - fu n ctio n

# \ AB)

• The call to the b i n d - k e y b o a r d - f u n c t i o n function binds Ctrl/B to the b r e a k
function.
• The call to the u n b i n d - k e y b o a r d - f u n c t i o n function removes the binding of
the function that is bound to Ctrl/B.

UNCOMPILE Function
Restores the interpreted function definition of a symbol, if the symbol’
s definition
was compiled with a call to the c o m p i l e function.
The u n c o m p i l e function is useful for editing function definitions and debugging.
For example, if you are dissatisfied with the results of a function compilation, you
can uncompile the function, edit it, and then recompile it.

140

UNCOMPILE Function
NOTE

You cannot uncompile:
• System functions and macros
• Functions and macros that were loaded from files compiled by the
c o m p i l e -f i l e function
• Functions and macros that were loaded from files compiled by the
DCL /COMPILE qualifier of the LISP command

Format
UNCOMPILE symbol
Argument
sym bol

The symbol that represents the function that is to be uncompiled.

Return Value
The name of the restored function, if the specifed symbol represents an existing
compiled lambda expression and has an interpreted definition; n i l , if it does not.

Example
Lisp> (defun add2 (first second) (+ first second))
ADD2
Lisp> (compile 'add2)
ADD2 compiled.
ADD 2
Lisp> (compiled-function-p #'add2)
T
Lisp> (uncompile 'add2)
ADD 2
Lisp> (compiled-function-p #'add2)
NIL

• The call to the d e f u n macro defines the function a d d 2.
• The call to the c o m p i l e function compiles the function a d d 2.
• The call to the u n c o m p i l e function successfully restores the interpreted
definition of the function a d d 2, because the function is defined and was
compiled with the c o m p i l e function.

141

UNDEFINE-UST-PRINT-FUNCTION Macro

UNDEFINE-LIST-PRINT-FUNCTION Macro
Disables the list-print function defined for a symbol. If another list-print func
tion was superseded by the undefined list-print function, the older function is
reenabled; otherwise, no other list-print function exists for the given symbol.
See VAX LISP Implementation and Extensions to Common LISP for more infor
mation about list-print functions.

Format
UNDEFINE-LIST-PRINT-FUNCTION symbol
Argument
sy m b ol

The name of the list-print function that is to be disabled.

Return Value
The name of the disabled list-print function.

Example
This example assumes that a list-print function m y -s e t q has already been defined
with the d e f i n e -l i St -p r i n t -f u n c t i o n macro.
Lisp> ( u n d e f i n e - l i s t - p r i n t - f u n c t i o n
MY-SETQ

m y-setq)

Undefines the list-print function named m y -s e t q .

UNINSTATE-INTERRUPT-FUNCTION Function
Informs LISP that the interrupt function identified by iif-id will no longer be
used. The iif-id can no longer be given as the astprm argument to a routine that
can cause an AST. However, u n i n s t a t e - i n t e r r u p t -f u n c t i o n does not prevent a
routine from causing an AST with that iif-id. For example, an external routine
that was called with that iif-id before the use of u n i n s t a t e - i n t e r r u p t -f u n c t i o n
might later cause an AST. VAX LISP ignores ASTs for which the corresponding
interrupt function has been uninstated.

Format
UNINSTATE-INTERRUPT-FUNCTION iif-id

142

UNINSTATE-INTERRUPT-FUNCTION Function

Argument
iif-id

An interrupt function identifier previously returned by i n s t a t e -i n t e r r u p t FUNCTION.

Return Value
Unspecified.

Examples
1.

Lisp> (uninstate-interrupt-function timer-iif)
T

Makes the interrupt function represented by timer-iif unavailable for future
use.
2.
(let ((button-iif (instate-interrupt-function
#'button-handler)))
(uis:set-button-action display window button-iif)

(uis: set-button-action display window nil)
(uninstate-interrupt-function button-iif)))

In this code fragment, the interrupt function b u t t o n -h a n d l e r is instated
and b u t t o n -iif is bound to its iif-id. The first call to s e t -b u t t o n -a c t i o n
establishes b u t t o n -h a n d l e r as the function to execute when a workstation
pointer button is pressed or released. Later, the second call to s e t -b u t t o n a c t i o n requests that no action be taken when buttons are pressed or released.
Finally, u n i n s t a t e -i n t e r r u p t -f u n c t i o n removes the interrupt function
represented by b u t t o n - iif from the system.

UNIVERSAL-ERROR-HANDLER Function
By default, this function handles all errors that are signaled. The VAX LISP
*u n i v e r s a l -e r r o r -h a n d l e r * variable is initially bound to this function.
VAX LISP Implementation and Extensions to Common LISP describes the VAX
LISP error handler.

Format
UNIVERSAL-ERROR-HANDLER function-name error-signaling-function
&REST args

143

UNIVERSAL-ERROR-HANDLER Function

Arguments
function-name
The name of the function that produced or signaled the error.
error-signaling-function
The name of an error-signaling function. Valid function names are e r r o r , c e r r o r ,
and w a r n .
args
The arguments of error-signaling-function.

Return Value
Invokes the VAX LISP Debugger, exits the LISP system, or returns n i l .

Example
Lisp>

(defun critical-error-handler (function-name
error-signaling-function
&rest args)
(when (or (eq error-signaling-function 'error)
(eq error-signaling-function 'cerror))
(flash-alarm-light))
(apply #'universal-error-handler
function-name
error-signaling-function
args))
CRITICAL-ERROR-HANDLER

Defines an error handler that checks whether a fatal or continuable error is
signaled. If either type of error is signaled, the handler flashes an alarm light
and then passes the error signal information to the universal error handler.
For more information on how to create an error handler, see VAX LISP
Implementation and Extensions to Common LISP.

*UNIVERSAL-ERROR-HANDLER* Variable
By default, this variable is bound to the VAX LISP error handler, the u n i v e r s a l e r r o r -h a n d l e r function. If you create an error handler, you must bind the
*UNIVERSAL-ERROR-HANDLER* variable to it.

144

*UNIVERSAL-ERROR-HANDLER* Variable

Example
Lisp>

(defun critical-error-handler (function-name
error-signaling-function
Srest args)
(when (or (eq error-signaling-function 'error)
(eq error-signaling-function 'cerror))
(flash-alarm-light))
(apply #'universal-error-handler
funct ion-name
error-signaling-function
args))
CRITICAL-ERROR-HANDLER
Lisp> (let ((*universal-error-handler*
#'critical-error-handler))
(perform-critical-operation))

• The call to the d e f u n macro defines an error handler named c r i t i c a l -e r r o r handler.

• The call to the special form l e t binds the *u n i v e r s a l -e r r o r -h a n d l e r *
variable to the error handler named c r i t i c a l -e r r o r -h a n d l e r , while the
p e r f o r m -c r i t i c a l -o p e r a t i o n function is evaluated.

VMS-DEBUG Function
Invokes the VMS Symbolic Debugger. Use this function to invoke the Symbolic
Debugger or to activate a shareable image and use the Debugger before calling
out to an external routine that you want to debug. See the VAX LISP /VMS
Program Development Guide for an example of using this function.

Format
VMS-DEBUG &KEY :EXTERNAL-ROUTINE :COMMAND-LINE
Arguments
:EXTERNAL-ROUTINE

A symbol naming the external routine you wish to debug. When you supply
this argument, the image containing the external routine is activated, and the
Symbolic Debugger executes the SET IMAGE command on the image.
:COMMAND-LINE

A string containing one or more Symbolic Debugger commands. Separate
commands with semicolons. If you have supplied a value for the :e x t e r n a l r o u t i n e argument, the resulting SET IMAGE command executes before the
commands you supply with the :c o m m a n d -l i n e argument.

145

VMS-DEBUG Function

Return Value
Unspecified.

WAIT Function
Causes the program that calls it to stop executing until a specified function
returns non-NiL. The first argument to w a i t is a reason for waiting, typically
a string. The second argument is a function; arguments to the function can be
provided as additional arguments to w a i t .
A program that calls the w a i t function stops executing. The function specified
in w a i t ’s second argument is called occasionally, typically when interrupts occur,
with the arguments provided in the w a i t call. If the function returns n i l , the
program continues to wait. When the function returns non-NiL, w a i t returns an
undefined value, and program execution continues.
The testing function you specify with w a i t does not execute in the context of the
program that issued the w a i t .Therefore, the testing function cannot depend on
the binding of special variables. You should pass the testing function some data
structure, such as a cons cell, structure, or array. Pass the same data structure
to an interrupt function that modifies the data structure. Chapter 7 in the VAX
LISP/VMS System Access Guide contains examples of this technique.
For efficiency and reliability, ensure that the testing function executes quickly
and does not cause errors. If the testing function encounters an error while
LISP is in a w a i t state, LISP is left in an inconsistent state and may have to be
terminated. For this reason, w a i t calls its testing function once before entering
the w a i t state. Errors that occur on this initial call can be debugged normally.

Format
WAIT reason function &REST args
Arguments
rea son

The reason for the wait, typically a string.
fu nction

A function that will be called occasionally to determine if the program should
continue to wait.
args

Arguments to be supplied to the function given in the second argument.

146

WAIT Function

Return Value
Unspecified.

Examples
1.

Lisp> (setf *flag* (list nil))
(NIL)
Lisp> (bind-keyboard-function
#\Af
#'(lambda () (setf (car *flag*) t)))
Lisp> (wait "Wait for Ctrl/F" t'car *flag*)
( A fter a p a u s e ,

u ser ty p es

|ctri/F|)

T
Lisp>

• The special variable *flag* is set to a list whose only element is n il .
•

Ctrl/F is bound to a function that sets the first element of *flag * to T.

• The call to the wait function specifies car as the testing function and
*flag* as the argument to the testing function, wait does not return
immediately.
• When the user types Ctrl/F, the keyboard function sets the first element of
*flag * to t , the testing function returns t , and the call to wait returns.
2.

Lisp> (defun set-timer-and-wait (seconds)
(let* ((delta 0)
(flag (list nil))
(iif (instate-interrupt-function
#'set-flag
:once-only-p t
:arguments (list flag))))
(call-out sys$bintim (time-string seconds) delta)
(call-out sys$setimr nil delta
common-ast-address iif)
(wait "Timer wait" #'CAR FLAG))
(princ "The timer has expired")
t)
SET-TIMER-AND-WAIT
Lisp> (defun set-flag (flag)
(setf (car flag) t))
SET-FLAG
Lisp> (set-timer-and-wait 5)
(F ive s e c o n d s e la p s e ) The timer has expired
T
Lisp>

This example uses the definitions of the external routines sys $setimr and
sys $bintim and the function time - string from Examples 1 and 2 under
INSTATE-INTERRUPT-FUNCTION.

• The function set - timer -and-wait is defined. It binds the symbol flag to
a list whose only element is n il , then causes that list to be passed to the
interrupt function set -flag as its only argument, set - timer -and-wait
then calls out to the external routine sy s $setimr , specifying that the
interrupt function set -flag be executed when the timer expires. Finally,
147

WAIT Function
s e t —t i m e r - a n d —w a i t

c a l l s t h e w a i t f u n c t io n , s p e c i f y i n g c a r a s t h e t e s t i n g

fu n c tio n a n d th e lis t to w h ic h

flag

is b o u n d a s th e a r g u m e n t to c a r .

• The function s e t - f l a g is defined. It sets the first element of the list
passed to it to T.
•

is called. It executes as far as the w a i t function call.
does not return until the timer expires and causes the first element
of f l a g to be set to t .
s e t - t i m e r - a n d - w a it

w a it

WARN Function
Invokes the VAX LISP error handler. The error handler displays an error mes
sage and checks the value of the * b r e a k - o n - w a r n i n g s * variable. If the value
is n i l , the w arn function returns n i l ; if the value is not n i l , the error handler
checks the value of the * e r r o r - a c t i o n * variable. The value of the * e r r o r a c t i o n * variable can be either the :E X IT or the :d e b u g keyword. If the value is
:E X IT , the error handler causes the LISP system to exit; if the value is :d e b u g ,
the handler invokes the VAX LISP Debugger.
For more information on warnings, see VAX LISP Implementation and Extensions
to Common LISP.

Format
WARN format-string &REST args
Arguments
form at-string

The string of characters that is passed to the f o r m a t function to create a warning
message.
args

The arguments that are passed to the f o r m a t function as arguments for the
format string.

Return Value
NIL.

148

WARN Function

Example
Lisp> (defun log-error-status (vms-status)
(declare (special *error-log*))
(let ((message (get-vms-message vms-status #*1111) ))
(if message
(write-line message *error-log*)
(warn
"There is no message for VMS status #X~8,'0X."
vms-status))))
LOG-ERROR-S TATUS

Defines a function that is an error-logging facility. The function logs the VMS
status that is returned from a callout to a system service or an RTL routine. If
the callout facility returns an error status that has no corresponding message
text, a warning message is displayed, and no log entry is produced.

WITH-GENERALIZED-PRINT-FUNCTION Macro
Locally enables a generalized print function when it evaluates the specified
forms. See VAX LISP Implementation and Extensions to Common LISP for more
information about using generalized print functions.

Format
WITH-GENERALIZED-PRINT-FUNCTION name &BODY forms
Arguments
nam e

A symbol identifying the generalized print function that is to be enabled. The
enabled generalized print function supersedes any previously enabled generalized
print function for name.
fo r m s

A call or calls to print functions.

Return Value
Output that is generated by the call or calls to print functions.

149

WITH-GENERALIZED-PRINT-FUNCTION Macro

Example
Lisp> (define-generalized-print-function prirrt-nil-as-list
(object stream)
(null object)
(princ "( )" stream))
PRINT-NIL-AS-LIST
Lisp> (with-generalized-print-function 'print-nil-as-list
(pprint nil))

()

The p p r i n t call prints ( ), because the generalized print function is enabled
locally and pretty-printing is enabled.

150

Index
a ______________________
ABORT function, 1 to 2
A ccess function
defining field types, 32
generating, 36
naming, 34
: ACCESS keyword
DEFINE-EXTERNAL-ROUTINE macro, 40
MAKE-CALL-BACK-ROUTINE function, 97
: ACCOUNT keyword
GET-PROCESS-INFORMATION function, 74
: A C P -P ID keyword
GET-DEVICE-INFORMATION function, 63
: ACP-TYPE keyword
GET-DEVICE-INFORMATION function, 63
: ACTIVE-PAGE-TABLE-COUNT keyword
GET-PROCESS-INFORMATION function, 74
Alien structure
a c c e s s function
defining field types, 32
generating, 36
naming, 34
constructor function
naming, 35
specifying an initial value, 36
copier function, naming, 35
defining, 34
dereferencing pointer to data vector, 2
field accessor, 3
length, 4
modify, 3
name, 34
options, 34
predicate function, naming, 35
ALIEN-DATA function, 2, 2
A LIEN -F IELD function, 3
ALIEN-STRUCTURE-LENGTH function, 4
: ALL keyword
TRANSLATE-LOGICAL-NAME function, 139
: ALLOCATION keyword
MAKE-ARRAY function, 95
: ALLOCATION-QUANTITY keyword
GET-FILE-INFORM ATION function, 66
: AP keyword
MAKE-CALL-BACK-ROUTINE function, 97
APROPOS function, 6
A P R O P O S-L IST function, 8
AREA-SEGMENT-LIMIT function, 9
AREA-SEGMENTS function, 9 to 10
Argument description, 39
Argument-passing mechanisms, 40

: ARGUMENTS keyword
MAKE-CALL-BACK-ROUTINE function, 97 to
98
Arrays
creating, 95
specialized, 95
: AST-A CTIV E keyword
GET-PROCESS-INFORMATION function, 74
: AST-COUNT keyword
GET-PROCESS-INFORMATION function, 74
: AST-ENABLED keyword
GET-PROCESS-INFORMATION function, 74
: AST-QUOTA keyword
GET-PROCESS-INFORMATION function, 74
ATTACH function, 10 to 11
: A U THORIZED-PRIV ILEGES keyword
GET-PROCESS-INFORMATION function, 74

B________________________
: BACKUP-DATE keyword
GET-FILE-INFORM ATION function, 66
: B A SE-P R IO R IT Y keyword
GET-PROCESS-INFORMATION function, 74
: BATCH keyword
GET-PROCESS-INFORMATION function, 74
Begin logical block directive, 57
BIND-KEYBOARD-FUNCTION function, 12 to 13
: BIO-BYTE-COUNT keyword
GET-PROCESS-INFORMATION function, 74
: BIO-BYTE-QUOTA keyword
GET-PROCESS-INFORMATION function, 74
: BIO-COUNT keyword
GET-PROCESS-INFORMATION function, 74
: BIO-OPERATION S keyword
GET-PROCESS-INFORMATION function, 74
: BIO-QUOTA keyword
GET-PROCESS-INFORMATION function, 74
: BIT-V ECTOR keyword
alien structure field type, 35
: B L O C K -SIZE keyword
GET-FILE-INFORM ATION function, 66
BREAK function, 13 to 14,25
binding control character to, 12
Break loop
exiting, 14,25
invoking, 13 to 14
*BREAK-ON-WARNlNGS* variable
WARN function, 148
: BROADCAST keyword
GET-TERMINAL-MODES function, 78

lndex-1

: BROADCAST keyword (cont’
d.)
SET-TERMINAL-MODES function,
: B U FF ER -SIZE keyword

116

GET-DEVICE-INFORMATION function, 63

c __________________________
CALL-BACK-ROUTINE type specifier,
CALL-OUT macro, 14

Cancel character, 1,16
CATCH-ABORT macro, 16
CERROR function,

144

D___________________________________

Changing default directory
with SETF macro, 30 to 32
CHAR-NAME-TABLE function, 17 to 18
Character names, 17 to 18
: CHECK-STATUS-RETURN keyword
DEFINE-EXTERNAL-ROUTINE macro, 38
: CLI-TABLENAME keyword
GET-PROCESS-INFORMATION function, 74
: CL U ST E R -SIZE keyword
GET-DEVICE-INFORMATION function, 63

Command Language Interpreter (CLI) commands,

120

COMMAND-LINE-ENTITY-P function, 18
COMMAND-LINE-ENTITY-VALUE function, 19
: COMMAND-STRING keyword
SPAWN function, 121
COMMON-AST-ADDRESS parameter, 20
COMPILE function, 20 to 21,140
COMPILE-FILE function, 21 to 23,23,24
*COMPILE-VERBOSE* variable, 23 to 24
default for : VERBOSE keyword, 22
*COMPILE-WARNINGS* variable, 24 to 25
default for : WARNINGS keyword, 22
Compiled functions, 20 to 21
COMPILEDP function, 20 to 21
Compiler optimizations, 22
: CONC-NAME keyword
DEFINE-ALIEN-STRUCTURE macro,

C onstructor function

naming, 35
specifying an initial value, 36
: CONSTRUCTOR keyword
DEFINE-ALIEN-STRUCTURE macro,
CONTINUE function, 25

exiting the break loop, 14
Control characters
binding to functions, 12 to 13
returning information about bindings, 72 to 73
unbinding from functions, 140
Controlling output
from Debugger, Stepper, and Tracer, 28 to 29
Copier function, naming, 35
: CO P IER keyword
DEFINE-ALIEN-STRUCTURE macro, 35
CPU time
displaying, 127
garbage collection, 69 to 70
getting elapsed, 70 to 71
: CP U -LIM IT keyword
G E T -P R O C E SS-IN F O R M A T IO N function,
: C P U -T IM E keyword

GET-PROCESS-INFORMATION function,

lndex-2

Ctrl/s and BIND-KEYBOARD-FUNCTION, 13
Current package, 103
: CURRENT-PRIORITY keyword

GET-PROCESS-INFORMATION function, 75
: CURRENT-PRIVILEGES keyword
GET-PROCESS-INFORMAT ION function, 75
: CYLINDERS keyword
GET-DEVICE-INFORM ATION function, 63

Calling back to LISP functions, 96 to 98
Calling functions asynchronously, 12
CALLOUT macro,

: CREATION-DATE keyword
GET-FILE-INFORM ATION function, 66
C R IT IC A L -S E C T IO N macro, 26
Ctrl/C, 1,16
Ctrl/Q and bind - keyboard-function , 13

: D-FLOATING keyword
alien structure field type, 36
Data types
arrays, 95
character names, 17 to 18
checking, 39
conversions, 35
LISP, 32, 39
packages, 6, 7, 8
pathnames, 48
strings, 95
VAX, 40
vectors, 95
: DCL-SYMBOLS keyword
SPAWN function, 121
DEBUG function, 27
binding control character to, 12
: DEBUG keyword
*ERROR-ACTION* variable, 54
DEBUG-CALL function, 27 to 28
: DEBUG-IF keyword
TRACE macro, 129
*DEBUG-PRINT-LENGTH* variable, 28 to 29
*DEBUG-PRINT-LEVEL* variable, 29 to 30
Debugger
controlling output, 28 to 29, 29 to 30
invoking, 27, 129
: DECWINDOWS keyword
TRANSLATE-LOGICAL-NAME function, 139
Default directory
changing with SETF macro, 30 to 32
: DEFAULT keyword
DEFINE-ALIEN-STRUCTURE macro, 36
DEFAULT-DIRECTORY function, 30 to 32
S e e also *DEFAULT-PATHNAME-DEFAULTS*
variable
: DEFAULT-EXTENSION keyword
GET-FILE-INFORM ATION function, 66
: DEFAULT-PAGE-FAULT-CLUSTER keyword
GET-PROCESS-INFORMATION function, 75
*DEFAULT-PATHNAME-DEFAULTS* variable
default directory, 30 to 32
DIRECTORY function, 48
filling file specification components, 21
resuming a suspended system, 125
: DEFAULT-PRIVILEGES keyword
GET-PROCESS-INFORMATION function, 75
D EFIN E—A LIEN —F IE L D —TYPE macro, 32
DEFINE-ALIEN-STRUCTURE macro, 34 to 37
options (table), 34

DEFINE-EXTERNAL-ROUTINE macro,

14, 37 to

40
argument options (table), 40
routine options (table), 38
DEFINE-FORM AT-DIRECTIVE macro, 41 to 42
DEFINE-GENERALIZED-PRINT-FUNCTION
macro, 43 to 44, 62
D EFIN E-L IST -P R IN T -FU N CT IO N macro, 44 to

warnings,
ERROR function,

DELETE-PACKAGE function, 46
DESCRIBE function, 46 to 47
Descriptor (: DESCRIPTOR)
argument-passing mechanism, 40
Device, getting information, 63 to 65
: D EV ICE-CH A RA CTERISTICS keyword
GET-DEVICE-INFORM ATION function, 63
: D EV ICE-CLA SS keyword
GET-DEVICE-INFORMATION function, 63
: DEVICE-DEPENDENT-0 keyword
GET-DEVICE-INFORMATION function, 63
: DEVICE-DEPENDENT-1 keyword
GET-DEVICE-INFORM ATION function, 63
: DEVICE-NAME keyword
GET-DEVICE-INFORM ATION function, 64
: DEVICE-TYPE keyword
GET-DEVICE-INFORM ATION function, 64
: DIO-COUNT keyword
GET-PROCESS-INFORMATION function, 75
: DIO-OPERATIONS keyword
GET-PROCESS-INFORMATION function, 75
: DIO-QUOTA keyword
GET-PROCESS-INFORMATION function, 75
DIRECTORY function, 48 to 49
DO-ALL-SYMBOLS macro, 7, 8
DO-SYMBOLS macro, 7, 8
Documentation string, 35, 39
D ESCR IB E function, 46
DRIBBLE function, 50
: DURING keyword
TRACE macro, 130
Dynamic memory, 113, 124
DYNAMIC-SPACE-RATIO function, 51

E____________________________________
: ECHO keyword
GET-TERMINAL-MODES function,
SET-TERMINAL-MODES function,
ED function, 51 to 53

Ephemeral garbage collector, 60
status, 113
Error
messages
Compiler, 24
warnings, 24 to 25
types

78
116

binding control character to, 12
Editor
invoking, 51 to 53
invoking with control character, 12
End logical block directive, 57
End position
A L IE N -F IE L D function, 4
field, 36
: END—OF—F IL E —BLOCK keyword
GET-FILE-INFORM ATION function, 66
ENLARGE-BINDING-STACK function, 53
ENLARGE-LISP-MEMORY function, 53
: ENQUEUE-COUNT keyword
GET-PROCESS-INFORMATION function, 75
: ENQUEUE-QUOTA keyword
GET-PROCESS-INFORMATION function, 75
: ENTRY-POINT keyword
DEFINE-EXTERNAL-ROUTINE macro, 38

148 to 149
144

Error handler
creating, 144 to 145
error m essages, 109 to 110
*ERROR-ACTION* variable, 54 to 55
invoking, 148 to 149
UNIVERSAL-ERROR-HANDLER function,

143

to 144
: ERROR keyword
E X IT function, 55
*ERROR-ACTION* variable, 54 to 55
WARN function, 148
: ERROR-COUNT keyword
GET-DEVICE-INFORM ATION function, 64
*ERROR—OUTPUT* variable
PRINT-SIGNALED-ERROR function, 109

Error-signaling functions,
: ESCAPE keyword

144

GET-TERMINAL-MODES function, 78
SET-TERMINAL-MODES function, 117
: EVENT-FLAG-WAIT-MASK keyword
GET-PROCESS-INFORMATION function,
E X IT function, 55
:E X IT keyword
*ERROR-ACTION* variable, 54
: EXPIRATION-DATE keyword

GET-FILE-INFORMATION function, 66
Extended attribute block (XAB), 65
External routine
access method, 40
calling, 14
checking data types, 39
checking status return, 38
defining, 37
entry point, 38
image name, 38
name, 38
options, 38
result data type, 39

F_______________________
:F-FLOA TIN G keyword

alien structure field type, 35
Fast-loading file
loading, 91
locating, 91
producing, 21, 22
Field
accessing, 3
end position, 4, 36
gaps, 37
initial value, 36
name, 4, 35
options
(table), 36
repeating, 36
start position, 4, 36
type, 4, 35

ln dex-3

Field
type (cont'd.)
defining, 32
predefined, 32
File a cc e ss block (FAB), 65
: F I L E keyword
DEFINE-EXTERNAL-ROUTINE macro, 38
Files
getting information, 65 to 67
Fill directive, 58
: FIR ST -F R EE-B Y T E keyword
GET-FILE-INFORM AT ION function, 66
:F IR ST -FR EE-P O -P A G E keyword
GET-PROCESS-INFORMATION function, 75
:F IR S T -F R E E -P 1-PAGE keyword
GET-PROCESS-INFORMATION function, 75
: F IX ED -C O N T R O L-SIZE keyword
GET-FILE-INFORM ATION function, 66
FORCE-INTERRUPT-FUNCTION function, 56
Format directives
provided with VAX LISP, 56 to 58
FORMAT function, 56 to 58
break-loop m essages, 14
~ ! directive, 57
~ . directive, 57
directive, 58
- / F I L L / directive, 58
~ I directive, 58
-/L IN EA R / directive, 58
-/TABULAR/ directive, 58
-w directive, 57
warning m essages, 148
: FREE-BLOCKS keyword
GET-DEVICE-INFORM ATION function, 64
: FUNCTION keyword
ED function, 52
Functions
ABORT, 1 to 2
AREA-SEGMENT-LIMIT, 9
AREA-SEGMENTS, 9 to 10
ATTACH, 10 to 11
BIND-KEYBOARD-FUNCTION, 12 to 13
BREAK, 13 to 14, 25
CHAR—NAME—TABLE, 17 to 18
COMPILE, 20 to 21
COM PILE-FILE, 21 to 23, 23, 24
compiled, 20 to 21
COMPILEDP, 20 to 21
CONTINUE, 25
exiting the break loop, 14
DEBUG, 27
DEBUG-CALL, 27 to 28
DEFAULT-DIRECTORY, 30 to 32
definition
editing, 140
pretty-printing, 102 to 103
DELETE-PACKAGE, 46
DESCRIBE, 46 to 47
DIRECTORY, 48 to 49
DRIBBLE, 50
DYNAMIC-SPACE-RATIO, 51
ED, 51 to 53
ENLARGE-BINDING-STACK, 53
ENLARGE-LISP-MEMORY, 53
EXIT, 55
FORMAT, 56 to 58
break-loop m essages, 14

Index-4

Functions (cont'd.)
GC, 58 to 59
GC-COUNT, 59 to 60
GC-MODE, 60 to 61
GENERALIZED-PRINT-FUNCTIONENABLED-P, 62 to 63
GET-DEVICE-INFORMATION, 63 to 65
GET-FILE-INFORMATION, 65 to 67
GET-GC-REAL-TIME, 67 to 68
GET-GC-RUN-TIME, 69 to 70
GET-INTERNAL-RUN-TIME, 70 to 71
GET-INTERRUPT-FUNCTION, 71 to 72
GET-KEYBOARD-FUNCTION, 12, 72 to 73
GET-PROCESS-INFORMATION, 73 to 78
GET-TERMINAL-MODES, 78 to 79
GET-VMS-MESSAGE, 80
HASH-TABLE-REHASH-SIZE, 81
HASH-TABLE-REHASH-THRESHOLD, 82
HASH-TABLE-SIZE, 83
HASH-TABLE-TEST, 84
IMMEDIATE-OUTPUT-P, 85
INSPECT, 85 to 86
interpreted, 20
keyboard, creating, 12 to 13
L IN E -P O SIT IO N , 90
LISTEN2, 91
LOAD, 91 to 92
LONG-SITE-NAME, 93
MACHINE-INSTANCE, 93 to 94
MACHINE-VERSION, 94
MAKE-ARRAY, 95 to 96
MAKE-CALL-BACK-ROUTINE, 96 to 98
MEMORY-ALLOCATION-EXTENT, 99
NREAD-LINE, 100
OPEN-STREAM-P, 100
PP R IN T -D E F IN IT IO N , 102 to 103
P P R IN T -P L IST , 103 to 105
PRINT-SIGNALED-ERROR, 109 to 110
REQUIRE, 111 to 112
RIGHT-MARGIN, 112
ROOM, 113 to 115
ROOM-ALLOCATION, 115 to 116
SET-TERMINAL-MODES, 116 to 118
SHORT-SITE-NAME, 118 to 119
SOFTWARE-VERSION-NUMBER, 119
SOURCE-CODE, 120
SPAWN, 120 to 122
SUSPEND, 124 to 126
TRANSLATE-LOGICAL-NAME, 138 to 140
UNBIND-KEYBOARD-FUNCTION, 12, 140
UNCOMPILE, 140 to 141
UNIVERSAL-ERROR-HANDLER, 143 to 144
WARN, 148 to 149

G_______________________
: G-FLOATING keyword
alien structure field type,

Gaps, 37
Garbage collection
area segments, 9 to 10
counting, 59
CPU time, 69 to 70
displaying time, 127
dynamic space, 51
elapsed time, 67 to 68
ephemeral, 60

Garbage collection (cont'd.)
frequency of, 51
full, 60

: IMAGE-NAME keyword

invoking, 58 to 59
m essages, 61,101,105
modes, 60 to 61
static memory, 95
status, 113
stop-and-copy, 51
GC function, 58 to 59
GC-COUNT function, 59 to 60
GC-MODE function, 60 to 61
*GC-VERBOSE* variable, 59, 61
GENERALIZED—P R IN T —FUNCTION—ENABLED—P
function, 62 to 63
GET-DEVICE-INFORMATION function, 63 to 65
keywords (table), 63 to 64
GET-FILE-INFORM ATION function, 65 to 67
keywords (table), 66
GET-GC-REAL-TIME function, 67 to 68
GET-GC-RUN-TIME function, 69 to 70
GET-INTERNAL-RUN-TIME function, 70 to 71
GET-INTERRUPT-FUNCTION function, 71 to 72
GET-KEYBOARD-FUNCTION function, 12,72 to

73
GET-PROCESS-INFORMATION function,

73 to

78
keywords (table), 74 to 77
GET-TERMINAL-MODES function, 78 to 79
keywords (table), 78 to 79
GET-VMS-MESSAGE function, 80
: GLOBAL-PAGES keyword
GET-PROCESS-INFORMATION function, 75
: GROUP keyword
GET-FILE-INFORM ATION function, 66
GET-PROCESS-INFORMATION function, 75
TRANSLATE-LOGICAL-NAME function, 139

argument-passing mechanism, 40
85
Indentation directive, 58
Input access (: IN), 40
: IN P U T - F IL E keyword
SPAWN function, 121
Input-output access (: IN-OUT), 40
IN S P E C T function, 85 to 86
IN S T A T E -IN T E R R U P T -F U N C T IO N function, 71,
86
IN T E R N A L -T IM E -U N IT S -P E R -S E C O N D constant,
67, 69, 70
Interpreted function definition
restoring, 140 to 141
Interpreted functions, 20
Interrupt functions
blocking, 26
forcing, 56
getting information, 71 to 72
instating, 86 to 90
suspending, 125
uninstating, 142 to 143
Interrupt levels
51
12, 73

J________________________
: JOB-SUBPROCESS-COUNT keyword
GET-PROCESS-INFORMATION function,

K________________________
Keyboard functions
creating; 12 to 13
getting information about, 72 to 73
interrupt level, 12
accessing, 73
specifying, 13
passing arguments to, 13

L________________________
: LEVEL keyword

I___________________________
I/O functions
IMMEDIATE-OUTPUT-P, 85
L IN E -P O SIT IO N , 90
LISTEN2, 91
NREAD-LINE, 100
OPEN-STREAM-P, 100
RIGHT-MARGIN, 112
: IF -D O E S-N O T -E X IST keyword
LOAD function, 92

IM M ED IA TE -O U TPU T-P function,

for the ED function,
keyboard functions,

H________________________
: H-FLOATING keyword
alien structure field type, 36
: HALF-DUPLEX keyword
GET-TERMINAL-MODES function, 79
SET-TERMINAL-MODES function, 117
Hash tables
comparing keys, 84
initial size, 83
rehash size, 81
rehash threshold, 82
HASH-TABLE-REHASH-SIZE function, 81
HASH-TABLE-REHASH-THRESHOLD function,
H A SH -TA BLE-SIZE function, 83
HASH-TABLE-TEST function, 84
Hibernation state, 120

GET-PROCESS-INFORMATION function,
: IM AGE-PRIV ILEGES keyword
GET-PROCESS-INFORMATION function,
immediate value (: VALUE)

BIND-KEYBOARD-FUNCTION function, 12
INSTATE-INTERRUPT-FUNCTION function,

87
Lexical environment
Stepper, 123
Tracer, 129
L IN E - P O S IT IO N function,

Linear directive, 58
LISP, exiting, 55
: L IS P - T Y P E keyword
DEFINE-EXTERNAL-ROUTINE macro,
M A K E-CALL-BACK -ROU TIN E function,

40
98

List-print function, 44
LISTEN2 function, 91
Listing file, producing, 21
: L IS T IN G keyword
COM PILE-FILE function,
LOAD function, 91 to 92

Index-5

* LOAD-VERBOSE* variable
load m essage, 92
: LOCAL-EVENT-FLAGS keyword
GET-PROCESS-INFORMATION function,

N_______________________
75

Logical name table, 138
Logical names, 138 to 140
translating, 93
: LOGICAL-NAMES keyword
SPAWN function, 121

M_______________________
: MACHINE-CODE keyword
CO M PILE-FIL E function, 22
MACHINE-INSTANCE function, 93 to 94
MACHINE-VERSION function, 94
Macros
CATCH-ABORT, 16
DEFINE-FORMAT-DIRECTIVE, 41 to 42
DEFINE-GENERALIZED-PRINT-FUNCTION,
43 to 44
D EFIN E-LIST-PR IN T-FU N CTIO N , 44 to 45
STEP, 123
TIME, 127
TRACE, 128 to 136
UNDEFINE-LIST-PRINT-FU NCTION, 142
W ITH-GENERALIZED-PRINT-FUNCTION,
43, 149 to 150
MAKE-ARRAY function, 95 to 96
MAKE-CALL-BACK-ROUTINE function, 96 to 98
MAKE-HASH-TABLE function, 81,84
: MAX-BLOCKS keyword
GET-DEVICE-INFORM ATION function, 64
: MAX-FILES keyword
GET-DEVICE-INFORMATION function, 64
: MAX-RECORD-SIZE keyword
GET-FILE-INFORM ATION function, 66
: MECHANISM keyword
DEFINE-EXTERNAL-ROUTINE macro, 40
MAKE-CALL-BACK-ROUTINE function, 97
: MEMBER keyword
GET-FILE-INFORM ATION function, 66
GET-PROCESS-INFORMATION function, 75
Memory, 113 to 115
dynamic, 113, 124
management, 51
read-only, 113, 124
static, 95, 113, 124
MEMORY-ALLOCATION-EXTENT function, 99
Miser mode, 107 to 108

99, 111

Modules, 99
loading, 111 to 112
: MOUNT-COUNT keyword
GET-DEVICE-INFORM ATION function, 64
: MOUNTED-VOLUMES keyword
GET-PROCESS-INFORMATION function, 75
Multiline mode new line directive, 58

Index-6

o________________

: LOGICAL-VOLUME-NAME keyword
GET-DEVICE-INFORM ATION function, 64
: LOGIN-TIME keyword
GET-PROCESS-INFORMATION function, 75
LONG-SITE-NAME function, 93
: LONGEST-RECORD-LENGTH keyword
GET-FILE-INFORM ATION function, 66

* MODULE—D IR E C T O R Y * variable,

: NEXT-DEVICE-NAME keyword
GET-DEVICE-INFORM ATION function,
NREAD-LINE function, 100

: OCCURS keyword
DEFINE-ALIEN-STRUCTURE macro, 36
: OFFSET keyword
DEFINE-ALIEN-STRUCTURE macro, 37
: OPEN-FILE-COUNT keyword
GET-PROCESS-INFORMATION function, 76
: OPEN-FILE-QUOTA keyword
GET-PROCESS-INFORMATION function, 76
OPEN-STREAM-P function, 100
: OPERATION-COUNT keyword
GET-DEVICE-INFORM ATION function, 64
: O P T IM IZE keyword
CO M PILE-FIL E function, 22
: ORGANIZATION keyword
GET-FILE-INFORM ATION function, 66
: OUTPUT-FILE keyword
CO M PILE-FIL E function, 22
SPAWN function, 121
: OWNER-PID keyword
GET-PROCESS-INFORMATION function, 76
: OWNER-UIC keyword
GET-DEVICE-INFORM ATION function, 64

P_______________________
Packages, 6, 7, 8
accessible, 103
current, 7, 8,103
: PAGE-FAULTS keyword
GET-PROCESS-INFORMATION function, 76
: PAGE-FILE-COUNT keyword
GET-PROCESS-INFORMATION function, 76
: PAGE-FILE-QUOTA keyword
GET-PROCESS-INFORMATION function, 76
: PAGES-AVAILABLE keyword
GET-PROCESS-INFORMATION function, 76
: PARALLEL keyword
SPAWN function, 121
: PASS-ALL keyword
GET-TERMINAL-MODES function, 79
SET-TERMINAL-MODES function, 117
Pass-all mode, 117
: PASS-THROUGH keyword
GET-TERMINAL-MODES function, 79
SET-TERMINAL-MODES function, 117
Pass-through mode, 116
Pathnames
default directory, 30 to 32
DIRECTORY function, 48 to 49
:P ID keyword
GET-DEVICE-INFORM ATION function, 64
GET-PROCESS-INFORMATION function, 76
: P ID - O F —PARENT keyword
GET-PROCESS-INFORMATION function, 76
: POINTER keyword
alien structure field type, 36
: POST-D EBU G-IF keyword
TRACE macro, 129
*POST-GC-M ESSAGE* variable, 61,101 to 102

: PO ST-PRIN T keyword
TRACE macro, 129
P P R IN T -D E F IN IT IO N function, 102 to 103
P P R IN T -P L IS T function, 103 to 105
: PRE-DEBUG-IF keyword
TRACE macro, 129
*PRE-GC-MESSAGE* variable, 61,105 to 106
: PRE-PRIN T keyword
TRACE macro, 129
Predicate function, naming, 35
: PREDICATE keyword
DEFINE-ALIEN-STRUCTURE macro, 35
Pretty-printing
abbreviating output by lines, 106 to 107
controlling margins, 108 to 109
function definitions, 102 to 103
miser mode, 107 to 108
property lists, 103 to 105
right margin, 112
Print function, 35
: PRINT keyword
LOAD function, 92
TRACE macro, 129
*PR IN T-ESCA PE* variable, 57
: PRINT-FUNCTION keyword
DEFINE-ALIEN-STRUCTURE macro, 35
*PRINT-LENGTH* variable, 57
* p r i n t - l e v e l * variable, 57
*P R IN T —L IN E S* variable, 57, 106 to 107
*P R IN T —MISER-W IDTH* variable, 107 to 108
*PRIN T-PRETTY * variable, 57
*PRINT-RIGHT-M ARGIN* variable, 108 to 109
PRINT-SIGNALED-ERROR function, 109 to 110
*PRINT-SLOT-NAMES-AS-KEYWORDS* variable,
110 to 111
Process
connecting to, 10
getting information, 73 to 78
identification, 11
: PROCESS keyword
TRANSLATE-LOGICAL-NAME function, 139
: PROCESS-CREATION-FLAGS keyword
GET-PROCESS-INFORMATION function, 76
: PROCESS-IN DEX keyword
GET-PROCESS-INFORMATION function, 76
: p r o c e s s - n am e keyword
GET-PROCESS-INFORMATION function, 76
SPAWN function, 122
Prompt, changing top-level, 127 to 128
Property lists, pretty-printing, 103 to 105
: PROTECTION keyword
GET-FILE-INFORM ATION function, 66
PROVIDE function, 111

R_______________________
: READ-ONLY keyword
DEFINE-ALIEN-STRUCTURE macro, 36
Read-only memory, 113,124
Real time
displaying, 127
garbage collection, 67 to 68
: RECORD-ATTRIBUTES keyword
GET-FILE-INFORM ATION function, 66
: RECORD-FORMAT keyword
GET-FILE-INFORM ATION function, 66

: R E C O R D - S IZ E

keyword

GET-DEVICE-INFORMATION function, 64
Reference (: REFERENCE)
argument-passing mechanism, 40
: REFERENCE-COUNT keyword
GET-DEVICE-INFORMATION function, 64
REQUIRE function, 99, 111 to 112
: RESULT keyword
DEFINE-EXTERNAL-ROUTINE macro, 39
MAKE-CALL-BACK-ROUTINE function, 98

/RESUME qualifier, 124
: R EV ISIO N keyword
GET-FILE-INFORM ATION function, 66
: REV ISION -DATE keyword
GET-FILE-INFORM ATION function, 66
RIGHT-MARGIN function, 112
ROOM function, 113 to 115,115
ROOM-ALLOCATION function, 115 to 116
: ROOT-DEVICE-NAME keyword
GET-DEVICE-INFORM ATION function, 64

Routine argument,

s__________________
: SE C T O R S keyword
G E T -D E V IC E -IN F O R M A T IO N function,
: S E L E C T IO N keyword

alien structure field type, 36
: SERIAL-NUMBER keyword
GET-DEVICE-INFORM ATION function, 64
SET-TERMINAL-MODES function, 79, 116 to 118
SETF macro
A LIEN -F IELD function, 2, 3
SHORT-SITE-NAME function, 118 to 119
: SIGNED-IN TEGER keyword
alien structure field type, 35
: S I T E - S P E C I F IC keyword
GET-PROCESS-INFORMATION function, 76
SOFTWARE-VERS ION-NUMBER function, 119

Source file
compiling, 21
loading, 91
locating, 91
SOURCE-CODE function, 120
SPAWN function, 120 to 122
* STANDARD—OUTPUT * variable

LOAD function, 92
P P R IN T -D E F IN IT IO N function,
P P R IN T -P L IS T function, 104

102

Start position
A L IE N -F IE L D function, 4
field, 36
: STATE keyword
GET-PROCESS-INFORMATION function,
: ST A T IC keyword

See : ALLOCATION keyword
Static memory, 95,113,124
Status code, 80
: STATUS keyword
GET-PROCESS-INFORMATION function,

Status return, 38, 55
STEP macro, 123
* STEP -ENVIRONMENT* variable,
*STEP-FORM* variable, 124
: S T E P - IF keyword
TRACE macro, 129

123 to 124

Index-7

Stepper
Controlling output, 28 to 29, 29 to 30
invoking, 123, 129
lexical environment, 123
Stop-and-copy garbage collector, 60
Streams
buffered output, 85
resuming, 125
testing for end-of-file, 91
: STRING keyword
alien structure field type, 35
Strings, creating, 95
Subprocess, 120
: SUBPROCESS-COUNT keyword
GET-PROCESS-INFORMATION function, 76
: SUBPROCESS-QUOTA keyword
GET-PROCESS-INFORMATION function, 76
: SUCCESS keyword
E X IT function, 55
: S U P P R E SS-IF keyword
TRACE macro, 129
SUSPEND function, 124 to 126
Suspended systems, 124 to 126
CPU time, 69
real time, 67
resuming, 124
System identification (SID) register, 94
: SYSTEM keyword
TRAN SLATE-LOGICAL-NAME function, 139

T______________________
Tabular directive, 58
: TERMINAL keyword
GET-PROCESS-INFORMATION function, 76
Terminal, getting information, 78 to 79
* TERMINAL-10* variable
BIND-KEYBOARD-FUNCTION function, 12
GET-TERMINAL-MODES function, 78
SET-TERMINAL-MODES function, 116
: TERMINATION-MAILBOX keyword
GET-PROCESS-INFORMATION function, 76
TIME macro, 127
: TIMER-QUEUE-COUNT keyword
GET-PROCESS-INFORMATION function, 76
: TIMER-QUEUE-QUOTA keyword
GET-PROCESS-INFORMATION function, 76
* TOP-LEVEL-PROMPT * variable, 127 to 128
TRACE macro, 128 to 136
* TRACE-CALL* variable, 135,137
* TRACE-VALUES* variable, 136,137 to 138
Tracer
controlling output, 28 to 29, 29 to 30
enabling, 128 to 136
lexical environment, 129
options (table), 129 to 130
: TRACKS keyword
GET-DEVICE-INFORM ATION function, 64
: TRANSACTION-COUNT keyword
GET-DEVICE-INFORMATION function, 64
TRANSLATE-LOGICAL-NAME function, 138 to

140
Type specifier
CALL-BACK-ROUTINE, 14
: TYPE-AHEAD keyword
GET-TERMINAL-MODES function,
SET-TERMINAL-MODES function,

lndex-8

79
117

: TYPE-CHECK keyword
DEFINE-EXTERNAL-ROUTINE macro,

u_________________
: UAF-FLAGS keyword
GET-PROCESS-INFORMATION function, 76
: U IC keyword
GET-FILE-INFORM ATION function, 66
GET-PROCESS-INFORMATION function, 76
UNBIND-KEYBOARD-FUNCTION function, 12, 140
UNCOMPILE function, 140 to 141
U N D EFIN E-LIST-PRIN T-FU N CTION macro,

142
UNINSTATE-INTERRUPT-FUNCTION function,

142
:UNIT keyword
GET-DEVICE-INFORM ATION function, 64
UNIVERSAL-ERROR-HANDLER function, 143 to

144
* UNIVERSAL-ERROR-HANDLER* Variable, 143,
144 to 145
: UNSIGNED-INTEGER keyword
alien structure field type, 35
: USERNAME keyword
GET-PROCESS-INFORMATION function, 76

V________________________
: VALUE keyword
ED function, 52

Variables
*COMPILE-VERBOSE*, 23 to 24
*COMPILE-WARNINGS*, 24 to 25
*DEBUG-PRINT-LENGTH*, 28 to 29
*DEBUG—P R IN T —LEVEL*, 29 to 30
*DEFAULT-PATHNAME-DEFAULTS *, 30 to
32
*ERROR—ACTION*, 54 to 55
*GC-VERBOSE*, 61
*MODULE-DIRECTORY*, 99
*POST-GC-MESSAGE*, 101 to 102
*PRE-GC-MESSAGE*, 105 to 106
*P R IN T —LIN ES*, 106 to 107
*P R IN T —MISER-WIDTH*, 107 to 108
*PRINT-RIGHT-M ARGIN*, 108 to 109
*PRINT-SLOT-NAMES-AS-KEYWORDS*, 110
to 111
* STEP-ENVIRONMENT*, 123 to 124
* STEP-FORM*, 124
* TERMINAL-IO*
and B IN D -K EY B O A R D -FU N CTIO N function,

12
* TOP-LEVEL-PROMPT*, 127 to 128
* TRACE-CALL*, 137
*TRACE-VALUES*, 137 to 138
* UNIVERSAL-ERROR-HANDLER*, 144 to
145
: VARYING-STRING keyword
alien structure field type, 35
: VAX-TYPE keyword
MAKE-CALL-BACK-ROUTINE function, 98
Vectors, creating, 95
: VERBOSE keyword
COM PILE-FILE function, 22, 23
LOAD function, 92

: V E R SIO N -L IM IT keyword
GET-F I L E - INFORMAT ION function, 66
: VIRTUAL-ADDRESS-PEAK keyword
GET-PROCESS-INFORMATION function, 77

VMS hibernation state,

VMS-DEBUG function, 145
: VOLUME-COUNT keyword
GET-DEVICE-INFORMATION function,
: VOLUME-NAME keyword
GET-DEVICE-INFORM ATION function,
: VOLUME-NUMBER keyword
GET-DEVICE-INFORM ATION function,
: VOLUME-PROTECTION keyword
GET-DEVICE-INFORM ATION function,

64
64
64
64

w_________________
WAIT function, 146
WARN function, 144,148 to 149
: w a r n in g keyword
E X IT function, 55
: WARNINGS keyword
COM PILE-FILE function, 22,24

W ITH-GENERALIZED-PRINT-FUNCTION macro,
43, 149 to 150
: WORKING-SET-AUTHORIZED-EXTENT keyword
GET-PROCESS-INFORMATION function, 77
:WORKING-SET-AUTHORIZED-QUOTA keyword
GET-PROCESS-INFORMATION function, 77
: WORKING-SET-COUNT keyword
GET-PROCESS-INFORMATION function, 77
: WORKING-SET-DEFAULT keyword
GET-PROCESS-INFORMATION function, 77
: WORKING-SET-EXTENT keyword
GET-PROCESS-INFORMATION function, 77
: WORKING-SET-PEAK keyword
GET-PROCESS-INFORMATION function, 77
: WORKING-SET-QUOTA keyword
GET-PROCESS-INFORMATION function, 77
: W ORK IN G-SET-SIZE keyword
GET-PROCESS-INFORMAT ION function, 77
: WRAP keyword
GET-TERMINAL-MODES function, 79
SET-TERMINAL-MODES function, 117
Write directive, 57

Window streams, resuming, 125

lndex-9

HOW TO O R D ER ADDITIONAL DOCUMENTATION
From

C all

603-884-6660
Alaska, Hawaii,
or New Hampshire
Rest of U.S.A.
and Puerto Rico1

W rite

Digital Equipment Corporation
P.O. Box CS2008
Nashua NH 03061

800-DIGITAL

1P r e p a id o r d e r s f r o m P u e r t o R ico, c a ll D ig it a l’
s lo c a l s u b s id ia r y (809-754-7575)

Canada

800-267-6219
(for software
documentation)

Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: Direct Order Desk

613-592-5111
(for hardware
documentation)

Internal orders
(for software
documentation)

—

Internal orders
(for hardware
documentation)

DTN: 234-4323
508-351-4323

Software Supply Business (SSB)
Digital Equipment Corporation
Westminster MA 01473
Publishing & Circulation Services (P&CS)
NR03-1/W3
Digital Equipment Corporation
Northboro MA 01532

Reader’s Comments

VAX LISP/VMS Object Reference Manual

AA-MK72A-TE

Your comments and suggestions will help us improve the quality of our future documen
tation. Please note that this form is for comments on documentation only.

I rate this m anual’
s:
Accuracy (product works as described)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

Good

Fair

Poor

□
□
□
□
□
□
□
□

What I like best about this manual:
What I like least about this manual:
My additional comments or suggestions for improving this manual:

I found the following errors in this manual:
Page
Description

Please indicate the type of user/reader that you most nearly represent:
□ Administrative Support
□ Computer Operator
□ Educator/Trainer
□ Programmer/Analyst
□ Sales

□ Scientist/Engineer
□ Software Support
□ System Manager
□ Other (please specify)

Name/Title ___

Dept.

Company _____

_______ Date

Mailing Address
Phone
10/87

______

—

Do Not T e a r — Fold Here and Ta pe

HIDDEN

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO .33 M A Y N A R D MASS.
POSTAGE W IL L BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
PKO3-1/30D
129 PARKER STREET
MAYNARD, MA 01754-2198

Do Not T e ar — Fold Here

v_.