Digital PDFs

AA-GH75A-TE

May 1986

132 pages

Original

21MB

view download

OCR Version

21MB

view download

Document:	VAX LISP/VMS System Access Programming Guide
Order Number:	AA-GH75A-TE
Revision:	000
Pages:	132
Original Filename:

OCR Text

VAXLISP/VMS

System Access Programming Guide

Order Number: AA-GH75A-TE

May 1986

This document contains information required by a LISP language
programmer to make use of routines and other facilities offered by
the VMS operating system.

Operating System and Version:

VAX/VMS Version 4.2

Software Version:

VAX LISP/VMS Version 2.0

digital equipment corporation
maynard, massachusetts

First

The

information

and

should

Corporation.
for

any

The

software

and

this
be

Equipment

that

appear

may

described

document

wused

construed

Digital

errors

may

not

this

subject

this

only

assumed

for

the

assumes

May

without
Digital

1986

notice

Equipment

responsibility

document.

document

copied

change

commitment

Corporation
in

Printing,

furnished

accordance

under

with

the

license

terms

such

license.
No

responsibility

equipment

that

affiliated

not

supplied

Digital

Equipment

All

Rights

Printed
postage-paid

this

reliability

Equipment

software

Corporation

its

READER’S

document.

Your

COMMENTS

Corporation

page

U.S.A.

form

comments

1986.

Reserved.

will

included

assist

wus

the

last

preparing

documentation.
The

companies.
©

use

Digital

following

are

trademarks

Digital

Equipment

Corporation:

DEC

UNIBUS

PDP

DECUS

VAX

VMS

MicroVAX

VAXstation

DECnet

ULTRIX

ULTRIX-32

ULTRIX-32m

I1I

MicroVMS
II

EHEEEQETM

VAXstation

ULTRIX-11

future

CONTENTS
PREFACE
I

PART

SYSTEM ACCESS

GUIDE TO

SYSTEM ACCESS

OVERVIEW OF

1
N

THE

STRUCTURES

FUNCTIONS

INTERRUPT

FACILITIES

FACILITY

CALL-OUT

ALIEN

CONTROLLING INTERRUPTIONS AND SYNCHRONIZING

CHAPTER

PROGRAMMING

EXECUTION

W
B

VU R NS
(G2 I oS

Checking the Return Status
Naming the Entry Point
Specifying the Shareable Image
Specifying the Result Data Type
Checking the Argument Data Types

o
B

Options

VAX
V & 24

W
>

Type

Passing Mechanism

Capability

Name

Argument

Data

LISP

Data
Y Wt

2-13

an External Routine

2-13

CALL-OUT Macro

the

2-12

ROUTINE

EXTERNAL

How to Call
Wwhat

2-11

Type
s

Bt Garl

CALLING AN

Documentation String
Argument Descriptions

Access

Does

How the CALL-OUT Macro Uses

DATA TYPE

OV OO

2-13

Internal Data

Arguments
:ASCIZ

VAX

with

2-14
2-14

CONVERSIONS

nxrcn‘i‘inn
LISP Objects
Converting

O
o

MDD

Name

R
R
R
T
R
OWWOWWOOOOOWNI~N~JO0O
Ui
bHwWo

Routine

External Routine Options

External

and Options

External

Routine Name

R
PO O

ROUTINE

EXTERNAL

IMAGE

SHAREABLE

Lists

Mechanisms for Passing Arguments
Values Returned by Functions

Argument

LINKING A
IO UTEWwWwWwwWwwWwWw
W

ROUTINES

STEPS TO TAKE IN CALLING AN EXTERNAL ROUTINE
STANDARD VAX CALLING CONVENTIONS
Transfer of Control

DEFINING AN

SRS IR O A IO A

NG N

SN SN SV RN (O I (O T

NS I

O I NS

NN NN
DDDNDDDDDDD

EXTERNAL

CALLING

Structures

CHAPTER

to VAX Data Types

:IN-OUT Access

2-14
2-16

2-16

Type

111

SYSTEM

CONTAINING

EXTERNAL

Names

AND

DEFINING

WHAT

DEFINE-ALIEN-STRUCTURE

ALIEN

STRUCTURE

OPTIONS,

AND

the

Constructor

Naming

the

Copier

Naming

the

Predicate

Specifying

Documentation

Type

Name

FIELD

Given

Field

User-Defined
-

€
e

Function

Function
DESCRIPTIONS

Types

Field

Types

Positions

Start
Gaps

Overlapping

and

3-14

End

Between

Positions
Field

3-14

Positions

3-15

Fields

3-15

Options

Initial

3-16

Read-Only Value

3-17

Field
L]

Field

Function

String

STRUCTURE

Field

Functions

wwwww

Access

Repeated

3-18

e
]
e

Naming

NN
w

@
e
&
®
»
&
€
&
&
o
e

B DWW
W W NN N

¢
9
e

Name

Options

ALIEN

e
&
e

W
&
@

W
W

e
8
e
&
€

DWW W

&
&
&

DS D
D

€
&

B
B

e
»

D o

B WD
B

@
&
&

o
@

OV UT o

¢
@
o

~I OY O

WwWwwwbwwwwwlwwwwwwwwwwwwwwwww

CHAPTER

Structure

DOCUMENTATION

STRING

Alien

DOES

TYPE
MACRO

DATA

STRUCTURES

STRUCTURE

NAME,

2-21

Fwwwwwwwww
|
!

ALIEN

FACILITY

OO OCWm~IJO
O U U DS

CREATING

CALL-OUT

THE

N
W

DEFINING
-

USING

2-21

Logical

2-20

2-21

Using

THE

2-20

Files

LIBSGET_VM

Data

Open

2-19

2-20

Memory with

Acquiring

2-18

EXECUTION

LISP

Services
ROUTINE

NS I NS

System

DEFINITIONS

Initializing

2-17

2-16
2-18

EXAMPLES

Objects

Services

EXTERNAL

Using

(NS

NS I O

LISP

SUSPENDING
ROUTINE

CHAPTER

out

SERVICES

System

DURING

Types

Calling

Data

SYSTEM

Defining
ERRORS

VAX

~J ~J ~J O

CALLING

(NI NS I NS R NS I NO I )

Converting

Value

3-16

Field

Similar-Field

Distances

EXAMPLES

ALIEN

STRUCTURE

CREATING

ALIEN

STRUCTURE

Initializing
Allocating
ADDITIONAL

INTERRUPT

OVERVIEW

and

Changing

3-18
DEFINITIONS

3-19

Data

Fields

3-22

AND

3-24

3-22

Memory

ALIEN

3-23

STRUCTURE

MACRO

FUNCTIONS

INTERRUPT

FUNCTIONS

4-2

INTERRUPT

CRITICAL

SECTIONS,

Y~
S o =N

ST OYOYUTUT
DS DS DD WN

TMY
Y S

R
U

LEVELS,

System Routines
>

Using VAX LISP Functions
Removing an Interrupt Function from LISP
Suspending Systems Containing Interrupt

Event

Calling Out

Functions

CHAPTER

Functions
Function with an

Interrupt

Functions

Associating an

FUNCTIONS

Uy
Uy U

INTERRUPT

Defining an Interrupt Function
Passing Arguments to Interrupt
Specifying the Interrupt Level
Automatic Removal of Interrupt

S
Y

Functions
LISP

Routines

LISP

Keyboard

o8
To G

N
&

ASTs

Cause

Y N

that

VAX

EEY

®
e

eN
@

w
W

T S

VMS

System Routines

Asynchronous

[EA N

O B AT NS s

Routines
N

8
o

wwwwdh
w

¢
&

EVENTS

ASTs

ESTABLISHING

ASYNCHRONOUS

AND

LEVELS

SECTIONS

SYNCHRONIZING PROGRAM

EXECUTION

PART

OBJECT

1I1

DESCRIPTIONS

ALIEN-FIELD

Function
ALIEN-STRUCTURE-LENGTH
CALL-0OUT

Function

Macro

COMMON-AST-ADDRESS
CRITICAL-SECTION

Parameter

Macro

DEFINE-ALIEN-FIELD-TYPE

DEFINE-ALIEN-STRUCTURE
DEFINE-EXTERNAL-ROUTINE

Macro

Macro
Macro

FORCE-INTERRUPT-FUNCTION Function
GET-INTERRUPT-FUNCTION Function
INSTATE-INTERRUPT-FUNCTION Function
WAIT

INDEX

Function

INTERRUPT

CRITICAL

USING

(NS

oy oy

SYNCHRONIZATION

FIGURES

External

Internal

Storage

(NS

Keywords

Specifying

External

Routine

Options

Keywords

Specifying

External

Routine

Argument

Ss W

2-3

Calling

Routines

Values

3-21

FAMILY-REC

TABLES

2-10

|
i

the

:MECHANISM

Conversion Table
Conversion
Alien

Values

Table

Structure

from LISP Type
from VAX
Field

2-12

Keyword
Type

to VAX Type
to

LISP

Type

2-15
2-17

3-11

Types

Used with Memory-Space

Keywords

3-23

DEFINE-ALIEN-STRUCTURE

Options

DEFINE-ALIEN-STRUCTURE

Field

Options

DEFINE-EXTERNAL-ROUTINE

wWwwWw NN

Options

DEFINE-EXTERNAL-ROUTINE Argument

Options

PREFACE

Manual Objectives

The VAX LISP/VMS System Access
that
1lets
vyou,
as
a
LISP
interface of the VMS operating
operating
system
give
vyou
accessible

from

the

LISP

Programming Guide provides
information
programmer, make use of the programming
system.
The routines included with the
access
to
capabilities
not
normally

environment.

iIntended Audience

This manual

intended for programmers with a good knowledge of

LISP and the programming

interface

both

to the VMS operating system.

Structure of This Document

An outline of the organization and

chapter

content

this

manual

follows:

PART

Part I
LISP

GUIDE

consists of

interface

TO SYSTEM ACCESS

PROGRAMMING

five chapters,

to operating

which explain how

wuse

the

VAX

system routines.

Chapter 1 provides an overview of the VAX LISP

system

access

facilities.

Chapter 2 shows how to define an external
how

call

(system)

routine and

from LISP.

to
allow you
which
structures,
alien
explains
Chapter 3
written in other
routines
and
LISP
between
data
exchange
languages.

Chapter 4 describes interrupt functions, which you can use

handle asynchronous events in the operating system.

vii

PREFACE

Chapter

shows

how you

and

interrupt

functions

levels.

You

can

interruption

occurs
PART

II:

Part

OBJECT

macro

and

full

description

involved

explains

applicable

Each

variable

use

Associated

Documents

and

the

code

wait

until

the

functions,

function’s

return

description

provides

documents

are

macro’s

value,

and

against
an

event

its

use.

relevant

VAX

LISP/VMS

COMMON LISP:

The

VAX/VMS Linker

Introduction

VAX/VMS

VAX/VMS Run-Time Library Routines

VAX/VMS

Record Management

VAX/VMS

Utility Routines

®@

VAX Architecture Handbook

complete

macros,

Each
use

function

and

examples

the

examples

User’s

shows

wvariable’s

use.
or

programming:

Guide

Language

Reference Manual

VAX/VMS

System Services

1list

the

access.

explains

VAX LISP/VMS

keyboard
interrupt

available.

system

Introduction

them

becomes

with

arguments,

constant

constant’s

For

sections

program

information

descriptions

constants

format,

following

execution

assigning

DESCRIPTIONS

its

The

vyour

the
by

protect

cause

needed

control

functions

also

and

some

contains

variables,
or

can

System Routines
Reference Manual

Services

Reference Manual

VAX/VMS

Reference Manual

software

Documentation

documents,

see

the

Set.

Conventions Used in This Document
The

following

Convention
(

)

conventions

are

used

this

manual:

Meaning
Parentheses

beginning
(SETQ

used

and

end

NAME

examples

LISP)

viii

LISP

form.

code

For

indicate

example:

the

PREFACE

Convention

Meaning

[

Square

]

For

brackets

enclose

elements

that

are

optional.

example:

[doc-string]

Square brackets do not indicate optional elements
when
they
are
used
1in the syntax of a directory name 1in a
VAX/VMS file specification.
Here, the
square
bracket
characters must be included in the syntax.
A horizontal

ellipsis

the

can be

ellipsis

means

that

repeated.

the

For

element

preceding

example:

function-name

{

]}

In function and

{keyword

{

macro

enclose
elements that
code.
For example:

format
are

specifications,

considered

to be

Dbraces

one unit

value}

In function and
macro
format
specifications,
Dbraces
followed
by
an
asterisk
enclose
elements
that are
considered to
be
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 after 1t are
defined to be optional.
For example:
PPRINT

object

&OPTIONAL package

Do not specify &OPTIONAL when you invoke a
macro whose definition includes &OPTIONAL.
&REST

function

In function and macro format specifications,
&REST
indicates that an indefinite number of
may appear.
For example:

CALL-OUT

external-routine

&REST

the
word
arguments

routine-arguments

Do not specify &REST when you invoke
the
macro whose definition includes &REST.

function

PREFACE

Convention
&KEY

Meaning
In

function

&KEY
For

and

macro

1ndicates

that

&KEY

not

whose

UPPERCASE

DCL

commands

characters

functions,

characters;

lowercase,

Lowercase

and

1in

1italics

text

however,

you

word

accepted.

combination

enter

symbol

with

that

vyou

and
you

and

arguments
them

function

defined

constants
can

combination

lowercase

indicates

and

however,

the

&KEY.

function

indicate
can

1invoke

gualifiers,

characters.

italics

you

includes

variables,

lowercase

the

are

:MACHINE-CODE

when

and

macros,

uppercase

lowercase

<RET>

&KEY

definition

uppercase,

arguments

input-pathname

:LISTING

specify

macro

specifications,

keyword

example:

COMPILE-FILE

format

are

enter

LISP

printed
them

uppercase

macro

that

and

descriptions

vyou

supply;

lowercase,

uppercase,

and

uppercase

characters.

3-character

press

key

returns

are

oOr

abbreviation

the

terminal.

For

example:
<RET>

examples,

each

CTRL/x
down

emphasize

indicates
key.
or

therefore,

“C

<RET>

carriage

key

while

implied

symbol

the

used

end

some

returns.

sequence

you

where

you

simultaneously

hold
press

example:

CTRL/Y

echoes

the

control

key

For

system
For

CTRL

CTRL/C

“x.

carriage

However,

the

another

The

<ESC>

1line.

examples
CTRL/x

control

examples

key

sequences

“X;

output,

CTRL/x

shown

that

all

the

1in

response

the

is not shown; or, that
enter is not shown.

all

the

example:
or

°Y

A vertical

ellipsis

that

system

the

indicates

would

particular function call
information a user is to

display

information

PREFACE

Convention

Black print

Meaning

In examples,
the

output

system displays

lines and prompting characters
are

in black print.

For

that

example:

$ LISP/COMPILE
S File(s):

Red print

In examples,

MYPROG.LSP

user

input

example:

$ LISP/COMPILE
S File(s):

MYPROG.LSP

shown

1in

red

print.

For

PART |

GUIDE TO SYSTEM ACCESS PROGRAMMING

CHAPTER

OVERVIEW OF SYSTEM ACCESS FACILITIES

The

VAX

you

LISP

system

restrict

vyour

layered

wuse

utilities

provided with

system.

VAX

facilities

LISP,
the

view

0of

those

them

detail.

The

VMS

any

programmer,

means

may

system.

the

interface

routines

and
the

system.
of

and

the

following

other

the

manual

general

the

operating

access

provides

this

use

the

broad

describes

facilities

routines

are

programmer:

system

routines.

system.

system

parameters

There

large

can

The

Some

routines

capabilities,

notification
1s

notice
means

chapter

remainder

LISP

that

system.

functions

hardly

retrieve

routines

operating

various

This

operating

and

set

VMS
LISP

The

operating

scheduling,

group

you

provides

including

with

the

LISP,

offers

services

COMMON

system

shipped

top
to

access.

System

entire

VAX

LISP

however,

operating

such

external
about

family

manage

the

Other

process

math

routines

screen

1I1I/0,

events.

provide

the

and

wvideo

terminal.

A multilanguage
a

langquage

called

by,

and

languages.

analysis
The

remainder

that

T
A
let

1.1
As

routine
this
each

conforms

can

For

environment.
to

the

return

values

example,

written

chapter

]
|P
you work
with

describe

programming

that

facility

to,

VLISP

Routines

Calling

routines
program

written

Standard
written

can

call

the

in
a

1in

can

other

numeric

FORTRAN.

briefly

- 4 4
operating

VAX

describes

+
system

each

» 1 4+ 4
facilities.

greater

The

facilities

chapters

+h ot

that

detail.

THE CALL-OUT FACILITY
a

VAX

LISP

programmer,

external

LISP

facility,

you

must

first

your

the

primary means

<call-ou

identify

1-1

facility.
system

routine

access
To

use

that

routines

the

call-out

you

want

OVERVIEW OF SYSTEM ACCESS FACILITIES

use,
or
write
and debug a routine in another language.
Information
about system routines is in Volume 5 of the VAX/VMS document
set,
or
the
MicroVMS
FORTRAN
Programming
Support
Manual
of
the MicroVMS
document set.
This documentation has information about the
arguments
that each routine expects, its effects, and the value, 1f any, that 1t
returns.

If you write a routine
routine’s
arguments.
those

arguments

are

in another language, you must be aware
of
the
The
VAX
data types and passing mechanisms of

especially

1mportant.

Once you have identified or written
an
external
routine,
you
must
define
it, using the DEFINE-EXTERNAL-ROUTINE macro.
This macro makes

known to LISP the location and arguments of an
external
routine
and
sets up a mechanism whereby arguments expressed in LISP data types can
be converted to the proper VAX data types for the external routine.
The CALL-OUT macro calls a defined external routine,
passing
arguments
vyou
specify
and returning a value if the external
returns

1.2

it
the
routine

value.

ALIEN STRUCTURES

The DEFINE-EXTERNAL-ROUTINE
macro
can
specify
arguments
for
most
common
VAX
data
types.
However, to pass more complex data you must
define an alien structure that corresponds to
the
structure
of
the
data
in
an
external routine.
An alien structure definition has two
"general

purposes:

layout

for a portion of memory.

To define a precise

memory,
that
1n
fields
interpret
to
To instruct LISP how
allowing you to access those fields using LISP data types.

An alien structure definition provides a
template
for
1instances
of
that
structure, similar to a COMMON LISP structure definition created
by the DEFSTRUCT macro.
The DEFINE-ALIEN-STRUCTURE macro
defines
an

alien

structure

accessor

and

functions,

also

type

provides

predicate,

and

constructor

function,

field

so on.

routine
external
an
to
structure
You pass an instance of an alien
control
precise
provides
RUCTURE
DEFINE-ALIEN-ST
Since
CALL-OUT.
using
alien
the
wup
set
can
over the memory layout of the structure, you
data
own
its
map
properly
can
routine
that the external
so
structure
1in
fields
modify
or
The external routine can access
types into it.
again
1is
When CALL-OUT returns, the modified structure
the structure.
available

for LISP

interpret as

LISP data.

OVERVIEW OF SYSTEM ACCESS

1.3

FACILITIES

INTERRUPT FUNCTIONS

Normally,

LISP

programs

occur

data.

Events

flow

o0f

synchronous

such

times

environment;

that

garbage

program execution

can

collections

that

predicted

that

way

that

is,

events

from

the

code

interrupt

the

LISP

and

the

normal

transparent

user

programs.

the

operating

synchronous
occur

that

they

will

request

execution

timer

but

not

number

complete
return;

not

system.

known

which

wuse

its

that

happen

that

you

1is,

can

unpredictable

operation

expiration

they

predict

point

completes.

can

predicted

time.

the

pointing

initiate

operating

device

the

activity

1.4

CONTROLLING

VAX

LISP

start

the

activity

presses

function

you

have

this

completes,

that

your

interrupt

asynchronous

the

for

write

you

control

You

can

also

the

i1nitiates

interrupt

program

wait

wuntil

that

1is

the

way

VAX

that

event

1is

the

function,

interrupt
an

along

vyou

functions

occurs

function.

with

will

VAX

You

LISP

activity.

execute.

EXECUTION

can

1interrupt

execution
or

asynchronous

function

program

event

and

interrupt

identifier,

synchronize

then
these

INSTATE-INTERRUPT-FUNCTION

INTERRUPTIONS AND SYNCHRONIZING

other.

All

function.

vyou

that

and

completion.

using

identifier

activities

activity

that

written

pass

routine

result

VLISP

form

the

complete.

notification

the

VAX

returns

When

routines

system

These
request

system

allows

I/0

time

takes

Once

CALL-OUT

constant,

although

the

state

for

execute

operating

function,

wait

vyou

make

not

example:

Later,

moves

routines

function

For

asynchronous;

program,

The

user

are

the

1ssued.

program

notification

1interrupt

designed

events

button.

allow

this

then

set.

system

they

events

the

asynchronously.

routines
LISP,

is
the

all

occur.

1s
of

A workstation
pointer

Some
points

eventually

I/0

the
A

however,

fashion.

unpredictable

system,

each

causing

1information

the

beccmes

available.
A

function

specified

INSTATE-INTERRUPT-FUNCTION

The

interrupt

execute,

level
can
SO.

level

<can

which

ensure

VAX

that

LISP

can

with

also

integer.

only

functions

1if

its

interrupt

When

the

function

interrupt

operating.
that

BIND-KEYBOARD-FUNCTION

have

must

level

By using
interrupt

level

called

higher

interrupt
other

specified.

than

the

levels,

functions

can

vyou
do

OVERVIEW OF SYSTEM ACCESS FACILITIES

Some

parts of

code

for example,

those

that modify

-must never be interrupted.
You can use
to protect such code from any interruption.

the

data

structures

CRITICAL-SECTION macro

If your program has to wait for the execution of a
keyboard
function
or
an
interrupt
function, VAX LISP provides the WAIT function.
The
WAIT function halts normal LISP execution
wuntil
a testing
function
that

you

specify

returns

non-NIL.

CHAPTER 2
CALLING

VAX

LISP

has

languages

LISP

the

programs

VAX

facility

from

can

call

Procedure

and

VMS

Run-time
an

and

RMS

external

the

RTL

into

that

and
VAX

(RTL)

routine,

written

routines

such

not

facility

interpreted

provides

Programs

languages

system

are

written

service,

call

other

call

the

such

VAX

environment

being

present

this

dependency,

take

garbage

that

out

collection

environment
FORTRAN
normally

FORTRAN

was

from

another

dynamic

memory,

1if

the

environment.

called

most

LISP

not

program would
performed

program

present

VAX

have
by

have

the

deal

not

linked

(see

at run

cause

since

the

function

memory

collector.

the

Part

the

would

the

VMS

I1I).

VAX

LISP

depend

1If

the

LISP

FORTRAN,
a

garbage

whole

LISP

called,

management

This

internals

use

time.

However,
the

in APL

routines.

example,

normally

LISP

can

call

written

for

require

such

collection.

language,

with

garbage

knowledge

Procedure

written

You

with

cannot

functions

would

when

VAX

that

Routines

languages

LISP

ran

other

adhere

must

operations

function

routine

routines.

subprocess

that

the

routine

communicate

reason

that

routines

The

entire

facility,

image.

external

examples
for

must

environment.

facilities

1is

you

shareable

functions

functions.
an

this

as:

routine

software

mailbox

LISP

the

cannot

BASIC

and

example

written

Using

routines

addition,

nonstandard

subprocess

call

program.

services

position-independent

call-out

you

LISP

Standard

system

library

Standard.

extensive,

lets

VAX

routines

Calling

The

FORTRAN

call

that

within

EXTERNAL ROUTINES

reqguire

LISP

the

tasks
the

system.

CALLING EXTERNAL ROUTINES

The

Introduction

VAX/VMS

System

Routines

contains

detailed

information
about
calling
external
routines and passing arguments.
You should be familiar with these subjects before you use the VAX LISP
call-out

facility.

A routine that can be called is termed a "procedure" in the previously
mentioned
manual .
This
chapter,
however,
uses
the
expression
"external routine" to maintain consistency with the VAX LISP
language
terminology.

This

chapter

covers

the

following:

routine.

in calling an external

Lists the steps to take

Describes the

Explains and gives examples of how to define and call external
routines,

standard VAX calling conventions.

including

system

services.

objects

Shows how data types are converted from LISP

objects

and

vice

VAX

versa.

Explains the errors that can occur while executing an external

routine.

how

Shows

definitions

containing

system

a&a

LISP

suspended.

external

2.1

STEPS TO TAKE IN CALLING AN EXTERNAL ROUTINE

For

LISP program to
1.

Write

the

Compile

Debug

Link

Define

Call

call

external

you must:

routine.

1t.

1it.

into
it

a VMS

i1n

LISP.

from

LISP.

shareable

Figure 2-1 illustrates these steps.
no way

routine,

routine

to debug

external

routines.

1image.

Note that VAX LISP currently

has

CALLING

EXTERNAL ROUTINES

Create, compile, and debug
external routine

VMS Environment

i
Link external routine into
a VMS shareable image

Invoke VAX LISP

Define external routine to
LISP

LISP Environment

Call out to external routine

ML.O-244-86

Figure

2-1:

Calling

External

Routines

2.2

STANDARD VAX CALLING CONVENTIONS

The

VAX

Procedure

routines

Services.

This

control,

how

returned.

used

compiled

that

VAX

nature
do

the

conform

the

prescribes

how

how VAX

Standard.

are

passed,

standard

operating

programs

LISP

language.
vyou

call

the

standard.

receive

LISP

calls

routines

how

conventions,

can

call
to

library

the

reason,

written

four

conforming

and

for

System

return

values

most

languages.

this

The

method

VAX/VMS

function

conform

routines

call

For

wuniform

and

system

cannot

Introduction

other VAX native-mode

1lets
to

defines

see

the

VAX/VMS
LISP

that

summarize
Calling

standard

the

Standard

another

arguments

written

facility

Calling
one

By means

with

routines

the

call

are

languages

routines

Interpreted

and
and

standard

because

VAX

provides

LISP

other

VAX

sections

the VAX

languages
briefly

Procedure

CALLING

2.2.1

EXTERNAL ROUTINES

Transfer of Control

VAX LISP calls external routines with a CALLG
1instruction.
External
routines
return
control
to
the
programs that call them with a RET
instruction.

2.2.2

Argument

Lists

Arguments are passed to an external routine in an argument list.
The
LISP
system
constructs
this
argument list each time a LISP program
calls an external
routine.
The
1list
1is
a
seqguence
of
longword
(4-byte) entries.
The first byte of the first entry in the list 1s an
argument count, indicating the number of longwords that follow in
the
list.

The

succeeding

data value,
the

longwords

contain either a data value,

specified passing mechanism.

2.2.3

a pointer

or a pointer to a descriptor of a data value,
The

limit

254

depending on

arguments.

Mechanisms for Passing Arguments

The VAX Procedure Calling Standard defines three mechanisms
arguments

are

passed

to external

which

routines:

By immediate value

-- The argument list contains the value.

By reference

-- The argument list contains the address
of

By descriptor

Section

2.4.7.3

the

value.

-- The argument list contains the address
of

describes

how

descriptor

specify

the value.

argument’s

passing

mechanism.

2.2.4

Values Returned by Functions

An external routine can be a subroutine or a function.
A
subroutine
is
invoked
only
to
produce side effects, and returns no value as a
result of

value

its execution.

after

value

execution

returned

one

A function,

on the

other

the value

returns

less

The function

two ways.

If the data type is scalar and requires 32

storage,

hand,

and might produce side effects.

returned in

bits

CALLING

the

data

storage,
register

2.3

program

object

shareable

images.
and

option

availlable

UNIVERSAL
<CTRL/Z>

scalar

the

and

requires

bits

o0f

high-order

from

the

bits

wvalue

the

are

bits

returned

value

are

returned

call

The

external

1into

into

UNIVERSAL

used

LISP

used

one

following

FUN.OBJ

option
1s

can

IMAGE

modules

TEST.OBJ
linker

and

A SHAREABLE

LISP

required

RO,

low-order

LINKING

Before

type

the

EXTERNAL ROUTINES

through

the

specify

1links

the

1link

the

object

VMS

modules

MYIMAGE.EXE.

The

the

entry

points

are

facility.

must

called

example

end

you

position-independent

1mage

list

call-out

the

example

shareable

following

LINK/SHAREABLE=MYIMAGE

routines,

are

the

taken

that

values

from

the

SYSSINPUT,

file.

TEST,FUN,SYSSINPUT:/OPTIONS

UNIVERSAL=ENTRY_1,ENTRY_Z2,ENTRY_3
<CTRL/Z>

The

number

LISP

address
If

you

that

can

the
1in

shareable

contains

that

images
image

that

can

restrictions

mapped
and

the

into

VAX

available

you

contains

the

blocks,

option

issues

section

has

can

call

these
an

command

warning

based,

vyou

that

message

cannot

1nvokes

that

<call

VMS

Linker.

same

to writable,

routines

that

the

must

has

informs
external

1in

the

shareable.

i1n

the

which

code.

program

section

the

image’s

map

the
in

file.

1image

the

routine

and

install

such

(WRT)

shareable

refer

contain

external

the

write

either

image

that

FORTRAN,

produce

the

whether

option

that

examine

routine

PSECT

section

that

vyou

shareable

not

1mages
VAX-11

determine

utility

additional

attributes

shareable
written

writable

external

routines

the

1in
are

attributes,

INSTALL

into

(PSECT)

sections,

VMS

all

that

examples

attributes.

Supply

routines

contains

image

Link

image

are

program

the

linker

Routines

writable

with

address

i1f

image.

1image

shareable

shareable
shareable

external

(SHR)

base

sections.

COMMON

Before

VMS

shareable

call

writable

linker

routines

image

specify

VMS

use

individual

space.

the

You

depends

that

shareable

following:

writable,

single

linker

question

shareable

invocation

that

PSECT

changes

from writable,

the

shareable

CALLING EXTERNAL ROUTINES

For example, suppose you have two routines which access a named COMMON
block
called
SHARED SPACE.
These routines exist in different source
modules, FOR1.FOR and FOR2.FOR.
After compiling both source
modules,

you

would

wuse

the

following VMS

Linker

command

create

shareable

image:

LINK/SHARE=MYEXE

FOR1,FOR2,SYSSINPUT:/OPTIONS

UNIVERSAL=ROUTINE1, ROUTINE?2
PSECT

ATTR=SHARED SPACE,WRT,NOSHR

The

resulting

shareable

having
to
install
it
procedure will not work
shareable
The

procedure

Linker

2.4

PSECT

exist

for

Reference

DEFINING AN

image

may be

<called

from

VAX

LISP

without

wusing the VMS INSTALL utility.
However, this
if routines that
access
the
same
writable,

different

linking

shareable

images

images.

explained

the

VAX/VMS

Manual.

EXTERNAL ROUTINE

Programs written in VAX LISP cannot call external
way
as programs written in other VMS languages.

routines
the
When a program

same
calls

an external routine, the program must specify
information
about
the
routine.
Other
VMS
languages
specify the information by compiling
code into object modules that are linked by the VMS linker.
Since VAX
LISP
does
not
create
object
modules
that
<can be linked, 1t must
specify

information

about

an external

routine

another way.

After you link an external routine into a shareable image,
enter
the
VAX
LISP
environment
and
define
the
routine,
wusing the VAX LISP
DEFINE-EXTERNAL-ROUTINE macro.
The definition provides the
VAX
LISP
system
with
the information needed to create an argument list and to
locate
and
call
the
external
routine.
L
description
of
the
DEFINE-EXTERNAL-ROUTINE macro is provided in Part II.
The

format

for

defining

external

(DEFINE-EXTERNAL-ROUTINE

routine

(routine-name

1is:

keyword-1

value-1

keyword-2

value-Z2

¢/

[doc-string]

(argument-name

keyword-1
keyword-2

. )
(argument-name

...)

value-1
value-2

CALLING EXTERNAL ROUTINES

The
The following example illustrates an external routine definition.
An
used in this example are explained in the next sections.
keywords
1n
given
1s
routine
-external
this
illustration of calling out to
Section

2.5.1.

Lisp>

(LIBSCREATE_DIR

(DEFINE-EXTERNAL-ROUTINE

:FILE

"LIBRTL"

:CHECK-STATUS~-RETURN

(DEV-DIR-SPEC

:LISP-TYPE

STRING))

LIBSCREATE_DIR

This external routine will create

new

disk

directory

given

1ts

specification.

device

and directory

2.4.1

External Routine Name and Options

1it.
for
When you define an external routine, you must specify a name
In addition, you can specify options that provide the LISP system with
information about how to call

2.4.2

the external

routine.

External Routine Name

that
1identifies
wuniquely
The external routine name is a symbol that
also
The name
being defined.
routines
external
all
among
routine
1s
serves as the entry-point name unless a different entry-point name
specified with the :ENTRY-POINT option (see Section 2.4.3.2).

2.4.3

External Routine Options

by
routine
external
an
to
You can assign specific characteristics
Each option consists
specifying options in the routine’s definition.
of

keyword-value

pair.

the
Specify external routine options in a list whose first element 1is
to
which
in
format
The
characterize.
options
of the routine the
name
specify the name

and options

1is:

(name keyword-1 value-1 keyword-2 value-Z2

...)

the
Table 2-1 alphabetically lists
Option values are not evaluated.
in
option
each
explain
sections
next
The
use.
can
you
keywords
option
2.10.
Section
see
options,
these
use
to
how
of
For examples
detail.

CALLING

Table

2-1:

EXTERNAL ROUTINES

Keywords Specifying

External

Routine

Keyword

Purpose

: CHECK-STATUS-RETURN

check

name

specify

ENTRY-POINT

:FILE

the
the

Options

return
entry

the

status

point

VMS

file

name

the

external

routine’s

shareable

: RESULT

define

the

type

the

result

: TYPE-CHECK

check

types

the

arguments

the

data
data

1mage

NOTE
You

must

calling

2.4.3.1
register

status

1s
1s

routine
option

no
to

The

with

Naming

for

the

with

the

Entry

string

called

that

the

image.

The

either

logical

name

include
a

system

this

you

are

:CHECK-STATUS-RETURN

examine

routine.

done.

1If

you

code.

1If

severe-error,

option

thus,

you

The

specify

should

is
T,

severity

continuable

1implies

that

not

keyword

contents

default

the

specify

NIL,
the

the

error

1is

external

the

:RESULT

The

:ENTRY-POINT

external

represents

string
(The

routine.
the

name

different

default

keyword

You

must

the

entry

from

the

name

entry

point

specifies

specify
point

you

the

this
that

specify

name

routine.)

shareable

The

status

oOr

routine.

Specifying

specification

Point

of
that

that

name

external

this

integer;

string
a

name

external

2.4.3.3

wunless

option.

the

external

option

facility

checking
error,

this

the

contain

presence

entry-point

keyword

that

Status

call-out
from

assumed

returns

2.4.3.2

return

:FILE

service.

Return

the

warning,

signaled.

the

means

the

whether
RO

the

system

Checking

specifies
which

specify

Shareable

represents

cannot
keyword

Image

that

refers

image
be
a

The

specification

specification must

shareable

service.

the

arbitrary

routine’s

:FILE

of
in

the

keyword

specifies

external

routine’s

upper

shareable

case

and

must

image,

the

SYSS$SHARE
file

definition

directory.

specification.
unless

you

are

be
file

The

You must
<calling

CALLING EXTERNAL ROUTINES

LISP.
Note that this keyword is named :IMAGE-NAME in Version 1 of VAX
:IMAGE-NAME)
or
(:FILE
keyword
either
compatibility,
of
sake
the
For
ULTRIX
the
This change was made for compatibility with
is allowed.
operating

system.

NOTE

1in
available
If the specified entry point is already
LISP, modified versions of the routine are not used.

keyword
:RESULT
sSpecifying the Result Data Type - The
2.4.3.4
The
routine.
external
value returned by the
of
type
the
specifies
subroutine and
a
1is
routine
default is NIL, which means that the
returns

no value.

can
keyword
:RESULT
then the
If the routine does return a wvalue,
the
that
type
data
VAX)
a
and
LISP
a
both
(or
LISP
the
specify
wvalue
the
Specify
system.
LISP
the
to
return
to
is
external routine
If the VAX type of the returned
LISP data type.
a
:RESULT as
with
the
of
value does not correspond with the LISP data type, use a list
for
2-4
Table
See
lisp-type :VAX-TYPE vax-type).
(:LISP-TYPE
format
valid result types.
keyword and the

not

:RESULT

specify

both

the

:CHECK-STATUS-RETURN

keyword.

keyword
:TYPE-CHECK
Checking the Argument Data Types - The
2.4.3.5
external
an
to
passed
arguments
the
of
types
data
the
that
specifies
routine be checked for compatibility with the argument descriptions.
specify T,
1If you
You can specify the keyword with either T or NIL.
code that checks the type of actual LISP
system generates
LISP
the
the
of
types
the
If
CALL-OUT macro.
the
objects when you call
and actual arguments are incompatible, an error 1s
defined
routine’s
1If you specify NIL (the default value), the system does not
signaled.
generate

type-checking

code.

NOTE

Type

checking

call-out

2.4.4

adds

considerable

overhead

the

process.

Documentation String

The
routine.
You can include a documentation string for an external
and is attached to the symbol as a documentation
string is optional
2-9

CALLING

EXTERNAL ROUTINES

string

type

EXTERNAL-ROUTINE.

atter

the

name

and

2.4.5

Argument

External
arguments

the

usually

determine

that

you

default

description

argument

can

the
pass

one

description

remaining

elements

2.4.6

Argument

Name

argument

name

either

unique
Unique

than

the

string

the

definition

names

make

are

the

whose

The

argument

characteristics

the

first

then

argument

argument.

element

Otherwise,
the

name

and

characteristics.

names

routine’s
some

arguments.

and

adeguate,

name

the

that

the

order,

routine.

list

specify

symbol

within

number,

characteristics

nothing

whose

desired.

Place

list.

Descriptions

routines

descriptions

options

the

argument.

definition

call-out

error

The

NIL

symbol

messages

must

name

1is

easier

argument

understand.

2.4.7

Argument

You

define

can

specifying

Options
the

characteristics

options

keyword-value

element

i1s

the

name

(argument-name
Option
the

values

are

the

external

argument

description.

pair.

Specify

options

argument

they

the

keyword-1

not

argument-option

Table 2-2:

value-1

evaluated.

keywords

with

the

1in

option

1list

characterize.

keyword-2

Table

routine

Each

2-2

values

value-2
an

they

whose
The

Defined

alphabetical

:ACCESS

Access

:IN

capability

: IN-OUT

LISP

see

type

Options
(default)

Table

INTEGER

2-4

(default)

is:

...)

define:

Value

first

format

Keywords Specifying External Routine Argument Options

Keyword

:LISP-TYPE

consists

list

CALLING

Table

2-2

EXTERNAL ROUTINES

(cont.)

Value
Keyword

:MECHANISM

Defined

Options

Passing

: VALUE

mechanism

: REFERENCE

(default

: VAX-TYPE

:DESCRIPTOR

(default

: VAX-TYPE

VAX

data

type

see

Table

(default

2.4.7.1

Access

capability
access

and

:IN.
not

the

value.

argument

has input

argument

has

the

must

details.

of
2-4.

the

new

LISP

Data

Type

LISP

you

Passing

specify

by which

:MECHANISM

described

access.

1is

allocate

assumed

are

LISP

access

for

input

default

objects,

type)

the

:IN

The

LISP

1it.

specifies

output

access,

and

1is

:0UT

read-only,

form

acceptable

the

external

and

modified,

the

:LISP-TYPE

keyword

defines

keyword

the

values

Section

2.2.3.

data

type

and

the

CALL-OUT

uses

SETF

Section

the

types

2.6.2

LISP

VAX

The

data

shown

data

type

signaled.

The

argument

These

LISP

with

it.

The

and

See

INTEGER.

2-3.

SETF.

returns.

keyword,

routine

modify

routine

this

external

routine

Specify

for

the

optionally

defaults

error

output

wvalue

the

The

Mechanism

mechanism
Table

type

With
1n

after

argument.
The

values

the

keyword

modify

and

argument

value

incompatible,

2.4.7.3

input

specified

for

type

not

2-5
depends

values

and

for

:TEXT)

possible

cannot

access,

may

both

the

Table

input

argument’s

reassign

2.4.7.2

:ACCESS

The

for

unpredictable.

passes

The

routines

routine

argument

macro

both

external

obtain

are

for

Since

are

argument.

possible

results
If

:IN-OUT

external

can

Capability

for

except

:TEXT)

you

:MECHANISM
to

can

passed

specify

correspond

keyword

the

one

three

defines

external

the

three

defined

the

routine.

values

mechanisms

CALLING

Table

2-3:

Values

of the

EXTERNAL ROUTINES

:MECHANISM

Value

Corresponding

Name

VAX

: VALUE

Immediate

Keyword

Mechanism

Description

Value

The

1mmediate

passes

the

copy

argument

this
and

that

longword
Reference

:DESCRIPTOR

Descriptor

have

that

these

was

:DESCR.

names

You

LISP,

can

For

cannot

the

specify

descriptor

The

class

the

value

was
sake

names

:IMMED,
of

and

the

alien

the

argument

The

descriptor

the

address

mechanism

of
the

structure

that

address

the

have

been

:REFERENCE

compatibility,

both

passes

argument

argument
18

list.

data

contains

argument,

type

and

changed.
was

1in

list.

data

passes

argument

descriptor

its

storage.

the

specific

VMS

descriptor

DEFINE-EXTERNAL-ROUTINE

macro

routine

assigns

argument

with

the

structures,

2.4.7.4

types

than

mechanism

the

well

Version

and

old

the

size.

1In

:REF,

when

are

the

classes
macro

LISP

:DESCRIPTOR

and

the

DSCSK_CLASS_S

VAX Data

type

the

2-4.

The

default

alien

reference

see

Type

Chapter

argument.
depends

The

structures

mechanism.

new

external
an

1it.

DSCSK_CLASS_A.

define
the

the

and

pass

For

information

routine

appropriate

The
pass

descriptor

alien-structure

defining

:VAX-TYPE

Specify
on

assigns

system evaluates

an argument using a user-specified descriptor,
descriptor

data

used.

definitions.

values

keyword
:VALUE

for
access

reference

wuse

1input

address

VAX

can

1in

only

the

descriptor

You

have

mechanism

argument

The

Note

list.

that

reguliring

REFERENCE

the

mechanism

arguments

value

the

this
LISP

keyword

defines

keyword with
type,

also

the

VAX

types

Table

2-4.

data

in Table

CALLING EXTERNAL ROUTINES

2.5

CALLING AN EXTERNAL ROUTINE

This section describes how to
call
an
external
routine,
what
the
CALL-OUT
macro
does,
and
how the CALL-OUT macro uses internal data
structures.

2.5.1
You

How to Call an External Routine
call

an external

routine by using

the

VAX

LISP

CALL-OUT

macro

with:

The defined name of the external

must
These
Arguments to be passed to the external routine.
the
to
call
the
in
defined
arguments
the
with
compatible
be
DEFINE-EXTERNAL~-ROUTINE

The

routine.

format

for

(CALL-OUT

macro.

calling an external
routine-name argl

routine

argl

1is:

...)

The following example calls out to the external routine LIBSCREATE_DIR
defined
1in
Section
2.4.
This
call
will create the new directory
LISPWS:
[ MYNAME.WORK ] :

Lisp>

(CALL-0OUT LIBSCREATE_DIR "LISPWS: [MYNAME.WORK]")

561

If you specify fewer
arguments
to
the
CALL-OUT
macro
than
those
defined,
the
remaining
defined
arguments
are
not included in the
reflects
1list
The count in the first longword of the
argument list.
an
defined,
those
than
arguments
more
specify
you
If
situation.
this
error

signaled.

If an argument evaluates to NIL,
The
longword.
1list
argument
optional

2.5.2

The

argument

a zero is placed in the corresponding
=zero is normally used to mean that an

not desired.

What the CALL-OUT Macro Does

CALL-OUT

macro

produces

code

that

performs

following

the

operations:

:TYPE-CHECK option is specified.

Checks all arguments if the

On the first call to an external routine,
into

memory.

reads

the

routine

CALLING

Creates

Transfers

Returns
values

2.5.3
When

argument
control

any
1f

you

define
and

structure
LISP

defined

then

before

external

result

external

the

routine.

from

the

routine,

Structures

internal

the

CALL-OUT

must

ensure

running

definition

LISP

1is

data

that

macro
that

structure

routine.

and

This

the

is
data

resulting

external

routine

functions,

1loaded

make

before

sure

<calling

the

out

file

that

routine.

The

internal

VAX

format

converts

the

argument

returns,

the

representation
for

the

LISP

argument

object

call-out
before

call-out

routine

controlled
definition.

data
with

Table

2-4

and

the

table

types.

descriptor

described

shows

the

VAX

differs

types.

data

Likewise,

converts
return

the

convert

object
shows

For

each

the

that

and
the

from

The

before

after

the

standard
facility

passing

external

resulting

data

the

call-out

type

the

VAX

arguments

data

the

routine

VAX

data

LISP

system.

valid

options
the

This

combinations

type,

for

type.

:VAX-TYPE

LISP

the

passing

are

mechanisms

valid

descriptor

argument

formats,

objects
data

1n
of

external

conversion
an

LISP

default

data

VAX

1is

argument
types

type

1is

asterisk.

specifies
in

can

must

2-4

Descriptor)

included

:LISP-TYPE

Table

also

routine.

LISP

the

LISP

LISP Objects to VAX Data Types

facility

the

facility

from

corresponding

external

Converting

VAX

external

Data

naming

both

DATA TYPE CONVERSIONS

marked

symbol

vyou

2.6

2.6.1

provided.

called.

when

the

arguments

result.

routine,

with

used

particular,

external

and

the

Therefore,

containing

The

using

specified

there

associated

code.

LISP

list,

How the CALL-OUT Macro Uses Internal

created

EXTERNAL ROUTINES

for

class

descriptor

Introduction

each

and

when

<class,

VAX/VMS

Value,

combination.

data

type

passing

and

data

Reference,

1In

addition,

that

will

by descriptor.

type

System Routines.

codes

be
The

are

CALLING

Table 2-4:

EXTERNAL ROUTINES

Conversion Table from

LISP Type to VAX Type
Descriptor

LISP

Mechanisms

Class/

VAX Type

Allowed

Data

:UNSIGNED-BYTE

V,R,D

Scalar/BU

INTEGER

:BIT

V,R,D

Scalar/LU

INTEGER

:BYTE

V,R,D

Scalar/B

INTEGER

:UNSIGNED-BYTE

V,R,D

Scalar/BU

INTEGER

: WORD

V,R,D

Scalar/W

INTEGER

:UNSIGNED-WORD

V,R,D

Scalar /WU

V,R,D

Scalar/L

Type

Default

CHARACTER

INTEGER

LONGWORD

Type

INTEGER

: UNSIGNED-LONGWORD

V,R,D

Scalar/LU

INTEGER

: QUADWORD

R,D

Scalar/Q

INTEGER

:UNSIGNED-QUADWORD

R,D

Scalar/QU

SINGLE-FLOAT

: F-FLOATING

V,R,D

Scalar/F

DOUBLE-FLOAT

:G-FLOATING

R,D

Scalar/G

:D-FLOATING

R,D

Scalar/D

DOUBLE-FLOAT
LONG-FLOAT

:H-FLOATING

R,D

Scalar/H

STRING

: TEXT

R,D

Scalar/T

:ASCIZ

:BIT

R,D

Scalar/V

:UNSIGNED-LONGWORD

V,R,D

Scalar/LU

STRING

SIMPLE-BIT-VECTOR

SIMPLE-BIT-VECTOR
ALTEN-STRUCTURE

:UNSPECIFIED

R,D

Scalar/Z

(ARRAY

:UNSIGNED-BYTE

R,D

Array/BU

:BIT

R,D

Array/V

:UNSIGNED-BYTE

R,D

Array/BU

CHARACTER)

(SIMPLE-ARRAY

BIT)

(ARRAY
(UNSIGNED-BYTE

8))

2-15

CALLING EXTERNAL ROUTINES

Table

2-4

(cont.)

Descriptor

LISP
Type

Default VAX Type

(ARRAY
(UNSIGNED-BYTE

Mechanisms
Allowed

Class/
Data Type

: UNSIGNED-WORD

R,D

Array,/WU

: LONGWORD

R,D

Array/L

(ARRAY SINGLE-FLOAT)

:F-FLOATING

R,D

Array/F

(ARRAY DOUBLE-FLOAT)

:G-FLOATING

R,D

Array/G

(ARRAY LONG-FLOAT)

:H-FLOATING

R,D

Array/H

16))

(ARRAY
(SIGNED-BYTE

2.6.2

32))

Arguments with :IN-OUT Access

Arguments with both input and output access can
be
modified
by
the
external
routine.
If
the
argument is a character or a number, the
modified value will be made into a new LISP object
that
1s
distinct
from
the
original
argument.
This action ensures that you can pass
constants or shared data objects and they will not be modified.
If the argument is not a character or a number, then the argument will
be
directly
modified
by
the external routine, and no copy is made.
This means that all array arguments are modified in place.

2.6.3

:ASCIiZ VAX Type

Every simple string is guaranteed to have a
zero
byte
at
the
end,
following
the
1last
actual
character.
Thus
vyou do not have to be
concerned about adding the zero byte when passing
simple
strings
as
ASCIZ

arguments.

If an ASCIZ argument has :IN-OUT access and is modified by
placing
a
s
by
.
.
.
d
zero
byte
somewhere
in
the middle of the string, VAX LISP will not
notice this and shorten the
string.
You
must
take
<care
of
this
‘situation yourself.

2.6.4

Converting VAX Data Types to LISP Objects

The call-out facility must convert the VAX
data
resulting
£from
the
execution
of an external routine to a LISP object before the facility

2-16

CALLING

can

return

the

data

combinations

the

location

the

EXTERNAL ROUTINES

LISP

data

types

the

result

return

the

type

with

the

:RESULT

keyword

require

that

you

specify

both

you

must

column

Table 2-5:

LISP

always

the

specify

the

data

from

cases,

LISP

with

Table

VAX

default
cases

marked

system.

and

asterisk,

LISP

the

type,

2-5

the

that

Section

LISP

and

that

wvalid

specifies

routine.
you

VAX

1is

The

specify

2.4.3).

the

type

the

also

external

require

(see

shows

types.

All

types.

the

only
other
Since

first

table.

Conversion Table from

Type

Default

CHARACTER

VAX Type to

VAX

LISP Type
Location
of Result

Type

:UNSIGNED-BYTE

Low-order

byte

INTEGER

:BIT

RO,

unsigned

INTEGER

:BYTE

RO,

signed

INTEGER

:UNSIGNED-BYTE

RO,

unsigned

INTEGER

RO,

signed

INTEGER

:UNSIGNED-WORD

RO,

unsigned

RO,

signed
unsigned

INTEGER

WORD

LONGWORD

INTEGER

:UNSIGNED-LONGWORD

RO,

INTEGER

RO/R1,

signed

INTEGER

:UNSIGNED-QUADWORD

RO/R1,

unsigned

SINGLE-FLOAT

:F-FLOATING

DOUBLE-FLOAT

:G-FLOATING

DOUBLE-FLOAT

:D-FLOATING

QUADWORD

SIMPLE-BIT-VECTOR
v

¥y

2.7

CALLING

SYSTEM

SERVICES

The

call-out

facility

provides

and

system

standard

how

examples

VMS

RMS

define

and

<calling

mechanism

services.

for

system

services.

2-17

LISP

Sections

services.
For

programs

2.7.1

Section
a

listing

and

call

2.7.2

list

2.10
of

VMS

provides
services

CALLING EXTERNAL ROUTINES

and

information

Reference

those

Manual.

For

the

VAX

services,

see

services,

see

listing

the

RMS

Record

VAX/VMS
services

Management

System
and

Services

information

Services

Reference

Manual.

2.7.1

Defining System Services

Defining VMS
external

the

and

explanation

understand

RMS

routines
the

system

with

services

few

defining

following

similar

restrictions.

external

You must

routine

1in

defining
be

other

familiar with

Section

2.4

restrictions:

You
must
omit
the
file
name
argument
from
the
DEFINE-EXTERNAL-ROUTINE macro specification.
Omission of this
argument causes the macro to assume that
the
function
being
defined
1is a system service.
If you use the name of a system
service but supply a file name
(not
NIL),
the LISP
system
assumes
that you want an entry point in an ordinary shareable
image of that name rather than the VMS system service given as
the

external

routine

name.

The

entry-point
name
specification must be

1in
the
DEFINE-EXTERNAL-ROUTINE
macro
one of the system service entry points.

The order and the correct number of system
service
arguments
in
the
DEFINE-EXTERNAL-ROUTINE
macro
specification
must
correspond to the order and number specified by the
service'’s
definition.

If a system service resides in a shareable image (for example,
SYSSMOUNT
in MOUNTSHR), then the system service is defined as
any other external routine in a shareable image.
For purposes
of
this discussion, the system service is is not considered a
system

See

Section

out

2.7.2

service.

2.10

system

for

examples

of defining

external

routines

that

«call

services.

Calling out to System Services

Calling VMS and RMS
system
services
1is
similar
to
calling
other
external
routines with a few restrictions.
You must be familiar with
the explanation of calling out to an external routine in
Section
2.5
following

restrictions:

stem services with a complete
argument
the last several arguments.
Put NIL in
the omitted arguments -- including
omitted
trailing
N

u must
mus
al
You
always
list, even 1if you om

|]._..l.

the

place of

arguments.

to understand

CALLING EXTERNAL ROUTINES

Many system services require data structures that
are
filled
in
or
modified
at
a
later time (for example, the IOSB for
SYS$SQIO).
These data structures
must
be
created
as
alien
structures
and
statically allocated so that they will not be
moved by VAX LISP

Chapter

3).

You cannot refer to VMS symbolic
constants
(such
as
return
status values or field offsets) by their symbolic names.
LISP
has

2.8

(See

knowledge

these

constants.

ERRORS DURING EXTERNAL ROUTINE EXECUTION

Errors that occur
during
the
activation
or
the
execution
of
an
external routine are trapped by the VAX LISP error handler.
The types
of errors that might occur during these operations include VMS
errors
that
occur
while
vyou
are
accessing
a
shareable
image and error
conditions that the external
routine
signals
(by
way
of
the
VMS
error-signaling mechanism).
You cannot correct these errors.

NOTE
The VAX LISP error handler regards signaled conditions
as
fatal
errors
(including
conditions
that have a
success

status).

Status codes returned by an external routine, however, do
not
always
represent
uncorrectable
errors.
The
operation
that
the call-out
facility performs when a routine returns a status code
1s
determined
by
the
wvalue that is specified with the :CHECK-STATUS-RETURN keyword
(see Section 2.4.3) in the routine’s definition.
1If the value
1s
T,
the
facility
examines the contents of register RO and interprets the
routine’s return value as a VMS status code or a user status code.
If
the
severity
of the return value is warning, error, or severe-error,
the
LISP
system
signals
a
continuable
error.
If
the
:CHECK-STATUS-RETURN
keyword
1is specified with NIL, all status codes
are ignored.
If the value is an integer, an error is signaled 1f
the
return value

The
of

was

equal

that value.

error message "Key not found in tree" may occur
a call to an external routine.
This means that

unable

locate

the

entry

point

during
execution
the CALL-OUT macro

specified

with

the

DEFINE-EXTERNAL-ROUTINE
macro.
The
macro
specification
may
be
incorrect or the entry point was not specified in the UNIVERSAL option
to the VMS linker when the shared image was created.

CALLING

EXTERNAL ROUTINES

2.9

SUSPENDING A LISP SYSTEM CONTAINING

You

can

suspend

routine
such

system,

correct

you

mapped

environment
they

that

executing
or

the

1images

(with

cannot

follows

not

you

are

memory

are

contains
When

you

suspend

certain

restrictions

ensure

system.

These

restrictions

acguired

from

outside

unmapped when
remapped

operation.

the

time

aware of the

undesirable

that

routines.

automatically

remapped

system

external

resumed

suspend

automatically
create

aware

LIBSGET_VM)

LISP

calls

must

operation

because

and

definitions

results.

EXTERNAL ROUTINE DEFINITION”

the

during

Defined

the

resume

LISP

operation

routines

routine

other

results

exist

the

system exits,

external

restrictions,

Undesirable

LISP

external

are

called.

side effects might

can

occur

from

the

following:

Memory acquired with

Data

initialization

Open

files

Undefined

logical

2.9.1

Acquiring

Memory

acquired with

routine
by

names

Memory with
the

LIBSGET_VM
VMS

deleted when you

resume

operation.

for

example,

LIBSGET_VM

exit

This

acquired memory between
routines,

LIBS$SGET_VM

calls
use

the

LISP

prevents
across

such

function

system

you

1in

and

from

and

vyou

external

not

remapped

storing

suspend/resume

memory,

data

cycle.

cannot

1in

Many RTL

resume

the

routines.

2.9.2

Initializing

When

Data

external

initialization

and

routine
takes

reset

when

the

time

vyou

<call

the

it were

retain

executes
If

you want

code

that

routine’s

depends

contains

branches
image

routine

data

across

remapped.

after

executing

code

based

for
a

that

sets

those

flags,

resume

the

first

flag.

result,

operation,

for

flags
the

the

are

first

routine

time.

suspend/resume

first-time

flags
the

Use

cycle,

one

do not write

the

methods:

following
|

@ Retain data as individual LISP objects, which
external

routines.

2-20

are

passed

CALLING

®@

Store

Undesired
in

data

side

series

system
LISP

effects
with

the

suspended

system

alien

structures.

not

occur

external

DEFINE-EXTERNAL-ROUTINE

before

retains

EXTERNAL ROUTINES

the

call

information

routines
macro

external
the

are

and

the

defined
resulting

routine.

external

routine

The

VAX

definition

provides.

2.9.3

Using

When you

Open

exit

the

operation does

2.9.4

Using

‘Logical

Files
LISP

system,

not

reopen

Logical

Names

names

used

the

files

call

files

the

EXAMPLES OF USING THE CALL-OUT FACILITY
following

call

examples

out

Lisp>

external

resume

routines.

DEFINE-EXTERNAL-ROUTINE

2.10

closed.

still

how

resume

are

opened

must

The

defined when you

open

that were

suspended

show both how to define

macro

system.

external

routines

and

them.

(DEFINE-EXTERNAL-ROUTINE

(MTHSACOSD
-FILE

"MTHRTL"

c:RESULT

(:LISP-TYPE
SINGLE-FLOAT
cVAX-TYPE

:FP-FLOATING)
)

"This routine returns the
of an angle in degrees.”
(X

arc

:LISP-TYPE

SINGLE-FLOAT

cVAX-TYPE

:F-FLOATING))

cosine

MTHSACOSD

Defines an RTL routine, called MTHSACOSD, which
returns
the
arc
cosine
of
an
angle in degrees.
The routine takes one
read-only argument, which is a F_floating number, and returns
the result as a F_floating number.
Lisp>

(CALL-OUT MTHSACOSD

0.5)

60.0
9
o
Calls
N

value.

the RTL

routine MTHSACOSD,

and

returns

the

routine’s

CALLING

Lisp>

EXTERNAL ROUTINES

(DEFINE-EXTERNAL-ROUTINE

(SMGS$SCREATE_PASTEBOARD
:FILE

"SMGSHR"

:RESULT

(NEW_PASTEBOARD-ID

:LISP-TYPE

INTEGER

:VAX-TYPE

: ACCESS

(OUTPUT-DEVICE
(PB-ROWS

:LISP-TYPE

(PB-COLUMNS

(PRESERVE-SCREEN-FLAG

:UNSIGNED-LONGWORD

:IN-OUT)

STRING)

INTEGER

:LISP-TYPE

INTEGER)

:ACCESS

INTEGER

:IN-OQUT)

:ACCESS

:LISP-TYPE

: VAX-TYPE

:IN-OUT)

INTEGER

:UNSIGNED-LONGWORD)
)

SMGSCREATE_PASTEBOARD
Defines

the

SMG

screen

management

routine

called

SMGSCREATE_PASTEBOARD.
Lisp>

(DEFVAR

*PASTEBOARD-ID*

-1)

*PASTEBOARD-ID*

Defines
ID

special

returned

Lisp>

the

variable

that

external

will

contain

the

pasteboard

routine.

(CALL-OUT SMGSCREATE_PASTEBOARD

*PASTEBOARD-ID*
NIL

NIL

Calls the external routine
the
special
wvariable
to
arguments
given.

are

The

This

example

that

omitted,

result

shows

written

and

status

you

SMG$SCREATE_PASTEBOARD,
receive the pasteboard
a
1s

how to

1is

returned.

call

out

external

routine

FORTRAN:

FUNCTION

NUMBERS (X,

IMPLICIT

INTEGER*4

(A-2)

NUMBERS=Y *

preserve-screen-flag

specifying
ID.
Three

(X + Y ** X) / X

RETURN
END

Defines

function written

manipulates
$

FORTRAN

Compiles

two

integers

and

FORTRAN,
returns

NUMBERS

the

FORTRAN

function NUMBERS.

called NUMBERS,
1integer.

which

CALLING EXTERNAL ROUTINES

LINK/SHAREABLE=DBA2:[SMITH]EXAMPLE

NUMBERS,SYSSINPUT:/OPTIONS

UNIVERSAL=NUMBERS

DEFINE

Links
The

the

new

Lisp>

DBAZ:[SMITH]EXAMPLE

FORTRAN

name

globally
the

EXAMPLE

function NUMBERS

NUMBERS

1is

available.

shareable

specified
logical

into
as

name

shareable

an entry point
defined

1image.
that

refer

1is
to

image.

(DEFINE-EXTERNAL-ROUTINE

(NUMBERS

:FILE

"EXAMPLE"

:RESULT

INTEGER)

NUMBERS

Defines

manipulates
name

external
integers

routine,
called
NUMBERS,
returns an integer.
The

two

specified

for

and

the

shareable

image

because

the

‘which
logical
name

1is

not

in SYSSSHARE.
The arguments do not have options because,
by default, the arguments are assumed to be longword integers
that are passed by reference.
Lisp>

(CALL-OUT NUMBERS

23536

Calls

the

function

external

routine

which

example illustrates
facility.
Assume
that
the

LISP

a more

outside

Lisp>

(DEFINE-ALIEN-STRUCTURE

the

the
call-out
named COMPLEX

system.

:G-FLOATING

(IMAGINARY

complex use of
external
routine

exists

(REAL

returns

This

NUMBERS,

value.

COMPLEX-NUMBER

:G-~FLOATING

16))

COMPLEX-NUMBER

Defines a
complex
number
(double
precision).
The
alien
structure
facility is used to define complex numbers because
the data type cannot be represented
directly
1in
VAX
LISP.
Chapter 3 describes the alien structure facility.
Lisp>

(DEFINE-EXTERNAL-ROUTINE

(COMPLEX_EXP
(OUTPUT

:FILE

:LISP-TYPE
:ACCESS

(INPUT
COMPLEX_EXP

"COMPLEX")
ALIEN-STRUCTURE

:IN-OUT)

::LISP-TYPE

ALIEN-STRUCTURE)
)

CALLING

Defines

the

complex

numbers.

Lisp>

(SETQ

external

EXTERNAL ROUTINES

routine,

called

(MAKE-COMPLEX-NUMBER

COMPLEX EXP,

:REAL

Lisp>

Structure

(SETQ

6.123456d-4))

COMPLEX-NUMBER #x5010324>

(MAKE-COMPLEX-NUMBER

:REAL

0.0d0

: IMAGINARY

#<Alien

Structure

These

expressions

Lisp>

(CALL-OUT

Calls
the

the

returned
was

not

Lisp>

COMPLEX-NUMBER
create

1in

from

two

COMPLEX_EXP

external

wvalues

uses

5.0d1

: IMAGINARY

#<Alien

which

routine

the

#x5010348>

complex
C2Z2

numbers,

function

Cl1 and

C2.

C1)

COMPLEX_EXP.

alien

0.0d0))

The

structure
call

routine

C2.

because

the

changes

value

:RESULT

1is

not

option

specified.

(DEFINE-EXTERNAL-ROUTINE

(SYSSDALLOC

(DEVNAM

:LISP-TYPE

STRING)

(ACMODE

:LISP-TYPE

INTEGER

:RESULT

:MECHANISM

INTEGER)

:IMMED))

SYSSDALLOC

Defines
Lisp>

the VMS

system service

(CALL-OUT

SYSSDALLOC

SYS$SDALLOC.

"TTH7:"

NIL)

2312

Calls

the VMS system service SYSSDALLOC.
NIL is specified to
for
the
omitted
argument;
this
-ensures that the
correct number of arguments are specified.

account

Suppose

that

statically
are

the

LISP variables

allocated

file

alien

attribute

OLD

and

structures

blocks

NEW

(see
be

are

Chapter

wused

1in

bound
3),
a

which
rename

operation.

Lisp>

(DEFINE-EXTERNAL-ROUTINE
(OLD-FAB

:LISP-TYPE

NIL

sError

NIL

:will

(NEW-FAB

:LISP-TYPE

and
not

(SYSSRENAME

:RESULT

INTEGER)

ALIEN-STRUCTURE)

success
be

routines

used

ALIEN-STRUCTURE))

SYSSRENAME

Defines
Lisp>

the RMS

(CALL-OUT

system service

SYSSRENAME.

SYSSRENAME

NIL

OLD

NIL

NEW)

Calls

the RMS

system service

2-24

SYSSRENAME.

NIL

specified

CALLING EXTERNAL ROUTINES

This ensures that the
arguments.
omitted
the
for
account
correct number of arguments are specified.
NIL is
specified
for the
error
and status routines because ASTADR arguments
must be omitted.
The call returns 1, indicating success.

CHAPTER 3

DEFINING AND CREATING ALIEN STRUCTURES

A structure in COMMON LISP is a collection of fields and field values.
It 4is similar to a record in Pascal or a typedef in C and is a useful
data-management tool. See COMMON LISP: The Language for a full
explanation

structures.

An alien structure is a VAX LISP data type used to exchange data
between LISP programs and external routines utilizing VAX data
Like a COMMON
structures that LISP code cannot ordinarily access.
LISP structure, the definition of an alien structure causes the
definition of a number of functions for the «creation of alien
structures, the accessing of fields or slots, and so on. The "alien"
in the name "alien structure" refers to the structure’s double
purpose:

To access data coded in a language foreign to LISP

To make data coded in LISP available to a different language

Typical alien structures are represented internally
collections of integers, floating-point numbers,

as byte-aligned
strings, and bit

vectors.

VAX LISP provides macros that let you define, create, and access alien
These macros are used primarily with the VAX LISP
structures.
call-out facility; they are wused to create argument values for
have arguments or control Dblocks too
that
routines
external
complicated for the call-out facility to convert (see Chapter 2).
This

chapter describes:

How to define an alien structure

What the DEFINE-ALIEN-STRUCTURE macro does

Components of an alien structure definition

DEFINING AND CREATING ALIEN STRUCTURES

The

Examples

How

chapter

how

create

also

alien

lists

the

3.1

alien

structures

functions

and

macro.

See

DEFINE-ALIEN-STRUCTURE

define

DEFINE-ALIEN-STRUCTURE

macros
Part

vyou

for

can
a

use

summary

with

the

description

macro.

DEFINING AN ALIEN STRUCTURE DATA TYPE

Before

you

can

structure.

create

You

DEFINE-ALIEN-STRUCTURE
macro

The

described

with

definition

structures

that

function)

create

macro

than

one

and

named

new

that

macro 1is

and

macro

types

DEFSTRUCT

objects

while

the

containing

non-LISP

The

format

that

you

This

the

that

VAX

LISP

the

DEFSTRUCT

type

structure;

can

then

(the

the

macro

DEFINE-ALIEN-STRUCTURE

create

from

the

type

macro

1in

contains

their

type

macro

DEFUN

defines.

predicate,

different

objects

defines

system

use

copier,

rather

LISP

DEFSTRUCT

data

constructor,

kind

The

different

function

DEFSTRUCT
in

structure.

similar

access,

DEFINE-ALIEN-STRUCTURE

define

the

similar

create

the

data

The

type

type.

compound

component)

not

creates

functions.

contain.

does

data

must

Language.

definition

DEFINE-ALIEN-STRUCTURE

both

macro

The

macro

this

(define

This

LISP:

<creates

individual

that

vyou

structure

macro

treats

The

structure,

the

macro.

COMMON

DEFINE-ALIEN-STRUCTURE

this

alien

define

from

the

defined

data

containing

LISP

defines

type

objects.

alien

structure

definition

1is:

DEFINE-ALIEN-STRUCTURE name-and-options
[doc-string]

{field-description}*
The

following

example

alien

structure

definition:

(DEFINE-ALIEN-STRUCTURE SPACE
"An

The

structure

definition"

(AREA-2

:SIGNED-INTEGER

8))

definition

defines

preceding
type

and AREA-2,
numbers

bytes.

See

alien

:SIGNED-INTEGER

new data

example

(AREA-1

alien

which
the

defined

are

stored

definition

Sections
structure

3.3

and

alien

object

internally as
specify

3.4

definition.

for

structure

consisting

the

VAX

named
two

32-bit

structure’s

description

SPACE.

fields,

This
AREA-1

integers.
field

the

lengths

The
in

components

DEFINING AND CREATING ALIEN STRUCTURES

3.2

WHAT THE DEFINE-ALIEN-STRUCTURE MACRO DOES

When the LISP system evaluates the definition of an
alien
the DEFINE-ALIEN-STRUCTURE macro automatically creates:
New data

structure,

type

The name you give to the alien structure becomes a
LISP
data
type.
For example, the preceding definition creates the data
type SPACE, which is a subtype of ALIEN-STRUCTURE.
Access

functions

Access functions are created that can access the data in
each
data
field of the defined alien structure.
There are as many
access functions
as
there
are
data
fields
1in
the
alien
structure.
The DEFINE-ALIEN-STRUCTURE macro by default names
each access function by prefixing each data
field
name
with
the name of the alien structure and a hyphen (-).
In the preceding example, the
access
functions
SPACE-AREA-1
and
SPACE-AREA-2 are created automatically.
These l-argument
functions return the LISP integers corresponding
to
the
VAX
integers
stored
in
the
fields AREA-1 and AREA-2.
Although
these functions have only one argument, access
functions
can
have
one or two arguments, depending on the complexity of the
field

the

functions

access.

These access functions are acceptable access forms in
a
call
to
the
SETF
macro
(unless
:READ-ONLY T was specified as a
field option -- see Section 3.4.4).
Constructor

function

A
constructor
function,
whose
default
name
1s
the
new
data-type
name
with
the
prefix
"MAKE-",
1is
<created.
A
constructor function is used to create alien structures
after
you
define
thenm.
For
example,
the
preceding
definition
automatically creates a constructor function named MAKE-SPACE.
You
would
wuse
this
function
to
<create structures of type
SPACE.
See Section 3.6 for information on
keyword
arguments
the

constructor

Copier

function

accepts.

function

A copier function, whose default name
1is
the
new
data-type
name
beginning with the prefix "COPY-", is created.
A copier
function is a l-argument function that can make a
copy
of
a
created
alien
structure.
This
copy
1s
not
a
copy of a
structure’s
definition,
but
a
copy
of
a
specific
alien
structure.
#

9 9

29 Y

DEFINING

For

example,

function

(the
It

that

alien

1is

the

named

function

AND

preceding

returns

sometimes

before

This

copy

1is

type

wuseful

ALIEN

STRUCTURES

definition

COPY-SPACE.

structure)

structure

CREATING

creates

function

its

argument

1s
1f

a
a

copier

l-argument

the

argument

SPACE.

preserve

copy

passing

routine

whose

default

name

the

suffix

"-P",

created.

function

that

determines

whether

its

that

alien

modifies

destructively.

Predicate
A

function

predicate,

ending

with

l1-argument

occurrence
preceding

predicate
argument

the

named
is

function
only

memory

function

does

#<Alien
initial

are

Structure

name

predicate
argument

For

creates

function

identifies

#x5036E8

you want

structure,
Section

However,

address

not

For
output
having

SPACE

1is
1s

example,

a
an

the

l-argument

returns

its

(#)

character

the

as an

structure’s

the

and

the

The

alien

name

that

the

function

show

vyou

must

specify
a

angle

alien

data

Dbrackets

syntax used

Alien

structure.

user-defined

specifying

two

COMMON LISP

contents

function
structure.

example,
the following line
as the
wvalue
of
an
the default print function:

the memory address

3.3.2.5

individual

device

standard

objects.

object

this

#x5036E8>

part
the

pound

nonreadable

identifies

3.3

structure.

This

created.

the

structure’s
data
fields.
be displayed on your
individual alien structure

data-type

SPACE.

would

new

function

prints

The

alien

automatically

SPACE-P.

type

A print
This

defined

definition

the

The word

type.

Structure

SPACE

The

number

alien

structure.
the

data

vyour

own print

function.

See

ALIEN STRUCTURE NAME, OPTIONS, AND DOCUMENTATION STRING

When you define

the

structure.
structure as

an alien structure, you must specify a
name
for
In
addition,
vyou
can specify options that apply to
a whole and a documentation string.

the

DEFINING

3.3.1

Alien Structure

When
as

specifying
a

symbol

the
as

AND

CREATING

ALIEN

STRUCTURES

Name
alien

structure’s

the

name

preceding

without

options,

definition

type

specify
SPACE.

it
For

example:
(DEFINE-ALIEN-STRUCTURE

SPACE

- )
If

you

specify

first
each

options,

element
option.

o0f
For

specify

list

the

whose

alien

other

structure’s

elements

are

name

separate

the

lists

for

example:

(DEFINE-ALIEN-STRUCTURE

(SPACE

(option-1)

(option-2)

...)

. )

NOTE
To

3.3.2
By

same

symbol

both

structure

use

data

type

and

also

structure

(DEFSTRUCT)

data

the

type

name

as
is

the

alien

name

error.

Options

specifying

definition,

You

the

options

you

the

name

field

alien

Change

the

default

names

Change

the

default

name

the

constructor

Change

the

default

name

the

copier

Change the default name of the predicate function

Specify

your

can

also

request

predicate
Specify
value.

own

print
that

functions

not

option

list

You

structure’s

can:

can

the

access

functions

function

function
the

access,

generated
that

specify more

contains
than

one

constructor,

copier,

and

all.
a

option

keyword
at

and

time.

symbol

The

format

1s:

(alien-struc-name
You

can

keyword

use

the

(keyword-1

following

detail.

value-1)

keywords.

The

(keyword-2

value-2)

sections

...)

explain

each

DEFINING AND CREATING ALIEN STRUCTURES

to name access

functions

:CONC-NAME

:CONSTRUCTOR -- to name the constructor ffinction

:COPIER --

to name

:PREDICATE

:PRINT-FUNCTION

the copier

to name

function

the predicate

to specify your

function

own print

function

3.3.2.1
Naming
Access
Functions - By
default,
the
DEFINE-ALIEN-STRUCTURE
macro
produces names for an alien structure’s
access functions by prefixing each field name with
the
name
of
the
alien
structure
and a hyphen (-).
For example, the default names of
the
access
functions
created
by
the
preceding
definition
are
SPACE-AREA-1

and

SPACE-AREA-2.

If you want to change the default names of an alien structure’s access
functions,
specify
the :CONC-NAME (concatenated name) keyword with a
string (the prefix you want the names to have) in your alien structure
definition.
For example:

Lisp>

(DEFINE-ALIEN-STRUCTURE
(AREA-1

(AREA-2

(:CONC-NAME "GALAXY-"))

(SPACE

:UNSIGNED-INTEGER
:UNSIGNED-INTEGER

0
4

4)
8))

SPACE

When
the
LISP
system
evaluates
the
preceding
definition,
the
DEFINE-ALIEN-STRUCTURE
macro
produces
access
functions
named
GALAXY-AREA-1
and
GALAXY-AREA-2.
If
you
specify
NIL
with
the
: CONC-NAME
keyword,
the
function
names
are
the same as the field
names,

AREA-1

The access

and AREA-2.

functions

can be used with SETF

change

the

value

field.

3.3.2.2
Naming
the
Constructor
Function - By
default,
the
DEFINE-ALIEN-STRUCTURE
macro produces a name for an alien structure’s
constructor function by prefixing the
string
"MAKE-"
to
the
alien
structure’s
name.
For
example, the default name of the constructor
function created by the preceding definition 1s MAKE-SPACE.
If you want to change the default
name
of
a
constructor
function,
specify
the :CONSTRUCTOR keyword with a string (the name you want) in
your alien structure definition.
For example:

3-6

DEFINING

Lisp>

AND

CREATING

(DEFINE-ALIEN-STRUCTURE

ALIEN STRUCTURES

(SPACE

(:CONSTRUCTOR

(AREA-1

:UNSIGNED-INTEGER

(AREA-2

:UNSIGNED-INTEGER

8))

CREATE-SPACE))

SPACE

The

LISP

system

structure,
you

create.

definition,
If

does

though

you

For

the

not

hyphenate

your

appropriate

for

example,

macro

specify

NIL

DEFINE-ALIEN-STRUCTURE

and

you

cannot

when

names

create

the

alien

LISP

the
does

the

name

the

new

name

that

evaluates

function

define

that

the

preceding

CREATE-SPACE.

CONSTRUCTOR

not

structures

with

system

constructor

with
macro

new name
you

keyword,

constructor

the

function

type.

NOTE
Alien

structure

argument
functions

3.3.2.3

contructor

list,
do

Naming

take

function

structure’s

preceding

you

Copier

macro

Function

prefixing

the

example,

definition

COPY-SPACE.

change

alien
Lisp>

the

name

string

with

structure.

For

the

(SPACE
0

8))

alien
of

specify

your

the

definition

REPRODUCE-SPACE))

system

evaluates

1If

you

Naming

the

name.

created

produces

specify

NIL

does

Predicate

attaching

macro

the
For

the

macro
macro

DEFINE-ALIEN-STRUCTURE

function

the

function

function,
want)

the

structure’s

copier

(:COPIER

:UNSIGNED-INTEGER

DEFINE-ALIEN-STRUCTURE

alien

example:

:UNSIGNED-INTEGER

REPRODUCE-SPACE.

function

default,
an

"COPY-"

you

(AREA-1

LISP

structure’s

copier

(AREA-2

DEFINE-ALIEN-STRUCTURE

3.3.2.4

take

constructor

for

default

name

SPACE

When

name

string
the

(the

(DEFINE-ALIEN-STRUCTURE
~

not

list.

produces

For

keyword

DEFSTRUCT

argument

name.

want

:COPIER

the

DEFINE-ALIEN-STRUCTURE

copier

functions

although

with

not

string

preceding

"-P"

the

function

named

:COPIER

copier

Function

the

definition,

copier

the

define

produces

example,

preceding

default,

the

name

the

end

default

definition

keyword,

name

the

function.

the

of
of

SPACE-P.

the

predicate

the

alien

predicate

DEFINING AND CREATING ALIEN STRUCTURES

If you want to change the name of the predicate function, specify
the
: PREDICATE
keyword
with
a
string
(the
name
you
want)
1in
your
definition of an alien

structure.

For example:

(DEFINE-ALIEN-STRUCTURE (SPACE (:PREDICATE
(AREA-1 :UNSIGNED-INTEGER 0 4)
(AREA-2 :UNSIGNED-INTEGER 4 8))

CHECK-SPACE))

SPACE

When
the
LISP
system
evaluates
the
preceding
definition,
the
DEFINE-ALIEN-STRUCTURE
macro
produces
the
predicate
function
CHECK-SPACE.
1If you specify NIL
with
the
:PREDICATE
keyword,
the
DEFINE-ALIEN-STRUCTURE macro does not define a predicate function.

NOTE

P,
name
Be aware that if you create a field with the
then there will be a name conflict between the default
of
predicate function and the default access function
For example, with an alien struture of
field.
P
the
type SPACE, both the predicate function and the access
would have the same name,
field
P
the
of
function
SPACE-P.

3.3.2.5
Specifying a Print Function - You can use the :PRINT-FUNCTION
keyword
option
to
specify
the
function
that is to print an alilen
structure.
You might want to do this since the default print function
prints
only
the memory address of a structure; it does not print the
contents
of
the
structure’s
data
fields.
To
alter
the
print
representation of an alien structure, specify a print function in that
alien structure’s definition.
The following example is
of
an
alien
structure definition specifying a print function:
(DEFINE-ALIEN-STRUCTURE

(SPACE (:PRINT-FUNCTION SPACE-PRINT))
(AREA-1 :UNSIGNED-INTEGER 0 4)
(AREA-2 :UNSIGNED-INTEGER 4 8))

If you specify a print function in an alien structure definition,
you
also
must
have
previously
defined that print function.
This print
function can be defined to have an
arbitrary
action.
However,
the
print

function definition must have

three

arguments:

A NAME indicating the alien structure to be printed

A STREAM indicating the stream to print to

An INTEGER indicating the current print depth

3-8

DEFINING AND CREATING ALIEN STRUCTURES

These

three

arguments

function

argument,

than

ignored with

alien

structure
(DEFUN

the

The

printed.

The

DEPTH

The

alien

STREAM

allowing you

However,

the

wuseful

Consequently,

STREAM

that

following

last

with

argument

example

DEPTH)

area-1

ALIEN)))

example,

the

argument

three

refers

STREAM argument

LISP.

depth,

wuser-defined

DEPTH))

"#<Space:

ignored

argument

structure’s

definition:

(SPACE-AREA-2

argument

DEPTH

structures

ALIEN)

The

COMMON

(SPACE-AREA-1

ALIEN

structure.

(ALIEN

(IGNORE

preceding

alien

SPACE-PRINT

(FORMAT

current

print-function

(DECLARE

DEPTH.

the

often

requlirements

specified

indicating

structure

are

can

control

the
the

stream

by using

deep

are

= “d>" &"

ALIEN,

individual

compared with

how

area-2

arguments

here

= "d,

the

to which

the
the

DECLARE
value

printer

STREAM,

alien

will

and

structure

print.

special

form.

*PRINT-LEVEL*,

print.

This

argument
is useful with structures since you may wish to restrict the
printer from printing all the
information
1in
a
complex
structure.
However,

this

argument

of
to

the alien structure
abbreviate the data

you want

variable

The

to use

following

user-defined
Lisp>
Lisp>

this

example

argument,

COMMON LISP:

the

output

see

and

the

The

Language.

printed

because

the

fields

1is unnecessary

the

*PRINT-LEVEL*

the

previous,

function:

EXAMPLE-3

area-1

(MAKE-SPACE

area-2

= 6,

area-2

:AREA-1

:AREA-2

5))

EXAMPLE-3

#<Space:
the

ignored

DEPTH

example
print

(SETF

$#<Space:

the

description

are immediate objects,
fields printed.

area-1

preceding

example,

the

MAKE-SPACE

function

creates

individual
structure
of
the
previously
defined
type
SPACE.
addition, the preceding,
wuser-defined
print
function
displays
contents of the new alien structure’s data fields.

In
the

or more information on creating print functions
ormatting them, see COMMON LISP:
The Language.
N

3.3.3

for

structures

and on

lad

Documentation String

You

can include a documentation string for an
alien
structure.
The
string
is
optional
and is attached to the symbol as a documentation
string of type STRUCTURE.
Place the string in
the
definition
after
the name and options list as in the example in Section 3.1.

3-9

DEFINING AND CREATING ALIEN STRUCTURES

3.4

ALIEN STRUCTURE FIELD DESCRIPTIONS

Alien

structures
description
in
description

are

composed of data fields,
each
of
the
alien
structure
definition.

contains:

Field

name

Field

type

Start and end positions

Options

When you define an alien
list
of
the
preceding
name.

Use

this

structure,
elements

specify a field description
as
a
whose first element 1s the field’s

format:

(data-field-name
For

which
has
a
A
data-field

type start-position end-position options)

example:

(FIELD-1

:TEXT

:0CCURS

:OFFSET

15)

The following sections describe the elements in a field description.

3.4.1

Field

Name

An alien structure’s
field
name
1is
FIELD-1
1is
a
field
name
1in
the
constructor functions refer to field
values of their respective fields.

3.4.2

Field Type

Alien structure field types specify a
data
1in a field and a LISP data type.
structure data in both directions:

When

storing

objects

the

a
symbol
naming
that
field.
previous
example.
Access
and
names
to
access
and
set
the

the data

in a

field,

the

system

converts

LISP

into VAX data.

When accessing

the data

data

objects.

into

relationship
between
the
VAX
The LISP system converts alien

LISP

example,

:TEXT

in a

field,

field

3-10

the

type.

system

converts

VAX

DEFINING AND CREATING ALIEN STRUCTURES

3.4.2.1

by VAX

Given

LISP.

Table 3-1:

Field

See

Types

Chapter

Alien Structure

Table

for

3-1

lists

the

field

information

types

these

defined

types.

Field Types
Internal

Type

VAX

:ASCIW

Storage

character

word
of

the

string.

:VARYING-STRING

+:ASCIZ

VAX

string;

data

You
to

must

the

allocate

maximum

this

for

:ASCIW.

character

string

NULL

character

byte(s)).

space

You

for

accessing
string

16-bit

count

1in

two

length

the

bytes

the

count.

terminated

(0's
must

the

this

first

contains

characters

hold

synonym

the

vector

number

addition

string

Representation

with

the

allocate

terminating

slot,

terminates

the
at

the

last
enough

returned

LISP

the

first

NULL

character.

VAX

+TEXT

nonvarying

allocate
the

one

byte

character
for

every

string.

+ STRING

synonym

for

: SIGNED-INTEGER

Signed

:UNSIGNED-INTEGER

Unsigned

integer

:BIT-VECTOR

Unsigned

1integer

: F-FLOATING

F_floating

data

:G-FLOATING

G_floating

data

:D-FLOATING

D_floating

data

two'’s

:TEXT.
complement

integer

NOTE
When you

access

a VAX

converts

equilvalent

:H-FLOATING

to a VAX

:D-FLOATING type,
the
LISP
DOUBLE-FLOAT,

:G-FLOATING type.

H_floating

3-11

data

accessor
1is

which

string;

character

DEFINING AND CREATING ALIEN STRUCTURES

Table

3-1

(cont.)

Type

Internal

:POINTER

(See

: SELECTION

(See below)

The

:POINTER and

the

:SELECTION

Storage Representation

below)

types

have

the

following

explanations:

¢:POINTER

If you want your alien structure to contain the address of the data in
another alien structure, specify the :POINTER field type in one of the
data fields.
This field type indicates that the field contains a
VAX
pointer
pointing
to
the
start
of
the
data area of another alien
structure.

NOTE
The alien structure pointed to must not be dynamically
allocated.
Otherwise, after a garbage collection, the
pointer will no longer point
to
the
specified
data
field.
For
a
description
of
how
to
statically
allocate alien structures, see Section 3.6.2.

The

format

for

using

(:POINTER [name]

:POINTER

field

type

1is:

[:DISPLACED value])

The optional name argument is the type of alien structure pointed
to.
If
vyou specify this argument, the field’s update function checks that
the new value of this field (the name you give it when you
create
an
instance
of
the
structure)
points
to a structure of the specified
type.

The optional :DISPLACED keyword causes the stored VAX pointer to point
to the start of the alien structure data area plus the number of bytes
specified for the value.
You can omit the parentheses if you
do
not
specify

example

the

(AREA-1

field
i wde St efm Nl

name

field with

data

(:POINTER

and

SPACE)

the

:DISPLACED
@ @ oo B Gn ok G O S Sk o

the

type

keyword.
Y e @ e &

:POINTER.

The

following
— e e a B EY S 22

DEFINING AND CREATING ALIEN STRUCTURES

¢cSELECTION

The :SELECTION field type lets you enumerate
all
the
possible
values of a field.
The format for using a :SELECTION field type
(:SELECTION
If

you

specify

the

data
1is:

...)

:SELECTION

type,

the

DEFINE-ALIEN-STRUCTURE

macro

associates
each
element
1in
the
1list (sn) with an unsigned 1integer
corresponding to the element’s position in
the
1list.
For
example,
take the
following alien structure definition with one field of type
:SELECTION.

Lisp>

(DEFINE-ALIEN-STRUCTURE MAP
(STATE (:SELECTION

YORK"

"CALIFORNIA"

"NEW HAMPSHIRE")

"MASSACHUSETTS"
0

"NEW

4))

MAP

This defines a MAP structure whose MAP-STATE field can have one of the
following
values
("MASSACHUSETTS"
"NEW
YORK"
"CALIFORNIA"
"NEW
HAMPSHIRE").
The field is internally stored
as
an
wunsigned-integer
indicating
the
position
of
the
wvalue
1in
the
selection
1list
("MASSACHUSETTS" "NEW YORK" "CALIFORNIA" "NEW HAMPSHIRE").

The DEFINE-ALIEN-STRUCTURE macro uses the EQUALP function
to
compare
the
LISP
object
vyou
give when creating an alien structure with the
item in the selection list of the definition.
Next, an instance of
a
MAP
structure
is
created,
with
its MAP-STATE field initialized to
"MASSACHUSETTS":

Lisp> (SETF GEO (MAKE-MAP :STATE
#<Alien Structure MAP #x47D95C>

Then,

the ALIEN-FIELD function
is used

unsigned

"MASSACHUSETTS"))

access

the

field

integer:

Lisp>

(ALIEN-FIELD GEO

:UNSIGNED-INTEGER Q 4)

Notice the actual value stored in the field is 0 since

"MASSACHUSETTS"

is
the
0’'th
element
of
the
1list.
Next,
the MAP-STATE accessor
function accesses the field as
an
wunsigned
1integer
and
wuses
that
integer
as
an
index
into
the
selection
1list,
returning
the
corresponding
Lisp>

element:

(MAP-STATE

GEO)

"MASSACHUSETTS"

Finally, the SETF form
places
"CALIFORNIA"
in
the
field
and
b 2
s £
ALIEN-FIELD function verifies that "CALIFORNIA" is in position 2.

the

DEFINING

Lisp>

(SETF

AND

(MAP-STATE

CREATING

GEO)

ALIEN

STRUCTURES

"CALIFORNIA")

"CALIFORNIA"
Lisp>

(ALIEN-FIELD

GEO

:UNSIGNED-INTEGER

3.4.2.2

User-Defined

types,

you

Field

can

Types

define

DEFINE-ALIEN-FIELD-TYPE

your

macro.

addition
own

See

Part

the

field
II

for

given

types

field

with

description

the

this

macro.

3.4.3
You

Field Positions

position

start

and

rational
field.
4

are

For
the

3.4.3.1

example,

the

data
the

field

Each

field

arbitrary
units

does

are

not

end

bit

Positions
starts
start

8-bit

divide

end

byte

fixnums,
The

LISP

expands

not

the

The

These

end

specifying

arguments

positions

description,

are

the

and

the

inclusive

and

the

field:

start

That

is,

the

position

the

first

and

field’s

the

field
last

its

end

alien

position

end-position

and

value.

position

For

{4,

8-bit

that

1s,

For

example,

bit

the

start

end

example,

and

field

position

units

1/3)

bytes.

The

you

specify

can

field with

data

area.

value

with

causes

position

start

However,
a

error

value,

fields

within

value

because

the

denominator

when

you

that

call

the

macro.

all

wvalues

:G-FLOATING,
boundaries;

that

are

:D-FLOATING,
is,

their

start

strings

are

type

:H-FLOATING must begin and
and

end

positions

must

ratios.

system does
the

(for

position

bytes,

exceptions:

:F-FLOATING,

ratio;

fifth

DEFINE-ALIEN-STRUCTURE

Some

boundaries.
the

preceding

positions

area

exclusive.

measured

start

following

positions

data

specification.

the

End

field’s

structure’s

field

INTEGER

area

can

starts

the

position

occupies

therefore,
1/2

and

position

alien

the

determine
in

:SIGNED

Start

structure’s
field

and

that

example,

start

end

values

numbers

(AREA-1

the

field

end

not

evaluate

the

DEFINE-ALIEN-STRUCTURE

start

macro.

3-14

and

end

positions

when

DEFINING AND CREATING ALIEN STRUCTURES

3.4.3.2
Gaps Between Field Positions - A gap 1s memory space that you
can
allocate
as part of an alien structure.
For example, if you use
the :OFFSET keyword (see Section 3.4.4.4), you might produce
gaps
1in
an
alien
structure.
See
the
second example in Section 3.5 for an
illustration

gaps.

Even though gaps can exist between fields or at
the
beginning
of
a
field
-- if the first field does not start at 0, only the ALIEN-FIELD
function (see Section 3.7) can access gaps.
The LISP system does
not
generate
forms
that access or set fields that include gaps; that 1is,
LISP-level

code

does

not

process

gaps.

3.4.3.3
Overlapping
Fields - Alien
structure
fields
can
overlap,
letting you access data from more than one field at a time or from one
field in a number of ways.
If you change the data
in
a
field
that
overlaps other fields, the other overlapping fields are also changed.

Overlapping fields are useful when you want data to be interpreted
in
more
than
one
way.
The
following
definition
defines
an
alien
structure that contains
fields
that
overlap.
The
individual
BIT
fields
overlap
the
NUMBER
field,
though
they
do not overlap one
another:
Lisp>

(DEFINE-ALIEN-STRUCTURE

MASK

(NUMBER
(BIT-0
(BIT-1

:UNSIGNED-INTEGER
:UNSIGNED-INTEGER
:UNSIGNED-INTEGER

0 4)
0 1/8)
1,/8 2/8)

(BIT-2

:UNSIGNED-INTEGER

2/8

(BIT-3
(BIT-4

:UNSIGNED-INTEGER
:UNSIGNED-INTEGER

3/8
4/8

3/8)
4/8)
5/8))

MASK

If you specify
different
values
for
overlapping
fields
when
you
initialize
them
(see
Section
3.4.4.1
on initializing fields), the
field values that result are
undefined.
For
example,
consider
an
alien
structure
of the previously defined MASK type where the number
field overlaps the bit fields.
1If you create an instance of MASK with
the
MAKE-MASK
function, and you initialize the number and bit fields
to conflicting values (for example, (MAKE-MASK :NUMBER 0
:BIT-2
1)),
the

result

undefined.

The next example shows the creation of the alien structure NEWMASK
the

previously defined
Lisp>

(SETF

#<Alien

type

NEWMASK

MASK:

(MAKE-MASK))

Structure MASK #x50C600>

3-15

DEFINING

The

following

all

other

are

two

AND

ways

CREATING

ALIEN

STRUCTURES

set

and

16))

bits

NEWMASK

and

clear

bits:

Lisp>

(SETF

(MASK-NUMBER

NEWMASK)

(SETF

(MASK-NUMBER NEWMASK)

Lisp>

3.4.4
By

Field

specifying

that

(MASK-BIT-4

NEWMASK)

the

definition,

options

vyou

data

data-field

can

Whether

field

has

Whether

field

Whether

field

repeats

The
a
in

option

distance

data-field
a

1list

format

can

use

initial

following

alien

characteristics

and

how often

similar

option

whose

first

You

value

read-only

can

fields

keyword

and

element

specify more

the

keyword-1
following

value-1

value.

the

name

than

one

keyword-2

Include
of

the

option

that

field

the

time.

keywords.

The

value

value-2

explain

each

...)

sections

detail.

:DEFAULT

:READ-ONLY

:0CCURS

Tells

the

number

:0FFSET

Tells

the

distance

3.4.4.1

1Initial

specify

that

Gives

value

when

initialized

fields,

the

initial
if

with

Then,

1Instead,

Tells

Value

definition.
fields.

descriptions

the

is:

(field-name

keyword

between

characterizes.

define

fields.

Specify

you

structure’s

option

The

NEWMASK)

Options

structure’s

(MASK-BIT-2

you

LISP

field

specify

the
you

not

system

set

times

between

:DEFAULT
create

can

field

repeats

similar

fields

1initial

keyword
instance

have

wvalue

the
of

alien
a

puts

field,

structure’s

structure

specify values

automatically

3-16

for

your

for

with
those

initial

DEFINING AND CREATING ALIEN STRUCTURES
For example, in the following data
the fields you create.
in
values
definition, the value of the
structure
field specification of an alien
initialized to 2.

NUM-CHILDREN field

:UNSIGNED-INTEGER 68

(NUM-CHILDREN

You can override the default field
the structure.
creating
on
field

:DEFAULT 2)

structure’s
alien
an
for
wvalue
To do so, place new values in the

defined
a
of
initialized fields when you create a specific instance
alien
an
of
creation
following
the
in
example,
For
structure.
initialized
1is
field
:NUM-CHILDREN
the
structure of type FAMILY-REC,

(SETF EXAMPLE-4

(MAKE-FAMILY-REC

:NUM-CHILDREN 3

))

The default field value can also be changed after creation of an alien
by using the SETF macro with the accessor function of that
structure
field.

NOTE

By default,

the

initial

contents

field

are

unpredictable.

specify
lets you
keyword
Read-Only Value - The :READ-ONLY
3.4.4.2
with
specify
you
value
The
set.
or
<can be accessed
field
a
whether
default.
the
NIL is
this keyword can be either T or NIL.
If you specify T,

the DEFINE-ALIEN-STRUCTURE

macro

generates

access

are not acceptable access forms in a call to the SETF
that
functions
That is, if you specify the keyword-value pair :READ-ONLY T 1in
macro.
SETF macro on the
the
wuse
cannot
you
data-field description,
a
individual
an
create
vyou
after
field
that
accessor function for
field.
the
access
only
can
you
structure having such a field;

the
default),
(the
NIL
specify
if you
hand,
other
the
On
are
that
functions
access
generates
DEFINE-ALIEN-STRUCTURE macro
if
That 1is,
acceptable place indicators in a call to the SETF macro.
specify the keyword-value pair :READ-ONLY NIL in a data field (or
you
field with
omit the keyword altogether), you can write data in that
the

SETF

form.

the
of
default wvalue
For example, in the following definition, the
after
changed
not
but
accessed
This value can be
is 4.
field
AREA-2
However, the
you create an individual structure from this definition.
the AREA-1 field, which defaults to 2, can be changed after
of
value
you create an individual structure from this definiton.

DEFINING

AND

CREATING

(DEFINE-ALIEN-STRUCTURE

(SPACE

ALIEN

STRUCTURES

(:PRINT-FUNCTION

(AREA-1

:UNSIGNED-INTEGER

:DEFAULT

(AREA-2

:UNSIGNED-INTEGER

:DEFAULT

: READ-ONLY

3.4.4.3

Repeated

structure.

you

determine

the

first

you

index

not

this

number

line

bytes

:0CCURS

1ts

argument,

the

access

field.

Consider

the

within

the

repeated.

field

:0CCURS

For

occurs

alien

keyword,

example,

times

with

30.

keyword,

and
1s

first

access

field

takes
an

function

occurs

the
of

that
the

takes

once.

name

and

indicates

the

field

integer

occurrence

following

(DEFINE-ALIEN-STRUCTURE

the

function

1ndex

The

NAME
and

with

20)

the

The

T))

repeated

field

between

the

the
the

specify

times

integer

that

keyword,

Lisp>

can

indicates

arguments.

occurrence

positive

name

for

index

field

:TEXT

field

specify

occurrence

(NAME

the

specifying

the

following

1ts

Field

#’'SPACE-PRINT)
)

field

has

you

definition:
SPACE

(AREA-1

:UNSIGNED-INTEGER

(AREA-2

:UNSIGNED-INTEGER

system

evaluates

:0CCURS

4))

SPACE

When

the

LISP

functions

AREA-1

and AREA-2

(SPACE-AREA-1

field)

(SPACE-AREA-2

field

3.4.4.4

Similar-Field

similar

fields

sense

only

field

field.

number

indicates

CHILD-NAME

If
in

you

using
the

with

the

You

<can

:OFFSET

:0CCURS

distance

definition,

following

specify

keyword.

access

8-bit

bytes

the

start

offset

lets

the

:OFFSET

how

This

far

apart

option

makes

keyword.

the

formats:

you

access

keyword.

8-bit

bytes

come

:TEXT

:0CCURS

value

that

from

the

data

start

occurrence

files

that

For example,

between

each

:OFFSET

25)

the

one

that

consist
following

occurrence

1length

(as

the

field:

specify

previous
the

Distances

field

that

(CHILD-NAME

the

index)

with

Specifying

rational

line

used

offset

occurrence

are

the

have

alien

example),
structure.

the
You

greater

than

the

field

DEFINE-ALIEN-STRUCTURE
can

fill

3-18

them by

macro

defining

produces

gaps

one

DEFINING AND CREATING ALIEN STRUCTURES

other

1is,

you

The LISP system does not evaluate
the
wvalue
you
specity
with
:OFFSET keyword when it expands the DEFINE-ALIEN-STRUCTURE macro.
offset defaults to the length of the field.

the
The

can

3.5
This

fields

with the

interleave

:0CCURS

different

and

the

:0OFFSET

keywords;

that

fields.

EXAMPLES OF ALIEN STRUCTURE DEFINITIONS
section

provides

two

examples

how

define

alien

structure.

(DEFINE-ALIEN-STRUCTURE MY-ALIEN

Lisp>

(FIELD-1

:TEXT 0 9))

MY-ALIEN

This form defines an alien structure
named
MY-ALIEN,
which
contains
one field named FIELD-1.
The structure is a string
that begins on the first byte and is 10 characters long.
2.

The

following

example

shows

Pascal

record

definition:
TYPE

FAMILY

REC

RECORD

record structure definition.}
SURNAME
: PACKED ARRAY[1..20]
:

RECORD

NAME

PACKED ARRAY[1..20]

AGE

INTEGER;

FATHER

END;

{of

father

record}

RECORD

NAME

PACKED ARRAY[1..20]

AGE

INTEGER;

MOTHER

END;

{of mother

OF CHAR;
OF

CHAR;

record}

NUM_CHILDREN

INTEGER;

CHILDREN

:
:

ARRAY [0..20] of RECORD
PACKED ARRAY[1..20] OF CHAR;

AGE

INTEGER;

SEX

(FEMALE,

NAME

END;
END; {of

{of children record]
family record}

MALE);

structure

DEFINING

equivalent

Lisp>

AND

LISP

CREATING

record

structure

(DEFINE-ALIEN-STRUCTURE
"A

record

ALIEN

structure

STRUCTURES

definition:

FAMILY-REC

definition."

( SURNAME :TEXT 0 20)
:TEXT 20
( FATHER-NAME

40)

(FATHER-AGE

:UNSIGNED-INTEGER

(MOTHER-NAME

:TEXT

44)

64)

(MOTHER-AGE"

:UNSIGNED-INTEGER

68)

(NUM-CHILDREN

:UNSIGNED-INTEGER

(CHILD-NAME

:TEXT

(CHILD-AGE

:UNSIGNED-INTEGER

(CHILD-SEX

(:SELECTION

:0CCURS

"FEMALE"

:DEFAULT

:OFFSET

25)

:0CCURS

:OFFSET

25)

"MALE")

:OCCURS

:OFFSET

25))

FAMILY-REC

This

form

defines

has

fields

and

the

sex

:DEFAULT,

The

the
in

that

family

The

:0CCURS,

repeat

are

since

record.

and

the

The

name

fields

are

strings

The

age

fields

are

integers

length.

The

sex

fields

can

that

integer,

one

but

the

alien

shown

similar

field

itself

CHILD-AGE
how

way.

occupies

and

storage

since

can

CHILD-AGE,

names

The

bytes

are
of

and

possible
children,

comes

since

the

Dbytes.

CHILD-SEX

fields.

internally

Only
of

through

3-20

gap

field

rest

20
are

represented

every

fields.

that

the

numbers

either

structure.
the

length.

CHILD-NAME

repeats

the

that

1internally
1in

illustrates

1in

surname

are
byte

FAMILY-REC

structure

the

two.

values

3-1

that
ages,

contains

number

length.

the

children’s
default

their

keywords.

CHILD-NAME,

FAMILY-REC

family,

definition

bytes

:0OFFSET

The

preceding
repeated

children.

fields

named

members

filled

the

structure

the

however,

alien

the

CHILD-SEX

occurrence

Figure

alien

:SELECTION,

fields
this

indicating

indicated

unsigned

between

field

first

The

bytes;

names

gap

for

part
for

each

contains

This

structure

indicate

longword

two

allocated

the

19.

characters
one

1is

the

would

example,

identify

the

DEFINING AND CREATING ALIEN STRUCTURES
|

4 BYTES

-]
0

SURNAME

FATHER-NAME

40 |«— FATHER-AGE

44 1)

MOTHER-NAME

)

64 |[=—

68 |<—— NUM-CHILDREN

MOTHER-AGE

CHILD-NAME-1

92 | CHILD-AGE-1

95
97 l

<—— CHILD-SEX-1
\

CHILD-NAME-2

116

121

| 120

1 CHILD-AGE-2

MLO-243-86

Figure 3-1:

Internal Storage of FAMILY-REC

3-21

CHILD-SEX-2

DEFINING AND CREATING ALIEN STRUCTURES

3.6

CREATING AN ALIEN STRUCTURE

Once

you

have

defined

individual

alien

call

constructor

the

structures

Section
3.2).
gives the

symbol

type

created

macro

SPACE,

alien

For

structure

that

function

data

data
the

type,

type.
data

you

To do
type

can

so,

you

create

specify
want

(see

example,
1in
the following expression, the SETF
EXAMPLE-1 a value of
the
alien
structure
of

when

the

LISP

system

evaluates

the

form

(MAKE-SPACE)
.

(SETF

EXAMPLE-1

Constructor

3.6.1

(MAKE-SPACE))

functions

Keywords

for

Keywords

affecting

two

types

initializing data

optional

keywords:

fields

allocation of

alien

structures

Initializing and Changing Data Fields

The

constructor
function
for
an
alien
structure
accepts
keyword
arguments
to
initialize
data fields.
Each keyword is the name of a
data field prefixed by a colon.
For example,
when
the
LISP
system
evaluates
the
following
definition,
the
MAKE-SPACE
constructor
function accepts two data-initialization keywords
named
:AREA-1
and
:AREA-2.
Lisp>

(DEFINE-ALIEN-STRUCTURE

SPACE

(AREA-1

:UNSIGNED-INTEGER

(AREA-2

:UNSIGNED-INTEGER

8))

SPACE

When you
to
the

create an individual alien
structure’s
fields
with

structure, you can
assign
values
the
initialization keywords.
For

example:

Lisp>

(SETF

EXAMPLE-1

#<Alien Structure

(MAKE-SPACE

c:AREA-1

:AREA-2

SPACE #x403B80>

You can also initialize the fields by specifying the
(see Section
example, the
and

:DEFAULT

keyword

3.4.4.1) with a value when you define the structure.
For
following AREA fields have default initial
values
of
6

12:
Lisp>

10))

(DEFINE-ALIEN-STRUCTURE

(AREA-1
(AREA-2

SPACE

:UNSIGNED-INTEGER
:UNSIGNED-INTEGER

SPACE

3-22

0
4

4
8

:DEFAULT
:DEFAULT

6)
12))

DEFINING

data

default

initialization

you

want

change

the
to

same

change

with

(see

Section

the

following

Lisp>

(SETF

CREATING

ALIEN

make

with

the

constructor

function

the

alien

structure

definition.

you

field
a

the

change.

AND

field

SETF

value

3.4.4.2).

SETF

after

macro

For

you

the

STRUCTURES

have

field

example,

created

it,

definition

the

field

the

data

overrides

you

can

allows

the

AREA-1

set

form:

(SPACE-AREA-1

EXAMPLE-1)

28)

defined

3.6.2
In

Allocating

addition

constructor

allocation,

Table 3-2:

Memory

the

functions

keywords
also

:ALIEN-DATA-LENGTH

Values

Used with

and

keywords

fields,

that

all

affect

data

:ALLOCATION.

Memory-Space

Keyword
:ALTEN-DATA-LENGTH

two

Keywords

Value
1integer

The

number

structure’s
This
use

alien

the

length
allows

allocated;

<can

alien
the

accessed

ALIEN-FIELD

function.

alien

constructed

than

data

size
large

normal

the

data

defined

default

than

"extra"

are

as
1is

the

structure

vyou

variable
default

store

larger

when

structure.
than

alien

efficient

structures

The

enough
larger

allows

for

records.

memory

the

vector.

storage

buffers

with

data

alien

for

keyword

using

bytes

allocated

structure

with

default,

access

smaller

set

the

size

error

omitted

fields.
See

the

description

ALIEN-STRUCTURE-LENGTH

Part

default

3-23

byte

for

the

function

example

allocations.

DEFINING

Table

3-2

AND

CREATING

ALIEN

STRUCTURES

(cont.)

Keyword

Value

:ALLOCATION

value

The

type

used

for

Valid

values

allocation

the

alien
are

+:STATIC.

structure.

:DYNAMIC

and

the

default.
If

:STATIC

alien

static

space

address
garbage

LISP/VMS

3.7
In

ADDITIONAL ALIEN
addition

following
@

the

alien

STRUCTURE MACRO AND

DEFINE-ALIEN-STRUCTURE

structure

macro

DEFINE-ALIEN-FIELD-TYPE

and

specified,

structure
1s

and

not

1ts

changed

collection

User’s

the

allocated

(see

virtual
during
the

VAX

Guide).

FUNCTIONS

macro,

VAX

LISP

provides

the

functions:

macro

Defines

alien

structure

field

types.

ALIEN-STRUCTURE-LENGTH
alien

ALIEN-FIELD

function

structure.

Descriptions

function

Returns

the

1length

structure.

alien
of

the

macro

and

Can

functions

3-24

used

access

are

Part

arbitrary

II.

fields

CHAPTER 4
INTERRUPT FUNCTIONS

VAX

LISP

provides

for

example,

the

movement

the

normal

specify

event
This

chapter

LISP

function

occurs.

chapter

completion

workstation

flow

mechanism whereby events

Such

provides

Section

4.1

I/0,

the

device

program execution.

executed when

functions

organized

pointing

are

guilide

follows:

provides

called

wusing

overview

that

occur

expiration
can

This

made

timer,

interrupt

mechanism allows

particular

interrupt

you

asynchronous

functions.

interrupt

asynchronously

the

functions.

wuse

The

interrupt

functions.

Section 4.2 defines an asynchronous event and
shows
operating
system,
through
the
AST mechanism,

VMS

regquest

notification

asynchronous

how
lets

the
you

events.

Section 4.3 shows how you establish an interrupt
<function
1in
and
specify
that
1t
be
executed
as the result of a

LISP

particular

Chapter

interrupt

asynchronous

contains

event.

1information

three

topics

that

relate

functions:

Establishing priority

1levels

which

1interrupt

functions

operate
Protecting
J.LU\.\.;L»\—J.J.J.\J

gsectioneg
o Yo b b e W b A NI

Synchronizing
WAIT

function

the

LY e NN

~nAde
WA W 5 W

[ 4

execution of

interrupt

functions

wusing

the

INTERRUPT FUNCTIONS

4.1

OVERVIEW OF INTERRUPT FUNCTIONS

Interrupt functions allow your LISP program to respond to events
that
occur
independently
of normal program execution.
If you decide that
you need

to use

interrupt

function,

follow these

Decide what asynchronous event is

what
the
requires.

function
Section

steps:

trigger

the

is to do, and what information the
4.2
provides
information
about

function
wvarious

sources

Define

the

Use
the
INSTATE-INTERRUPT-FUNCTION
function
to
make
your
function
known
to
LISP
as
an
interrupt
function.
INSTATE-INTERRUPT-FUNCTION returns an
identification
number,
the
1if-id, that you must retain for future use.
Section 4.3
shows

asynchronous

function,

events.

function as you would any LISP function.

how to use

INSTATE-INTERRUPT-FUNCTION.

Use the call-out facility to define and call a system
routine
that
causes
an
AST;
or
call
one of the VAX LISP-supplied
functions

that establishes

such

pointer

iif-id of your

response

movement.

interrupt

to an asynchronous event

When using CALL-OUT,

function as

the

astprm

supply the

argument

the
system
routine.
When
<calling
one
of
the
VAX
LISP
functions, give the iif-id as the
action
argument.
Section
4.3
provides
examples
of using both system routines and VAX
LISP

functions.

When the specified asynchronous event occurs,
function

executes.

than once,

function

event

executes

your

interrupt

can occur more

each

time

the

occurs.

this

function.

When your interrupt function is no longer needed -that
1is,
after the asynchronous event has occurred for the last time -use the UNINSTATE-INTERRUPT-FUNCTION function
to
remove
the
interrupt

4.2

event

asynchronous

If you need to synchronize your program with the execution
of
an
interrupt
function,
wuse
the
WAIT
function.
Chapter 5
describes

the

your interrupt

asynchronous

I1f

function from LISP’s

table of

interrupt

functions.

ASYNCHRONOUS EVENTS IN VMS

An asynchronous event occurs at
an
wunpredictable
point
during
the
execution
of a program.
(By contrast, a synchronous event happens at
the
same
point
in
the
program
every
time.)
Some
examples
of
asynchronous

events

follow:

4-2

INTERRUPT FUNCTIONS

program

execution.
input

gueues

later

some

completed.

request

The

for

point,
input

1input,

then

unpredictable

completion

continues

advance,

the

asynchronous

event.

program

sets

continues
event

what

The

occurs.

code

user

timer

execution.
This

will

When
event

the

pointer

and

the

button

click

this

section

knowledge

mechanism will

The

operating

mechanism
AST

when

that

variety

system

are

routines,
started

the

AST

normal

are

workstation
The

predict

how

the

events.

VMS
As

the

events.

LISP

wuseful

and

operating

Services

pointer

movement

asynchronous

System

Some

request
you

routines

you

can

the

system

programmer,

background.

Reference

that

number

event

For

Manual.

that

occurs;

System

Trap)

asynchronous

event.

such

routines

The

call

pointer

the

cause

asynchronous

time

AST

service

executed
are

called

ASTs
an

When

AST

Other

single

service

each

When

the

causes

you

these

activity

the

service

AST

was

only

system

call.
routine

pointer

routine

interrupted.

timer

continue

routine.

wuse

and

will

system

vyou

AST,

ASTs

Wwhen

interrupting

time

button

and,

system

cause

sets

These

I/0O,

executes,
it

can

that

once.

from

AST

where

nature,

routine
only

the

event.

routine.

specified

resumes

and

events.

completes,

vyou

their

expire

establishes

causes

released.

another

can

execution

example,

routine

(Asynchronous

routine

execution.

routines,

activation

pointer

routine

For

timer

program

unlimited

AST

notification

can

those

specify

system
the

specify

asynchronous

workstation,

flow

call.

provides

primarily

service

completes,

provide

VAX/VMS

then

asynchronous

routines."

using

you

lets

specified

service

routines

AST;

the

system

lets

mechanism

"AST
A

see

ASTs
VMS

The

this

information,

asynchronous

seconds,

up,

because

buttons.

describes

five
is

impossible.

application moves

access

1in

asynchronous

one

off

interval

clicks

rest

4.2.1

executing

provides
more

go
the

one

can

AST

cause

routines

For

can

example,

for

pointer

button
until

for

they

each

only

system
button

pressed
are

one

cause

halted

INTERRUPT FUNCTIONS

4.2.2

Routines that Cause ASTs

Ultimately,
direct
wuse
functions

all ASTs are caused by
system
of
these
system
routines.

call

system

routines

that

routines.
You
can
make
Also, a number of VAX LISP
cause ASTs.

4.2.2.1
System Routines - A number of VMS system services
and
other
system
routines can cause ASTs.
The documentation for these routines
notes when a routine completes asynchronously.
You can also tell when
a
routine
<can
cause
an
AST
by
the presence of the following
two
arguments in the routine’s argument list:

astadr -- the address of the AST service routine.
You
supply
this address when you call the routine that causes the AST.

astprm (or some equivalent) -- the AST parameter.
This 1s
an
arbitrary value that you supply.
VMS passes the AST parameter
to the AST service routine.
When multiple asynchronous events
share
a
single
AST service routine, the AST service routine
can use the AST
parameter
to
determine
which
asynchronous
event

caused

to be

called.

To make use of system routines that declare ASTs,
you
must
call-out
facility,
Jjust as with any other external routine.
4.3 describes how to call these system routines.

use
the
Section

4.2.2.2
VAX LISP Routines - A number of VAX LISP functions
establish
actions
to
be
taken
when
specified
asynchronous
events
occur.
Currently, most of these functions are part of VAX LISP’s
support
of

the

VAXstation.

Functions

are

provided

that set up a response

pointer
movement,
pointer
button
activation,
and
viewport
manipulation.
These functions ultimately call system routines.
Using
these functions saves you the trouble of defining the
system
routine
and
wusing CALL-OUT.
In other respects, the use of these functions 1s
similar to the use of system routines.

4.2.2.3
Keyboard Functions
function
to bind a control

- You can use
the
BIND-KEYBOARD-FUNCTION
character on the keyboard to the execution
of a LISP
function.
(See
the
VAX
LISP/VMS
User’s
Guide
for
a
description
of BIND-KEYBOARD-FUNCTION.) VAX LISP invokes all keyboard
functions through a single interrupt function.
The function that
you
specify
with
BIND-KEYBOARD-FUNCTION
can
interrupt the execution of
LISP code.
However, you do not have to instate or uninstate
Kkeyboard
functions.

INTERRUPT FUNCTIONS

4.3

ESTABLISHING LISP INTERRUPT FUNCTIONS

This section details the steps you
function.

The

section

divided as

must

take

follows:

wuse

interrupt

Any function that LISP is to execute
asynchronously
must
be
made
known
to
LISP
as
an
interrupt
function.
The
INSTATE-INTERRUPT-FUNCTION
function
informs
LISP
that
a
particular
function may be invoked asynchronously at a future
time.

Section

4.3.1

shows

how

use

INSTATE-INTERRUPT-FUNCTION.

Once a function has been made known as an interrupt
function,
you
must
associate
the
interrupt function with one or more
asynchronous events.
Section
4.3.2
describes
two
ways
of
doing

so.

When an interrupt function is no

If you suspend a LISP system, the interrupt functions you have
instated become uninstated in the suspended system and are not
automatically reinstated when
the
system
1s
resumed.
See

remove it from LISP’s table of
system resources.
See Section

Section

4.3.1

longer

interrupt
4.3.3.

needed,

functions

you

should

to conserve

4.3.4.

Defining an Interrupt Function

To define an interrupt function, you first define the function in
the
normal
LISP
manner.
The
function
may
take
arguments,
since
INSTATE-INTERRUPT-FUNCTION
interrupt

can

specify

arguments

pass

function.

Next, you use the
function
known

INSTATE-INTERRUPT-FUNCTION
function
to
make
to
LISP
as
an
interrupt
function.

INSTATE-INTERRUPT-FUNCTION

function

takes

function

your
The

argument

and
returns
an
identifying
number,
the
1i1f-1id.
LISP
adds your
function to an internal list that identifies interrupt functions.
The
iif-id
allows
LISP
to retrieve a particular interrupt function at a
future
For

time.

example:

(LET

((IIF-ID

(INSTATE-INTERRUPT-FUNCTION

#'KEY-HANDLER)))

)

This example makes the function
KEY-HANDLER
known
as
an
interrupt
function.
The
value returned by INSTATE-INTERRUPT-FUNCTION is bound
to the symbol IIF-ID, to be
wused
1later
in
the
body
of
the
LET.

4-5

INTERRUPT

Section

4.3.2

function

with

You

can

times
having
you

use

as
the

4.3.1.1

same
an
1n

function

response

function,

This
use

same

slightly

Arguments

receives

that

useful

function

take

event

Your

interrupt

The

only

data

structure

making

technique

the

needs

way

for

pass

function

structure

argument.

special

wvariables

function

executes.

cannot

INSTATE-INTERRUPT-FUNCTION
value

function.
((IIF-ID

1is

For

<can

Ordinarily,
to

You

once

cause

can,

interrupt

each

argqument,

single
with

the

1interrupt

allowing

the

what

depending

invoked.

structure

You

should

the

takes

structure.
manipulate

the

not

because

certain

data

function

data

the

same

events.

functions

variable,

when

the

cases:

than

manipulate

function

list

many

wuseful

invoked.

interrupt

the

action

function

safe

whose

passed

different

appropriate

caused

function

following

You

essentially

interrupt

function

asynchronous

when

interrupt

Functions

several

passed

one

perform

arguments

definition.
be

single

This

INSTATE-INTERRUPT-FUNCTION
thereby

associate

than

arguments

technique

asynchronous

(LET

Interrupt

interrupt

differing

function

: ARGUMENTS,

used

one

function,

The

creating

definition.

function

You

thereby

function

specify

how

1interrupt

however,

1if-id
event.

like,

Passing

interrupt

the

asynchronous

INSTATE-INTERRUPT-FUNCTION

you

need

operation

shows
an

FUNCTIONS

store

the
time

the

data

binding

keyword

arguments

interrupt
of

interrupt

argument,

passed

the

example:

(INSTATE-INTERRUPT-FUNCTION
: ARGUMENTS

(LIST

#’'KEY-HANDLER

INTERRUPTING-KEY))))

)
This

example

makes

the

function

and

passed

KEY-HANDLER when

the

contents

other

LISP

requests

that

KEY-HANDLER
the

1is

can

the

interrupt

INTERRUPTING-KEY

KEY-HANDLER

Following
use

known

structure

invoked.

INTERRUPTING-KEY.
functions

data

can

execution

modified

manipulate
KEY-HANDLER,

contents

INTERRUPTING-KEY.

4.3.1.2
an

that

Specifying

1interrupt

contains

executing
more

the

level.

Interrupt
An

lower

information

Level

interrupt

about

level

interrupt

4-6

Each

function

interrupt
can

than

levels.

only

its

function

has

interrupt

code

own.

phapger

INTERRUPT FUNCTIONS

Use the :LEVEL keyword with INSTATE-INTERRUPT-FUNCTION to specify
the
interrupt
level.
The
wvalue
for
this keyword is an integer 1in the
range

through

The

default

4.3.1.3
Automatic
Removal
of
Interrupt
Functions - The
INSTATE-INTERRUPT-FUNCTION
function
takes
a
keyword
argument,
:ONCE-ONLY-P, that allows you to request that the
interrupt
function
be
uninstated
after a single execution.
1If you include :ONCE-ONLY-P
with a non-NIL argument, the interrupt function can only execute once;
then
it
1is
automatically
removed
from
LISP’'s
table of interrupt
functions.
Use this keyword only
if
you
know
that
the
1interrupt
function
will
only be needed once.
For interrupt functions that may
execute
more
than
once,
remove
them
explicitly
with
the
UNINSTATE-INTERRUPT-FUNCTION
function
after
the last use.
(Section
4.3.3

describes

UNINSTATE-INTERRUPT-FUNCTION.
)

4.3.2

Associating an Interrupt Function with an Asynchronous Event

To request invocation of an interrupt function, you must associate
1t
with
one or more asynchronous events.
This section shows how to call
out to system routines that cause
ASTs
and
how
to
pass
1interrupt
functions
as
arguments
to
VAX
LISP
functions
that establish the
response

asynchronous

event.

4.3.2.1
Calling Out to System
Routines - System
routines
that
can
cause
asynchronous
events
are
characterized by the presence of two
arguments, the astadr (address of the AST
service
routine)
and
the
astprm
(AST
parameter).
To
call
out to such a routine, you first
define

the

routine,

Always use

Use
the

DEFINE-EXTERNAL-ROUTINE.

:MECHANISM

either :MECHANISM
astprm argument.

routine

argument
For

using

determine
be

:VALUE to pass the

astadr argument.

:VALUE or :MECHANISM :REFERENCE to
pass
Consult the documentation of the system

how

the

routine

expects

the

astprm

passed.

example:

(DEFINE-EXTERNAL-ROUTINE
(EFN

:MECHANISM

(SYSSSETIMR

:CHECK-STATUS-RETURN T)

:VALUE)

(DAYTIM

:VAX-TYPE

:QUADWORD)

(ASTADR

:MECHANISM

:VALUE)

(ASTPRM

:MECHANISM

:VALUE))

;

Called the

REQIDT

in VMS docs.

INTERRUPT FUNCTIONS

This

example

that

sets

timer

expires.

When

you

use

appropriate

defines
a

timer

CALL-0OUT
values

For

the

This

1s
For

the

call

both

the

pass
o0of

astprm,

service

all

the

and

the
a

event

system

occur

routine,
the

pass

COMMON-AST-ADDRESS.

LISP-supplied

asynchronous

must

the

astprm:

parameter
VAX

you

service
when

events.

You

routine
can

that

pass

astadr.

pass

the

system

astadr

always

handles

SYSSSETIMR,

asynchronous

address

object

for

routine

the

initially

For

external
causes

astadr,

other

the
and

the

1if-id of

asynchronous

the

interrupt

function

that

event.

example:
(DEFUN

SET-TIMER

(LET

((IIF-ID

(DELTA-TIME)

(INSTATE-INTERRUPT-FUNCTION

# ' TIMER- INTERRUPT-HANDLER
: ONCE-ONLY-P

(CALL-OUT

SYSSSETIMR NIL

T)))

DELTA-TIME

COMMON-AST-ADDRESS

IIF-ID))

T)
This

example

defines

SYSSSETIMR.

the

Each

keyword

(uninstated)

4.3.2.2

after

Using

establish
asynchronous
of

the

event

pointer

LISP

these

functions

have

defined

For

example,

pointer

the

moves

pointer

actions

can

execute
following

can

Functions

(Most

the

virtual

supply

its

either

whenever
example

the

NIL

the

turn

causes

interrupt

(do
the

take
these

One
of

calls

the

out

function

function.
to

The

removed

wuse

SET-POINTER-ACTION:

4-8

interrupt

and

within
o0f

After

an
or

described

argument.

exits

wuse

function.

takes

actions

the

request

action

specified
can

establishes

when
or

you

function

the

functions

support

actions

viewport.
and

LISP

when

functions
the

function

nothing),
moves

VAX

©place

interrupt

window,

window

pointer

shows

Several

1if-id

workstation

display,

within

execution

instated

SET-TIMER
as

invocation.

SET-POINTER-ACTION

movement

arguments:

which

TIMER-INTERRUPT-HANDLER

VAXstation.)

and

you

the

instated

that

occurs.
on

you

4.3.1,

first

action

with

Section

causes

its

VAX

SET-TIMER,

invocation

TIMER-INTERRUPT-HANDLER
:ONCE-ONLY-P

function

the

response

four

required

perform

when

window.

The

interrupt

function

out

window.

The

function

with

1interrupt

the

INTERRUPT FUNCTIONS

(LET

((IIF-ID

(INSTATE-INTERRUPT-FUNCTION #'DRAW-RUBBER-BAND)))

(SET-POINTER-ACTION

*ART-DISPLAY*

*ART-WINDOW*

IIF-ID NIL)

(SET-POINTER-ACTION

*ART-DISPLAY*

*ART-WINDOW*

NIL

(UNINSTATE-INTERRUPT-FUNCTION

NIL)

IIF-ID))

In this example, a previously defined function,
DRAW-RUBBER-BAND,
1is
instated as an interrupt function.
Its iif-id is then supplied as the
first action argument to SET-POINTER-ACTION.
From that point onwards,
any
pointer
movement in the window *ART-WINDOW* causes the interrupt
function
DRAW-RUBBER-BAND
to
execute.
The
second
call
to
SET-POINTER-ACTION

asynchronous
removes

requests

event,

the unneeded

and

the

interrupt

that

pointer

movement

not

cause

UNINSTATE-INTERRUPT-FUNCTION
function

from LISP’s

table

function
interrupt

functions.

Some

LISP

functions

that

specify a

response

asynchronous

events

cause
arguments
to
be
passed
to
the
interrupt function that you
specify.
For example, the SET-BUTTON-ACTION
function
specifies
the
response when a workstation pointer button is pressed or released.
It
you
specify
an
interrupt
function
with
SET-BUTTON-ACTION,
the
interrupt
function
is
automatically passed two arguments when it 1s
invoked:
the button involved, and the
direction
of
the
transition
(down
or
up).
You
<can
still
wuse
the
:ARGUMENTS
keyword
with
INSTATE-INTERRUPT-FUNCTION to specify arguments to be
passed
to
the
interrupt
function.
Arguments that you request are passed following
any

arguments

passed

automatically.

For example, assume that you want to pass a virtual
display
to
your
button-handling
interrupt
function, in addition to the two arguments
that it
receives
automatically.
You
might
define
the
interrupt
function

(DEFUN

follows:

BUTTON-HANDLER

(BUTTON

TRANSITION

DISPLAY)

)

But when you use
argument

(LET

INSTATE-INTERRUPT-FUNCTION,

you only specify that one

passed:

((IIF-ID

(INSTATE-INTERRUPT-FUNCTION
# ' BUTTON-HANDLER
:ARGUMENTS

(LIST

DISPLAY))))

)

When BUTTON-HANDLER executes as the result of a button
being
pressed
or
released,
it
will
receive
three
arguments:
the
button
and
transition supplied by VAX LISP, and the display that you supply.

4-9

INTERRUPT FUNCTIONS

4.3.3

Removing an Interrupt Function from LISP

Wwhen you use
function
to

INSTATE-INTERRUPT-FUNCTION, VAX LISP
an
internal table listing all such

avoid unnecessary

functions

overhead,

you

should

sure

adds
the
functions.

1interrupt
Thus, to

to uninstate

interrupt

after their last use by using UNINSTATE-INTERRUPT-FUNCTION.

UNINSTATE-INTERRUPT-FUNCTION takes
the

interrupt

You

should

that

the

function

uninstate

being

interrupt

asynchronous

single

argument,

the

11f-i1id

uninstated.

event

function only

causing

asynchronous events occur only once
function
that
causes them.
Other

after

can

vyou

longer

are

sure

occur.

Some

for every use of
the
routine
or
asynchronous events, such as those

caused by SET-BUTTON-ACTION, can occur repeatedly.
1In either case, 1t
is
vyour
responsibility to be sure that the asynchronous event can no
longer
occur
Dbefore
uninstating
the
interrupt
function
the
asynchronous
event
invokes.
1If an asynchronous event occurs and 1ts
associated interrupt function has been uninstated,
LISP
1gnores
the
asynchronous

You

can

cause

one

invocation.

4.3.4
When

use

event.

the

:ONCE-ONLY-P

interrupt
See

Section

you

suspend

Therefore,
knowledge

if
of

the

function,
1nvokes

with

INSTATE-INTERRUPT-FUNCTION

be uninstated automatically after

4.3.1.3.

Suspending Systems Containing Interrupt Functions
a

LISP

system,

instated are uninstated
system, these interrupt

when

keyword

function

you

your

its

you

system

interrupt

system

must

the

interrupt

functions

in the suspended system.
When you
functions are
not
automatically
<can

functions,

resumed.

reassociate

When

suspended,
so

that

you

with

you

have

the

you
can

you

must

maintain

reinstate

reinstated

asynchronous

have

resume that
reinstated.

them

interrupt

event

that

function

with

the

need

rebind

the

restores

the

1t.

bind

control

BIND-KEYBOARD-FUNCTION
function

bindings

when

resumed
the

character

function,
system.

system

1is

vyou

VAX

resumed.

LISP

not

automatically

CHAPTER 5

INTERRUPT LEVELS, CRITICAL SECTIONS, AND SYNCHRONIZATION

This

chapter

priorities
these

discusses

facilities

functions

and

with

code

This

chapter

VAX

interrupt
to

control

keyboard

that

must

LISP
a

and

the

1in

might

which

Section

5.2
a

you

control
You

multiple

interfere

following

with

the

can

use

1interrupt

each

other

subjects:

Section 5.1 describes the system of
specify an interrupt level with the

prevent

let

functions.

unit.

INSTATE-INTERRUPT-FUNCTION

that

keyboard

system

functions

execute

discusses

facilities

functions

You

can

BIND-KEYBOARD-FUNCTION

interrupt

levels.

and

functions.

describes critical
section
of
code

sections,
which
you
wuse
to
being
interrupted during

from

execution.

Section
suspend

5.3 describes the WAIT function, which you
execution of your program until a keyboard

interrupt

5.1

USING

You

can

use

function

the

:LEVEL

between

executes

only

keyword

and

its

level.

or
The

assign

interrupt

For

1level,

function

level

example,

levels.

levels
a

not

executing

can

Certain

because

function

greater

define

low-level

they

any

keyboard

interrupted
cannot

interrupt

LISP

function

functions

safely

level

will

5-1

run

1integer

function

keyboard

one

current

functions

1level
3,
the
other way around.
interrupt

any of
very

interrupted.
interrupt

LISP’s

two

with

the

functions

specify

execute.
than

and
not

level

you

which
can

you

BIND-KEYBOARD-FUNCTION, one at level 2
second function can interrupt the first but

LISP

interrupt

function

interrupt

controls when

with

VAX

either

executes.

function

BIND-KEYBOARD-FUNCTION.

When

to
or

INTERRUPT LEVELS

interrupt

can use
function

the

function,
interrupt

high

1interrupt

Normally,

however,

LISP

execution.

INTERRUPT LEVELS,

VAX

LISP

keyboard

any

function

from

the

obtain
When

keyboard.

keyboard

you

should

use

that

keyboard,

interrupt

Functions

interrupt

level

that

the

consider

function

and

level

In general,
interrupt

must

which

able

that the

Furthermore,
its

level

less

operate

BIND-KEYBOARD-FUNCTION

interrupt

necessary.

operates

AND SYNCHRONIZATION

than

1level

meaning

that

can

perform

input

cannot

input.

carefully

ensure

needs

input

with

CRITICAL SECTIONS,

the

less

INSTATE-INTERRUPT-FUNCTION,

1interrupt

1level

interrupt

function

can

function
than

other

use.

input

or 7.
VAX

you

must

that

interrupted

guidelines

do not use interrupt levels 6
levels
may
interefere
with

You

functions

turn be

performs
Some

from

as
the

are:

Use of
LISP’'s

these
normal

operation.

If you bind a control character (such as
CTRL/E)
to
the
function,
use
either
level
1
(the
default
BIND-KEYBOARD-FUNCTION)
or
0.
The
Editor
must
interruptable by keyboard input and by interrupt functions
Editor

uses

handle

pointer

ED
for
be
the

input.

If
you
bind
control
characters
to
the
DEBUG
and
BREAK
functions,
wuse
an
interrupt
level high enough to interrupt
functions you wish to debug, but less than 6.
For example, 1f
application includes an interrupt function that executes
at
level
3,
vyou
should
specify
level
4
or
5
with
BIND-KEYBOARD-FUNCTION
to
be
able to invoke the debugger or
break loop using the control character
while
that
1interrupt

your

function

executing.

In this framework, choose interrupt levels
and
keyboard functions that allow them to
interrupted

Functions

that

execute

for your
interrupt

1interrupt
and to be

appropriate.

interrupt

level

can

interrupt

any

LISP

code
not
in
a
«critical
section, including low-level LISP code not
normally interruptible.
Functions that execute at level 7
may
leave
your
program
in
an
inconsistent
state.
Therefore, functions that
execute at level 7 must terminate by executing a THROW
to
some
tag,
such as CANCEL-CHARACTER-TAG.
Typically, you should not use interrupt
level 7 except to effect an emergency exit back to LISP’'s
top
level.

(CTRL/C
you can
Y

ae o b diead

5.2

is
bound
always use

to a function that executes at level
CTRL/C to get back to top level.)
T

B & Gl

BB wr ur Wl b

L0
S

therefore,

CRITICAL SECTIONS

A critical section consists of
forms
contained
in
the
body
of
a
CRITICAL-SECTION
macro.
The execution of forms in a critical section
cannot be interrupted by any interrupt function or keyboard
function,

5-2

INTERRUPT LEVELS, CRITICAL SECTIONS, AND SYNCHRONIZATION

any

level.

execution

that

code

Use

must

not

data

manipulates

structure

1in

interrupting

invalid.
sure

that

section

structure

that

situations

For

may

example,

temporarily

state

during

use

the

data

function

can

use

tries

manipulating

interrupted.

1inconsistent

function

The

critical

cannot

interrupted

that

occur

during

1its

the

function

leave

the

data

execution.

structure

critical

while

where

the

can

section

data

find

make

structure

invalid.
Interrupts

gqueued.

Since

When

critical

keyboard

For

infinite
have

You

should

critical

test

but

you

can

code

LISP

the

the
1s

must

critical

interrupts

careful

the

section,

removes

the
on

interruptions

perform

stopped

with

allow

any

infinite

vyou
be

loop

make

short

VAX

and

LISP

restrictions

you

serviced.

cannot
be

are

occur,

image.

before

critical

section

are

not

LISP

should

1If

<cannot

Should

sections

debugger.

the

also

section.

restrictions

open

interrupted,

thoroughly

Critical

occur

type

terminate

temporarily

restores

However,

ends,

section

you

critical

your

does

and

cannot

reason,

execution

section

critical

recourse

error

LISP

section.

debugger
that

section

this

loops

you

critical

input.

CTRL/C.

the

continue

from

interrupts

before
are

vyou

free.

invokes

the

interrupts

the

while

into

error

debugger,

continuing.

debugging

the

code.

5.3

SYNCHRONIZING

Sometimes

piece

program must

1information

function

The

WAIT

function

for

the

wait,

that
The

LISP
WAIT

PROGRAM EXECUTION

allow

stop

such
takes

two

required
a

event

VAX

LISP

arguments.

The

string.

determine

function

accepts

These

arguments

argument.

until

available.

some

provides

occurs

the

WAIT

first

synchronization.

typically

calls

execution

becomes

any

The

the

wait

number

second

condition
arguments

testing

has

been

following

are

used

arguments

called,

causes

normal

program

reason

function

satisfied.
the

the

second
testing

function.
the

NAIT

< ol

When

u
funct
4l

halt.

VAX

the

testing

function

returns,

and

testing

any

function.

The

then

function

calls

the

calls

non-NIL

the

testing

wvalue,

the

execution

function.

WAIT

When

function

continues.

you

However,

testing

repeatedly

returns

execution

The

LISP

specify

remember

the

function

should

testing

function

5-3

call

the

following

sho rt

once

WAIT

function

can

points:

a nd

be fore

error

free.

establishing

VAX

LISP

the

WAIT

INTERRUPT LEVELS, CRITICAL SECTIONS, AND SYNCHR‘ONIZATION
state.
An error that occurs
on
this
initial
<call
can
be
debugged normally.
However, if an error occurs in the testing
function after the WAIT state has been established,
the
LISP
system
will be left in an inconsistent state and will have to
be

terminated.

The testing function should not have side effects,
called at unknown

intervals.

since it 1is

The dynamic state of LISP is not guaranteed
during
execution
of
the
testing
function.
Therefore,
the testing function
cannot reely on the values of special variables.
You
should
pass

it arguments

instead.

One way .to use WAIT is with an interrupt function or keyboard function
that
modifies a data structure accessed by the testing function.
The
data structure can be a cons cell, a structure, or an array.
For
the
testing
function,
use an accessor function appropriate for that data
structure.
When the interrupt or keyboard function modifies the
data
structure,
the
testing
function
returns
non-NIL,
and
execution
continues.

For example,

the

then used
(SETF

FLAG

following forms
a WAIT
(LIST

set up a variable

called FLAG,

which

function:
NIL))

(BIND-KEYBOARD-FUNCTION

F
#\"
#' (LAMBDA
(WAIT "Wait

() (SETF (CAR FLAG) T)))
for CTRL/F" #'CAR FLAG)

In this example, the value of FLAG is a list
whose
only
element
1is
NIL.
BIND-KEYBOARD-FUNCTION
binds CTRL/F to a function that changes
the element of FLAG to T.
The WAIT
function
specifies
CAR
as
1ts
testing
function,
with
FLAG
given as the argument.
As long as the
testing
function
returns
NIL,
the
WAIT
function
blocks
further
execution.
When
the user types CTRL/F, the first element of FLAG 1is
set to T, the testing function returns T, the WAIT
function
returns,
and normal

execution continues.

To use the WAIT function to synchronize your program with an interrupt
function, pass a data structure to both the interrupt function and the
testing function named in the WAIT function.
For
example,
<consider
the
following
interrupt
function
that
handles the expiration of a
timer:

(DEFUN TIMER-INTERRUPT-HANDLER
(SETF

(CAR

FLAG)

T))

(FLAG)

INTERRUPT LEVELS,

This

function
(LET*

could

((FLAG

used

(LIST

(IIF-ID

CRITICAL SECTIONS,

AND SYNCHRONIZATION

follows:

NIL))

(INSTATE-INTERRUPT-FUNCTION

#'TIMER-INTERRUPT-HANDLER
:ONCE-ONLY-P
: ARGUMENTS

(CALL-OUT

SYSSSETIMR NIL

(LIST

FLAG))))

DELTA-TIME

COMMON-AST-ADDRESS

(WAIT

"Timer

wait"

#'CAR

IIF-ID)

FLAG)

)
In

this

example,

the

program

TIMER-INTERRUPT-HANDLER

calls

out

SYSSSETIMR,

execute

TIMER-INTERRUPT-HANDLER

only

TIMER-INTERRUPT-HANDLER

when

element
the

1is

timer

NIL.

after

that

execute

however,

calling

SYSSSETIMR,

before

calls

the

WAIT

TIMER-INTERRUPT-HANDLER

the

useful

pass

synchronization.
(DEFSTRUCT

you

<can

Consider

for

the

list
a

whose
to

the

until

CAR

structure
a

following

(BUTTON

slot

((IIF-ID

MENU)

T))

(INSTATE-INTERRUPT-FUNCTION

#’CLICK-IN-MENU

"Menu choice"

Since

both

been

passed

have

interrupt

1in

(MENU)

: ARGUMENTS

code

point,

TIMER-INTERRUPT-HANDLER

example:

TRANSITION

MENU)

with

some

1include

(MENU-CHOICE-MADE
POST-MENU

)

1list

timer.

NIL))

CLICK-IN-MENU

(WAIT

that

expires.

element

continues

(CHOICE-MADE

(LET

this

expired.

return

element

i1s

program

has

not

first

(DEFUN

sets

will

the

(SETF

timer

argument,

testing function

sets

<cases,

the

timer
wait

the

(DEFUN

the

list,

these

WAIT

same

and

the

Sometimes

FLAG

specifying

the

expires.

Meanwhile,

can

passed

when

(LIST

MENU))))

#’'MENU-CHOICE-MADE MENU)

the

function.

structure

for

INTERRUPT LEVELS, CRITICAL SECTIONS, AND SYNCHRONIZATION

This example shows parts of a menu system.
The menu 1s implemented as
a
structure,
one
of whose slots is called CHOICE-MADE.
The initial
value of CHOICE-MADE is NIL.
The
interrupt
function
CLICK-IN-MENU,
which executes when a pointer button is pressed over a menu choice, 1s
passed the menu structure as
an
argument.
CLICK-IN-MENU
sets
the
value
of
CHOICE-MADE
to
T.
The
function
POST-MENU takes a menu
structure as its argument, displays the menu, then waits for a
choice
to
be
made .
POST-MENU
uses
the
WAIT
function
and
supplies
MENU-CHOICE-MADE as the testing
function.
When
CLICK-IN-MENU
sets
this slot to T, the WAIT function returns, and execution continues.

5-6

PART i

OBJECT DESCRIPTIONS

ALIEN-FIELD

Function

Accesses the value of a field
of
a
structure.
The
function
ignores

specified
type
from
an
alien
the
alien structure’s predefined

fields.

You can modify alien structures if you use
the
ALIEN-FIELD
function
with
the
SETF
macro.
This function is most useful for debugging a
program that uses alien structures.
The function can also be used
to
write
vyour
own
accessing
functions, for example, to access unnamed
gaps

For more

alien

structure.

information about alien

structures,

see

Chapter

Format

ALIEN-FIELD alien-structure field-type start

end

Arguments

alien-structure

The alien structure from which a field value 1is to be accessed.
field-type

The type of the field from which a value is to be accessed.
This
alien
built-in
a
names
that
keyword
a
either
be
can
argument
type),
field
structure field type, a symbol (for a user-defined
or a list whose

first element names the

field type.

start

A rational number that specifies the
start
position
bytes) of a field in the alien structure’s data area.
is

inclusive

and

zero-based.

Default:

(in
8-bit
This value

none.

end

position
end
the
specifies
A rational number that
bytes) of a field in the alien structure’s data area.
is

exclusive.

Default:

none.

Return Value

The value

of a

field of

the

specified alien

structure.

8-bit
(in
This value

OBJECT DESCRIPTIONS

ALIEN-FIELD

Function (cont.)

Example

Lisp>

(DEFINE-ALIEN-STRUCTURE

SPACE

(AREA-1

:UNSIGNED-INTEGER

:DEFAULT

22)

(AREA-2

:UNSIGNED-INTEGER

:DEFAULT

2764))

SPACE

Lisp>

(SETF

#<Alien
Lisp>

SPACE-RECORD

Structure

SPACE

(MAKE-SPACE))

#x45FA60>

(SPACE-AREA-1

SPACE-RECORD)

(SPACE-AREA-2

SPACE-RECORD)

22
Lisp>

2764
Lisp>

(ALIEN-FIELD

SPACE-RECORD

:UNSIGNED-INTEGER

(ALIEN-FIELD

SPACE-RECORD

:UNSIGNED-INTEGER

(ALIEN-FIELD

SPACE-RECORD

:UNSIGNED-INTEGER

Lisp>
2764

Lisp>

11871289606166

This

example

you

types

1llustrates:

specify

and

structure,

accessed
If

you

types

the

and

data

type

and

you

data

with

specify

the

ALIEN-FIELD function

positions
you

that

the

field

are

access

from

could

positions

structure’s

ALIEN-FIELD

positions

access

that

the
the

different

you

specify.

the

definition
same

default

function

those

with

defined

field

alien

accessor

with

same

an
vyou

different

alien

depending

had

functions.
field

structure,

the

field

OBJECT DESCRIPTIONS

ALIEN-STRUCTURE-LENGTH

Function

Returns

alien

the

length

structure

bytes.

Format

ALIEN-STRUCTURE-LENGTH

alien-structure

Argument

alien-structure
The
Return

alien

structure

whose

length

returned.

Value

The

length

the

alien

structure

1in

bytes

Example

The

following

examples

ALIEN-STRUCTURE-LENGTH
illustrates
1.

Lisp>

why

illustrate

macro.

returns

The

specific

(DEFINE-ALIEN-STRUCTURE

(NAME

:STRING

the

use

diagram

after

value.

EXAMPLEI]

:OCCURS

:OFFSET

20))

EXAMPLE1

Lisp>

(ALIEN-STRUCTURE-LENGTH

(MAKE-EXAMPLEl))

+--

namel

offset

|
+---

name?2

--+

|
offset

name
3

of
each

the
example

OBJECT DESCRIPTIONS

ALIEN-STRUCTURE-LENGTH Function (cont.)
2.

Lisp>

(DEFINE-ALIEN-STRUCTURE

(NAME

:STRING

EXAMPLE2

:0CCURS

:OFFSET

10))

EXAMPLEZ2
Lisp>

(ALIEN-STRUCTURE-LENGTH

(MAKE-EXAMPLEZ2))

0
+

20
-+

40
+

Fomm e
—— - o

namel

fommm e

— -+

dommm
e
— -+

name 2

fmmm e
— -+

+---—- +

#omm oo +

+---

offset

EXAMPLE2,

the

information

offset

stored

information
Lisp>

name
3

stored

overlaps

NAME1l

in NAME2Z

and

(DEFINE-ALIEN-STRUCTURE

(NAME

:STRING

that

becomes
so

the
the

last

part

the

first

part

the

part

the

on.

EXAMPLES3

:O0CCURS

:OFFSET

40))

EXAMPLE3
Lisp>

(ALIEN-STRUCTURE-LENGTH

(MAKE-EXAMPLE3))

_______________________________________ +

gap

namel

o —————

offset

|
|

+---

In EXAMPLE3
length

offset

and EXAMPLE4,

the

|
+

--------- +

|
|

name?2
T

structure.

the

gaps

are

counted as

OBJECT DESCRIPTIONS

ALIEN-STRUCTURE-LENGTH Function (cont.)
4.

Lisp>

(DEFINE-ALIEN-STRUCTURE

EXAMPLE4

(NAME

:STRING

EXAMPLE4

Lisp>

(ALIEN-STRUCTURE-LENGTH

0
+

__________________________ -+

gap

namel

__________________________ +

(MAKE-EXAMPLE4))

40))

OBJECT DESCRIPTIONS

CALL-OUT Macro
Calls

that

has

LISP

system

For

defined
not

external

been

signals

information

Chapter

routine.

defined with
an

about

the

you

specify

external

routine

DEFINE-EXTERNAL-ROUTINE macro,

the

error.

how

use

the

VAX

LISP

call-out

facility,

see

Format

CALL-OUT

external-routine

&REST

arguments

Arguments

external-routine
The

name

defined

external

routine.

arguments

Arguments

passed

the

external

correspond
by position to the
The LISP system evaluates the
external

routine

specifying
position
the
VAX

called.

You

expression whose

the

routine.

arguments
argument
can

value

omit

The

defined for
expressions
an

optional

is NIL.

argument list will contain
Calling
Standard.
If

Procedure

The
a

0
you

arguments

the routine.
before
the
argument

corresponding
coincide with
fewer

specify

arguments
than
were
specified
1in the definition, the argument
list will contain only the number of arguments actually supplied.
LISP
signals
an
error
1f
vyou supply more arguments than were
specified

the

definition.

Return Value

the

:RESULT

specified,
no

value

the

option

external

returned.

the

DEFINE-EXTERNAL-ROUTINE

routine’s

result

returned.

macro

was

Otherwise,

OBJECT DESCRIPTIONS

CALL-OUT Macro (cont.)
Example

Lisp>

(DEFINE-EXTERNAL-ROUTINE

(SMGSCREATE-PASTEBOARD
:FILE

"SMGSHR"

:RESULT

(NEW-PASTEBOARD-ID

:LISP-TYPE
c VAX-TYPE

(PB-ROWS

:LISP-TYPE

(PB-COLUMNS

STRING)

INTEGER

:LISP-TYPE

(PRESERVE-SCREEN-FLAG

INTEGER
:UNSIGNED-LONGWORD

:IN-0OUT)

:ACCESS

(OUTPUT-DEVICE

INTEGER)

:ACCESS

INTEGER

:IN-OUT)

:ACCESS

:LISP-TYPE
: VAX-TYPE

:IN-OUT)

INTEGER
:UNSIGNED-LONGWORD))

SMGSCREATE-PASTEBOARD

Defines

the

SMG

screen

management

routine

called

SMGSCREATE-PASTEBOARD.
Lisp>

(DEFVAR

*PASTEBOARD-ID*

-1)

*PASTEBOARD-ID¥*

Defines a special variable which will
returned by the

external

Lisp>

SMGSCREATE-PASTEBOARD

(CALL-OUT

contain the

pasteboard

1ID

routine.
*PASTEBOARD-ID*
NIL

NIL

Calls the external routine SMG$CREATE-PASTEBOARD, specifying
the
special
wvariable
to receive the pasteboard ID.
Three arguments
are omitted, and a
preserve-screen-flag
of
1
1s
given.
The
result

status

returned.

OBJECT DESCRIPTIONS

COMMON-AST-ADDRESS Parameter
Specifies

the

initially
ASTs.

address

handles

This

parameter

external

routines

passed

the

VAX

LISP/VMS-supplied

all
must

that

astadr

routine

that

|
be

can

argument.

given

cause

Use

the

astadr

AST.

:VALUE

argument

other

mechanism

object

all

can

pass

this

parameter.
Format

COMMON-AST-ADDRESS

Example

See
of

the
the

description
use

INSTATE-INTERRUPT-FUNCTION

COMMON-AST-ADDRESS.

for

example

OBJECT DESCRIPTIONS

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/0

call

WAIT

critical

section.

If an error shoud occur 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

critical

section.

Return Value

The value(s)

the

last

form executed.

Example

Lisp>

(DEFUN RESTORE-TO-FREE-LIST

(CONS-CELL)

(CRITICAL-SECTION

(SETF

(CDR CONS-CELL)

*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 SETF, the list
is
in
an
inconsistent
state
because
the
special
variable
An
not point to the head of the list.
does
*HEAD-OF-FREE-LIST*
interrupting

elemen

function that used

from

the

list

RESTORE-TO-FREE-LIST uses

that the SETF call

*HEAD-OF-FREE-LIST*

would

the

break

the

CRITICAL-SECTION

1list.

to remove

macro

completes without interruption.

Therefore,
to

ensure

OBJECT DESCRIPTIONS

DEFINE-ALIEN-FIELD-TYPE

Macro

Defines

field

For

alien-structure

information

about

alien

types.

structures,

see

Chapter

Format

DEFINE-ALIEN-FIELD-TYPE

name

lisp-type

primitive-type

access-function

setf-function

Arguments
name

The

name

the

alien-field

type

1indicating

the

being

defined.

lisp-type
A

LISP

field

data

type

LISP

object

which

the

mapped.

primitive-type
Either

one

the

predefined

previously

defined

LISP

object

structure’s
passed

types

are

type

data

the

with

when
in

the

field

access

Table

types

type

DEFINE-ALIEN-FIELD-TYPE

primitive-type

specified

listed

alien-field

the

extracted

accessed.

function.

from
The

that

the

object

Predefined

was

macro.

alien
is

then

alien-field

3-1.

access-function
A

function

returns

one

argument

object

type

argument

(whose

type

primitive-type)

that

lisp-type.

setf-function
A

function

object

defined

whose

returned,

one

the
it

type

(whose

the

type

1is

the

primitive-type

argument.

packed

alien

into

the

lisp-type)

default

When

that

SETF

the

structure’s

field

form,

object

1is

data.

Return Value

The

name

the

alien-field

type.

NOTE
Functions

that

access

take

than

one

and

set

argument;

field

wvalues

additional

returns

can

arguments

OBJECT DESCRIPTIONS

DEFINE-ALIEN-FIELD-TYPE
are

Macro (cont.)

optional.

When

the

DEFINE-ALIEN-STRUCTURE

list,

field

the

first

type,

expressions

and

the

evaluates

the

passed

are

functions

element
the

LISP

values

argument

the

function.
or

set

1is

the

elements

list

are

The

when

resulting

arguments

the

description

evaluates

additional

access

field

remaining

system

access

that

type
macro’s

the

field.

Examples
1.

Lisp>

(DEFINE-ALIEN-FIELD-TYPE

INTEGER-STRING-8

"INTEGER

cSTRING

$' (LAMBDA

(X)
(PARSE-INTEGER

:JUNK-ALLOWED

T))

#'’ (LAMBDA

(X)

(FORMAT

NIL

"78"

X)))

INTEGER-STRING-8
Lisp>

(DEFINE-ALIEN-STRUCTURE

TWO-ASCII-INTEGERS

(INT-1

INTEGER-STRING-8

(INT-2

INTEGER-STRING-8

16))

TWO-ASCII-INTEGERS

The

call

field

the

type

DEFINE-ALIEN-FIELD-TYPE

named

INTEGER-STRING-8

strings
The

call

alien

fields,

INTEGER-STRING-8.

causes

alien

macro

The

structure

defines

field
to

type

convert

integers.

the

structure

each

DEFINE-ALIEN-STRUCTURE
named

type

TWO-ASCII-INTEGERS

INTEGER-STRING-8.

macro

defines
that

has

an
two

OBJECT DESCRIPTIONS

DEFINE-ALIEN-FIELD-TYPE Macro (cont.)
2.

Lisp>

(DEFINE-ALIEN-FIELD-TYPE SELECTION
T

: UNSIGNED-INTEGER

# ’ (LAMBDA

{ N)
( NTH N

’ (MA

NY)))

# ' (LAMBDA

(X)

X
p
(POSITION

' (MA RI

NY))))

SELECTIO N

be
<could
type
:SELECTION
the
how
of
This is an example
named
type
alien-field
an
defines
example
The
implemented.
This type defines a relationship between unsigned
SELECTION.
1In
objects.
data
LISP
and
field
alien
an
in
integers
the
type,
this
of
field
a
of
wvalue
the
accessing
access-function uses the integer stored in the alien field as
of
type
1In setting the value in this
an index into a list.
the position of a LISP object in that list is used to
field,
define the integer value stored in the alien structure.

OBJECT DESCRIPTIONS

DEFINE-ALIEN-STRUCTURE
Defines

alien

containing
The

For

structures.

VAX

syntax

DEFSTRUCT

Macro

data
the

macro

alien

structure

DEFINE-ALIEN-STRUCTURE

described

explanation

collection

bytes

types.

how

COMMON

LISP:

define

macro
The

alien

1is

similar

the

Chapter

Language.

structure,

see

Format

DEFINE-ALIEN-STRUCTURE

name-and-options

[doc-string]
{field-description}*
Arguments

name-and-options

The

name-and-options

new

LISP

data

options

define

you

not

argument

the

The

the

name

options,

you

name

and

argument

characteristics

specify

argument

type.

can

the

must

the

options

alien

specify

the

symbol.

The

structure.

name-and-options

symbol:

name

you

list

specify
whose

(name
Using

the

options,

first

{ (keyword
following

keyword-value

pairs.

(keyword

value)

Table

lists

the

specify

element

the

name-and-options

argument

name:

value)}*)
format,

keyword-value

specify

pairs

options

that

you

can

1list

specify.

DEFINE-ALIEN-STRUCTURE Options

Keyword-Value

: CONC-NAME

Pair

Description

name

Names
value
If

access

<can

functions.
a

symbol

you

specify

symbol

becomes

access

the

function

wish

the

access

The
NIL.

symbol,

prefix

names.

include

hyphen

function

in
If
(-)

the

the
you
in

names,

OBJECT DESCRIPTIONS

DEFINE-ALIEN-STRUCTURE
Table

Macro (cont.)

(cont.)

Keyword-Value

Description

Pair

specify

prefix.

access

same

as
you

part

specify

NIL,

the

names

are

the

function

the

field

default,

the

prefix

structure

name

the

names.
is

the

By
alien

followed

hyphen.
: CONSTRUCTOR

Names

name

the

constructor

The

value

NIL.

<can

you

becomes

the

you

specify

the

not

define

NIL,
a

1If

Names

copier

can

you

specify

the

alien

function.

The

symbol

NIL.

symbol,

the

a
a

symbol

becomes

the

name

copier

function.

you

the macro does

copier

function.

specify

this

function’s

COPY -

Names

the
value

NIL.

<can

you

symbol

the

predicate
a

you

not

the

macro

function

the

not

copier

the

prefix

the

alien

function.
a

symbol

specify

Dbecomes

the

NIL,

define

structure

create

you

predicate

the

specify

name.

The

-P.

attached

structure

not

keyword,

name

prefix

the

specify

NIL,

does

constructor

1s
to

name.

of
If

macro
not

the

structure

the

name

attached

name

constructor

you

keyword,

symbol,

function.

value

symbol

MAKE-

name

specify

constructor

function’s

:PREDICATE

symbol

the

this

name

function.
a

the

function.

+COPIER

function.

the

specify
names
by

name

you

does

not

function.

1If

this
the

attaching

macro

predicate

symbol,

the

characters

OBJECT DESCRIPTIONS

DEFINE-ALIEN-STRUCTURE
Table

Macro (cont.)

(cont.)

Keyword-Value

Pair

: PRINT-FUNCTION

Description

function-name

Specifies

the

function

the

alien

must

not

specify

LISP

system displays

structure.
function.

structure

this

The

for

value

vyou

keyword,

the

alien

following

format:

#<Alien
In

the

Structure
preceding

name

and

the

number

distinguishes
have

format,

name

1is

alien

structure

unique

identification

that

name number>

number,

alien

the

same

the

symbol

which

structures

name.

doc-string
The

the

documentation

alien

string

structure.

STRUCTURE.

See

DOCUMENTATION

The

COMMON

attached

documentation

LISP:

The

Language

function.

string
for

that

names

information

type
on

the

field-description

field

description

(name

The

that

name

type

the

start

argument

access

and

for

the

alien

following

end

must

set

the

structure.

Specify

field

format:

options)

symbol.

value

the

alien

used

name

structure

functions

field.

OBJECT DESCRIPTIONS

DEFINE-ALIEN-STRUCTURE Macro (cont.)
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

: SIGNED-INTEGER

: UNSIGNED-INTEGER

:BIT-VECTOR

: F-FLOATING

:G-FLOATING

:D-FLOATING

:H-FLOATING

: POINTER

: SELECTION

Types defined with

the VAX LISP

DEFINE-ALIEN-FIELD-TYPE

See

Chapter

for more

information on

field

macro

types.

As in COMMON LISP, the start and
end
arguments
are
with start being inclusive and end being exclusive.

zero-based

The

start argument must be a rational number or, 1n some cases, a
fixnum
(see Section 3.4.3.1) that specifies the 8-bit byte start
position of
the
field
in
the
alien
structure’s
data
area.
Default:
none.
See
Chapter
3
for more information on field
start

positions.

The end argument must be a rational number or, in some
cases,
a
fixnum
(see
Section
3.4.3.1) 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.
See Chapter
3
for
more information on field end positions.

The options define
each option with a
keyword

Table

Table 2:

lists

the characteristics
keyword-value pair:

the

field.

Specify

value

the

keyword-value

pairs

that you

can

specify.

DEFINE-ALIEN-STRUCTURE Field Options

Keyword-Value Pair

:DEFAULT

for

Description

form

Specifies

the

value

that

field.

1If

value

was

call

not

1initial

occupy

field’s

the

1initial

specified

alien

1in

structure’s

function,

evaluated

constructor

the

constructor

default

the

when

function

form
the

called.

OBJECT DESCRIPTIONS

DEFINE-ALIEN-STRUCTURE Macro (cont.)
Table

(cont.)

Keyword-Value

Description

Pair

The

value

that

evaluation
default
value

+:READ-ONLY

defaults

accessed

can

the

+:OFFSET

macro.
macro

value

must

value

the

from

start
the

value

alien

structure.

macro.

The

times

represented

structure.
an

integer.

(which

The
The

means

distance

the

The

that

8-bit
of

one

field

the

occurrence

value

number.

start

must

you

greater

than

the

structure

contains

gaps.

access

the

of
a

specify

length,

field

the

are

field’s

can

that

the

field.

rational

name

vyou

repeats).

occurrence

The

alien

bytes

Return Value

generates

number

1is

the

not

indicators

SETF

the

Specifies

rational-number

access

NIL.

field

default

specify

are

the

within

you

can
value

indicators

place

Specifies

1integer

SETF

the

default

:OCCURS

The

functions

acceptable
call

field

generates

place

specify NIL,
access

the
set.

~that

acceptable

This

NIL.

functions

call

macro

the

field’s

wvalue.

whether

from

the

1nitial

Specifies

value

results

the

alien
You

gaps with other

definitions.

OBJECT DESCRIPTIONS

DEFINE-ALIEN-STRUCTURE Macro (cont.)
Example
Lisp>

(DEFINE-ALIEN-STRUCTURE

(SPACE-SHIP

:STRING

(PHONE-NUMBER

:UNSIGNED-INTEGER

10)

(HOME

- STRING

17)

32))

Defines

named

alien

and
HOME
are
respectively.
unsigned
More

structure

SPACE-SHIP,

Chapter

ET,

which

and

HOME.

defined
to
The
field

integer

examples

named

PHONE-NUMBER,

seven bytes
how

strings

PHONE-NUMBER

contains

The

of
1is

three

fields

1length
defined

fields

SPACE-SHIP

10
to

and
be

provided

1in

long.

define

alien

structures

are

OBJECT DESCRIPTIONS

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 CALL-OUT
macro.
For information
about
how
to
wuse
the
VAX
LISP
call-out
facility,

see

Chapter

Format

DEFINE-EXTERNAL-ROUTINE name-and-options
[doc-string]

{argument-description}*
Arguments

name-and-options

being
routine
external
the
of
name
The name argument is the
define
options
The
symbol.
a
be
must
argument
The name
defined.
specify
If you do not
the characteristics of the name argument.
as a
argument
s
name-and-option
the
specify
can
vyou
options,
symbol:
name

If you specify options,
a

list whose
(name

specify the name-and-options argument

first element

the

name:

{keyword value}*)

Specify the options with keyword-value pairs:
keyword

value

The option values are not evaluated.

Table

3 lists the keyword-value pairs that you can specitfy.

Table 3:

DEFINE-EXTERNAL-ROUTINE Options

Keyword-Value Pair

Description

: CHECK-STATUS-RETURN value

Specifies whether

the

<call-out

the
check
to
is
facility
an
that
wvalue
severity of the
1in
returns
routine
external
you
wvalue
The
RO.
register
specify can be T, an integer, or

NIL.

you

specify

the

the
checks
facility
call-out
value.
return
the
severity of

OBJECT DESCRIPTIONS

DEFINE-EXTERNAL-ROUTINE
Table

Macro (cont.)

(cont.)

Keyword-Value

DeScription

Pair

the

error,

severity
oOr

system

signals

you

integer,

error

value

routine.

the

check

the

not

the return

the

specify

this

specify

the

not

the

entry

point.

external

string.

The

external

routine

Specifies

the

was

logical

SYS$SSHARE

the

this

merged

type,

NIL.

:RESULT

type

the

The

file

with

the

must
you

LISP

can

type-spec-list,

has

the

format:

(:LISP-TYPE

Table

routine

value

: VAX-TYPE

LISP/VAX

service.

type-spec-list

following

You

external
The

LISP

See

name

system

the

return.

the

must

option unless

the

image

must

image

Specifies

object
to

and

directory.

calling

the

for

This

SYSSSHARE: .EXE.

specify

are

shareable

specification

value

name.

case

executable

file

name

routine.

name,

uppercase

default

created

upper

must

converts

to
The

the

external

routine’s

value

macro

name

default

option.

Names

that

1is

type

NIL,

does

you

the

:RESULT

specify

characters.

pathname

the

facility

severity

NIL

:FILE

you

signaled

value.
:RESULT

string

specify
is

value.
option,

: ENTRY-POINT

LISP

continuable

returned

call-out

warning,
the

error.
that

1is

severe,

2-4
types.

for

LISP-type
VAX-type)

a
NIL

1list

specifies

OBJECT DESCRIPTIONS

DEFINE-EXTERNAL-ROUTINE Macro (cont.)
Table

(cont.)

Description

Keyword-Value Pair

the

that

routine

returns

1is
value
default
The
value.
this
specify
you
If
NIL.
the
specify
not
do
option,
: CHECK-STATUS-RETURN option.

the

call-out

routine

for

Specifies whether

: TYPE-CHECK value

to check the types
1is
facility
the
to
of the arguments passed

external

LISP
the
with
compatibility
specified in the argument
types
The value can be
specification.

If you specify T, the
T or NIL.
for
types
the
facility checks
specitfy
you
if
compatibility;
NIL, the facility does not check
The default
the argument types.
value

NIL.

doc-string

The documentation string for the symbol that names
routine.

See

COMMON

The

DOCUMENTATION

the

external

documentation string is of type EXTERNAL-ROUTINE.

LISP:

The

Language

for

information

the

function.

arqument-description

An argument description that is to be passed to the external
Include as many descriptions as the arguments you want
routine.
Specify the descriptions in the following
to call out to.
format:

(name options)

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

OBJECT DESCRIPTIONS

DEFINE-EXTERNAL-ROUTINE Macro (cont.)
If

you

first

specify
element

(name

The

options

option

Table

Table 4:

argqument

list

whose

value}*)

define

with

the

characteristics

keyword-value

argument.

pairs:

the

are

not

evaluated.

keyword-value

pairs

you

can

specify.

DEFINE-EXTERNAL-ROUTINE Argument Options

Keyword-Value

:ACCESS

the

value

values

lists

specify

name:

arguments

the

keyword
The

the

{keyword

options

Specify

options,
is

Pair

Description

value

Specifies

the

type

external

routine

argument.

The

:IN

default

value

specify

:IN,

the

but

external

:LISP-TYPE

type

the
you

argument

read

LISP

value

and
by

the

type

the

call-out

pass

the

routine.

See

Table

2-4

values

you

and

Table

can

specify.

2-5

for

the

Specifies

the

argument-passing

mechanism

the

external

The

expect
values

: VALUE,

for
you

can

The

:DESCRIPTOR

:TEXT
LISP

the

routine

argument.
specify

: REFERENCE,

:DESCRIPTOR.

vyou

can
by

modified

the

facility

value

The

routine.

Specifies

external

the

both

argument

:MECHANISM

:IN.
argument

modified

destructively
external

for

:IN-OUT.

:IN-OUT,
be

the

can

routine.

specify
can

needs

not

access

value

either

read,

and
data

default

for

:REFERENCE
types.

are
and

value

VAX-TYPE
for

other

OBJECT DESCRIPTIONS

DEFINE-EXTERNAL-ROUTINE Macro (cont.)
Table

(cont.)

Keyword-Value Pair

Description

:VAX-TYPE type

Specifies the VAX data

type

argument value the external
the
See Table
routine is to return.
2-4 and Table 2-5 for the values

you

can

specify.

Return Value

The symbol that names the external routine.
Example

Lisp> (DEFENEWEXTERNALwROUTINE (MTHSACOSD
«FILE

"MTHRTL"

-RESULT

(:LISP-TYPE
SINGLE-FLOAT
: VAX-TYPE

)
:F-FLOATING)

"This routine returns the arc cosine
of an angle

in degrees.”

:LISP-TYPE SINGLE-FLOAT
)
- VAX-TYPE :F-FLOATING)

MTHSACOSD

Defines an RTL routine, called MTHSACOSD, which returns the arc
cosine of an angle in degrees. The routine takes one read-only
argument, which is a F_floating number, and returns the result as
a

F_floating number.

More examples of how to define external routines are provided 1in
These examples also show you how to call out to
Chapter 2.
defined external

routines.

OBJECT DESCRIPTIONS

FORCE-INTERRUPT-FUNCTION Function
Forces

AST

and

thus

the

specified

primarily

useful

debugging.

for

1ts

invocation

function

argument.

the

interrupt

FORCE-INTERRUPT-FUNCTION

1is

Format

FORCE-INTERRUPT-FUNCTION

1i1f-id

Argument

11f-1d

interrupt

function

identifier

previously

returned

INSTATE-INTERRUPT-FUNCTION.

Return

Value

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

The

(FORCE-INTERRUPT-FUNCTION

timer

has

TIMER-IIF)

expired

The
function
TIMER-INTERRUPT-HANDLER
1s
1instated
interrupt
function
whose
1if-id is retained as the

as
value

an
of

TIMER-IIF

Passing TIMER-IIF

in a

TIMER-INTERRUPT-HANDLER

call
to

FORCE-INTERRUPT-FUNCTION

execute.

causes

OBJECT DESCRIPTIONS

GET-INTERRUPT-FUNCTION Function

Returns information about the

interrupt

function

specified

1ts

returned

argument.
Format

GET-INTERRUPT-FUNCTION

1if-1d

Argument

1if-1d

interrupt

function

identifier

previously

INSTATE-INTERRUPT-FUNCTION.
Return Value
Four

values:

The

function definition of the

The

argument

The value of

The

value

interrupt function

list

:LEVEL

(an integer in the range 0 through 7)

:ONCE-ONLY-P

NIL)

been
has
1if-id
by
represented
function
interrupt
the
If
uninstated, GET-INTERRUPT-FUNCTION returns four values of NIL.
Example

Lisp>

(DEFUN

TIME-ELAPSED

(FORMAT

"Y@("R”)

(N)

:P " :%" [have” ;has” :;have”]
second”

elapsed since

Lisp>

setting the

timer"

N))
(SETF T-E-IIF (INSTATE-INTERRUPT-FUNCTION
$# " TIME-ELAPSED
: ARGUMENTS (LIST

5)))

8388671

Lisp>

(GET-INTERRUPT-FUNCTION T-E-11F)

(LAMBDA (N)

(BLOCK TIME-ELAPSED (FORMAT T ""@("R”)

~“:%" [have” ;has” : ;have”TM ]
elapsed since

:P
second”

setting the timer" N)))

;

(5)
2 ;
NIL

of
The function TIME-ELAPSED, which prints out the number
single
a
takes
It
defined.
is
set,
was
timer
a
since
seconds
argument.

OBJECT DESCRIPTIONS

GET-INTERRUPT-FUNCTION
TIME-ELAPSED

Function (cont.)
1instated

: ARGUMENTS

keyword

argument,

the

specifies

number

INSTATE-INTERRUPT-FUNCTION

1interrupt

that

The
is

function.

TIME-ELAPSED

iif-id

retained

returns

four

passed

The

one

returned

the

value

T-E-IIF.

The

call

first

GET-INTERRUPT-FUNCTION

wvalue

1is

the

second value

function

1list

INSTATE-INTERRUPT-FUNCTION.

level
fourth

(2,

the

wvalue

specified with

default
1is

NIL,

for

definition

the
The

arguments
third

values.

TIME-ELAPSED.

value

specified
is

the

that

INSTATE-INTERRUPT-FUNCTION.

with

interrupt

INSTATE-INTERRUPT-FUNCTION).

1indicating

The

:ONCE-ONLY-P

was

The
not

OBJECT DESCRIPTIONS

INSTATE-INTERRUPT-FUNCTION

Function

Takes

its

first

asynchronously
instance

The

1if-id

AST.

The

when

executes.

allows

This
on

lets

function

The

:0ONCE-ONLY-P

will

routine

invokes

vyou

1later

(1if-id)
that

the

1nvoked

for

can

this

cause

interrupt

list

function

AST

specify

integer

passed
to the

single

interrupt

keyword

supply

particular

about

you

will

allows

the

keyword

information

passed
occurs,

arguments

depending

keyword

:LEVEL

that

identification

function

iif-id.

The

interrupt

when

actions

The

function.

the

:ARGUMENTS

arguments.

function

returns

intended

AST,

identified
The

the

argument

and

that

the

=zero

interrupt
to

invokes

take

function
different

1it.

interrupt

1level

range

0-7.

See

specify

that

this

for

Chapter

the

for

instance

levels.

allows you

the
function
will
only
be
invoked
once,
and
then
discarded.
Specifying
:ONCE-ONLY-P T
is
equivalent
to
using
UNINSTATE-INTERRUPT-FUNCTION
on
the
function
after
1its
first
invocation.
However,
:ONCE-ONLY-P
does
not
disable
further
occurrences

and

specified

second

the

AST

the

and

after

its

first

corresponding AST
subsequent

UNINSTATE-INTERRUPT-FUNCTION

occurrence.

occurs

ASTs

for

are

:ONCE-ONLY-P

than

once,

ignored.

the
(See

details.)

For more information about interrupt functions,

see Chapter 4.

Format

INSTATE-INTERRUPT-FUNCTION
&KEY

:ARGUMENTS

function

:LEVEL

:ONCE-ONLY-P

Arguments

function

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

A list

zero

function when

or more
it

1is

arguments

to be

passed

the

1interrupt

invoked.

: LEVEL

An integer in
the interrupt

the range
function.

0-7, specifying the interrupt
level
The default interrupt level 1is 2.

for

OBJECT DESCRIPTIONS

INSTATE-INTERRUPT-FUNCTION

Function (cont.)

:ONCE-ONLY-P

NIL

the

(the

default),

function

specifying whether

not

uninstated when

i1t

this

has

instance

been

invoked

once.

Return Value

1integer

that

function.
that

integer

1iif-id

require

routines

identifies

This
that

can

cause

this

becomes
and

1instance

the

iif-id argument

astprm

argument

interrupt

functions

external

an AST.

Examples

Lisp>

(DEFINE-EXTERNAL-ROUTINE

(SYSSSETIMR
:CHECK-STATUS-RETURN

(EFN

:MECHANISM

:VALUE)

(DAYTIM

:VAX-TYPE

:QUADWORD)

(ASTADR

:MECHANISM

:VALUE)

(ASTPRM

:MECHANISM

:VALUE))

SYSSSETIMR

Lisp>

(DEFINE-EXTERNAL-ROUTINE

(SYSSBINTIM
:CHECK-STATUS-RETURN

(TIMBUF

:VAX-TYPE

:TEXT

:LISP-TYPE

(TIMADR

:VAX-TYPE

:QUADWORD

:ACCESS

STRING)
:IN-OUT))

SYSSBINTIM
Lisp>

(DEFUN
(LET

SET-TIMER
((IIF-ID

(DELTA-TIME)
(INSTATE-INTERRUPT-FUNCTION

# ' TIMER-INTERRUPT-HANDLER
:ONCE-ONLY-P

(CALL-QOUT

T)))

SYSSSETIMR 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

;

DELTA must be

bound

before

CALL-OUT

Lisp>

(CALL-0OUT

SYSSBINTIM

::5"

DELTA)

Lisp>

(SET-TIMER

DELTA)

Lisp>

(five

seconds pass)

The external
a

routine

system service

the
both

timer

passed with

timer

has

expired"

SYSSSETIMR is defined.

that

expires.

"The

sets

timer

The ASTADR and

:MECHANISM

:VALUE.

and

SYSSSETIMR is

causes

ASTPRM

an AST when

arguments

are

OBJECT DESCRIPTIONS
INSTATE-INTERRUPT-FUNCTION
The
a

external
system

string
The
is

routine

that

binary

format

SET-TIMER

calls

for

function

then

calls

the

second

specified

SET-TIMER’s

before

timer

i1t

SYSSSETIMR,

argument.

interrupt

requests
after

The

passing

the

argument

expire.

instate

function.

The

the

interrupt
SET-TIMER

binary

time

must

be)

argument

(and

parameter;

i1iif-id

INSTATE-INTERRUPT-FUNCTION.

function

simply
After

the

call

SET-TIMER
and

The

format

for

Five

printing

(DEFUN
(LET

example

(IIF

defined.

stored

expire

later,

the

DELTA,

seconds.

timer

expires

TIMER-INTERRUPT-HANDLER

message.
shows

same

((DELTA

seconds

timer

seconds

The

SET-TIMER

1is

terminal.

function

the

functions.
the

the

sets

interrupt

SYSSBINTIM have
Lisp>

returns.

following

interrupt

message

SET-TIMER

the

executes,

binary

fourth

TIMER-INTERRUPT-HANDLER

prints

the

wuse

external

definitions

o0of

arguments

routines
as

shown

with

SYSSSETIMR
in

Example

and
1.

(SECONDS)

(INSTATE-INTERRUPT-FUNCTION

#'TIME-ELAPSED
:ONCE-ONLY-P

: ARGUMENTS

(LIST

(CALL-OUT

SYSSBINTIM

(CALL-OUT

SYSSSETIMR NIL

SECONDS))))

(TIME-STRING

SECONDS)

DELTA)

DELTA

COMMON-AST-ADDRESS

IIF))

T)
SET-TIMER

Lisp>

(DEFUN

TIME-STRING

(FORMAT

NIL

(N)
g

(TRUNCATE

60)

(MOD

60)))

TIME-STRING

Lisp>

(DEFUN TIME-ELAPSED
(FORMAT

(N)

""@("R”)

second”
:P " :*" [have” ;has” :;have”]

elapsed
N
)

once.

COMMON-AST-ADDRESS

the

argument

the

returned

should

that

executes

third

SYSSSETIMR.

the

The

SYSSBINTIM

time

INSTATE-INTERRUPT-FUNCTION

uninstated

out

defined.

:ONCE-ONLY-P
be

defined.

acceptable

time

TIMER-INTERRUPT-HANDLER

value

converts

binary-formatted

SET-TIMER

(cont.)

SYSSBINTIM

service

function
the

Function

TIME-ELAPSED

since

setting

the

timer"”

OBJECT DESCRIPTIONS
INSTATE-INTERRUPT-FUNCTION Function (cont.)
5)

(SET-TIMER

Lisp>
T

Lisp>

(five seconds

setting

elapse)

Five

seconds have elapsed since

timer

the

The
new
definition
of
SET-TIMER
accepts
an
integer
argument
that
1is
the
number
of seconds to wait (not a
binary-formatted time).
SET-TIMER
instates
a
function
called
TIME-ELAPSED
as an interrupt function, requesting
that one argument (the number of
seconds)
be
passed
to
TIME-ELAPSED.
SET-TIMER
then calls out to SYSSBINTIM to
convert the
seconds
to
binary
format.
(An
auxiliary
function,
TIME-STRING,
string
acceptable
to

converts the
SYSSBINTIM.

integer argument to a
TIME-STRING
cannot

format
an
argument
larger
than 3599 seconds properly.)
Finally, SET-TIMER calls out to
SYS$SSETIMR,
passing
the
binary-formatted time (the second argument) and the iif-id
for

TIME-ELAPSED

The

function

integer

(the

TIME-ELAPSED

argument

seconds

fourth

and

represented by

uses
that

argument).

defined.

accepts

FORMAT to print the number of
argument.

SET-TIMER
1is
<called
with
the
argument
5.
SET-TIMER
returns.
After
5
seconds elapse, TIME-ELAPSED executes
and
prints
the
formatted
message
on
the
terminal,
including the number of seconds.

The following example shows the use of an interrupt

with
on

Lisp>

VAX LISP-supplied function.

function

This example works only

VAXstation.

(DEFUN PRINT-BUTTON
(WHEN

(BUTTON TRANSITION)

TRANSITION

(CASE

BUTTON

(#.UIS:POINTER-BUTTON-1
(PRINC "Left button pressed"))
(#.UIS:POINTER-BUTTON-2
(PRINC

"Middle

button pressed"))

(#.UIS:POINTER-BUTTON-3
§§
«i s
b
FoN Ty
TN B O O
it
(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)

Lisp>

(Left button

is pressed)

Left button pressed

OBJECT DESCRIPTIONS

INSTATE-INTERRUPT-FUNCTION Function (cont.)
The function PRINT-BUTTON 1is defined.
Depending
on
1ts
arguments,
it
prints one of three lines on the terminal,
or

does

nothing.

PRINT-BUTTONS is instated as an interrupt
function.
The
iif-id
returned by INSTATE-INTERRUPT-FUNCTION is retained
as

the

value

BUTTON-IIF.

The function SET-BUTTON-ACTION 1s called
with
BUTTON-IIF
as
the
third argument.
SET-BUTTON-ACTION specifies what
should happen when a workstation pointer button i1s pressed
or
released
while
the
©pointer cursor is 1in a specified
window.
If an i1if-id is passed as the third argument, the
associated
interrupt function is invoked when a button 1is
pressed
or
released.
SET-BUTTON-ACTION
causes
an
interrupt function to be passed two arguments:
the button
involved, and T or NIL to indicate whether the button
was
pressed or released.

After SET-BUTTON-ACTION
returns,
a
button
1s
pressed.
PRINT-BUTTON
receives the two arguments passed to 1t, and
prints

the

message

the

screen.

OBJECT DESCRIPTIONS

UNINSTATE-INTERRUPT-FUNCTION
Informs

LISP

longer

argument

that

the

interrupt

used.

The

routine

Function
function

1if-id

can

that

does

an AST

with

that

iif-id.

For

example,

called

with

that

11f-id

before

might

later

cause

AST.

interrupt

longer

can

UNINSTATE-INTERRUPT-FUNCTION

corresponding

identified

VAX

cause

not

the

use

has

1iif-id will

given

prevent

the

AST.

routine

astprm

However,

from

external

UNINSTATE-INTERRUPT-FUNCTION

ignores

been

routine

causing

LISP

function

ASTs

for

that

was

which

the

returned

uninstated.

Format
UNINSTATE-INTERRUPT-FUNCTION

iif-id

Argument

1if-id
An

1interrupt

function

identifier

previously

INSTATE-INTERRUPT-FUNCTION.

Return

Value

Undefined
Examples

Lisp>

(UNINSTATE-INTERRUPT-FUNCTION

TIMER-IIF)

Makes

the

unavailable

(LET

interrupt

function

for

use.

future

((BUTTON-IIF

represented

(INSTATE-INTERRUPT-FUNCTION

# ' BUTTON-HANDLER) ) )

(UIS:SET-BUTTON-ACTION

DISPLAY

(UIS:SET-BUTTON-ACTION

DISPLAY

(UNINSTATE-INTERRUPT-FUNCTION

this

instated

call

code

fragment,

and

the

pressed

execute

are
by

when

NIL)

function

Later,

reqguests

hat
or

from

its

the

The

pointer

second

action

the

system.

first

the

button

1is

call

taken when

released.

removes
the

BUTTON-HANDLER

1if-id.

BUTTON-HANDLER

workstation

pressed
BUTTON-IIF

WINDOW

BUTTON-IIF))

bound

UNINSTATE-INTERRUPT-FUNCTION
represented

BUTTON-IIF)

establishes

released.

ET-BUTTON-ACTION
buttons

TIMER-IIF

WINDOW

interrupt

BUTTON-IIF

SET-BUTTON-ACTION

function

interrupt

Finally,
function

OBJECT DESCRIPTIONS

WAIT

Function

Causes the program that calls it to stop executing until
function
returns non-NIL.
The first argument to WAIT is
waiting, typically a string.
The
second
argument
1is
arguments
to
the function can be provided as additional

a
specified
a reason for
a
function;
arguments to

WAIT.

A program that calls the WAIT function stops executing.
The
function
specified
in
WAIT’s
second argument is called periodically with the
arguments provided in the WAIT call.
If the function returns NIL, the
program
continues
to
wait.
When the function returns non-NIL,
returns an undefined value, and program execution continues.

WAIT

The testing function you specify with WAIT does
not
execute
1in
the
context
of
the program that issued the WAIT.
Therefore, the testing
function cannot depend on
the
binding
of
special
wvariables.
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 5
contains

examples

this

technique.

For efficiency and
reliability,
ensure
that
the
testing
function
If the testing function
and does not cause errors.
quickly
executes
encounters an error while LISP is in a WAIT state, LISP is left in
an
inconsistent
state
and will have to be terminated.
For this reason,
WAIT calls its testing function once before entering the
WAIT
state.
Errors that occur on this initial call can be debugged normally.
Format

WAIT

reason

function

&REST

arguments

Arguments
reason

The

reason for the wait,

typically a string.

function

A function that will be called periodically to determine
program should continue

1if

the

to wait.

arguments

Arguments to be supplied to the
argument.

Return Value

Undefined.

function

given

1in

the

second

OBJECT DESCRIPTIONS
WAIT Function (cont.)
Examples
1.

‘Lisp>

(SETF

*FLAG*

(LIST

NIL))

(NIL)

Lisp> (BIND-KEYBOARD-FUNCTION

F
N
4’ (LAMBDA

Lisp>

(WAIT

(After

()

"Wait

pause,

(SETF

for

user

(CAR

CTRL/F"
types

*FLAG*)

#'CAR

T)))

*FLAG¥*)

CTRL/F)

Lisp>

The

special

element

CTRL/F

*FLAG*

The

call

bound

1is

set

1list

whose

only

function

that

sets

the WAIT

function

specifies

the

first

element

and

function.

*FLAG*

WAIT

does

not

the

CAR as

argument

return

the

testing

the

testing

immediately.

When the user types CTRL/F, the keyboard function sets the
first
T,

The

*FLAG*

function

variable
NIL.

element

and

the

call

following

routines

*FLAG*

the

WAIT

returns.

example

uses

the

SYSSSETIMR

TIME-STRING

and

from Examples

testing

definitions

SYSSBINTIM

and

wunder

function

returns

the

external

and

the

function

INSTATE-INTERRUPT-

FUNCTION.

Lisp>

(DEFUN

SET-TIMER-AND-WAIT

(LET*

((DELTA
(FLAG
(ITF

(SECONDS)

0)
(LIST

NIL))

(INSTATE-INTERRUPT-FUNCTION

#'SET-FLAG
:ONCE~-ONLY-P
: ARGUMENTS

(CALL-OUT

SYSSBINTIM

(CALL-0OUT

SYSS$SSETIMR NIL

(LIST

FLAG))))

(TIME-STRING

SECONDS)

COMMON~-AST~-ADDRESS

(WAIT
(PRINC

"Timer
"The

wait"

timer

has

1)
SET-TIMER-AND-WAIT

Lisp>

(DEFUN
(SETF

SET-FLAG
(CAR

(FLAG)

FLAG)

T))

SET-FLAG

#’CAR

DELTA)

DELTA
FLAG))

expired")

IIF)

OBJECT DESCRIPTIONS

WAIT Function

(cont.)

Li sp>

(SET-TIMER-AND-WAIT

(Five

seconds

timer

elapse)

The

has

expired

Lisp>

The

function SET-TIMER-AND-WAIT is defined.
It binds
the
symbol
FLAG
to
a
1list
whose only element is NIL, 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
SYSSSETIMR,
specifying

that

the interrupt function SET-FLAG be executed when the

timer expires.
Finally, SET-TIMER-AND-WAIT calls the WAIT
function,
specifying
CAR as the testing function and the
list to which FLAG 1is bound as the argument to CAR.

The function SET-FLAG
1is
defined.
It
element of the list passed to it to T.

sets

the

first

SET-TIMER-AND-WAIT is called.
It executes as far
as
the
WAIT
function call.
WAIT does not return until the timer
expires and causes the first element of FLAG to be set
to
T,

INDEX

Page numbers in the
a

page

Index in the form c-n

Page numbers

in the

(for example,

form n

2-13)

(for example,

ALIEN-FIELD

function,

description,

naming,

3-3
types,

3-24

:ALLOCATION

constructor

list,

structure

3-3

access function,
defining field
generating, 17

passing

function,

3-3,

3-17

initial
3-4,

function,

alien

3-22

defining,

3-2,

examples,

that

address

AST

mechanism,

Field

AST

parameter

3-22

3-24,

predicate
naming,

Asynchronous

and

3-4,

options,

4-4

4-3

argument,

function,

3-4,

3-7

1interrupt

functions,

4-10

description,

3-4,

responding

3-8

facility,

3-1

routines
waiting

3-24

See also Call out facility
:ALIEN-DATA-LENGTH keyword
constructor function, 3-23

Index-1

4-7

events

functions,

function,

4-4

uninstated

associating with

structure

declare,

passing mechanism for,
specifying, 4-8

storage

type,

4-8

description

length,

field

argument

specifying,

modify,

type,

keyword

structure

routines

Field

(figure),

Alien

field

AST

3-19

AST

internal

name,

functions,

3-11

field

See

structure

:ASCIZ-STRING

3-7

creating,

field

interrupt

3-11

naming,

See

keyword

alien

value,

copier

: ARGUMENTS keyword
INSTATE-INTERRUPT-FUNCTION,
:ASCIW

specifying an

2-4,
21

4-6

naming,

2-11

Arguments

types,

constructor

3-24

2-4

passing mechanisms,
argument description,

2-11

Alien

function,

method,

access

macro,

method,

naming,

keyword

Argument

DEFINE-EXTERNAL-ROUTINE

2-11,

description,

Access

function,

3-24

keyword

: ACCESS

refer

ALIEN-STRUCTURE-LENGTH

Access function,
defining field
generating, 17

refer

25)

II.

Part

page

Part

1in

that
for,

interrupt

4-7

4-2

LISP,

cause,
5-3

4-1

4-4

4-6

INDEX

-B-

Critical

errors
BIND-KEYBOARD-FUNCTION

specifying

interrupt

:BIT
VAX

interrupt

level,

data

alien

b5-3

-D~keyword

:D-FLOATING

field type,

alien

16
|

level

for,

5-2

VAX

keyword

structure

3-11,

data

type,

keyword

2-12

internal,
Data

also Alien

examples,
and

2-1

description,

See

routines,

4-8

LISP,

: CHECK-STATUS-RETURN

2-4
macro,

VAX,

COMMON-AST-ADDRESS parameter,
CALL-OUT,

DEBUG

3-6,

keywords,

keywords

'naming,

for,

3-17,

3-23

1initial

wvalue,

macro,

17
keyword
DEFINE-ALIEN-STRUCTURE macro,
3-7

DEFINE-ALIEN~-STRUCTURE macro

3-17,

3-4,

5-2

3-24

defining an alien structure,
3-2
description, 13 to 18

: CONSTRUCTOR

3-6, 14
Copier function,
naming, 14

2-12

DEFINE-ALIEN-FIELD-TYPE

description,
an

2-9

function

interrupt level
keyword

specifying

keyword,

DEFINE-ALTIEN~-STRUCTURE macro,

3-3

3-22

(table),

2-11

: DEFAULT

function,

2-9

:VAX-TYPE keyword,

4-8

: CONC-NAME keyword
DEFINE-ALIEN-STRUCTURE macro,
Constructor

3-10,

keyword,

2-12,

:RESULT

2-14,

+:RESULT

|
3-3

2-17

:LISP-TYPE

keyword

DEFINE-EXTERNAL-ROUTINE

10,

3-10

Field
2-9,

(table),

field,

structures,

conversions,

instruction,

~using with

also

checking,

2-19,

structure

alien

2-14

3-1

types

alien

2-21

asynchronous

2-8,

2-25

macro,

CALLG VAX

structure

facility

2-20

structure
VAX,

facility,

type,

2-12

initialization,

data type,

CALL-OUT

field

Data

-C-

See

4-4

function

Call-out

macro,

5-2

2-12

structure

interrupt

VAX

using,

(Cont.)

function

functions,

type,

3-11,

:BYTE

5-1

keyword

:BIT-VECTOR

BREAK

1in,

CRITICAL-SECTION

BIND-KEYBOARD-FUNCTION

and

sections

options (table), 13
DEFINE-EXTERNAL-ROUTINE macro, 6
and asynchronous routines, 4-7

:COPIER keyword
DEFINE-ALIEN-STRUCTURE macro,

argument options (table), 22
defining external routines, 2-6

3-7, 14
Cricital sections

defining system services,
description, 19 to 23

infinite loops
Critical

in,

sections,

debugging,

5-3

5-2

routine options
Descriptor

5-3

(table),

2-18

(:DESCR)

argument-passing mechanism,

Index-2

INDEX

Descriptor

(:DESCRIPTION)

Descriptor

(:DESCRIPTOR)

argument-passing mechanism,

2-4

(Cont.)
2-8
suspending a LISP system,

External
status

routine
return,

argument-passing mechanism,
2-11

Documentation string,
Dynamic memory, 3-24

...'F...

15,

:F-FLOATING keyword
alien structure field type,
3-11,

o e

VAX data type,
ED

function

level

for,

5-2

interrupt level

for,

5-2

Editor

position

ALIEN-FIELD function,
field, 3-14, 16
:ENTRY-POINT keyword
2-8,

accessing, 3-18, 1
defining, 3-24
description, 3-10

end position,

DEFINE-EXTERNAL-ROUTINE

Error

macro,

handler

calling external

routines,

2-19

Errors

in critical

sections,

Events

5-3

see Asynchronous

asynchronous,

routine
access method, 22
alien structures,

2-13,

2-21

(figure),

2-2

2-14

formal

See

2-8,

open, 2-21
:FILE keyword
DEFINE-EXTERNAL-ROUTINE macro,
20

FORCE-INTERRUPT-FUNCTION function,
24

(table), 2-17
data types, 2-18

error

Formal argument description,
FORTRAN,

2-5

Functions

2-18,

interrupt, see
functions

2-19

handler,
argument

formal

description

options,

2-7,

2-18,
19

2-9,

result data type,
status code, 2-19

Interrupt

-G=- |

argument

image name, 2-9,
name, 2-7, 2-18,

File

data type conversion,

entry point,

(table), 3-11
predefined, 10

2-9

checking data types, 21
checking status return, 20
data initialization, 2-20

defining, 2-6, 19
examples, 2-21

given

3-1

argument type checking,
2-1,

start position, 3-14, 1,
type, 3-10, 3-11, 1, 16
defining, 3-14, 10

External

examples,

3-14,

gaps, 3-15, 17
index, 3-18
initial value, 3-16,
name, 3-10, 1, 15
offset, 3-19
options, 3-16
(table), 16
overlapping, 3-15
repeated, 3-18
repeating, 17
setting, 3-18

events

calling,

2-12

Field

interrupt

End

2-20

:G-FLOATING keyword
alien structure field type,
3-11,

VAX data type,
Gaps, 3-15, 17

Index-3

2-12

2-10

INDEX

GET-INTERRUPT-FUNCTION

function,

Interrupt

levels

(Cont.)

specifying
interrupt

functions,

4-7

...K..

:H-FLOATING

alien
VAX

keyword

structure

field

type,

Keyboard

and

3-11,

data

type,

2-12

functions

suspended

interrupt
protecting

by,

-7
-

name,

: IMAGE-NAME
DEFINE-

2-18
keyword

Immediate

value

Keyboard

(:IMMED)

argument-passing
Immediate

waiting

2-9

value

: LEVEL
3-22

2-11,

Input-output

access

(:IN-0OUT),

2-6

calling

functions,

:LISP-TYPE

4-1

4-4

and

suspended

systems,

4-10

associating with
events,

VAX

4-5

interrupt

levels,

overview,

4-2

automatically,

2-21

keyword

data

type,

2-12

to,

-M-

:MECHANISM

4-6

4-9

keyword

DEFINE-EXTERNAL-ROUTINE

2-11,

interruption

5-2

macro,

Memory

synchronizing
uninstating,

4-8

CALL-OUT,

execution,

dynamic,

static,

5-3

3-24

4-10

single

execution,

automatically,
SUSPEND,

4-7

...‘0..

4-10

completion

levels,

guidelines,

using,

5-1

against

specifying with

Interrupt

macro,

4-7

arguments

for

data

names

: LONGWORD

4-5

level,

protecting

Logical

.errors

interrupt

structure

3-1

keyword

2-11,

asynchronous

instating,

routines,

DEFINE-EXTERNAL-ROUTINE

4-7

establishing,

alien

types,

functions,

waiting

external

defining

keyboard

after

types

2-6

and

by,

Data

program

4-5

function,

passing

4-7

type

See

INSTATE-INTERRUPT-FUNCTION

Interrupt

keyword

data

INSTATE-INTERRUPT-FUNCTION

using,

5-2

LISP

utility,

of,

INSTATE-INTERRUPT-FUNCTION,

(:IN),

INSTALL

level

2-4,

access

2-11,

5-3

...L...

mechanism,

keyword,

interrupt
4-4

2-11

Input

for,

(:VALUE)

argument-passing
Initialization

input

interrupt

mechanism,

interruption

5-2

functions,

macro,

4-10

5-1

against

relationship
Image

systems,

levels,

of,

5-3

:OCCURS

5-1

keyword

DEF INE-ALIEN-STRUCTURE

3-18,

5-2

Index-4

macro,

INDEX

:OFFSET

keyword

DEFINE-ALIEN-STRUCTURE

:ONCE-ONLY-P

linking,

keyword

INSTATE-INTERRUPT-FUNCTION,

4-7

2-5

3-11,

position

ALIEN-FIELD
field,

: POINTER

keyword

alien

structure

3-12,
Predicate

field

alien

keyword

DEFINE-ALIEN-STRUCTURE

function,

alien

3-4,

structure,

:PRINT-FUNCTION

alien structure
3-11, 16

Suspended

3-8

Program

macro,

section

(PSECT),

3-24

field

type,

systems

and interrupt functions, 4-10
and keyboard functions, 4-10
including calls to external

keyword

DEFINE-ALIEN-STRUCTURE

3-8,

structures,

keyword

: STRING

macro,

3-8,

3-24

code, 2-19
Status return, 2-8,
Storage allocation

3-4

: PREDICATE

Status

function,

naming,

function,

3-14,

memory,

Static

type,

2-5

: SIGNED-INTEGER keyword
alien structure field type,
Start

...P...

(SHR),

image

Shareable

macro,

3-19,

attribute

routines,

2-5

System

completion of,

asynchronous

-R=-

2-20

services

4-4

calling,
: READ-ONLY

2-1, 2-18
examples, 2-24

keyword

DEFINE-ALIEN-STRUCTURE

3-18,
Reference

defining,

macro,

examples,

Reference

(:REFERENCE)

argument-passing mechanisn,

2-4,

: TEXT

DEFINE-EXTERNAL-ROUTINE

2-9,

VAX

RMS

system

: TYPE-CHECK

field

type,

2-12

keyword

DEFINE-EXTERNAL-ROUTINE

2-4

2-9,

services

macro,

services

Routine

argument,

Run-time

library

2-1,

VAX data

macro,

instruction,

System

structure

3-11

keyword

RET

keyword

alien

2-11

See

2-24

(:REF)

argument-passing mechanism,

:RESULT

2-18

6
(RTL)

routine,

wJ
=

2-21

UNINSTATE-INTERRUPT-FUNCTION
function,

-G
-

using,
:SELECTION

alien
SETF

keyword

structure

field

type,

macro

access

functions,

creating alien

3-18

structures,

3-3,

3-15
with ALIEN-FIELD

function,

4-10

:UNSIGNED-BYTE keyword
VAX data type, 2-12
:UNSIGNED-INTEGER keyword
alien structure field type,
3-11, 16
: UNSIGNED-LONGWORD keyword
VAX data type, 2-12

Index-5

INDEX

:UNSIGNED-WORD
VAX

data

keyword

type,

VMS

linker,

2-12

system

See

2-5

services

System
-

....V..

: VARYING-STRING

alien

WAIT

keyword

structure

field

testing

3-11

VAX

data

See

VAX

2-1,

Calling

using,

Standard,

:WORD

2-3

:VAX-TYPE

VAX

keyword

DEFINE-EXTERNAL-ROUTINE

2-12

function
5-4

guidelines,

types

Procedure

5-3

debugging,

type

Data

function,

arguments,

type,

services

macro,

keyword
data

Writable
Write

Index-6

5-3

type,

2-12

section,

attribute

2-5

(WRT),

2-5

HOW TO ORDER
ADDITIONAL DOCUMENTATION

Write

From

Call

Chicago

312-640-5612

Digital Equipment Corporation

8:15am to 500 pm CT

Accessories & Supplies Center

1050 East Remington Road
Schaumburg, IL 60195

408-734-4915

San Francisco

8:15amM to 500pm PT

603—884—6660
830AaM to 6:00 M ET

Alaska, Hawaii

Digital Equipment Corporation
Accessories & Supplies Center
632 Caribbean Drive

Sunnyvale, CA 94086

408-734—-4915
8:15amM to 500 pm PT

New Hampshire

603—884—-6660

Digital Equipment Corporation

830 AaM to6:00pPmM ET

Accessories & Supplies Center

Rest of U.S.A.,

1-800-258-1710

Puerto Rico*

830 aM to6:00pPM ET

P.O. Box CS2008
Nashua, NH 03061

*Prepaid orders from Puerto Rico must be placed with the local DIGITAL subsidiary (call 809-754-7575)

Canada

British Columbia
Ottawa—Hull

1-800-267-6146

Digital Equipment of Canada Ltd

8:00 AM to 500 M ET

940 Belfast Road

613-234-7726

Ottawa, Ontario K1G 4C2
Attn: A&SG Business Manager

8:00 AM.t0 5:00 PM. ET

Elsewhere

112-800-267-6146
8:00 Am to 5:00 M ET

Elsewhere

Digital Equipment Corporation
A&SG Business Manager®

*c/o DIGITAL's local subsidiary or approved distributor

VAX LISP/VMS System Access Programming Guide
AA-GH75A-TE

READER’S

COMMENTS

Note: This form is for document comments only. DIGITAL will use comments

submitted on this form at the company’s discretion. If you require a written reply and

are eligible to receive one under Software Performance Report (SPR) service, submit

your comments on an SPR form.

Did you find this manual understandable, usable, and well organized?

Please make suggestions for

improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
Assembly language programmer

Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer

Other (please specity)

Name

City

Date

State

Zip Code

or Country

—

Do Not Tear — Fold Here and Tape

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.

POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION

CORPORATE USER PUBLICATIONS
MLO5-5/E45
- 146 MAIN STREET
MAYNARD, MA 01754-2571

GETRANES

020 SENNRED

AMENIND

WNmENES

GRSmSMS

oEmmws

omewsees

—

eNWAOWS

a—

cilmDMe

———

sssomowe

a————

0 GOuems

a——

eschMmes

a———

——

cceoess

eweswds

a—

wmeosn

———

000

——

ommeme

Cut Along Dotted Line

m——

esowwes

——

000

w—

enmamas

cn——

comuess

m—

GmTeaS

n—

Do Not Tear — Fold Here

—