VAX LISP/VMS Release Notes
March 1990
This file contains the release notes for VAX LISP/VMS Version
3.1. It describes additions and changes to VAX LISP/VMS and sum-
marizes any known restrictions and limitations in VAX LISP/VMS
Version 3.1.
Operating System and Versions:VMS Version 5.2, VMS Version 5.3
Software Version: VAX LISP/VMS Version 3.1
Digital Equipment Corporation
________________________
March 1990
The information in this document is subject to change without
notice and should not be construed as a commitment by Digital
Equipment Corporation. Digital Equipment Corporation assumes no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a
license and may be used or copied only in accordance with the
terms of such license.
No responsibility is assumed for the use or reliability of
software on equipment that is not supplied by Digital Equipment
Corporation or its affiliated companies.
Restricted Rights: Use, duplication or disclosure by the U.S.
Government is subject to restrictions as set forth in subpara-
graph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013.
__________
Copyright ©1990 Digital Equipment Corporation
All rights reserved.
Printed in U.S.A.
The following are trademarks of Digital Equipment Corporation:
AI VAXstation PDP VAX LISP/VMS
DEC ULTRIX VAX LISP/ULTRIX
DECnet ULTRIX-11 VAXstation
DECUS ULTRIX-32 VAXstation II
MicroVAX UNIBUS VMS
MicroVAX II VAX
MicroVMS VAX LISP DIGITAL PKO-S1426
This document was prepared using VAX DOCUMENT, Version 1.2
CONTENTS
Preface............................................... v
Chapter 1 ENHANCEMENTS AND TECHNICAL CHANGES............. 1
1.1 Installation....................................... 1
1.2 LISP Development Environment....................... 2
1.2.1 Customization................................... 2
1.2.2 Clipboard....................................... 3
1.2.3 Listener........................................ 3
1.2.4 Listener Stream................................. 6
1.2.5 Tracer.......................................... 6
1.2.6 Debugger........................................ 7
1.2.7 Stepper......................................... 8
1.2.8 Inspector....................................... 8
1.3 Base System........................................ 8
1.4 DECwindows Graphics................................ 11
1.4.1 Software and Hardware Platforms................. 12
1.4.2 DECwindows Version 2 Functions.................. 13
1.4.3 VAX LISP CLX and Public Domain CLX.............. 13
1.4.4 CLX and DECwindows Toolkit Support.............. 19
1.4.5 Window Streams.................................. 23
1.5 VWS Support........................................ 24
1.6 System-Building Utility............................ 24
1.7 ANSI Standard Committee X3J13 Changes to Common
LISP............................................... 25
iii
Chapter 2 RESTRICTIONS AND LIMITATIONS................... 29
2.1 DECwindows Toolkit................................. 29
2.2 DECwindows Interface to VAX LISP................... 31
2.2.1 The Listener.................................... 31
2.2.2 The Inspector................................... 32
2.2.3 The Editor...................................... 32
2.3 The Terminal-Based Editor.......................... 33
2.4 Memory Management.................................. 34
2.5 Callout Facility................................... 34
2.6 Suspending and Resuming............................ 37
2.7 Error Handling..................................... 37
2.8 Compiler........................................... 38
2.9 RECIPE Example..................................... 39
Chapter 3 DOCUMENTATION ERRATA........................... 41
3.1 VAX LISP/VMS System Access Guide................... 41
3.2 VAX LISP/VMS Implementation and Extensions to
Common LISP........................................ 42
3.3 VAX LISP/VMS System-Building Guide................. 43
3.4 VAX LISP/VMS Object Reference Manual............... 44
3.5 VAX LISP/VMS Graphics Programming Guide............ 50
3.6 VAX LISP/VMS Program Development Guide............. 51
iv
EXAMPLES
1 Read-Print Loop................................... 4
2 Read-Print Loop Using READ-EVAL-PRINT-LOOP
Function.......................................... 5
3 :LISP option...................................... 24
4 Hibernating Code.................................. 35
5 Multi-Dimensional Array........................... 36
6 Error Handler..................................... 38
7 Calling-Out and Calling-Back...................... 42
TABLES
1 CLX:LOGICAL-OP Values............................. 17
v
Preface
This document contains the release notes for VAX LISP/VMS Ver-
sion 3.1. It describes additions and changes to VAX LISP/VMS
and summarizes any known restrictions and limitations in VAX
LISP/VMS Version 3.1.
Intended Audience
This document is intended for all VAX LISP users and system
managers.
Structure
This document consists of three chapters:
o Chapter 1 describes technical enhancements for Version 3.1
and fixes for bugs found in Version 3.0.
o Chapter 2 describes restrictions and limitations on Version
3.1.
o Chapter 3 lists errata in Version 3.0 and Version 3.1 docu-
mentation.
Associated Documents
The following documents are relevant to installing and using VAX
LISP/VMS:
o VAX LISP/VMS Program Development Guide
o VAX LISP/VMS Installation Guide
o VAX LISP/VMS DECwindows Programming Guide
o VAX LISP Implementation and Extensions to Common LISP
o VAX LISP/VMS Object Reference Manual
Preface v
o VAX LISP/VMS System-Building Guide
o VAX LISP/VMS Editor Programming Guide
o VAX LISP/VMS System Access Guide
o Common LISP: The Language
vi Preface
CHAPTER 1
ENHANCEMENTS AND TECHNICAL CHANGES
VAX LISP Version 3.1 contains technical enhancements and fixes
for bugs found in Version 3.0. This chapter describes these
technical enhancements and bug fixes.
1.1 Installation
o VAX LISP Version 3.1 uses a new installation procedure. In
the new procedure you can choose the example files you want
to install. You can install any of the following in addition
to the VAX LISP product and library files:
- VAX LISP Example Files
- Portable Common Loops (PCL) Example Files
- RdbLISP Example Files
- Foxglove Example Files
- GKS and GKS3D LISP Bindings
- VAXFlavors Example Files
- VMS Starlet LISP Bindings
o For LISP Version 3.1 you must add a separate command line to
your site-specific system startup file for each example file
that you install (see the VAX LISP/VMS Installation Guide).
Enhancements and Technical Changes 1
o For systems where the working set extent is much smaller than
the process's virtual page usage, there is often excessive
paging. This is due to the larger area of locality that LISP
programs often exhibit compared to traditional programs. You
can reduce this paging by decreasing the number of pages that
are read in on a page fault. You accomplish this by changing
the PFCDEFAULT SYSGEN parameter to be a small value, such as
4. VMS systems normally have a default value of 64. Larger
values of PFCDEFAULT cause many unneeded pages to be read in,
increasing CPU time and disk I/O, and decreasing the number
of things that LISP programs can refer to simultaneously with
a given working set.
1.2 LISP Development Environment
o The VAX LISP Version 3.1 development environment allows more
customization than was allowed in Version 3.0, and contains
changes to the Clipboard, the Listener, the tracer, the
Debugger, the Stepper, and the Inspector.
1.2.1 Customization
o In VAX LISP Version 3.1, all the LISP development environment
utilities can be run independently. You can, for example, run
the Listener in a terminal while running the Inspector on a
DECwindows server.
In VAX LISP Version 3.1, the :INITIAL-STATE attribute-keyword
now applies to all values for the object-keyword argument
to the DECW-UTILS:CUSTOMIZATION function. A value of :OPEN
or :CLOSED may be specified for each utility in the LISP
development environment, giving the individual utilities
open or closed initial states. Save these values with DECW-
UTILS:SAVE-CUSTOMIZATIONS, and the next time you start up the
LISP interface, the utilities for which the :INITIAL-STATE is
closed will not be initialized.
2 Enhancements and Technical Changes
o You can still save customizations for uninitialized utili-
ties. These customizations are ignored until the utilities
are opened.
o The :DEFAULT keyword is now an acceptable value for all
customizations.
o Version 3.0 had a bug that caused the position and state
of the following windows not to be recorded when you saved
customizations. In Version 3.1 this bug has been fixed.
_____________________________________________________________
Utility_______Windows________________________________________
Debugger Calling Stack
Variable Bindings
Debugger Commands
Stepper_______Stepper_Commands_______________________________
1.2.2 Clipboard
o In Version 3.1 the LISP development environment Clipboard
hooks into the DECwindows global Clipboard. LISP objects
copied to the Clipboard are pasted as LISP objects in the
LISP development environment and as their printed representa-
tion (Latin1 text) in other windows.
1.2.3 Listener
o The functions PROMPT and READ-EVAL-PRINT-LOOP have been
exported from the VAX-LISP package to allow user code to
modify the Listener functionality. The READ-EVAL-PRINT-LOOP
function can define a top level interface for a LISP image
built with the System-Building utility. See Section 3.4 for a
display of these functions.
Enhancements and Technical Changes 3
Since the Listener records the location of objects printed in
the Listener, prompting is not the same as printing. You
should use the PROMPT function in the Listener when you
intend to perform a read operation after displaying some
text. Example 1 defines a read-print loop inside an interrupt
function to be used in the Listener; Example 2 defines a
customized read-eval-print loop using the READ-EVAL-PRINT-
LOOP function.
Example 1: Read-Print Loop
Lisp> (defun foo ()
(loop ;;define interrupt loop
(prompt "PROMPT> ") ;;prompt for input
(let ((value (prin1 (read)))) ;;read, print
(if (eq value 'exit) (return)))) ;;check exit condition
(format t "~%Exiting...~%")
(prompt))
FOO
Lisp> (compile 'foo)
FOO compiled
FOO
Lisp> (bind-keyboard-function #\^x #'foo)
T
Lisp> <Ctrl/X>
PROMPT> foo
FOO
PROMPT> bar
BAR
PROMPT> t
T
PROMPT> exit
EXIT
Exiting...
Lisp>
4 Enhancements and Technical Changes
Example 2: Read-Print Loop Using READ-EVAL-PRINT-LOOP Function
Lisp> ;;; Compile top level forms before executing them
(defun maybe-compile-before-eval (form)
(if (atom form)
(eval form)
(funcall (compile nil `(lambda () ,form)))))
MAYBE-COMPILE-BEFORE-EVAL
Lisp> (trace compile)
(COMPILE)
Lisp> (setq *trace-output* *standard-output*) ;so the timings are
#<Display Stream #<Listener>> ;visible here
Lisp> (time (dotimes (i 10000)))
CPU Time: 5.65 sec., Real Time: 9.75 sec.
NIL
Lisp>(read-eval-print-loop "Compile> " :eval #'maybe-compile-before-eval)
Compile> t
T
Compile> (+ 3 4 5)
12
Compile> (time (dotimes (i 10000)))
#15 (COMPILE NIL (LAMBDA NIL (TIME (DOTIMES #))))
#15=> #<Compiled Function #:G755 #x22CE2D>
CPU Time: 0.15 sec., Real Time: 0.16 sec.
NIL
o The Listener Operations menu, like the Trace Commands menu,
has a CLEAR item that clears the Listener window, redisplays
the Lisp> prompt, and reinitializes the Listener stream data
structures. Objects that had been remembered by the Listener
window are released for potential garbage collection.
o The ED item in the Listener's Operations menu now executes
(ED) instead of (ED 'NIL) when there is no selection.
Enhancements and Technical Changes 5
1.2.4 Listener Stream
o In Version 3.1, input focus is automatically set to the
window when appropriate and permissible.
o In the Listener Ctrl/space is bound to a symbol completion
function. Pressing Ctrl/space performs an APROPOS-LIST on
the string of undelimited characters to the left of the text
cursor in the input buffer when the text cursor is at the
end of the buffer. As many unique, succeeding characters as
possible are inserted into the input buffer.
o Pressing Ctrl/? also performs an APROPOS-LIST on the string
of undelimited characters to the left of the text cursor
in the input buffer. If the list has only one element, the
function performs a DESCRIBE on it. Otherwise, the function
displays the APROPOS list.
o In the APROPOS or DESCRIBE dialog boxes, double-clicking on
an object is a shortcut for selecting the object and pressing
the Describe button.
o The input buffer is now completely cleared after an aborted
entry into the Debugger.
o The following bugs have been fixed:
- The bug that prevented you from resizing the history limit
in the Listener and Debug I/O windows.
- The bug that caused a stack overflow when lines were
automatically or manually removed from the Listener
history.
1.2.5 Tracer
The following bug was fixed:
o The bug that kept an old object name in the Trace List after
you loaded a new definition for that object.
6 Enhancements and Technical Changes
1.2.6 Debugger
o The Debug I/O window's Operations menu has a CLEAR item that
clears the Debug I/O window, redisplays the Debug n> prompt,
and reinitializes the Debug I/O stream data structures.
o The ED item in the Debugger's Operations menu executes (ED)
instead of (ED 'NIL) when there is no selection.
o The Version 3.1 caution box displays error messages in a
scrollable region of text in a fixed-width font. You can
scroll through longer error messages that would have been
truncated in Version 3.0 and read (or write) multi-line error
messages in which the error format string depends on the
output being left-justified and fixed-width.
o Three buttons, DEBUG, CONTINUE, and ABORT, appear in a
continuable error caution box. Two buttons, DEBUG and ABORT,
appear in all other error caution boxes. Pressing Return,
selects ABORT for fatal errors and CONTINUE for continuable
errors. Pressing Shift/Return, selects DEBUG.
o The following bug has been fixed:
- The bug that caused recursive entry between the Debugger
and Stepper to destroy the window manager process. In
Version 3.0, the following sequence would have done this:
1. Invoke the DECwindows Debugger from the Listener
2. From the Debugger, invoke the Stepper
3. From the Stepper, invoke the Debugger
4. Quit back to the Listener
Enhancements and Technical Changes 7
1.2.7 Stepper
o The bug that prevented printing of the first Step> prompt in
the terminal interface has been fixed.
1.2.8 Inspector
o The documentation string and constants are now shown for
compiled functions and macros.
o The Remove item in the History window's Commands menu and the
Modify item in the Inspect window's Commands menu are dimmed
when the current selection is text.
o Inspect windows are raised to the top of the window stack
when the Update, Inspect, or Reinspect commands are executed.
o The following bugs have been fixed:
- The bug that allowed the display of large objects in
modal dialog boxes to push the dialog box buttons off
the physical screen, making the buttons inaccessible.
- The bug that corrupted objects in the History window if
they were reinspected after a package change.
- The bug that prevented the reuse of locked windows.
- The bug that made incorrect updates in the History
window.
1.3 Base System
Several enhancements and bug fixes have been made to the VAX
LISP Version 3.1 base system.
o Call-Out support for new VMS Version 5.2 system services: You
can call the following new VMS Version 5.2 system services
from VAX LISP Version 3.1:
- SYS$ABORT_TRANS
8 Enhancements and Technical Changes
- SYS$ABORT_TRANSW
- SYS$ADD_BRANCH
- SYS$ADD_BRANCHW
- SYS$CHANGE_CLASS
- SYS$CREATE_UID
- SYS$DECLARE_RM
- SYS$DECLARE_RMW
- SYS$DEVICE_SCAN
- SYS$EMAA
- SYS$END_TRANS
- SYS$END_TRANSW
- SYS$EVDPOSTEVENT
- SYS$FORGET_RM
- SYS$FORGET_RMW
- SYS$GRANT_LICENSE
- SYS$IMGACT
- SYS$IMGFIX
- SYS$IPC
- SYS$IPCW
- SYS$JOIN_RM
- SYS$JOIN_RMW
- SYS$PARSE_CLASS
- SYS$PROCESS_SCAN
- SYS$RELEASE_LICENSE
- SYS$RUNDWN
Enhancements and Technical Changes 9
- SYS$SETPFM
- SYS$START_BRANCH
- SYS$START_BRANCHW
- SYS$START_TRANS
- SYS$START_TRANSW
o Asynchronous events: You can now call a Wait at the interrupt
level without interfering with a Wait that you called at top
level.
o The following bugs have been fixed for Version 3.1:
- External routines and data: Version 3.0 had a bug that
caused the Reserved Operand Fault and other error messages
with use of the /MEMORY switch with values much greater
than 100,000 blocks.
- The function REMHASH: Version 3.0-A had a bug in which
REMHASH called on hashtables of type EQUAL and EQL failed
to remove objects from the hashtable.
- Arrays of element-type (SIGNED-BYTE n): Loading constant
arrays of element-type (SIGNED-BYTE n) from compiled files
caused an error in Version 3.0.
- The function EXPORT: In Version 3.0, if you had an
internal symbol in a package, FOO::X for example, and
then called
(export 'BAR::X "FOO")
it would perform this operation but not point out the
conflict with the existing symbol in the FOO package.
In Version 3.1., a continuable error is signaled asking
whether you want to call the IMPORT function to bring the
symbol BAR::X into the package FOO.
- The functions COUNT-IF and COUNT-IF-NOT: The functions
COUNT-IF and COUNT-IF-NOT returned NIL when given a null
list. In Version 3.1, they return 0.
10 Enhancements and Technical Changes
- Constant type checking of undefined types in COMPILE-FILE:
In Version 3.0, compiling a file containing the following
code:
(deftype foo () 'fixnum)
(defun try () (the foo 4))
when FOO was not defined as a type in the compiler's
run-time environment caused the compiler to signal an
error saying that FOO is not a type because FOO was passed
as the second argument to TYPEP, which signaled the error
about an undefined type.
- Inline expansions without implicit BLOCK: The file
compiler was not inserting the implicit (BLOCK
<function-name> <function-body>) in the inline expansions
remembered by the compiler. Compiling a file with the
following code:
(proclaim '(inline f))
(defun f (x)
(if (null x) (return-from f 234))
(* x x))
(defun g (y)
(f y))
produced an error while compiling G about F not being a
named block.
1.4 DECwindows Graphics
Access to DECwindows graphics is available from any VMS VAX or
VAXstation on which the LISP runs.
Enhancements and Technical Changes 11
1.4.1 Software and Hardware Platforms
The application you are running is known as the "client" and
the workstation on which the application appears is known as the
"server".
The CLX and XUI Toolkit routines supplied in VAX LISP Version
3.1 call through the VMS Xlib and XUI Toolkit shareable
libraries supplied by VMS on any VAX or VAXstation. The Xlib
libraries for VMS Version 5.2 and Version 5.3 are fundamentally
the same. LISP client applications using only CLX should behave
the same on these two VMS versions.
The XUI Toolkit libraries changed from VMS Version 5.2 to
Version 5.3; the former implementing VMS DECwindows Version
1.1, the latter implementing VMS DECwindows Version 2.0. If you
have an application that works with VAX LISP Version 3.0 and VMS
Version 5.1 or Version 5.2, it should run without modification
on VMS Version 5.3. (Note that you will have to recompile your
UIL sources if you use UIL. See the VMS DECwindows Programming
Documentation Supplement, part of the VMS Version 5.3/VMS
DECwindows Version 2.0 documentation, for more information.)
If you want to use any of the features added to the XUI Toolkit
for DECwindows Version 2.0, you must run your LISP client
application on VMS Version 5.3.
Applications written in VAX LISP Version 3.1 that use DECwindows
graphics should display correctly and work consistently on VAX-
and DECstations running Digital-supplied X servers and window
managers.
You need to be careful, however, in using fonts. Wildcarded
names that resolve to the same font on all VMS servers may
produce a different font on an ULTRIX server. If this happens,
you should name the font you are opening more explicitly. See
the VMS DECwindows Guide to Xlib Programming: MIT C Binding for
a complete list of font names.
12 Enhancements and Technical Changes
1.4.2 DECwindows Version 2 Functions
o VAX LISP Version 3.1 supports a DECwindows interface on VAX
workstations. VAX LISP Version 3.1 runs on VMS Version 5.2
and Version 5.3 with DECwindows Version 1.0 and Version 2.0.
DECwindows Version 2.0 defines some new functions that are
not compatible with DECwindows Version 1.0. For a list of
these functions, see Chapter 2.
o In order for VAX LISP Version 3.1 to support DECwindows
Version 1.0 and Version 2.0, the installation kit
contains two DECwindows UID files. The two files are
LISP$DECWINDOWS-V1.UID and LISP$DECWINDOWS-V2.UID. The
correct UID file for the version of VMS is determined during
VAX LISP initialization. You should not have to reinstall VAX
LISP when upgrading from VMS Version 5.2 to Version 5.3.
1.4.3 VAX LISP CLX and Public Domain CLX
o VAX LISP supports the Common LISP X (CLX) and DECwindows
Toolkit routines (see the VAX LISP/VMS DECwindows Programming
Guide). In implementing VAX LISP's version of CLX, we decided
not to use the public domain implementation (PD CLX) but
to call out to Digital's Xlib implementation (DEC CLX). Our
reasons for the decision were as follows:
- Network independence: If we had chosen to use the public
domain CLX, we would have been required to provide and
support LISP interfaces to all required X11 protocol
transport mechanisms (shared local memory, DECnet TCP/IP,
or whatever might appear in the future). We did not have
the time or expertise to do this. In implementing Xlib,
Digital decided to code Xlib not directly to the network,
but rather to a transport layer, which in turn would
provide "back-ends" to various transport mechanisms. By
coding CLX in terms of Xlib, we could piggyback on this
portability mechanism. Additionally, the interface to the
transport layer is not public or supported, even within
Enhancements and Technical Changes 13
Digital, so we could not have coded directly to it. Our
CLX will communicate with the server as efficiently as
Xlib, including the use of shared memory when running on a
standalone workstation.
- Data integrity between CLX and the XUI Toolkit: Since we
also decided it was necessary to provide access to the
XUI Toolkit routines (the DWT routines in VAX LISP), we
needed to be sure that the Xlib-level functionality (CLX)
was available to DWT programmers who use it for the same
reasons that Xt/Dwt C programmers use Xlib (lower-level
graphics, color allocation, font access, and so on).
Since client-side caching is allowed (for example, Xlib
batching of requests until an implicitly flushing call
or a direct call to XFlush or XSync is made), we were
concerned about possible data integrity problems in a
program intended to combine direct-to-the-wire CLX (like
the PD implementation) and the XUI toolkit.
For example, you could make some DWT (XUI Toolkit) calls
that should change the state of a widget and then call to
a CLX function that asks the server for information about
that widget's window. If the Xlib implementation of those
toolkit calls has not flushed yet and the server has not
yet received the earlier request from the Xlib routine,
you might get into trouble asking the server about that
window. You each have your own connection, so the CLX
request will not cause the DWT connection to flush. You
could therefore get around this problem by explicitly
flushing before each CLX call, but that is inefficient.
Another situation could be trying to have CLX and DWT
code sharing the event queue. We could not do this in LISP
because the toolkit, written in C, already uses its own
structures for this. We use the toolkit structures too,
through Xlib. With our system you could use CLX event
queue functions to write your own event dispatcher for a
toolkit program.
14 Enhancements and Technical Changes
Problems caused by such data inconsistency are very
difficult to understand and work around, especially given
the distributed nature of the problem. We thought it
best to avoid the problem by making CLX and DWT share
the same data structures and connections. When you call
DWT:WIDGET on a widget, you get back a CLX:WINDOW; when
you call DWT:OPEN-DISPLAY you get back a CLX:DISPLAY;
and when you call DWT:NEXT-EVENT, you can parse it with
the CLX:EVENT-* routines. This is analogous to the C
interface, where XtWindow and XtOpenDisplay return Window
and Display structure instance respectively, (where Window
and Display are Xlib, not Xtoolkit, structure types). When
you use the CLX routines to draw graphics into a toolkit
Window widget, the code path you take is the same as the
C programmer's. Since this path is guaranteed to work
correctly in C, it should also work from LISP.
- Robustness and maintenance: Digital's Xlib implementation
gets far more use and formal testing than the PD CLX
implementation or our implementation. As a result, we
have a high degree of confidence in the correctness
of the CLX functions that are direct calls to the Xlib
routines (the great majority of the graphics calls).
We never have to debug code at the protocol level, only
at the LISP and LISP-to-C level, and we do not need to
understand the internal details of the graphics routine or
the protocol request. This leads to more robust and more
easily maintainable code.
- Performance: For the same reasons that it is robust,
Digital's Xlib implementation is well tuned for Digital
hardware and is continually being improved. For most
graphics calls, our CLX implementation pays the penalties
of only a few local variable binds, the foreign-function
callout (which may include some type conversion), a call
to the display-after-function (which any CLX would have to
do), and a value return.
Enhancements and Technical Changes 15
- Availability of Xlib: CLX was initially used for LISP
machines that did not have an Xlib to programmatically
build protocol requests. The homogeneous LISP environment
was not limited by the constraints of LISP on a
traditional architecture. Indeed, in discussion some of
the authors of the CLX specification have agreed that
in a heterogeneous environment in which sharing event
queues and cooperating with a C-based toolkit are real
issues, an implementation in terms of Xlib might be the
best solution.
o DEC CLX differs from PD CLX in the following ways:
- CLX:PROCESS-EVENT accepts only a single function for
the HANDLER argument, not a sequence of handlers. Also
CLX:PROCESS-EVENT can accept an extra keyword, :EVENT,
which lets you specify an object of type DWT:EVENT.
CLX:PROCESS-EVENT processes the event as if it came out
from the event queue. If you use the :EVENT keyword,
then the :TIMEOUT, :PEEK-P, and :DISCARD-P parameters
are ignored.
- CLX:READ-BITMAP-FILE and CLX:WRITE-BITMAP-FILE take extra
arguments that let you read and write to pixmaps as well
as images.
- CLX:DRAW-ARC and CLX:DRAW-ARCS take an optional parameter,
DEGREES-P, which specifies that ANGLE1 and ANGLE2 are in
degrees instead of the default, radians.
- There is only one image structure, CLX:IMAGE. Data
can be extracted from it by CLX:IMAGE-XY-BITMAP-LIST
or CLX:IMAGE-Z-PIXARRAY, depending on the format of
data stored in the image. Use CLX:FREE-IMAGE to free
up the memory of an image returned by CLX:GET-IMAGE or
CLX:CREATE-IMAGE.
- CLX:CREATE-IMAGE requires an extra keyword argument.
This is necessary because the current implementation uses
the Xlib XGetImage routine to allocate the image on the
server, instead of in LISP.
16 Enhancements and Technical Changes
- The DEC CLX CLX:MAKE-VISUAL-INFO function differs from the
PD CLX version. The PD CLX function is a default Common
LISP constructor for the VISUAL-INFO structure type and
accordingly takes keyword arguments for each of the slots
defined for this type. The DEC CLX function instantiates a
VISUAL-INFO structure given the X id (the VisualID slot)
of a non-LISP XVisualInfo structure.
- The description of the abstract CLX:LOGICAL-OP type, which
is used for the value of the CLX:GCONTEXT-FUNCTION slot,
does not explain the relationship between between the
:GX-* keywords and Common LISP Boolean constants. Table 1
is an expanded version of Table 7-2, CLX:LOGICAL-OP
Values, from the VAX LISP/VMS DECwindows Programming
Guide. Either the keyword or the LISP Boolean constant
may be used as an argument to the :FUNCTION parameter
of CLX:CREATE-GCONTEXT or as the new value for the
CLX:GCONTEXT-FUNCTION when used with SETF. These
keywords are a Digital extension to PD CLX. If you
are concerned with portability, restrict yourself to
the Common LISP Boolean constants. The :GX-* keywords'
names correspond to the C Xlib constants defined in
<X11/X.h> (DECW$INCLUDE:X.h on VMS); that is, LISP keyword
:GX-AND-REVERSE has the same meaning as the C constant
GXandReverse.
________________________________________________________________
Table_1:__CLX:LOGICAL-OP_Values_________________________________
LISP Boolean
Keyword____________Constant___________Description_______________
:GX-CLEAR BOOLE-CLR 0
:GX-AND BOOLE-AND src AND dst
:GX-AND-REVERSE BOOLE-ANDC2 src AND NOT dst
Enhancements and Technical Changes 17
________________________________________________________________
Table_1_(Cont.):__CLX:LOGICAL-OP_Values_________________________
LISP Boolean
Keyword____________Constant___________Description_______________
:GX-COPY BOOLE-1 src
:GX-AND-INVERTED BOOLE-ANDC1 (NOT src) AND dst
:GX-NOOP BOOLE-2 dst
:GX-XOR BOOLE-XOR src XOR dst
:GX-OR BOOLE-IOR src OR dst
:GX-NOR BOOLE-NOR (NOT src) AND NOT dst
:GX-EQUIV BOOLE-EQV (NOT src) XOR dst
:GX-INVERT BOOLE-C2 NOT dst
:GX-OR-REVERSE BOOLE-ORC2 src OR NOT dst
:GX-COPY-INVERTED BOOLE-C1 NOT src
:GX-OR-INVERTED BOOLE-ORC1 (NOT src) OR dst
:GX-NAND BOOLE-NAND (NOT src) OR NOT dst
:GX-SET____________BOOLE-SET__________1_________________________
- Text Drawing Routines: PD CLX glyph drawing functions
rely on CHAR-FONT bits and other functionality that is
being removed from Common LISP. DEC CLX routines call
the C routines that take an ASCII string and draw it in
the chosen font. This causes some differences between the
18 Enhancements and Technical Changes
two CLX implementations. PD CLX works in the following
sequence:
1. Accept a sequence of chars.
2. Apply #'CLX:TRANSLATE, which can be user-supplied, to
the sequence.
3. Calculate the Width and Extent of the resultant font
indices.
4. Draw the glyphs in the Drawable, dealing with multiple
font changes within a sequence.
The DEC CLX code does not handle indices since the
string is passed directly to C. In DEC CLX, the following
conditions apply:
* The result of #'CLX:TRANSLATE must be a LISP string. In
most cases, it is not needed as the default definition
returns a LISP string unchanged.
* Functions such as CLX:TEXT-WIDTH, CLX:TEXT-EXTENT,
and CLX:TRANSLATE-DEFAULT are implemented but not used
internally by the glyph drawing functions.
- The home package for the symbols that define DEC CLX is
named CLX, although as of VAX LISP Version 3.1, XLIB is a
nickname for this package.
1.4.4 CLX and DECwindows Toolkit Support
o The CLX package is now created with the nickname XLIB. All
the symbols exported from the CLX package that are described
in the VAX LISP/VMS DECwindows Programming Guide can be
accessed with the package name XLIB or the package name CLX.
Enhancements and Technical Changes 19
For example: (clx:open-display "MYNODE") could also be coded
(xlib:open-display "MYNODE").[1]
o The VAX LISP interface to the DECwindows Toolkit differs from
the VAX and C Toolkit interfaces in the following way:
- The functions DWT:INITIALIZE, DWT:MAIN-LOOP,
DWT:NEXT-EVENT and DWT:APP-MAIN-LOOP are actually LISP
functions composed of calls to other routines in the DWT:
package. They do not simply call the C Toolkit routines
of the same name, although they should provide the same
behavior and interface.
o For any C toolkit routine that takes zero as the argument
to indicate a default value, the corresponding LISP function
takes NIL.
o CLX and DECwindows Toolkit functions can be used together.
Several Toolkit accessor functions return CLX objects such as
windows, displays, and screens. To have a Toolkit accessor
function return a CLX object, initialize the Toolkit and use
the DWT:WINDOW function to return the CLX:WINDOW associated
with a widget. (Be aware, however, that only the window
widget, as created by DWT:WINDOW-CREATE is supported for
arbitrary graphics output.) Then you can use CLX functions to
access that window. Remember that the DECwindows Toolkit
automatically queries the event queue and dispatches
events, so be careful using CLX event-processing routines
on a display that has been set up by a DECwindows Toolkit
function.
o For Version 3.1, initializing the LISP development
environment defines a CLX error handler for the LISP
development environment display. Setting another error
handler does not reset the Xlib error handler; rather, it
___________________
[1] If you are concerned with portability to other CLX
implementations, use the Xlib package name in your source
code.
20 Enhancements and Technical Changes
defines the mapping between a display and an error handler to
be used by the CLX error handler.
o The :FORGET keyword can be used with the WINDOW-BIT-GRAVITY
function. The WINDOW-BIT-GRAVITY function returns the bit
gravity for the specified window. The :FORGET keyword with
a value of T indicates that the window contents are to be
discarded after any size change.
o The keywords :XLIB and :CLX are on the features list when DEC
CLX is present in VAX LISP Version 3.1.
o The event-type :NO-EXPOSURE and the following event-keywords
operate in Version 3.1.
- :ALL
- :CHILD
- :VISIBILITY-NOTIFY
- :STATE
- :ENTER-NOTIFY
- :FOCUS-P
- :MAP-NOTIFY
- OVERRIDE-REDIRECT-P
o The FREE-IMAGE function has been implemented for Version 3.1.
CLX:FREE-IMAGE Function
Frees up memory used by an image. The image should not be
used again.
Format
CLX:FREE-IMAGE image
Enhancements and Technical Changes 21
Arguments
image
A CLX:IMAGE object
Return Value
Unspecified.
o The following CLX bugs have been fixed for Version 3.1:
- The bugs that broke GCONTEXT-CLIP-MASK and
GCONTEXT-DASHES.
- The bug that made READ-BITMAP-FILE return an incorrect
image.
- The bug that broke CREATE-IMAGE.
- The bugs that made IMAGE-XY-BITMAP-LIST and
IMAGE-Z-PIXARRAY handle data transfers incorrectly.
- The bug that caused a continuable error when
CLX:MAKE-WM-SIZE-HINTS handled keyword arguments.
- The bug that made CLX:GET-PROPERTY not correctly check the
status returned by XGetWindowProperty.
- The bug that made CLX:CREATE-WINDOW take a CLX:VISUAL-INFO
structure instead of a CLX:VISUAL (an integer) as the
:VISUAL keyword argument. The function now matches its
description in the VAX LISP/VMS DECwindows Programming
Guide.
o The following DWT bugs have been fixed for Version 3.1:
- The constants DWT:GRAB-NONE, DWT:GRAB-EXCLUSIVE, and
DWT:GRAB-NONEXCLUSIVE have been redefined to have correct
values.
22 Enhancements and Technical Changes
- The functions DWT:MAIN-LOOP and DWT:APP-MAIN-LOOP: In
Version 3.0, MAIN-LOOP and APP-MAIN-LOOP failed to reset
all state when aborted. This caused errors when you tried
to call these functions a second time.
1.4.5 Window Streams
o CLX window streams work the same as UIS window streams.
The default is black lettering on a white background.
The exported window stream functions work with CLX window
streams.
o CLX window streams have a backing store that can be used to
maintain the contents of a CLX window. There are two options
for using the window stream backing store:
- An additional optional keyword argument has been defined
for the function WINDOW-STREAM:MAKE-WINDOW-STREAM. You may
specify the keyword argument :HANDLE-EXPOSURE to have a
value of T or NIL. The value of this keyword is ignored
except for CLX window streams. In CLX window streams a
value of T indicates that all exposure events are to be
automatically processed asynchronously; a value of NIL
indicates exposure events are processed by user code. The
default value is T.
Automatic processing of all exposure events requires
polling of the event queue(s) even when no events are
being queued. This causes CPU utilization even during an
idle LISP process.
- The backing store may be manually refreshed as part of the
user processing of exposure events for a window containing
a window stream by calling:
(WINDOW-STREAM:WINDOW-STREAM-REFRESH stream)
Enhancements and Technical Changes 23
1.5 VWS Support
VAX LISP Version 3.1 supports VWS Version 4.2. The following
bugs have been fixed for VAX LISP Version 3.1:
o The bug in UIS:CREATE-WINDOW that caused the function to
ignore the :NOBORDER keyword.
o The bug in the UIS editor that kept it from running in a
separate UIS terminal window.
1.6 System-Building Utility
o The System-Building utility now includes a new feature
that allows you to exclude the VAX LISP and Common LISP
symbols not referenced by the system. To use the feature
in a system-build, include the option :LISP with the :EXCLUDE
keyword( Example 3). This keyword has an effect only when
used with the :ORPHAN-SYMBOLS keyword.
Example 3: :LISP option
:exclude '(:orphan-symbols :lisp :uis :decwindows :wsstream :editor)
o A new function has been exported from the DWT package
that may be used to control the DECwindows programming
environment. The function DWT:DECWINDOWS is primarily
designed to initialize the DECwindows programming environment
after a small system build. The function DWT:DECWINDOWS
does not call READ-EVAL-PRINT-LOOP. It only creates
the windows and data structures needed to define the
DECwindows programming environment. It can also be used
to verify customizations that can only be verified after
initializing the DECwindows programming environment.
Terminating the DECwindows environment with this routine
leaves objects and pointers to memory that can never be
garbage collected. Toggling between a DECwindows Listener and
24 Enhancements and Technical Changes
a terminal interface is therefore not recommended. Resetting
*STANDARD-INPUT* and *STANDARD-OUTPUT* to *TERMINAL-IO* is a
safe way of changing to a terminal interface.
The DWT:DECWINDOWS function is defined in the VAX LISP/VMS
DECwindows Programming Guide.
1.7 ANSI Standard Committee X3J13 Changes to Common LISP
o A macro cannot legitimately expand into a declaration; the
only valid declaration is a list whose CAR is the symbol
DECLARE. However, it is still possible for a macro call to
expand into a PROCLAIM form.
o If the one-argument form of DEFVAR is used, the initial value
of NIL is no longer given to the variable.
o Each function created by FLET and LABELS and each macro
created by DEFMACRO and MACROLET has an implicit block around
its body. The name of this block is the same as the name
of the function or macro. Similarly, the body of a DEFSETF,
DEFINE-SETF-METHOD, and DEFTYPE is surrounded by a block with
the same name as the accessor or type.
o The syntax of FLET, LABELS, and MACROLET allows declarations
between the list of local function or macro definitions and
the body. In FLET and LABELS, the scope of such declarations
includes the bodies of the locally defined functions when the
declarations are pervasive. Nonpervasive declarations have
no effect on those bodies except when LABELS includes the
body in the scope of a function non-pervasively declared. The
scope of such declarations does not include the bodies of the
macro expander functions defined by MACROLET.
o A new function called ROW-MAJOR-AREF allows one-dimensional
access to the storage backing up a given array, assuming the
normal row-major storage layout. ROW-MAJOR-AREF is valid for
use with SETF.
Enhancements and Technical Changes 25
Syntax:
ROW-MAJOR-AREF array index
o VAX LISP Version 3.0 and later versions adhere to new rules
for the interaction between ADJUST-ARRAY and displaced
arrays, described here in terms of three arrays, called A,
B, and C. Array A may be displaced to B before a call to
ADJUST-ARRAY or it may be displaced to C after the call. That
is, the following four situations are possible:
1. A is not displaced before or after the call to
ADJUST-ARRAY. In this case, the dimensions of A are
altered and the contents rearranged as appropriate.
Additional elements of A are taken from the
:INITIAL-ELEMENT. The use of :INITIAL-CONTENTS causes
all old contents to be discarded.
2. A is not displaced before the call but is displaced to C
after. In this case, none of the original contents of A
appears in A afterwards; A now contains the contents of C,
without any rearrangement of C.
3. A is displaced to B before the call and to C after.
In this case, the contents of B do not appear in
A unless such contents also happen to be in C. If
:DISPLACED-INDEX-OFFSET is not specified in the
ADJUST-ARRAY call, it defaults to zero; the old offset
into B is not retained.
4. A is displaced to B before the call but not after. In this
case, A gets a new data region and the contents of B are
copied into it as appropriate to maintain the existing
old contents; additional elements of A are taken from the
:INITIAL-ELEMENT. However, the use of :INITIAL-CONTENTS
causes all old contents to be discarded.
If array A is displaced to array B, and array B is displaced
to array C, and array B is altered by ADJUST-ARRAY, array A
must now refer to the adjusted contents of B. VAX LISP does
not collapse the chain to make A refer to C directly.
26 Enhancements and Technical Changes
If A is displaced to B, it is an error to adjust B so that it
no longer has enough elements to satisfy A.
NOTE
Omitting the :DISPLACED-TO argument to ADJUST-ARRAY is
equivalent to specifying :DISPLACED-TO NIL; in either
case, the array is not displaced after the call.
o The :FILL-POINTER keyword argument to ADJUST-ARRAY is treated
as follows:
If the :FILL-POINTER argument is not given, then the fill
pointer of the array to be adjusted is left alone. It is
an error to adjust an array to a size smaller than its fill
pointer without specifying the :FILL-POINTER option so that
its fill pointer is properly adjusted in the process.
If supplied, the :FILL-POINTER argument must be either an
integer (between 0 and the new size of the array), the symbol
T (indicating that the new size of the array should be used),
or the symbol NIL (indicating that the fill pointer should be
left as it is, that is, as if the :FILL-POINTER option had
not been specified).
An error is signalled if a non-NIL value for :FILL-POINTER is
supplied and the array to be adjusted does not already have a
fill pointer.
o Array element types are automatically upgraded. See the
description of MAKE-ARRAY in the VAX LISP Implementation
and Extensions to Common LISP manual.
o VAX LISP Version 3.0 and later versions allow a :KEY keyword
for ASSOC-IF, ASSOC-IF-NOT, RASSOC-IF, and RASSOC-IF-NOT.
If not supplied, the value of :KEY defaults to #'IDENTITY.
As with the :KEY argument for ASSOC and RASSOC, the :KEY
argument is applied to the CAR of the pair in the association
list for ASSOC-IF and ASSOC-IF-NOT and the CDR of the pair
for RASSOC-IF and RASSOC-IF-NOT.
Enhancements and Technical Changes 27
o The REDUCE function now takes a :KEY keyword. If a :KEY
argument is supplied, its value must be a function of one
argument which will be used to extract the values to reduce.
The :KEY function will be applied exactly once to each
element of the sequence in the order implied by the reduction
order, but not to the value of the :INITIAL-VALUE argument.
o Type declarations may be made for free variables. The value
of the variable must be a member of the declared type, within
the scope of the declaration. This kind of declaration
means the same thing as wrapping a THE form around every
reference to the variable, including modifying references by
SETQ or SETF. If nested type declarations refer to the same
variable, then the value of the variable must be a member of
the intersection of the declared types.
o DEFSTRUCT types which use :INCLUDE to include another type
but do not specify an explicit :PRINT-FUNCTION inherit the
structure print function from the included type. A print
function that uses the default #S syntax, which overrides
any print function for the parent type, can be specified by
:PRINT-FUNCTION NIL.
o In Version 3.0 and later versions, (LCM) returns the integer
1.
o COMPILE-FILE and LOAD bind *READTABLE* to its current
value. This was not defined by Common LISP: The Language
and different implementations did different things.
If you have code such as
(setq *readtable* (copy-readtable *other-readtable*))
in a file that was loaded, you may need to replace it with
the following code:
(copy-readtable *other-readtable* *readtable*)
28 Enhancements and Technical Changes
CHAPTER 2
RESTRICTIONS AND LIMITATIONS
2.1 DECwindows Toolkit
DECwindows Version 2.0 defines functions that were not defined
in Version 1.0. To allow compatibility in VAX LISP Version 3.1
with both versions of DECwindows, the new routines are defined
but cause errors if used with DECwindows Version 1.0. The new
functions are exported from the DWT package. They include the
following:
o ACTIVATE-WIDGET
o APP-ADD-ACTIONS
o APP-ADD-CONVERTER
o APP-ERROR
o APP-ERROR-MESSAGE
o APP-GET-ERROR-DATABASE
o APP-GET-ERROR-DATABASE-TEXT
o APP-GET-SELECTION-TIMEOUT
o APP-SET-ERROR-HANDLER
o APP-SET-ERROR-MSG-HANDLER
o APP-SET-SELECTION-TIMEOUT
o APP-SET-WARNING-HANDLER
o APP-SET-WARNING-MSG-HANDLER
Restrictions and Limitations 29
o APP-WARNING
o APP-WARNING-MESSAGE
o CLIPBOARD-REGISTER-FORMAT
o COLOR-MIX-CREATE
o COLOR-MIX-GET-NEW-COLOR
o COLOR-MIX-SET-NEW-COLOR
o CS-TEXT
o CS-TEXT-CLEAR-SELECTION
o CS-TEXT-CREATE
o CS-TEXT-GET-EDITABLE
o CS-TEXT-GET-MAX-LENGTH
o CS-TEXT-GET-SELECTION
o CS-TEXT-GET-STRING
o CS-TEXT-REPLACE
o CS-TEXT-SET-EDITABLE
o CS-TEXT-SET-MAX-LENGTH
o CS-TEXT-SET-SELECTION
o CS-TEXT-SET-STRING
o END-COPY-FROM-CLIPBOARD
o FETCH-COLOR-LITERAL
o FETCH-ICON-LITERAL
o GET-USER-DATA
o START-COPY-FROM-CLIPBOARD
o START-COPY-TO-CLIPBOARD
o STRING-FREE-CONTEXT
30 Restrictions and Limitations
o STRING-INIT-CONTEXT
2.2 DECwindows Interface to VAX LISP
o When running LISP in the DECwindows environment, the DECterm
or FileView Task Output windows may not be visible. Useful
messages and other output, however, may still appear in
these windows; for example, a full GC is in progress, the
X connection was broken, or a control stack overflow caused
an ABORT. You should look at these windows in situations such
as when the LISP system seems to be hung or some actions seem
to have been aborted. Furthermore, the value of *TERMINAL-IO*
is normally bound to a terminal stream that does I/O with
this DECterm or FileView window. Supplying a value of T as
the stream argument to most reading or writing functions
(except FORMAT) causes output to go to *TERMINAL-IO*.
o Resuming a system suspended under DECwindows reinstates only
the Listener. The state of the other DECwindows utilities is
lost.
2.2.1 The Listener
o There are restrictions on using SPAWN with the DECwindows
interface to VAX LISP. See the VAX LISP/VMS Object Reference
Manual for details.
o Object selection is affected by the value of the special
variable *PRINT-CIRCLE*. When *PRINT-CIRCLE* is non-NIL, only
the top-level object is selectable. For example, consider the
Listener dialog below:
Lisp> (quote (a b c))
(A B C)
Lisp>
If *PRINT-CIRCLE* is NIL, four objects printed by LISP
are selectable: (A B C), A, B, and C. If *PRINT-CIRCLE* is
Restrictions and Limitations 31
non-NIL only the top-level object, (A B C), is selectable.
o Ctrl/S and Ctrl/Q are not defined in the Listener. In the
Listener, Ctrl/S does not pause output and Ctrl/Q does not
resume it.
2.2.2 The Inspector
o When you are inspecting an object, pressing the middle button
brings up the pop-up menu even if the pointer cursor is in
one of the scroll bars. This bug is due to a problem with
DECwindows text widgets.
2.2.3 The Editor
o There is no automatic attachment of the input focus to the
Editor when the ED function is called. You must click in the
Editor window to attach input focus.
o If you scroll an anchored window that is partially covered by
a floating window, some of the text that was covered may not
be properly exposed when the anchored window moves out from
under the floating window. You can use the Redisplay Screen
command to bring up the missing text.
o In V3.1, under DECwindows, the behavior of the
EDITOR:RETURN-FROM-EDITOR macro in a top-level (as opposed to
recursive) call to ED is a no-op, since the Editor is running
separately from the Listener's READ-EVAL-PRINT loop.
o If you resize the Editor window with the DECwindows window
manager controls, you either clip the information inside
the window or expose blank space. Use the functions
EDITOR:SCREEN-HEIGHT and EDITOR:SCREEN-WIDTH with SETF to
resize the Editor display. Note that you can call these
functions before you invoke the Editor (for example, they
can go into an initialization file). Only in this case
are your values remembered across Editor invocations in
32 Restrictions and Limitations
a single LISP session. If you simply start the Editor, it
comes up at 46 rows by 80 columns (the default size). If
you go into the Listener and change the screen height with
EDITOR:SCREEN-HEIGHT, the Editor is resized. If you then exit
the Editor and call ED, the Editor comes up the default size.
However, if you call EDITOR:SCREEN-HEIGHT or -WIDTH while the
Editor is not running, you reset the default values used when
the Editor window is brought up.
2.3 The Terminal-Based Editor
o If you respond to the last prompt in the "Bind Command"
command with binding context :GLOBAL, you may be left in
the prompting window when you should have been returned to
your previous window. Use the "Next Window" command (bound to
Ctrl/X Ctrl/N globally) to set your cursor back. Any other
action when your cursor remains in the prompting window is
unpredictable.
o The "General Prompting" buffer does not work in overstrike
mode. The variable EDITOR:TEXT-OVERSTRIKE-MODE is bound
to NIL in the "General Prompting" buffer so that you can
change the global binding of EDITOR:TEXT-OVERSTRIKE-MODE
without affecting the "General Prompting" buffer. You should
not change the binding in the "General Prompting" buffer;
otherwise, commands that prompt will not work.
o The function WINDOW-LINES-WRAP-P and the Editor Variable
"Default Window Lines Wrap" do not always display wrapped
lines correctly. The bottom wrapped line may not appear when
you scroll continuation lines. Instead, you may see a second
copy of the first line.
Restrictions and Limitations 33
2.4 Memory Management
o ENLARGE-CONTROL-STACK is no longer supported. To change
the size of the control stack, use the /CSTACK qualifier at
startup or :CONTROL-STACK-SIZE argument to DEFINE-LISP-SYSTEM
when creating new executables.
2.5 Callout Facility
o If VMS issues a warning message during shareable image
activation, a callout function will abort even though the
image is correctly mapped.
o LISP interrupt functions are not run during execution of
foreign code by CALL-OUT. Not running the LISP interrupt
functions can have severe consequences in a LISP-based
DECwindows application because it may result in a failure
to check the queue of pending window events in a timely
fashion. The LISP development environment is a DECwindows
application. Consequently, it is best to minimize the time
spent in non-LISP code when DECwindows is running. Using the
function (spawn :parallel nil) in the DECwindows programming
environment is one example of a function that can cause these
consequences.
o In general, it is safer to use LISP-provided primitives to
block the execution of your program when there is nothing
to be done pending the execution of some event. For example,
call-outs to the runtime library function, LIB$WAIT must
be handled carefully. Since many facilities, including
VMS facilities such as the Parallel Processing Library,
VMS DEBUG, LISP, and the LIB$WAIT service, use the $HIBER
and $WAKE system services, user calls must be prepared to
cooperate with these facilities. $HIBER and $WAKE have no
internal counter that assures that a single hibernate is
terminated by a single wake-up. This means that all users
of the services must be careful not to mistakenly consume a
$WAKE intended for another facility by waking up too soon.
34 Restrictions and Limitations
Example 4 assumes that ASTs are used within the process for
issuing the wake-up. Part A shows code that hibernates, and
Part B shows code that might run at AST level to properly
issue the $WAKE.
Example 4: Hibernating Code
A:
loop
(
$setast (enbflg = true); !asts have to come in to get past the hiber
$hiber;
$setast (enbflg = false); !critical-section for valid_wake test
if valid_wake then
(
valid_wake = false; !reset for next time we come through A:
$setast (enbflg = true); !reenable
exitloop;
);
);
$wake ();
!The extra $WAKE is required because another facility can lose its $WAKE
!if it occurs just before we $HIBER. The presence of an extra $WAKE here
!for the calling code is innocuous because of the check of the
!valid_wake flag.
B:
(running at ast level)
valid_wake = true;
$wake ();
o Arrays (simple vectors, non-simple vectors, and
multi-dimensional arrays) may be passed by reference or by
descriptor. An array is not copied between external and LISP
storage-only a pointer to the start of the data portion of
the array.
- For CALL-OUTs, DEFINE-EXTERNAL-ROUTINE accepts
specifications of arrays with unknown dimension size using
Restrictions and Limitations 35
a * in the dimensions list. See Common LISP: The Language
for for more information. Example 5 shows an array of rank
3 where the size of each dimension is unspecified.
Example 5: Multi-Dimensional Array
(define-external-routine
(multid-descr-callout :entry-point "multid_descr_callout"
:file "arr")
(an-array :access :in-out
:mechanism :descriptor ;or :reference
:lisp-type (array (unsigned-byte 16) (* * *))
:vax-type :unsigned-word))
The type specifiers (array) and (array *) are illegal for
DEFINE-EXTERNAL-ROUTINE and MAKE-CALL-BACK-ROUTINE since
insufficient information is provided for correct LISP
handling. Dimension information is obtainable at the time
of the CALL-OUT from the actual argument.
- For call-backs, when an array is passed by reference
to a CALL-BACK-ROUTINE, dimension information is not
available in the external representation of the array.
Consequently, the user must specify the size of each
dimension to MAKE-CALL-BACK-ROUTINE (that is, no *
dimensions), and the array passed at run-time must conform
to this specification. LISP has no way of verifying the
conformance to specification.
An array passed by descriptor to a call-back-routine
need not observe the same restriction, since the size
information can be obtained at run-time from the actual
argument's VAX DESCRIPTOR.
When a vector is passed to a call-back function by
reference, a fill-pointered vector is created, and
displaced to the external data being passed. The user's
36 Restrictions and Limitations
call-back function must explicitly set the array's
fill-pointer to the right size.
2.6 Suspending and Resuming
o You must use exactly the same LISP image and operating system
when you suspend and resume your LISP.
2.7 Error Handling
o CANCEL-CHARACTER-TAG is now obsolete. Use CATCH-ABORT and
ABORT instead of (CATCH 'CANCEL-CHARACTER-TAG ...) and
(THROW 'CANCEL-CHARACTER-TAG ...). CATCH-ABORT and ABORT
are described in VAX LISP/VMS Object Reference Manual.
o THROW-TO-COMMAND-LEVEL is no longer supported.
o The Xlib error handler is not well designed for use in
an interactive language environment such as LISP. You
should register per-display error handlers using the CLX
error functionality rather than by calling out to the
XsetErrorHandler entry point. For example:
(setf (clx:display-error-handler display) #'error-handler)
where:
display a clx display object
error-handler a function that takes two arguments:
o a display
o an error-event
Restrictions and Limitations 37
Example 6: Error Handler
(defun decw-environment-error-handler (display event)
;; extract the values in the error event structure
(let ((err-code (clx::erev-error-code event))
(maj-code (clx::erev-request-code event))
(min-code (clx::erev-minor-code event))
(err-mess (clx::make-asciz-ptr)))
;; ignore error if it is an XSetInputFocus error
(unless (and (eq err-code 8) ;BadMatch
(eq maj-code 42)) ;XSetInputFocus
;; put text corresponding to error code in error-mess variable
(call-out clx::xgeterrortext display err-code err-mess 128)
;; print error message
(format t "~2%Xlib error signaled on LISP development environment.~2%~
X Error received from server: ~%~A~%~
Failed request major op code ~A~%~
Failed request minor op code ~A~%"
(clx::asciz-ptr-value err-mess) ;;string from alien
;;struc.
(clx::get-protocol-name maj-code) ;;get major-code text
min-code)))) ;; minor code integer
(setf (clx::display-error-handler display) #'decw-environment-error-handler)
If no error handler is specified for a display, the default
error handler signals a continuable error for all Xlib
errors. The error handler in Example 6 ignores XSetInputFocus
errors:
2.8 Compiler
o The compiler cannot write circular objects to a fastload
file.
38 Restrictions and Limitations
2.9 RECIPE Example
o The UID file for the RECIPE example that is shipped on the
kit was compiled on VMS Version 5.3 (DECwindows Version 2.0).
It does not work correctly with VMS Version 5.2. If you have
a VMS Version 5.2 system, perform the following DCL commands
before attempting to run the RECIPE example:
$ SET DEFAULT LISP$EXAMPLES
$ UIL RECIPE
This sequence of DCL commands produces a new RECIPE.UID file.
Restrictions and Limitations 39
CHAPTER 3
DOCUMENTATION ERRATA
3.1 VAX LISP/VMS System Access Guide
o In Section 3.3, the description of the GET-DEVICE-INFORMATION
function is wrong. If the specified device does not exist,
the function returns an error; it does not return NIL.
o In Table 4-2, the entries in the column headed "Compatible
VAX Types" are incorrect for the rows (ARRAY (SIGNED-BYTE
8)) and (ARRAY (SIGNED-BYTE 16)). The correct entry for
(ARRAY (SIGNED-BYTE 8)) is :BYTE. The correct entry for ARRAY
(SIGNED-BYTE 16)) is :WORD.
o In Table 4-2, the information for the LISP type
ALIEN-STRUCTURE indicates that both calling-out and
calling-back support passing ALIEN-STRUCTUREs. This is
only true for calling-out. To use an ALIEN-STRUCTURE in a
calling-back routine, you must pass an integer that is the
address of the external data and then use that integer as
the :DATA value of an ALIEN-STRUCTURE constructor you create
in the call-back routine, or use that value with SETF of
ALIEN-DATA of an existing alien.
In Example 7, DEFINE-EXTERNAL-ROUTINE arranges for a
CALL-OUT that will pass an ALIEN-STRUCTURE. A LISP
function, LISP-CALL-BACK, is defined, and the call to
MAKE-CALL-BACK-ROUTINE allows this to be called from external
code. The specification of the argument shows that the
call-back routine receives a LISP integer. This integer is
stored with :DATA when the user's ALIEN-STRUCTURE is created
Documentation Errata 41
by MAKE-MY-ALIEN. At this point, the call-back routine has an
ALIEN-STRUCTURE that points to the same data passed to the
external routine "test".
Example 7: Calling-Out and Calling-Back
(define-external-routine (test :file "TEST" :result integer)
(arg1 :access :in :mechanism :reference :lisp-type alien-structure))
(defun lisp-call-back (arg)
(let* ((arg1 (make-my-alien :data arg)))
(use-my-alien arg1)))
(setf call-back
(make-call-back-routine 'lisp-call-back
:arguments
'((arg :access :in
:mechanism :reference
:lisp-type integer
:vax-type :unsigned-longword))))
3.2 VAX LISP/VMS Implementation and Extensions to Common LISP
o In the introductory material to Chapter 1, the fourth
sentence of the first paragraph is incorrect. Not all of
the implementation differences between VAX LISP/VMS and VAX
LISP/ULTRIX are described in the VAX LISP Release Notes.
o In Section 1.3.7.1, the last sentence of the fourth paragraph
is incorrect. There is no maximum byte size. VAX LISP reads
and writes binary files as 510-byte variable-length records,
up to the byte size that you specify.
o In Section 3.4.2.4, the final sentence of the second
paragraph and the example should be replaced with the
following sentence and example.
42 Documentation Errata
For example, the following code will make the window stream
display blue text on a green background:
(let ((gc (window-stream:window-stream-gcontext ws))
(cm (clx:window-colormap (window-stream:window-stream-window ws))))
(setf (clx:gcontext-foreground gc) (clx:alloc-color cm "green"))
(setf (clx:gcontext-background gc) (clx:alloc-color cm "blue")))
The following sentence should be added after the example:
The gcontext can be used to change not only colors but also
the mechanism that determines how text is drawn and reexposed
in the viewing area. You can alter this mechanism using
the function CLX:GCONTEXT-FUNCTION. See the VAX LISP/VMS
DECwindows Programming Guide for more information on CLX
graphics contexts.
3.3 VAX LISP/VMS System-Building Guide
o In Table 2-1, the descriptions of the :CLX,
:DECW-DEVELOPMENT-ENVIRONMENT, :DECWINDOWS, and :DWT keyword
values are incorrect.
Excluding :DECWINDOWS precludes the built system from using
the DECwindows programming environment, the DECtoolkit, and
the CLX interface. That is, excluding it also excludes:
- :CLX
- :DWT
- :DECW-DEVELOPMENT-ENVIRONMENT
o Excluding :CLX precludes the built system from using the
programming environment, and the DECtoolkit. Excluding it
also excludes:
- :DECW-DEVELOPMENT-ENVIRONMENT
- :DWT
Documentation Errata 43
o Excluding :DWT precludes the built system from using the
programming environment, but not the CLX interface. Excluding
it also excludes :DECW-DEVELOPMENT-ENVIRONMENT.
o Excluding :DECW-DEVELOPMENT-ENVIRONMENT precludes the built
system from using the DECwindows programming environment, but
not the CLX interface or the DECtoolkit.
o Table 2-1 should also be changed to include a new keyword:
:LISP This keyword only has an effect when used with the
:ORPHAN-SYMBOLS keyword. Using (:orphan-symbols
:lisp) excludes the VAX LISP and Common LISP symbols
not referenced by the rest of the system.
3.4 VAX LISP/VMS Object Reference Manual
BIND-KEYBOARD-FUNCTION Function
The following information should be added to the second
paragraph of the description of the BIND-KEYBOARD-FUNCTION
function:
In the DECwindows environment, if the interrupt function writes
output to the Listener (that is, to the *STANDARD-INPUT* or
*STANDARD-OUTPUT* streams), the output is written above the
current Lisp> prompt. If this output is intended to be a prompt
for user input, the desired appearance can be achieved by using
the PROMPT function rather than the PRINT function.
PROMPT and READ-EVAL-PRINT-LOOP Functions
The PROMPT and READ-EVAL-PRINT-LOOP functions should be added
to the VAX LISP/VMS Object Reference Manual following the
*PRINT-SLOT-NAMES-AS-KEYWORDS* variable and preceding the
REQUIRE function.
44 Documentation Errata
PROMPT Function
Prints a prompt to a stream. Resets input stream read buffer.
Format
PROMPT &OPTIONAL prompt output-stream input-stream
Arguments
prompt
A string or a function that takes no arguments and returns a
string to be used as the prompt for input. The default is the
value of *TOP-LEVEL-PROMPT*.
output-stream
The stream into which the prompt string is written. The default
is the value of *STANDARD-OUTPUT*.
input-stream
The stream in which reading is reset. The default is the
value specified for output-stream or *STANDARD-INPUT* when
output-stream defaults.
Return Value
The string that was used as the prompt.
READ-EVAL-PRINT-LOOP Function
Loops to print the evaluated forms after a prompt. This function
is run at the top level in the default LISP image, and used
to implement the BREAK function. Aborts executed by evaluating
forms read are caught by this loop and cause reprompting.
Documentation Errata 45
Format
READ-EVAL-PRINT-LOOP &OPTIONAL *top-level-prompt* &KEY
:prompt :read :eval :print
:input-stream :output-stream
Arguments
*top-level-prompt*
The string to be bound to *TOP-LEVEL-PROMPT* and printed to
signal an iteration of the read-eval-print cycle.
:prompt
A function that handles three arguments (prompt, input-stream,
output-stream) and that is used to print the prompt. Defaults to
#'PROMPT.
:read
A function that is used to read input and that takes four
arguments (input-stream, eof-error-p, eof-value, recursive-p).
Defaults to #'READ.
:eval
A function that is used to process the result of the read. It
takes one argument. Defaults to #'EVAL.
:print
A function that is used to print the results of the evaluation
and that takes two arguments: (list-of-values, output-stream).
Defaults to an internal printing function.
:output-stream
The stream to which output is processed. Defaults to
*STANDARD-OUTPUT*.
:input-stream
The stream from which input is processed. Defaults to
*STANDARD-INPUT*.
46 Documentation Errata
Return Value
This function does not return.
APROPOS Function
The APROPOS function has a new argument. The following
information should be added to the Format statement, the
Arguments section, and the Example section of the APROPOS
function in the VAX LISP/VMS Object Reference Manual.
Format
APROPOS string &OPTIONAL package test
Arguments
test
An optional argument that defines how to match the specified
string with symbols. If you do not specify the argument, a match
will be found by searching for a substring using CHAR-EQUAL.
If you specify :PREFIX, only symbols that start with the string
match. If you specify :SUFFIX, only symbols that end with the
string match. You can also specify a predicate that takes two
arguments: the simple string pattern to be searched for and the
simple string to be searched.
Example
Lisp> (apropos "sub")
Documentation Errata 47
Symbols in package USER containing the string "sub";
SUBST-IF, has a definition
SUBSETP, has a definition
NSUBLIS, has a definition
NSUBST-IF, has a definition
NSUBSTITUTE-IF-NOT, has a definition
SUBLIS, has a definition
NSUBST-IF-NOT, has a definition
SUBST-IF-NOT, has a definition
NSUBSTITUTE, has a definition
SUBST, has a definition
SUBSTITUTE-IF, has a definition
SUBSTITUTE-IF-NOT, has a definition
SUBSTITUTE has a definition
SUBTYPEP, has a definition
SUBSEQ, has a definition
Lisp> (apropos "sub" *package* :prefix)
Symbols in package USER containing the string "sub":
SUBST-IF, has a definition
SUBSETP, has a definition
SUBLIS, has a definition
SUBST-IF-NOT, has a definition
SUBST, has a definition
SUBSTITUTE-IF, has a definition
SUBSTITUTE-IF-NOT, has a definition
SUBSTITUTE, has a definition
SUBTYPEP, has a definition
SUBSEQ, has a definition
Lisp>
This function searches the symbols in the current package for
the string "SUB" and displays two lists: a list of the symbols
that contain the specified string and a list of the symbols that
start with the specified string.
48 Documentation Errata
APROPOS-LIST Function
The APROPOS-LIST function has a new optional argument.
The following information should be added to the Format
statement, the Arguments section, and the Example section in
the APROPOS-LIST function in the VAX LISP/VMS Object Reference
Manual.
Format
APROPOS-LIST string &OPTIONAL package test
Arguments
test
An optional argument that defines how to match the specified
string with symbols. If you do not specify the argument,
a match will be found by searching for a substring using
CHAR-EQUAL. If you specify :PREFIX, only symbols that end with
the string match. You can also specify a predicate that takes
two arguments: the simple string pattern to be searched for and
the simple string to be searched.
Example
Lisp> (apropos-list "array")
(ARRAY-DIMENSION-LIMIT ARRAY-RANK ARRAY-IN-BOUNDS-P
ARRAY-ELEMENT-TYPE ARRAY-DIMENSION MAKE-ARRAY *PRINT-ARRAY*
ARRAY-HAS-FILL-POINTER-P ARRAYP ARRAY ARRAY-TOTAL-SIZE ADJUST-ARRAY
ADJUSTABLE-ARRAY-P ARRAY-ROW-MAJOR-INDEX ARRAY-TOTAL-SIZE-LIMIT
SIMPLE-ARRAY ARRAY-DIMENSIONS ARRAY-RANK-LIMIT)
Lisp> (apropos-list "array" *package* :prefix)
(ARRAY-DIMENSION-LIMIT ARRAY-RANK ARRAY-IN-BOUNDS-P ARRAY-ELEMENT-TYPE
ARRAY-DIMENSION ARRAY-HAS-FILL-POINTER-P ARRAYP ARRAY ARRAY-TOTAL-SIZE
ARRAY-ROW-MAJOR-INDEX ARRAY-TOTAL-SIZE-LIMIT ARRAY-DIMENSIONS
ARRAY-RANK-LIMIT)
Lisp>
Documentation Errata 49
This function searches the symbols in the current package for
the string "ARRAY" and returns two lists: a list of the symbols
that contain the specified string and a list of symbols that
start with the specified string.
GET-DEVICE-INFORMATION Function
o There is an error in the description of the Return Value for
GET-DEVICE-INFORMATION. If the device does not exist, NIL is
returned instead of an error being signaled.
3.5 VAX LISP/VMS Graphics Programming Guide
o The name of the VAX LISP manual that describes VAX LISP's
interface to the VMS Workstation Software graphics (also
called the UIS graphics interface) has changed. The manual
was called the VAX LISP/VMS Graphics Programming Guide. It
is now called the VAX LISP/VMS Interface to VWS Graphics.
The original manual and the VAX LISP/VMS Version 3.0 update
to that manual are not automatically included in the VAX
LISP/VMS documentation set. You must order the manual
and its update separately (order numbers AA-GH76B-TE and
AD-GH76B-T1).
o All references to MicroVMS routines in the VAX LISP/VMS
Interface to VWS Graphics manual refer to the VMS Workstation
Software routines described in the VMS Workstation Software
Graphics Programming Guide.
50 Documentation Errata
3.6 VAX LISP/VMS Program Development Guide
o Customization of the programming environment has been
enhanced by extension of the :INITIAL-STATE attribute from an
attribute defined only for the Debugger auxiliary windows to
a common attribute settable for all utilities.
The following information should be added to Section C.1.1 of
Appendix C.
Initial State
A value of :OPEN or :CLOSED may be specified for each of the
applicable utilities. The default value is :OPEN. Setting the
initial state for a utility does not change the current state
of the utility. To operate the initial state attributes,
the value must be set and then saved. The values specified
for a utility's initial state then affect the programming
environment only at DECwindows initialization time. The :OPEN
and :CLOSED values have the following effects:
________________________________________________________________
Utility____________:OPEN_value_____________:CLOSED_value________
Listener The Listener runs in The Listener runs in
a separate window. the terminal window.
Debugger The Debugger runs in The Debugger runs in
a separate window. the same window as
the Listener.
Inspector The Inspector is The Inspector is
initialized. not defined in the
session.
Documentation Errata 51
________________________________________________________________
Utility____________:OPEN_value_____________:CLOSED_value________
Trace Trace output goes to Trace output goes to
a separate window. the same window as
Listener output.
Apropos-windows DECwindows APROPOS All APROPOS output
output goes to goes to the same
separate windows. window as Listener
output.
Describe-windows DECwindows DESCRIBE All DESCRIBE output
output goes to goes to the same
separate windows. window as Listener
___________________________________________output.______________
When the DECW-UTILS:CUSTOMIZATION function is used with SETF,
:DEFAULT can be used as the new value for any attribute. This
results in the attribute being reset to the system default
value. If you subsequently call DECW-UTILS:CUSTOMIZATION
on the same attribute, you see the actual value of the
attribute. You do not see :DEFAULT except in the case of
the :FOREGROUND-COLOR and :BACKGROUND-COLOR attributes, which
were documented in Version 3.0 as returning :DEFAULT. If
you save your changes using DECW-UTILS:SAVE-CUSTOMIZATIONS,
:DEFAULT is saved for the attribute, and you get the system
default value for the attribute the next time you start LISP.
o A CLEAR item has been added to the Listener Operations menu.
Figures 7-1, 9-2, 10-5, and 10-8 display the Operations menu
without the CLEAR item.
o An Abort button has been added to the Continuable Error
Debugger Caution Box. Figure 10-2 shows the Continuable Error
Caution Box without the Abort button.
52 Documentation Errata