Digital PDFs
Documents
Guest
Register
Log In
AA-KM37B-TE
July 1989
44 pages
Original
17MB
view
download
Document:
VAX LISP/VMS System-Building Guide
Order Number:
AA-KM37B-TE
Revision:
000
Pages:
44
Original Filename:
OCR Text
VAX LISP/VMS System-Building Guide Order Number: AA-KM37B-TE This revised manual provides the information needed to create executable LISP im ages with the VAX LISP System-Building Utility on VMS systems. Revision/Update Information: This manual su persedes VAX LISP/VMS System-Building Guide, AA-KM37A-TE. Operating System and Version: VMS Version 5.1 Software Version: digital equipm ent corporation maynard, m a ssa ch u setts VAX LISP Version 3.0 First Printing, July 1987 Revised, July 1989 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assu m es no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assum ed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. © Digital Equipment Corporation 1987, 1989. All rights reserved. Printed in U.S.A. The postpaid Reader's Comments form at the end of this document requests your critical evaluation to assist in preparing future documentation. The following are trademarks of Digital Equipment Corporation: AI VAXstation DEC DECnet DECUS MicroVAX MicroVAX II MicroVMS PDP ULTRIX ULTRIX-11 ULTRIX—32 UNIBUS VAX VAX LISP VAX LISP/ULTRIX VAX LISP/VMS VAXstation VAXstation II VMS X Window System™ is a trademark of the Massachusetts Institute of Technology. ML-S830 This document was prepared using VAX DOCUMENT, Version 1.1. Contents P r e f a c e .............................................................................................................. Chapter 1 v Overview of the System-Building Utility 1.1 Features of a User-Built S y s t e m ......................................................... 1-1 1.2 D ifferences from a S u sp e n d e d S y s t e m ................................................. 1-2 1.3 G eneric System -Building P ro c e d u r e ..................................................... 1-3 1.4 Preparing to Use the System -Building U tility ......................................... 1.4.1 Digital-Supplied F i l e s .......................................................... 1.4.2 Disk S pa ce and M em ory....................................................... 1-4 1—4 1-4 Chapter 2 DEFINE-LISP-SYSTEM Function 2.1 Format and Behavior of DEFINE-LISP-SYSTEM....................................... DEFINE-LISP-SYSTEM.......................................................... 2-1 2-2 2.2 Naming the Output F i le s ................................................................... 2.2.1 Using the Argument im age-nam e ............................................ 2.2.2 Using the :BUILD-FILE-NAMES Keyword .................................. 2-4 2—4 2-5 2.3 C u stom izin g the I m a g e ..................................................................... 2.3.1 Using the Keyword :INPUT-FILES............................................ 2.3.2 Using the :MAIN, :INIT-FUNCTION, and :HERALD K e y w o r d s ........... 2-6 2-6 2-7 2.4 Excluding Digital-Supplied C o d e ......................................................... 2-9 2.5 Making an Execute-Only S y s t e m ......................................................... 2.5.1 Development System s ......................................................... 2.5.2 Execute-Only S y s t e m s ......................................................... 2-12 2-12 2-13 2.6 Specifying Memory R e q u ir e m e n ts ....................................................... 2-14 Chapter 3 Working with User-Built Systems 3.1 Installing the I m a g e ......................................................................... 3-1 3.2 Invoking the I m a g e .......................................................................... 3.2.1 Using RUN or a Foreign Command ............ 3-2 3-2 iii 3.2.2 3.2.3 Defining a DCL C om m an d ..................................................... 3.2.2.1 Defining a Command Without Qualifiers........................ 3.2.2.2 Defining the Qualifiers /MEMORY, /RESUME, and /C ST A C K .......................................................... 3.2.2.3 Defining Other Digital-Defined Qualifiers ...................... 3.2.2.4 Defining Other Command-Line Entities ........................ 3.2.2.5 Summary of Restrictions on Command Definition ........... Using the Digital-Defined Command LISP .................................. 3-3 3-4 3-4 3-5 3—5 3-6 3-6 Index Tables 2-1 Values for the Keyword :EXCLUDE 2-9 Preface The VAX LISP/VMS System Building Guide provides the information needed to create executable LISP images with the VAX LISP System-Building Utility on VMS systems. Intended Audience Readers of this manual should have a working knowledge of LISP programming and be familiar with the general information about VAX LISP and VMS that appears in the VAX LISP /VMS Program Development Guide. Document Structure This manual consists of three chapters: • Chapter 1 provides an overview of the System-Building Utility, the features of the user-built system that the utility creates, and the generic procedure for using the utility. • Chapter 2 describes the d e f in e - l i s p - system function, which is the center of the System-Building Utility, and the arguments to d e f in e -l i s p - system . • Chapter 3 explains how to make the read-only portions of a user-built system shareable and how to define a DCL command to invoke a user-built system. Associated Documents The following documents are relevant to using the VAX LISP/VMS System Building Guide-. • The VAX LISP/VMS Program Development Guide provides general informa tion about using VAX LISP and serves as a guide to helpful VAX LISP and VMS documentation. • The Guide to Setting Up a VMS System gives an overview of some VMS utilities that you can use with a user-built LISP executable image. • The VAX LISP/VMS Installation Guide explains the VMS Install Utility, which you can use to make an executable image shareable. • The VMS Command Definition Utility Manual explains the Command Definition Utility, which you can use to create a new DCL command for invoking an executable image. v Conventions The following conventions are used in this manual: C o n v e n t io n M e a n in g UPPERCASE DCL commands and qualifiers and VMS file names are printed in uppercase characters; however, you can enter them in uppercase, lowercase, or a combination of uppercase and lowercase characters. For example: The examples directory (SYS$SYSROOT:[VAXLISP.EXAMPLES] by default) contains sample LISP source files. U PPERCA SE TY PEW RITER Defined LISP functions, macros, variables, constants, and other symbol names are printed in uppercase TY PEW RITER charac ters; however, you can enter them in uppercase, lowercase, or a combination of uppercase and lowercase characters. For example: The CALL-OU T macro calls a defined external routine . . . . lo w e r c a s e t y p e w r it e r LISP forms are printed in the text in lowercase t y p e w r it e r characters; however, you can enter them in uppercase, lowercase, or a combination of uppercase and lowercase characters. For example: SANS SERIF Format specifications of LISP functions and macros are printed in a sans serif typeface. For example: ( s e t f example-1 (m ake-space)) CALL-OUT external-routine &REST routine-arguments italics Lowercase italics in format specifications and in text indicate argu ments that you supply; however, you can enter them in lowercase, uppercase, or a combination of lowercase and uppercase characters. For example: The routine-arguments must be compatible with the arguments defined in the call to the D E F IN E -E X T E R N A L -R O U T IN E macro. () Parentheses used in examples of LISP code and in format spec ifications indicate the beginning and end of a LISP form. For example: ( setq name lis p ) N Square brackets in format specifications enclose optional elements. For example: [doc-string] Square brackets do not indicate optional elements when they are used in the syntax of a directory name in a VMS file specification. Here, the square bracket characters must be included in the syntax. For example: (pathname {} " M IA M I: : D B A 1 : [ S M IT H ] L O G IN . C O M ;4 ") In function and macro format specifications, braces enclose elements that are considered one unit of code. For example: {keyword value} U* In function and macro format specifications, braces followed by an asterisk enclose elements that are considered one unit of code, which can be repeated zero or more times. For example: {keyword value}' C on v en tion M ean in g &OPTIONAL In function and macro format specifications, the word &OPTIONAL indicates that the arguments that follow it are optional. For exam ple: PPRINT object &OPTIONAL stream Do not specify &OPTIONAL when you invoke a function or macro whose definition includes &OPTIONAL. &REST In function and macro format specifications, the word &REST indicates that an indefinite number of arguments may appear. For example: CALL-OUT external-routine &REST routine-arguments Do not specify &REST when you invoke a function or macro whose definition includes &REST. &KEY In function and macro format specifications, the word &KEY indi cates that keyword arguments are accepted. For example: COMPILE-FILE input-pathname &KEY LISTING :MACHINE-CODE :OPTIMIZE :OUTPUT-FILE :VERBOSE WARNINGS Do not specify &KEY when you invoke a function or macro whose definition includes &KEY. A horizontal ellipsis in a format specification means that the ele ment preceding the ellipsis can be repeated. For example: function-name .. . A vertical ellipsis in a code example indicates that all the informa tion that the system would display in response to the function call is not shown; or that all the information a user is to enter is not shown. | R e turn | A word inside a box indicates that you press a key on the keyboard. For example: | R e tu rn |or |tab| In code examples, carriage returns are implied at the end of each line. However, IR e turn |is used in some examples to emphasize carriage returns. [C triä c l Two key names enclosed in a box indicate a control key sequence in which you hold down Ctrl while you press another key. For example: I C trl/C |or IC M /S | iPFTir^i A sequence such as | p f i | |_x j indicates that you must first press and release the key labeled PF1, then press and release another key. mouse The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus. MB1, MB2, MB3 By default, MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. You can rebind the mouse buttons. Red print In interactive examples, user input is shown in red. For example: L is p > (cdr ' (a b c)) (B C) L is p > Chapter 1 Overview of the System-Building Utility The VAX LISP System-Building Utility enables you to create a LISP system that is a single executable image. This user-built system can serve as: • A customized VAX LISP development environment that can be shared efficiently by multiple users at the same time • A delivery vehicle for VAX LISP-based applications This chapter gives an overview of the System-Building Utility and of the user-built system that it creates. The chapter introduces: • The purpose of the System-Building Utility, described in terms of the features of the LISP system that it creates. • The capabilities that the System-Building Utility provides. These capabilities are described in terms of the differences between a LISP system created with the System-Building Utility and a LISP system created with the VAX LISP suspend function. • The generic procedure for building a LISP system with the System-Building Utility. • Prerequisites for using the System-Building Utility. 1.1 Features of a User-Built System T h e L ISP system created by the System -B uilding U tility con sists o f a sin gle VMS executable (.EXE) file. When you build a LISP system, you have the following options: • You can exclude certain portions of Digital-provided VAX LISP code from the image, thus making the image smaller. Reducing the image size reduces the frequency of paging and the requirements for disk space and memory. • You can incorporate LISP code that you write into the image. When possible, your code is built into read-only sections of the image. The read-only sections can be shareable. • You can specify the im age’ s entry point; that is, the main function to be executed when the image is invoked. • You can specify the size of the im age’ s dynamic memory and of its control stack and binding stack. Overview of the System-Building Utility 1-1 In addition to these optional features, the user-built system shares the normal features of a VMS executable file: • You can use the VMS Install Utility to make the read-only portion of the image (including the read-only portion of the code you supply) shareable. Making the image shareable reduces the physical memory requirements when more than one user at a time runs the image. • You can invoke the image with the DCL command RUN, which does not take LISP-specific qualifiers. (A LISP-specific qualifier is any command line qualifier processed by the LISP image.) Alternatively, you can use the VMS Command Definition Utility to create a new DCL command for invoking the image. The new command can take LISP-specific qualifiers. Finally, an important feature of user-built systems is that some systems may be distributed to CPUs that have no VAX LISP software license. See Section 2.5 for further information on Digital licensing requirements for user-built systems. 1.2 Differences from a Suspended System An executable image created by the System-Building Utility differs from a system created by the LISP function suspend in several important respects. A call to suspend creates a suspended system with a default file type of .SUS instead of an executable image with a default file type of .EXE. (For information on suspend and on using suspended systems, see the VAX LISP /VMS Program Development Guide.) Before Version 2.2 of VAX LISP, only a suspended system enabled you to capture a modified LISP environment. Since VAX LISP Version 2.2, your system-building options have included two choices: • An executable image created with the System-Building Utility • A suspended system created from within a user-built system This section outlines the differences between the two kinds of systems— executable and suspended—that you can create from within VAX LISP. (The discussion does not apply to a suspended system created from within a user-built executable system.) The differences are: • A user-built executable image is a stand-alone system; that is, it can run on a system on which VAX LISP has not been installed. (However, a user-built executable image may require a VAX LISP license to run; see Section 2.5.) In contrast, a suspended system can be resumed only in the presence of the executable file from which it was suspended—in this case, the VAX LISP executable file. Although you can create a suspended system from a user built system, it is not possible to suspend the build of a .EXE file and then resume it. • A user-built executable image can exclude unneeded Digital-provided code. In contrast, all Digital-provided code is included in the system that results when a suspended system is resumed from VAX LISP. • In a user-built executable image, multiple users can share read-only portions of both the Digital-provided and user-supplied code; in contrast, they cannot share a suspended system, A suspended system is useful as a personal, single-user development environment and as a way to save some of the state of your work when you need to interrupt 1-2 Overview of the System-Building Utility an interactive LISP session. A suspended system created from within VAX LISP is less useful as: • A multiuser customized development environment, because user-written code cannot be placed in read-only space and made shareable. • A delivery vehicle for user-written applications, because the suspended system requires the original executable file in order to resume. A user-built executable file is more useful for both these purposes, because it is a stand-alone system, because read-only portions of user-written code can be made shareable, and because unneeded Digital-provided code can be excluded. On the other hand, creating an executable image involves considerably more overhead than creating a suspended system. Also, a suspended system saves the present LISP environment, while a user-built executable file must build the environment from compiled files. 1.3 Generic System-Building Procedure The system-building procedure has two steps: 1. From within VAX LISP, call the d e f in e - l i s p - system function. Use keyword arguments to specify features of the system. The function d e f in e -l i s p system creates a VMS command procedure and other files required to build your system. 2. From DCL, execute the command procedure. Commands in the procedure build the executable image file. You can treat the user-built system like any other VMS executable image. For instance, you can install it to make its read-only portions shareable, and you can define a special DCL command to invoke it. An example of the generic system-building procedure is: 1. From LISP, call the d e f in e -l i s p - system function with the desired argu ments: Lisp> (define-lisp-system "my-program" ... ) This step produces a command file named LISP$BUILD-MY-PROGRAM.COM and a compiled file named LISP$BUILD-MY-PROGRAM.FAS. 2. From DCL, execute the command procedure: $ @ LISP$B U ILD -M Y -PRO G RA M This step uses the compiled file (and a number of other special-purpose files) to produce an executable file named MY-PROGRAM.EXE. (This step may produce a number of linker warning messages, which may be ignored.) 3. Optionally, use VMS utilities to make the executable file shareable and/or to define a new DCL command to invoke the executable file. (See Chapter 3 for a description and examples of these steps.) 4. From DCL, invoke the executable image: $ RUN MY-PROGRAM The executable image can also be transferred to and used on another CPU on which Digital-supplied VAX LISP is not installed. Such a transfer may require a Digital software license. (See Section 2.5.) Overview of the System-Building Utility 1-3 1.4 Preparing to Use the System-Building Utility Before using the System-Building Utility, you should make sure that you have access to the necessary components of the Digital-supplied VAX LISP kit and that your account has an adequate quota of disk space, as described in the following sections. 1.4.1 Digital-Supplied Files The command procedure in the System-Building Utility uses the following four files, which are supplied with the VAX LISP system: • LISP$LIBRARY:LISP$FASLIB.TLB • LISP$LIBRARY:LISP$OBJLIB.OLB • LISP$LIBRARY:LISP$BUILD-VAXLISP.EXE • LISP$LIBRARY:LISP$BUILD-VAXLISP.CLD These files must be available to your process. Because only the VAX LISP System-Building Utility uses these files, you can save space by removing them from your system (leaving them on the Digital distribution medium) when you are not using the System-Building Utility. 1.4.2 Disk Space and Memory When you execute the System-Building U tility’ s command procedure, it starts a new LISP process from DCL. It also generates a large number of intermediate files that are later deleted and the executable file. For you to use the System-Building Utility, your account needs a quota of disk space large enough for the command file, the compiled file, and the executable file that the utility creates, plus additional blocks for the intermediate files that the command procedure generates. The number of blocks that these files require depends on options specified with d e f in e - l i s p - system . Building a full VAX LISP system requires approximately 34,000 blocks. The virtual memory required to execute the System-Building U tility’ s command procedure includes the virtual memory required by the new LISP process that it generates. If you use the VAX LISP s p a w n function to execute the command procedure in a subprocess, your account will require process quotas large enough to run two LISP processes simultaneously. 1-4 Overview of the System-Building Utility Chapter 2 DEFINE-LISP-SYSTEM Function This chapter describes the d e f in e -l i s p - system function, the center of the System-Building Utility. The following sections describe the function and its effects: • Section 2.1 describes the format of the d e f in e -l i s p - system function. • Section 2.2 shows how to specify the names of the executable image file and the files used to build the executable image. • Section 2.3 shows how to customize the image by specifying files of userwritten code to be included in the image, by changing the im age’ s entry point (that is, the function that executes when the image starts), and by either preventing the standard VAX LISP welcome message from being displayed or changing the contents of that message. Section 2.3 also lists restrictions on actions that user-written code can perform as it is loaded. • Section 2.4 shows how to exclude components of Digital-provided code from the image. • Section 2.5 shows how to specify whether the image will require a VAX LISP software license for distribution. • Section 2.6 shows how to specify the default size of the im age’ s dynamic memory and the sizes of the control stack and binding stack. 2.1 Format and Behavior of DEFINE-LISP-SYSTEM The d e f in e -l i s p - system function creates a VMS command procedure and returns a string that is the VMS file specification of that procedure. When you execute the command (.COM) file from DCL, an executable image containing a LISP custom system is produced. The d e f in e - l i s p - system function also creates a compiled (.FAS) file that the command procedure uses. The command file and the compiled file remain on your system—along with the new executable file—after the system-building procedure ends. The format of the d e f in e - l i s p - system function is shown below. DEFINE-LISP-SYSTEM Function 2-1 DEFINE-LISP-SYSTEM DEFINE-LISP-SYSTEM Format DEFINE-LISP-SYSTEM image-name &KEY :BUILD-FILE-NAMES :INPUT-FILES :INIT-FUNCTION :MAIN :HERALD :EXCLUDE :REQUIRES-LICENSE :MEMORY :BUILD-MEMORY :CONTROL-STACK-SIZE :BINDING-STACK-SIZE Arguments image-name A string, symbol, or pathname used to create the name of the executable file and (by default) command file and the compiled file. (See Section 2.2.1.) :BUILD-FILE-NAMES A string, symbol, or pathname used to name the command file and the compiled file. (See Section 2.2.2.) :INPUT-FILES A file specification or a list of file specifications (symbols, strings, or pathnames). The file type defaults to .FAS or .LSP, with the more recently created file being used in case of a conflict. Code in the files is built into the system. (See Section 2.3.1.) :INIT-FUNCTION A symbol or string that names the function that executes after the welcome message (if one is printed) and before the function named by :MAIN or the read-eval-print loop. (See Section 2.3.2.) :MAIN A symbol or string that names the function that executes after the function named by : i n i t - function and whose return terminates the image. The default value is the VAX LISP read-eval-print loop. A value of n il specifies this default. (See Section 2.3.2.) :HERALD The value t (the default), n il , or a string specifying whether the standard VAX LISP welcome message, no message, or a user-supplied message should be displayed when the system starts. (See Section 2.3.2.) :EXCLUDE A keyword or list of keywords specifying VAX LISP components to be excluded from the system. (See Section 2.4.) :REQUIRES-LICENSE The value T (the default) or n il , specifying whether the system may run only on CPUs with VAX LISP software licenses. (See Section 2.5.) 2-2 DEFINE-LISP-SYSTEM Function DEFINE-LISP-SYSTEM :MEMORY An integer specifying, in 512-byte pages, the default total size of the system ’ s dynamic memory when the executable file is invoked. (See Section 2.6.) :BUILD-MEMORY An integer specifying, in 512-byte pages, the total size of dynamic memory used during the build of the executable file. (See Section 2.6.) :CONTROL-STACK-SIZE An integer specifying, in 512-byte pages, the size of the system ’ s control stack. (See Section 2.6.) :BINDING-STACK-SIZE An integer specifying, in 512-byte pages, the size of the system ’ s binding stack. (See Section 2.6.) DEFINE-LISP-SYSTEM Function 2-3 2.2 Naming the Output Files The System-Building Utility creates three files that remain on your system after the entire procedure is completed. These three files are: • A command procedure (.COM file) that is created by the d e f in e -l i s p - system function, then executed to create the customized system • A com p iled file (.FAS file) that is created b y the d e f in e - l i s p - system function, then u sed by the com m an d p rocedu re to create the cu stom ized system • An executable file (.EXE file) that is the customized system created by the command procedure In addition to these three files, the System-Building Utility creates (and later deletes) a number of intermediate files that it uses to create the executable file. The d e f in e - l i s p - system function’ s image-name argument and :BUILD-f i l e names keyword specify the names of the three permanent output files. Both values can be specified as symbols, strings, or pathnames. As with all such file specifications in VAX LISP, you can supply a full VMS file specification or just a file name. The system supplies default values for any other components of a full file specification that you do not supply. (See the VAX LISP/VMS Program Development Guide or the VAX/VMS documentation set for more information on VMS file specifications.) 2.2.1 Using the Argument image-name The required image-name argument names the executable file that the SystemBuilding Utility creates. The file type is .EXE, and the device and directory components, if not specified, are the default device and directory when the d e f in e - l i s p - system function is called. For instance, the following two examples have equivalent effects: (define-lisp-system "diskl:[smith.build]expert.exe") and (setf (default-directory) "diskl:[smith.build]") (define-lisp-system "expert") Both examples direct the System-Building Utility to produce an executable file with the name: DISKI: [SMITH.BUILDJEXPERT.EXE By default, the image-name argument also names the command procedure and the compiled file that the d e f in e - l i s p - system function produces. The file name specified by image-name is prefixed with LISP$BUILD-, and the file types are .COM and .FAS, respectively. You can supply a value for the keyword : b u il d - f i l e -names to override this default. 2-4 DEFINE-LISP-SYSTEM Function For example, the preceding calls to the d e f in e - l i s p - system function produce “ build”files named: DISKI:[SMITH.B UILD]LISP$B UILD-EXPERT. COM and DISK1:[SMITH.BUILD]LISP$BUILD-EXPERT.FAS NOTE If the value you supply for image-name corresponds to a logical name that is currently defined, that logical name is translated and the result is used to form the names of the output files. 2.2.2 Using the :BUILD-FILE-NAMES Keyword If you want some or all components of the build file specifications to differ from the default, supply a : b u il d -f i l e -names argument. For example: (define-lisp-system "diskl:[smith.build]expert.exe" :build-file-names "diskl:[smith.test]expert-testi") or (setf (default-directory) "diskl:[smith.build]") (define-lisp-system "expert" :build-file-names " [smith.test]expert-testi") Both calls to the d e f in e - l i s p - system function ultimately produce an executable file named: DISK1:[SMITH.BUILD]EXPERT.EXE The build files, however, are named: DISK1:[SMITH.TEST]EXPERT-TEST1.C0M DISK1:[SMITH.TEST]EXPERT-TEST1.FAS I f you su p p ly a value for the :b u il d -f i l e - names keyw ord bu t do not specify a device and/or directory, the bu ild files are p laced in the sam e directory as the execu table im a ge file. You can supply just a device and/or a directory with the :b u il d -f i l e -names key word, allowing the file names to be constructed from the image-name argument. For example: (define-lisp-system "expert" :build-file-names "disk2:[smith.test]") The two resulting build files are named: DISK2:[SMITH.TEST]LISP$BUILD-EXPERT.COM DISK2:[SMITH.TEST]LISP$BUILD-EXPERT.FAS DEFINE-LISP-SYSTEM Function 2-5 The disk on which the build files are placed must also have room for a number of other files that are needed to build the system. The total size of these files is about 34,000 blocks for a full VAX LISP system. The examples in this section illustrate only the name-related arguments to the DEPINE-LISP-SYSTEM function. Since they do not change image contents or behavior in any way, these examples produce an executable image that is functionally identical to the Digital-supplied VAX LISP. 2.3 Customizing the Image lb customize the content and the behavior of the user-built system, use the : in pu t - f i l e s , : i n i t - function , : main , and :herald keywords. The values of these keywords specify the following items: • : in pu t - f il e s —File(s) of user-written code to be built into the image • : i n i t - function —The function that executes after the welcome message and before the function named by :MAIN or the read-eval-print loop • :main—The function that executes after the function named by : i n i t function and whose return terminates the image • 2.3.1 : herald—The presence of the standard message “ Welcome to VAX LISP, Vx.x,”a user-supplied message, or no message when the image starts Using the Keyword :INPUT-FILES The : in pu t - f il e s keyword specifies one or more files of LISP code to be built into the image. The value of : in pu t - f il e s is a file specification or a list of file specifications. A file specification can be a symbol, a string, or a pathname. The files you specify are loaded into the image in the order you list them. Using the : in pu t - f il e s keyword to include user-written code in an image is like using the load function to load code into a running VAX LISP system, with two important differences: • Code included in a user-built system with the : i n p u t -f i l e s keyword becomes part of the image file; code loaded into a running system with the lo a d function must be in a separate file. • Portions of the code that you supply with the : in p u t -f il e s keyword are placed in read-only sections of the image; for example, parts of compiled function definitions are placed in read-only sections. In contrast, code loaded into a running system with the load function can never be placed in read-only sections. You can include some user-written development tools in the image to create a customized VAX LISP development environment. For example: (setf (default-directory) "diskl:[smith]") (define-lisp-system "graphics-lisp" :input-files ' ("editor-extensions" "disk2:[jones]graphics-editor" "menu-package")) The image ultimately produced by this call to d e f in e -l i s p - system contains three files of user-written code. 2-6 DEFINE-LISP-SYSTEM Function You can also use : in pu t - f il e s to create a customized execute-only system for distribution to other VAX CPUs. (See Section 2.5 for information on execute-only systems.) The d e f in e -l i s p - system function provides defaults for any file specification components that are not supplied in the argument. The file type defaults to .FAS or to .LSP. If two files differ only in their file types, : in p u t -f il e s uses the most recently created file. In this respect, : in pu t - f il e s behaves just like the load function. Files specified with the : in pu t - f il e s function can contain calls to the load function. Thus, one file specified with : in p u t -f il e s can actually bring many files into the image; this is a convenient alternative to entering a long list of files with : in pu t - f i l e s . If you use load in this way, the code included in the system is still placed in read-only space whenever possible. In general, files specified with : in pu t - f il e s can contain any VAX LISP code. However, you should observe the following restrictions and guidelines: • While they load, the files must not create a static alien structure that contains pointer fields. (However, the files can contain code that creates such structures after the image starts.) • Any data structures with pointers to them, for example, an array that is the value of a symbol, become part of the image, even if they are not useful. Therefore, be sure that only useful data structures are still accessible when all your code has been executed. Data structures with no pointers to them will be garbage-collected before the image is built. • When the image starts, certain aspects of its state are lost, in the same way that a suspended system ’ s state is lost when it resumes. In particular, streams that were left open when the system was built are closed, and callout state may be lost. (See the description of the suspend function in the VAX LISP /VMS Object Reference Manual for more information.) • Callout initialization occurs each time the image is run, even if the input files caused callout initialization to occur before the system was built. As a result, the first use of CALL-OUT in the image causes a short delay while callout initialization takes place. 2.3.2 U sing the :MAIN, :INIT-FUNCTION, and :HERALD K eyw ord s In a system that is intended to be a delivery vehicle for a user-built application, you may want either to change the entry point and the welcome message or to perform some computation after the welcome message but before the read-eval-print loop starts. The value of the : i n i t - function keyword specifies the function that executes after the welcome message and before either the read-eval-print loop or the function specified by the value of the :MAiN keyword. If you omit the : i n i t function keyword or the value of : i n i t - function is n il , the value of the :MAIN keyword specifies the function that executes when the image starts. When the function specified by : i n i t -function returns, either the read-evalprint loop or the function specified by the value of the :MAIN keyword executes. When the function specified by the value of the :main keyword returns, the image terminates. Therefore, the functions you specify with the : i n i t - function and : main keywords control the operation of the system. DEFINE-LISP-SYSTEM Function 2-7 :i n i t -f u n c t i o n or :MAIN must perform system initialization when they start, and :MAIN must perform any necessary cleanup before it exits. The function specified by the value of the : i n i t -f u n c t i o n keyword will not run if the /COMPILE command line qualifier is present and the compiler has not been excluded. (See Section 3.2.2.3 for further information.) If you omit the :MAIN keyword, or if you specify a value of n i l with the :MAIN keyword, the VAX LISP read-eval-print loop executes and controls the operation of the system. The values of the :Ma i n and : i n i t -f u n c t i o n keywords can be symbols or strings. A string is interpreted as the name of a symbol that names the function. Specify only a single symbol. The symbol must exist in the system that is being built, but it need not be defined in the system in which you are using the DEFINE-LISP-SYSTEM function. To specify a function in a package that does not exist in the VAX LISP system from which you are calling d e f i n e -l i s p -s y s t e m , use a string argument to : i n i t f u n c t i o n or :MAiN. However, the package must exist in the system that results from the d e f i n e -l i s p -s y s t e m call. For example: (define-lisp-system "expert" :input-files ' ("expert-system" "[jones]expert-rules") :main "expert-tools:expert-command-loop") The package e x p e r t -t o o l s need not exist when this call to d e f i n e -l i s p -s y s t e m is made, but the files specified with the : i n p u t -f i l e s keyword must create the package e x p e r t -t o o l s and define the e x p e r t -c o m m a n d -l o o p function in that package, so that e x p e r t -t o o l s :e x p e r t -c o m m a n d -l o o p exists in the new system. The default package for a function name you specify with the : i n i t -f u n c t i o n or :m a i n keyword depends on whether you use the symbol or string form of the argument. If you use the symbol form, the default package is the current package when the symbol is read. If you use the string form, the default package is always the u s e r package. If you use the :Ma i n keyword to specify a function, that function processes all the command line qualifiers. If you define a DCL command to invoke the system after having specified a function with the :Ma i n keyword, you have to write LISP code to process them. (See Section 3.2.2.3 for more information.) The value of the :h e r a l d keyword controls whether the standard VAX LISP welcome message, a user-supplied message, or no message is printed when the image starts. The default value of the symbol t requests the standard message: Welcome to VAX LISP, Vx.x When the value of :h e r a l d is a string, that string prints as the welcome message. A value of n i l suppresses this message. The following example demonstrates the use of the :m a i n and :h e r a l d keywords: (define-lisp-system "expert" :input-files '("expert-system" " [jones]expert-rules") iherald nil :main 'expert-command-loop) The image eventually produced by this call includes code from two files. When this image starts, it does not print the standard VAX LISP welcome message, and the function it calls is e x p e r t -c o m m a n d -l o o p .When the value of the e x p e r t c o m m a n d -l o o p function returns, the image terminates. 2-8 DEFINE-LISP-SYSTEM Function 2.4 Excluding Digital-Supplied Code You can use the : exclude keyword to prevent certain parts of standard VAX LISP from becoming part of your image. When you exclude code from the image, the image takes less space on disk and has smaller memory and run-time requirements. The value of the :exclude keyword is a keyword or list of keywords. Each keyword specifies a part of VAX LISP to exclude from your image. Table 2-1 fists the values for the keyword :exclude . With each value, the table lists the component(s) of Digital-supplied code that are excluded from the image when that value is specified and the approximate amount of disk space saved. Some components of VAX LISP are automatically excluded from systems defined with :r e q u ir e s -l ic e n s e n il . These components are noted in Table 2-1. (See Section 2.5 for more information.) Table 2-1: Values for the Keyword :EXCLUDE Value Approx. Savin gs in B lock s :ALIEN 128 The resulting image loses the ability to define new alien data structures. :BITBLT 128 The BITBLT function, which allows you to alter bitmaps. : CALLOUT 6912 The Call-Out facility, which lets you call routines written in other languages. Excluding the Call-Out facility precludes the built system from using the DECwindows interface and also excludes: C om p o n en t E x clu d e d from th e Im age : CLX :DWT :DECW-DEVELOPMENT-ENVIRONMENT : CLX 4224 A package of LISP routines that give you access to the capabilities of the X Window System without having to call out to external routines or to define non-LISP data structures. The resulting image can still have a programming environment including the Editor and the DECtoolkit (DWT). : COMPILE-FILE varies The VAX LISP COMPILE-FILE function, which is automatically excluded by : REQUIRES-LICENSE NIL. (See Section 2.5.2.) : COMPILER 2430 The VAX LISP Compiler. This precludes using the VAX LISP functions COMPILE and COMPILEFILE. (continued on next page) DEFINE-LISP-SYSTEM Function 2-9 Table 2-1 (Cont.): Values for the Keyword :EXCLUDE Value Approx. Savin gs in B lock s : DEBUGGER 1920 C om p o n e n t E x clu d ed from th e Im age The VAX LISP Debugger, and the STEP, TRACE, and INSPECT functions. The VAX LISP Debugger is automatically excluded by : REQUIRES-LICENSE NIL (see Section 2.5.2) and by any of the following values to the keyword :EXCLUDE: : EVAL :MACROS :REPLOOP You cannot use the VAX LISP Debugger as a DECwindows-based utility if you spec ify :DECWINDOWS, DECW-DEVELOPMENTENVIRONMENT, or : CALLOUT as a value for the : EXCLUDE keyword. (See Section 2.5.2.) : DECW-DEVELOPMENT-ENVIRONMENT 2304 The DECwindows-based functionality including the Inspector, Listener, and DECwindows Help, and the DECwindows interface to the Debugger and Editor. : DECW-DEVELOPMENT-ENVIRONMENT is automatically excluded by : DECWINDOWS. :DECWINDOWS 4224 The DECwindows interface and DECwindowsbased utilities—the Listener and the Inspector. Including : DECWINDOWS as a value for the keyword : EXCLUDE also excludes: : CLX : DWT :DECWINDOWS-DEVELOPMENT-ENVIRONMENT : DEFINE-LISP'-SYSTEM 128 The DEFINE-LISP-SYSTEM function. The resulting image cannot build another LISP system. The DEFINE-LISP-SYSTEM function is automatically excluded by : REQUIRES-LICENSE NIL. (See Section 2.5.2.) :DEFMACRO 128 The DEFMACRO macro. : DWT 2560 The DECtoolkit. The resulting image cannot build any DECwindows applications. :EDITOR 2302 The VAX LISP Editor. This precludes using the ED function or any functionality in the EDITOR package. The VAX LISP Editor is automatically excluded by : REQUIRES-LICENSE NIL (See Section 2.5.2.) (continued on n ext page) 2-10 DEFINE-LISP-SYSTEM Function Table 2-1 (Cont.): Values for the Keyword :EXCLUDE Value Approx. Sav in gs in B lock s C om p o n e n t E x clu d e d from th e Im age : EVAL 6784 T h e e v a lu a t o r . I n c l u d i n g :EV AL a s a v a l u e t o t h e k e y w o r d : EXCLUDE p r e c l u d e s t h e r e s u l t i n g im a g e fr o m u s in g t h e fo llo w in g ite m s: D E C w in d o w s in t e r fa c e R e a d - e v a l- p r in t l o o p C o m p ile r E d it o r D e b u g g i n g u t il i t i e s — : MACROS 4224 & M ore D ebu gger — S tep p e r — T racer — In sp ector M a c r o e x p a n d e r fu n c t io n s . T h e s e f u n c t i o n s a r e c r e a t e d b y DEFMACRO a n d u s e d w h e n a m a c r o is in v o k e d fr o m in t e r p r e t e d c o d e a n d w h e n t h e m a c r o i s c o m p il e d . S i n c e m a c r o i n v o c a t i o n s i n c o m p i l e d c o d e a r e f u l ly e x p a n d e d , a s y s t e m c o n t a in in g o n ly c o m p ile d c o d e n e e d s no m acroexp an ders. : ORPHAN-SYMBOLS V a r ie s VAX L I S P - c r e a t e d s y m b o l s t h a t a r e n e v e r r e fe r e n ce d . ( T h ese s y m b o ls e x is t a s a r e s u lt o f b u ild in g th e s y s t e m o r e x c lu d in g p a r ts o f VAX L IS P , b u t t h e y h a v e n o f u r t h e r u se.) U s e r c r e a t e d s y m b o l s a r e n o t a ffe c te d . T h e r e s u l t i n g i m a g e i s i d e n t i c a l i n f u n c t i o n a l it y t o o n e t h a t d o e s n o t e x c l u d e : ORPHAN-SYMBOLS, b u t t a k e s u p l e s s s p a c e . H o w e v e r , i t t a k e s l o n g e r t o b u ild . : RANDOM 128 R a n d o m n u m b e r gen era tors. : REPLOOP 1024 T h e VAX L I S P r e a d - e v a l- p r in t lo o p . If you e x c l u d e t h e r e a d - e v a l- p r in t lo o p , y o u m u s t u s e t h e :M AIN k e y w o r d t o s p e c i f y a f u n c t i o n t o e x e c u t e w h e n t h e i m a g e s ta r ts . T h e r e a d - e v a lp r i n t l o o p i s e x c l u d e d b y :R E Q U IR E S - L IC E N S E N IL . ( S e e S e c t i o n 2.5.2.) : SO RT 128 T h e SO R T a n d S T A B L E -S O R T fu n c t io n s . : SUSPEND 128 T h e SUSPEND fu n c t io n . T h e SUSPEND f u n c t i o n i s e x c l u d e d b y :R E Q U IR E S - L IC E N S E N IL . ( S e e S e c t i o n 2.5.2.) (continued on next page) DEFINE-LISP-SYSTEM Function 2-11 Table 2-1 (Cont.): Values for the Keyword :EXCLUDE Value Approx. Savin gs in B lock s C o m p o n e n t E x clu d e d fro m th e Im a ge : TRANSCENDENTAL 128 The transcendental math functions: EXP LOG SQRT CIS SIN ASIN SINH ASINH COS ACOS COSH ACOSH TAN ATAN TANH ATANH (Space savings may be greater in future re leases.) : UIS 1152 The VAX LISP UIS graphics functionality. This precludes using any functionality in the UIS package, but not in the CLX graphics interface. :VMS-DEBUG 270 The VMS-DEBUG function. (See the VAX L IS P /V M S System A ccess G u ide for a description of the VMS-DEBUG function.) The VMS-DEBUG function is excluded by :REQUIRES-LICENSE NIL. (See Section 2.5.2.) :WSSTREAM 640 The VAX LISP window stream facility. (See Chapter 4 of VAX L IS P Im plem en tation a n d E xten sion s to C om m on LISP.) 2.5 Making an Execute-Only System Since the System-Building Utility can create a complete VAX LISP programming environment, the distribution of some user-built systems is restricted. The basic principle is: • If a user-built system can be used for creating new VAX LISP programs, its use on another CPU requires a valid VAX LISP software license. Such a system is called a development system in this manual. • If a user-built system is not useful as a VAX LISP programming environment, it may be transferred to another CPU without a VAX LISP software license. Such a system is called an execute-only system in this manual. The value of the keyword r e q u ir e s - l ic e n s e determines whether a user-built system is a development system and whether the user-built system can be transferred to a CPU without a VAX LISP software license. 2.5.1 Development System s If the value of the keyword :r e q u ir e s - l ic e n s e is T (the default), you may not use a user-built system without a valid VAX LISP software license. This requirement holds no matter which components of VAX LISP you have excluded with the keyword :exclude . 2-12 DEFINE-LISP-SYSTEM Function An example of a development system is the user-built expert system created by the following call: (define-lisp-system "expert" :input-files '("expert-system" "[jones]expert-rules") iherald nil :main 'expert-command-loop :exclude ' (:editor :uis)) The file EXPERT.EXE that ultimately results from this form is created with the value t for :r e q u ir e s -l ic e n s e . EXPERT.EXE may not legally be used on a CPU that does not have a valid VAX LISP software license. 2.5.2 Execute-Only System s To make the above user-built system execute-only, you would write the following: (define-lisp-system "expert" :input-files '("expert-system" "[jones]expert-rules") rherald nil :main 'expert—command-loop :exclude '(:editor :uis) :requires-license nil) Because the value of the keyword :r e q u ir e s -l ic e n s e is n il , this system may be freely distributed. If the value of :r e q u ir es - l ic e n s e is n il , the user-built system will not contain the following components of Digital-provided code. The components correspond to the :exclude keyword in parentheses, when such a keyword exists: • The VAX LISP debugging facilities (: debugger and :VMS-debug) • The VAX LISP Editor (: ed I tor ) • The VAX LISP System-Building Utility (: d e f in e - l i s p - system ) • The VAX LISP function com pile - f il e (: co m pil e - f i l e ) • The VAX LISP read-eval-print loop :rep loop • The VAX LISP function suspend (: suspend ) • The VAX LISP fu n ctions t im e , d e s c r ib e , in s p e c t , d isa s se m b l e , d r ib b l e , TRACE, STEP, ROOM, APROPOS, and APROPOS-LIST If you have not already excluded these components with the keyword :exclude , d e f in e - l i s p - system with :r e q u ir e s - l ic e n s e n il will exclude them. While d e f in e - l i s p - system is executing, it displays warnings that identify the VAX LISP components being excluded because :r e q u ir e s - l ic e n s e is n il . NOTE Tb create a user-built execute-only system , you must specify r e q u i r e s l ic e n s e NIL no m a tter w hich sy stem com pon en ts you have excluded w ith :EXCLUDE. DEFINE-LISP-SYSTEM Function 2-13 2.6 Specifying Memory Requirements The :memory keyword specifies the default size of a user-built system ’ s dynamic memory; it is equivalent to the LISP command’ s /MEMORY qualifier. The value of the :memory keyword is the total size of LISP’ s dynamic memory, in 512-byte pages. The default size is 5000 pages; the minimum size is 2000 pages. You can use the room function to find out how much dynamic memory your system is using at any time. VAX LISP’ s dynamic memory space is divided into sections known as areas. Use the room function to print information about dynamic space. By default, a garbage collection occurs whenever 50% or more of the dynamic memory has been consumed. You can change this ratio by using se t f with the DYNAMIC-SPACE-RATIO function. To determine a value for the :memory keyword, build a trial system with the default size; then, start the system and use the room function to see how much dynamic memory the system consumes. As you use the system, use room from time to time to see how quickly dynamic memory is consumed. Also note the frequency of garbage collection. Frequent or nearly continuous garbage collection activity indicates insufficient memory and a larger value for the :memory keyword is in order. When you set a default value for dynamic memory, remember the following points: • A smaller dynamic memory size leads to faster but more frequent garbage collections. • A larger dynamic memory size leads to slower but less frequent garbage collections. A large dynamic memory also requires more virtual memory and may cause more paging. The default dynamic memory size you specify can be overridden when your image is invoked, if you define a DCL command with the /MEMORY qualifier to start the image. (See Section 3.2.2 for more information.) The :b u il d -memory keyword specifies the size, in 512-byte pages, of the amount of memory used during the build. A normal build requires 50,000 pages. If you specify fewer pages, the build will take longer. The :control - sta ck - s i z e and :b in d in g - stack - s i z e keywords specify the size, in 512-byte pages, of the im age’ s control and binding stacks. The default for : control - stack - s i z e is 185 pages; the minimum size is 32 pages. The default for : bind ING-stack - s i ze is 62 pages; the minimum size is 16 pages. The sizes required for the control and binding stacks are a rough function of the complexity of your system. Highly recursive systems require larger control stacks. One way to determine whether you should increase stack sizes is to build a test system with the default stack sizes. If the stacks overflow in normal operation, increase the sizes. (Control stack overflows are treated as errors; binding stack overflows are handled automatically, and program execution continues.) 2-14 DEFINE-LISP-SYSTEM Function Chapter 3 Working with User-Built Systems A user-built system can be treated like any other VMS executable image. This chapter describes: • Installing the image to allow sharing of read-only code • Invoking the image 3.1 Installing the Image If you intend the user-built system to be run concurrently by several processes, it is worthwhile to install the image as shareable. Installing an image improves performance and reduces the requirements for physical memory in the following ways: • An installed image is permanently “ open,”which means that directory information on the image file remains permanently resident in memory. An open image does not require the usual directory search to locate the file. • When an image is installed as shareable, only one copy of its read-only sections need be in physical memory. These global sections can be accessed by more than one user at a time. The VMS Install Utility installs an executable image, allowing you to make the image open as well as shareable. This utility is described in the VAX/VMS documentation set: VMS Install Utility Manual and Guide to Setting Up a VMS System. To install the image: 1. Invoke the VMS Install Utility. 2. Execute the CREATE command with the /SHARED qualifier. (/SHARED also installs the image as permanently open.) 3. Exit the VMS Install Utility. For example, to make the user-built system MY-LISREXE shareable, you would do the following: 1. Invoke the VMS Install Utility. If you are adding a new image to an established VMS system, it is probably most convenient to invoke the utility in interactive mode. To do so, type: $ INSTALL := $SYS$SYSTEM:INSTALL $ INSTALL/COMMANDMODE Working with User-Built System s 3-1 2. At the VMS Install Utility prompt, execute the CREATE command with the /SHARED qualifier. The parameter is the name of the executable file. If you omit the device and directory, they default to those indicated by the logical name SYS$SYSTEM. The default file type is .EXE. INSTALL> CREATE/SRARED D ISK I: [SMITH.BUILD]MY-LISP This step establishes global sections of the specified executable file ’ s read only contents and makes it permanently open. You need not specify the /OPEN qualifier, since an image installed as shareable is also installed as permanently open. 3. If you later want to delete the global sections associated with the image, use the VMS Install U tility’ s DELETE command. INSTALL> DELETE D ISK I:[ SMITH.BUILD] MY-LISP This command removes any global sections created for the image MYLISP. EXE. The image file itself is not affected by this operation. 4. Type either of the following commands to exit the VMS Install Utility: INSTALL> EXIT INSTALL> [ctrl/zj See the VMS documentation set for further information on the VMS Install Utility, especially for other qualifiers to the Install command CREATE. 3.2 Invoking the Image There are four ways to invoke a user-built system: • The DCL RUN command • A user-defined foreign command • A user-defined DCL command • The Digital-defined DCL LISP command If you use RUN or a foreign command, you cannot use LISP-specific command line entities; that is, you cannot use command qualifiers, parameters, or keywords processed by the LISP image. With a specially defined DCL command—either user-defined or Digital-defined—you can use LISP-specific command-line entities with certain restrictions. This section discusses these four methods of invoking a user-built system. For each method, the section identifies the restrictions, if any, on the use of LISP-specific command-line entities. 3.2.1 Using RUN or a Foreign Command You can invoke a user-built LISP system like any VMS executable image with either a RUN command or a user-defined foreign command. For example: $ RUN MY-LISP or $ $ 3-2 MYLISP := $DISK1:[SMITH.BUILD]MY-LISP MYLISP Working with User-Built System s See the VMS DCL Dictionary for more information on the RUN command and on the facility for defining foreign commands. When you use RUN or a foreign command to invoke a LISP image, the LISP image cannot call back to DCL to check for the presence of qualifiers or other command-line entities. For this reason, you cannot use any LISP-specific qualifiers, such as /MEMORY, with RUN or a foreign command. 3.2.2 Defining a DCL Command You can use the VMS Command Definition Utility (CDU) to create a new DCL command that invokes a user-built system. This command can be used with or without LISP-specific command-line entities. The CDU is described in the VMS Command Definition Utility Manual. This section assumes that you are generally familiar with DCL command definition and with writing code to retrieve command string information. The procedure for creating a DCL command is: 1. Write a command language definition (CLD) file that defines the command and its qualifiers, parameters, and keywords, if any. 2. Be sure that the image to be invoked by the command contains code that calls back to DCL to check for the presence of each such qualifier, parameter, or keyword, then responds appropriately. 3. Use the DCL command SET COMMAND to add your CLD file to the system command table or to an individual process command table. 4. Log out and log in again to make the command available. (This step is not necessary if you used SET COMMAND to add the CLD file to your own process command table.) The Digital-provided VAX LISP image contains code that checks for and processes the Digital-defined qualifiers to the LISP command. (The VAX LISP /VMS Program Development Guide lists and describes these qualifiers.) A user-built system contains all or part of the Digital-provided VAX LISP. Therefore, in defining a DCL command to invoke a LISP image, you face some restrictions when choosing qualifier names, and you may have to redefine some Digitaldefined qualifiers. In general terms, the restrictions are: • If your user-built system contains the Digital-provided code that checks for a given qualifier and you want to use that qualifier when invoking the system, your CLD file must define the qualifier exactly as it is defined in LISP$SYSTEM:LISP.CLD, the file that defines the DCL LISP command. If you do not want to use the qualifier, your CLD file need not define it. • If your user-built system does not contain the Digital-provided code that checks for a given qualifier, you can define that qualifier in any way you like. However, your image must include user-written code to check for the qualifier. (See Sections 3.2.2.2 and 3.2.2.3 to determine whether your image contains code that checks a given qualifier.) • Qualifiers with names that are not defined by Digital as qualifiers to the LISP command—and all other command-line entities—can be defined in your CLD file in any way you like. You must, however, include user-written code in your image to check for each such entity. Working with User-Built System s 3-3 To check for the presence of command-line entities, use the VAX LISP functions COMMAND-LINE-ENTITY-P and COMMAND-LINE-ENTITY-VALUE. These functions provide interfaces to the VMS utility routines CLI$PRESENT and CLI$GET_ VALUE, which retrieve information about the command string that invoked an image. For further information: • The VAX LISP /VMS System Access Guide describes the two VAX LISP functions. • The VMS Utility Routines Manual describes the two VMS routines. The remainder of this section outlines the specific procedures for writing a DCL command to invoke a LISP image. It also identifies the circumstances under which you are limited in defining command qualifier names. 3.2.2.1 Defining a Command Without Qualifiers As an example of defining a DCL command without qualifiers or other command-line entities, you might write the following code in a file called MYCOMMANDS.CLD. This code defines a DCL command named EXPERT, which in vokes the image EXPERT.EXE. The device and directory of this file are indicated by the logical name EXPERT$SYSTEM. DEFINE VERB EXPERT IMAGE "EXPERT$SYSTEM:EXPERT" Once the file MY-COMMANDS.CLD has been added to the appropriate command table, you can invoke EXPERT.EXE by typing EXPERT at the DCL prompt. Because the command EXPERT has no qualifiers, parameters, or keywords, the image EXPERT.EXE need not contain code that processes DCL command-line entities. 3.2.2.2 Defining the Qualifiers /MEMORY, /RESUME, and /CSTACK A user-built LISP image always contains the Digital-provided code that checks for and processes the /MEMORY, /RESUME, and /CSTACK qualifiers in the command that invoked the image. You cannot alter the action of these qualifiers. Therefore, if you w an t your DCL com m an d to take qu alifiers named /MEMORY, /RESUME, or /CSTACK, you must define them in your CLD file exactly as follows: QUALIFIER MEMORY, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) QUALIFIER RESUME, VALUE(TYPE=$INFILE,REQUIRED) QUALIFIER CSTACK, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) For example, a CLD file that defines the command EXPERT with the qualifiers /MEMORY, /RESUME, and /CSTACK would look like this: DEFINE VERB EXPERT IMAGE "EXPERT$SYSTEM:EXPERT" QUALIFIER MEMORY, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) QUALIFIER RESUME, VALUE(TYPE=$INFILE,REQUIRED) QUALIFIER CSTACK, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) Since these three qualifiers are processed by Digital-provided LISP code, they behave in exactly the same way with the command EXPERT as they do with the command LISP. That is, /MEMORY allows you to invoke EXPERT.EXE with a specified amount of dynamic memory, /RESUME allows you to resume a suspended system that was created from within EXPERT.EXE, and /CSTACK allows you to invoke EXPERT.EXE with a specified size for the default control stack. 3-4 Working with User-Built System s If you do not define these qualifiers in your CLD file, you cannot use them with the command EXPERT. You can, of course, continue to use them with the LISP command. 3.2.2.3 Defining Other Digital-Defined Qualifiers In addition to /MEMORY, /RESUME, and /CSTACK, the LISP command takes 10 qualifiers; they are processed by the VAX LISP function that is the default value of the d e f in e - l i s p - system keyword sMAIN or the value of the d e f in e -l i s p system keyword : i n i t - fu nction . That is, the default entry point in a user-built system processes the following compiler-related qualifiers: /COMPILE /LISTING /MACHINE_CODE /OPTIMIZE /OUTPUT_FILE /WARNINGS and the following general-purpose qualifiers: /ERROR_ACTION /INITIALIZE /INTERACTIVE /VERBOSE If you have not specified a value for i n i t - function or :MAIN in your call to d e f in e - l i s p - system and you want to use any of these qualifiers when you invoke the system, you must define the qualifiers and their parameters exactly as they are defined in LISP$SYSTEM:LISP.CLD. In addition, the VAX LISP Compiler must be present in your image for the entry point to process the compiler-related qualifiers. NOTE Except for the definitions of /MEMORY and /RESUME, the qualifier definitions in LISP$SYSTEM:LISP.CLD are not supported by Digital and may not be upward-compatible between versions. For example, the following CLD file defines the command EXPERT with the qualifier /INITIALIZE: DEFINE verb expert IMAGE "EXPERT$SYSTEM:EXPERT" QUALIFIER INITIALIZE, VALUE(TYPE=$INFILE, REQUIRED,LIST) The qualifier /INITIALIZE is defined as it is in LISP$SYSTEM:LISP.CLD. If EXPERT.EXE contains the default entry point, this qualifier behaves in the same way with the command EXPERT as it does with the command LISP. If you have specified a value for :Ma in in your call to d e f in e -l i s p - system , the Digital-provided code for processing the qualifiers other than /MEMORY, /RESUME, and /CSTACK is inaccessible in your image. You can then define any of these qualifier names in any way you like. You must, however, include userwritten code in your image to check for and process each such qualifier that you define. 3.2.2.4 Defining Other Command-Line Entities Apart from the Digital-defined qualifiers to LISP, you can define any command line entity—qualifier, parameter, or keyword—in any way you like. For defining such entities, the values of : i n i t -function and i MAIN are irrelevant. However, your image must always include user-written code for processing all such entities Working with User-Built System s 3-5 3.2.2.5 Summary of Restrictions on Command Definition The restrictions on defining command-line entities for a user-defined DCL com mand to invoke a LISP image are: • The qualifiers /MEMORY, /RESUME, and /CSTACK are always processed by Digital-provided code. To use these qualifiers, you must define them as they are defined in LISP$SYSTEM:LISP.CLD. • The VAX LISP default entry-point function processes the remaining qualifiers to the command LISP. If your image includes the default entry point and you want to use these qualifiers, you must define them as they are defined in LISP$SYSTEM:LISP.CLD. Note that several of these qualifiers require the presence of the VAX LISP Compiler in the image. For example, the following CLD file defines the command EXPERT for invok ing the image EXPERT$SYSTEM:EXPERT.EXE. (Assume that EXPERT.EXE contains the default entry point.) DEFINE VERB EXPERT IMAGE "EXPERT$SYSTEM:EXPERT" PARAMETER PI, PROMPT="FILE(S)", VALUE(TYPE=$INFILE,LIST) QUALIFIER MEMORY, NONNEGATABLE, VALUE(TYPE=$NUMBER,REQUIRED) QUALIFIER INITIALIZE, VALUE(TYPE=$INFILE,REQUIRED,LIST) QUALIFIER QUICKJTRAVERSE, DEFAULT The command EXPERT takes one parameter and three qualifiers. • The parameter PI is to be processed by code you supply. You can define this parameter in any way you like. In this example, the command EXPERT prompts the user for one or more input file names. • The qualifier /MEMORY is to be processed by Digital-provided code. You must define the qualifier as shown. • Because the entry point to EXPERT.EXE is the default, the qualifier /INITIALIZE is to be processed by Digital-provided code. You must define the qualifier as shown. If the entry point is a function you supply, it must contain code to process /INITIALIZE. In this case, the qualifier could be defined in any way you like. • The qualifier /QUICK_TRAVERSE is to be processed by code you supply. You can define this qualifier in any way you like. 3.2.3 Using the Digital-Defined Command LISP With certain restrictions, you can use the Digital-defined LISP command—along with any of its qualifiers—to invoke a user-built system. The major restriction on using the LISP command is that your executable file must be named LISP.EXE and must be in a directory pointed to by the logical name LISP$SYSTEM. LISP.EXE is the name of the Digital-supplied VAX LISP executable image, and the LISP command looks in LISP$SYSTEM for LISP.EXE. NOTE If you name your image file the same as the Digital-provided image file, take care that you do not accidentally delete the Digital-provided image file. 3-6 Working with User-Built System s For example, if you use VAX LISP on a terminal instead of a workstation, and you want to dispense with the graphics functionality and the DECwindows interface in your development environment, you could write: (define-lisp-system "diskl:[smith.buildjlisp.exe" :exclude ' (:uis idecwindows)) The executable image that eventually results from this form contains all the functionality of the Digital-supplied VAX LISP except the graphics functionality and the DECwindows interface. Since the image has the same name as the Digital-supplied VAX LISP executable image, you can use the LISP command— with any of its qualifiers—to invoke the image you create. Before you can use the LISP command to invoke your image, you must redefine LISP$SYSTEM to point to DISK1:[SMITH.BUILD] so that the LISP command can locate the image. However, LISP$SYSTEM also contains other Digitalprovided files (such as the documentation string text library, LISPDOC.TLB) that VAX LISP needs in order to run. To avoid copying these files into DISK1:[SMITH.BUILD], you can define the logical name LISP$SYSTEM to be a search list: $ SHOW LOGICAL LISP$SYSTEM "LISP$SYSTEM" = "SYS$SYSROOT: [VAXLISP]" (LNM$ SYS TEMTABLE) $ DEFINE LISP$SYSTEM DISKI:[SMITH.BUILD],SYS$SYSROOT: [VAXLISP] The LISP command now starts the image LISP.EXE in DISK1:[SMITH.BUILD], LISP looks in SYS$SYSROOT: [VAXLISP] for files it needs but cannot find in DISK1:[SMITH.BUILD], Restrictions on using the LISP command qualifiers are listed below under the set of LISP qualifiers to which they apply. • The qualifiers /MEMORY, /RESUME, and /CSTACK and their respective parameters: No further restrictions. Note that you need not create your own CLD file to use these two qualifiers with the Digital-defined LISP command. • The qualifiers /INITIALIZE, /VERBOSE, /INTERACTIVE, and /ERROR. ACTION and their respective parameters: RESTRICTION: Your image must include either the default entry point or user-written code that processes these qualifiers. • The qualifiers /COMPILE, /OPTIMIZE, /LISTING, /MACHINE.CODE, /OUTPUT.FILE, and /WARNINGS and their respective parameters: RESTRICTIONS: Your image must include either the default entry point or user-written code that processes these qualifiers. In either case, you must not exclude the VAX LISP Compiler from your image by supplying the : comp il e r keyword with : exclude . Working with User-Built System s 3-7 Index A : ALIE N , value for keyword : EXCLUDE, 2-9 Alien structures, static in user-built system, 2-7 Applications license requirements, 2-12 B Binding stack specifying size, 2-14 : B IN D IN G -S TA C K -S IZ E keyword D EFIN E -LIS P -S Y S TE M function default value, 2-14 :B IT B L T , value for keyword :EXCLUDE, 2-9 c ______________________________ Callout initialization, 2-7 state lost in user-built system, 2-7 : CALLOUT, value for keyword : EXCLUDE, 2-9 CLD file See Command language definition file CLI$GET_VALUE routine, 3 ^ t CLI$PRESENT routine, 3-4 : CLX value for keyword : EXCLUDE, 2-9 Command Definition Utility, 3-3 Command language definition file, 3—3 to 3—6 Command line retrieving qualifiers from, 3-4 Command procedure created by D EFIN E-LISP-SYSTEM , 1-3, 2-1 default name, 2-4 naming, 2-5 Command tables, 3-3 Compiled file created by D EFIN E-LISP-SYSTEM , 2-1 default name, 2-4 naming, 2-5 : CO M P ILE -FILE , value for keyword : EXCLUDE, 2-9 /COMPILE qualifier to DCL LISP command, 3-5 : COMPILER value for keyword : EXCLUDE, 2-9 Control stack specifying, when invoking user-built system, 3-4 specifying size, 2-14 : CONTROL-STACK-SIZE, keyword definition, 2—3 : CONTROL-STACK-SIZE keyword D EFIN E -LIS P -S Y STE M function default value, 2-14 CREATE command install utility, 3-2 /CSTACK qualifier using, when invoking user-built system, 3-4 D________________________ DCL command defining, to invoke user-built system, 3-3 without qualifiers, 3-4 Debugger excluded by : REQUIRES-LICENSE N IL , 2-13 : DEBUGGER, value for keyword : EXCLUDE, 2-10 :DECW-DEVELOPMENT-ENVIRONMENT, value for keyword : EXCLUDE, 2-10 :DECWINDOWS, value for keyword : EXCLUDE, 2-10 : DEFIN E-LISP-SYSTEM , value for keyword : EXCLUDE, 2-10 D EFIN E -LIS P -S Y STE M function, 2-1 to 2-14 arguments, 2-2 to 2-3 format, 2-2 in system-building process, 1-3 keywords, 2-2 to 2-3 : DEFMACRO, value for keyword : EXCLUDE, 2-10 DELETE command, install utility, 3-2 Development systems creating, 2-12 defined, 2-12 Disk space on disk specified by : B U IL D -F IL E -NAMES, 2-6 required by system-building procedure, 1—4 saving, with : EXCLUDE, 2-9 : DWT, value for keyword : EXCLUDE, 2-10 Dynamic memory default size, 2-14 determining need, 2-14 effect on garbage collection, 2-14 overriding default, 2-14 specifying, when invoking user-built system, 3—4 specifying size, 2-14 E_________________________________ : EDITOR, value for keyword : EXCLUDE, 2-10 Entry point for user-built system, 2-7 lndex-1 Entry point (cont'd.) processing Digital-defined qualifiers, 3-5 /ERROR_ACTION qualifier to DCL LISP command, 3-5 : EVAL, value for keyword :EXCLUDE, 2-11 ; EXCLUDE keyword value table, 2-9 Executable image LISP command qualifiers to when invoking user-built system, 3-3 using, to invoke user-built system, 3-6 /LISTING qualifier to DCL LISP command, 3-5 LOAD function used with : IN P U T -F IL E S , 2-7 created by D EFIN E-LISP-SYSTEM , see User-built systems Execute-only systems creating, 2-13 defined, 2-12 M________________________ G________________________ /MACHINE_CODE qualifier to DCL LISP command, 3-5 : MACROS, value for keyword : EXCLUDE, 2-11 :M AIN keyword D E FIN E -LIS P -S Y STE M function and qualifier processing, 3-5 default package, 2-8 default value, 2-8 value of, 2-8 Memory dynamic, see Dynamic memory required by system-building procedure, 1-4 saving, with : EXCLUDE, 2-9 : MEMORY keyword, 2-3 D E F IN E -LIS P -S Y STE M function default value, 2-14 /MEMORY qualifier and : MEMORY, 2-14 using, when invoking user-built system, 3-4 Multiuser access, 3-1 Garbage collection and dynamic memory size, 2-14 Global sections, 3-1 o _______________________________ F________________________ Files executable image, see User-built systems command language definition, 3-3 created by D EFIN E-LISP-SYSTEM , 2-1 naming, 2-4 LISP code incorporating into system, 2-6 used by System-Building Utility, 1-4 Foreign command invoking user-built system, 3-2 Function, specifying initial, 2-7 H________________________ : HERALD keyword D E FIN E -LIS P -S Y S TE M function, 2-8 I_____________________________________ image file installing, 3-1 im a ge-n am e argument, 2-2, 2—4 : IN IT -F U N C T IO N keyword D EFIN E -LIS P -S Y S TE M function and qualifier processing, 3-5 default package, 2-8 value of, 2-8 /INITIALIZE qualifier to DCL LISP command, 3-5 : IN P U T -F IL E S keyword D EFIN E -LIS P -S Y S TE M function, 2-6 file specification defaults, 2-7 guidelines, 2-7 Install utility installing user-built system with, 3-1 to 3-2 /INTERACTIVE qualifier to DCL LISP command, 3-5 L________________ _ License needed by user-built systems, 2-12 LISP$BUILD-VAXLISP.CLD, 1-^1 LISP$BUILD-VAXLISP.EXE, 1-4 LISP$FASLIB.TLB, 1-4 LISP$OBJLIB.OLB, 1-4 lndex-2 /OPTIMIZE qualifier to DCL LISP command, 3-5 ORPHAN-SYMBOLS value for keyword : EXCLUDE, 2-11 /OUTPUT_FILE qualifier to DCL LISP command, 3-5 Overflow control and binding stack, 2-14 P________________________ Packages, specifying, 2-8 Q ____________________________________ Qualifiers LISP command /MEMORY, /RESUME, and /CSTACK, 3-4 restrictions on using, 3-3 using, when invoking user-built system, 3-3 retrieving from command line, 3-4 R________________________ : RANDOM, the value for keyword : EXCLUDE, 2-11 Read-eval-print loop default entry point, 2-8 excluded by : REQUIRES-LICENSE N IL , 2-13 Read-only sections code placed into, 2-6 making shareable, 3-1 : REPLOOP excluded by : REQUIRES-LICENSE N IL , 2-13 value for keyword : EXCLUDE, 2-11 : REQUIRES-LICENSE keyword, 2-2 : REQUIRES-LICENSE keyword D E F IN E -L IS P -SYSTEM function default value, 2-12 : REQUIRES-LICENSE keyword D E F IN E -L IS P SYSTEM function components excluded by, 2-13 /RESUME qualifier using, when invoking user-built system, 3-4 RUN command invoking user-built system, 3-2 s__________________ SET COMMAND command, 3-3 Software license needed by user-built systems, 2-12 : SORT, value for keyword : EXCLUDE, 2-11 Stacks, specifying sizes, 2-14 Static alien structures in user-built system, 2-7 Streams closed in user-built system, 2-7 : SUSPEND, value for keyword : EXCLUDE, 2-11 Suspended system compared with user-built system, 1-2 System-building utility excluded by : REQUIRES-LICENSE N IL , 2-13 file produced by, 1-1 files used by, 1-4 incorporating user-written code, 2-6 overview, 1-1 to 1-4 procedure for using, 1-3 requirements for using, 1-4 Systems user-built, see user-built systems User-built systems (cont’d.) license requirements, 2-12 multiuser access to, 3-1 naming, 2-4 specifying memory, 2-14 User-written code, including, 2-6 V____________________________________ /VERBOSE qualifier to DCL LISP command, 3-5 :VMS-DEBUG, value for keyword :EXCLUDE, 2-12 w__________________ /WARNINGS qualifier to DCL LISP command, 3-5 Welcome message, suppressing, 2-8 :WSSTREAM, value for keyword rEXCLUDE, 2-12 T________________________ : TRANSCENDENTAL, value for keyword : EXCLUDE, 2 -1 2 u_______________________________ :U IS , value for keyword :EXCLUDE, 2-12 User-built systems compared with suspended system, 1-2 customizing, 2-6 development systems creating, 2-12 defined, 2-12 distributing, 2-12 entry point default, 2-8 specifying, 2-7 excluding Digital code from, 2-9 execute-only systems creating, 2-13 defined, 2-12 features of, 1-1 incorporating user-written code, 2-6 installing image file, 3-1 invoking, 3-2 defining DCL command, 3-3 foreign command, 3-2 LISP command, 3-6 RUN command, 3-2 using qualifiers, 3-3 lndex-3 HOW TO ORDER ADDITIONAL DOCUMENTATION F rom Call 603-884-6660 Alaska, Hawaii, or New Hampshire Rest of U.S.A. and Puerto Rico1 Write Digital Equipment Corporation P.O. Box CS2008 Nashua NH 03061 800-DIGITAL 1Prepaid orders from Puerto Rico, call Digital’s local subsidiary (809-754-7575) Canada 800-267-6219 (for software documentation) Digital Equipment of Canada Ltd. 100 Herzberg Road Kanata, Ontario, Canada K2K 2A6 Attn: Direct Order Desk 613-592-5111 (for hardware documentation) Internal orders (for software documentation) — Software Supply Business (SSB) Digital Equipment Corporation Westminster MA 01473 Internal orders (for hardware documentation) DTN: 234-4323 508-351-4323 Publishing & Circulation Services (P&CS) NR03-1AV3 Digital Equipment Corporation Northboro MA 01532 Reader’s Comments VAX LISP/VMS System -Building Guide AA-KM37B-TE Your comments and suggestions will help us improve the quality of our future documentation. Please note that this form is for comments on documentation only. I ra te th is m an ual’ s: Accuracy (product works as described) Completeness (enough information) Clarity (easy to understand) Organization (structure of subject matter) Figures (useful) Examples (useful) Index (ability to find topic) Page layout (easy to find information) Excellent □ □ □ □ □ □ □ □ Good □ □ □ □ □ □ □ □ Fair □ □ □ □ □ □ □ □ What I like best about this manual: What I like least about this manual: I found the following errors in this manual: Page Description My additional comments or suggestions for improving this manual: Please indicate the type of user/reader that you most nearly represent: □Administrative Support □Computer Operator □Educator/Trainer □Programmer/Analyst □Sales □Scientist/Engineer □Software Support □System Manager □Other (please specify) Name/Title -------------------------------------------------- Dept. _____ Company ----------------------------------------------------------Date * Mailing Address ___________________________________________________________ _____________________________________________________________ Phone _____ 10/87 Poor □ □ □ □ □ □ □ □ — — mmm Do Not Tear — Fold Here and Tape NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES TM BUSINESS REPLY MAIL FIRST CLASS PERMIT NO.33 M A Y N A R D MASS. POSTAGE WILL BE PAID BY ADDRESSEE DIGITAL EQUIPMENT CORPORATION CORPORATE USER PUBLICATIONS PKO3-1/30D 129 PARKER STREET MAYNARD, MA 01754-2198 Do Not Tear — Fold Here Cut Along Dotted Line — —
Home
Privacy and Data
Site structure and layout ©2025 Majenko Technologies