ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

Allegro CL documentation is regularly updated between releases. This page on the Franz Inc. website (https://franz.com/) has links to the latest version of the Allegro CL documentation.

### Index

The main page for the index for the Allegro CL documentation is index-top.html. Every documentation HTML page has a link to the index on the Navigation Bar at the top and bottom. index-top.html points to index pages for each letter (some letters are combined). There are pages with Common Graphics functionality and pages without Common Graphics functionality.

### Permuted Index

The main page for the permuted-index for the Allegro CL documentation is permuted-index.html. Every documentation HTML page has a link to the permuted index on the Navigation Bar at the top and bottom.
permuted-index.html points to index pages for each letter (some letters are combined).

The permuted index is generated from the link text of the index pages. Every word in such link text is indexed. For example, the link to the function build-lisp-image appears under B (for build), L (for lisp) and I (for image). This makes the permuted index a very useful tool for finding information on any topic where you know keywords but do not know which specifically appears in the index or the first letter of the names of the relevant symbols.

The permuted index has entries for each section heading of the essay documentation. Since they are indexed by each word in the heading, finding a section of interest using a keyword in the heading is relatively easy with the permuted index. (The headings are not in the regular index because they mostly start with "a" or "about" or "the" which are not words actually associated with the topic covered.)

### Table of Contents

The table of contents of most of the essay documents is in contents.html. Every documentation HTML page has a link to contents.html (labeled ToC) on the Navigation Bars at the top and bottom. The following documents are not included in contents.html: the AllegroServe documentation, debugger-api.html, phtml.html, pxml.html, using-webactions.html, and webactions.html.

## 1.0 Documentation introduction

The documentation for Allegro CL is online at https://franz.com/support/documentation/current/.

The online documentation is arranged into an overview section and a reference section.

Installation information can be found in installation.html.

The release notes can be found in release-notes.html.

The User Guide for the Emacs-Lisp interface is in eli.html.

Every documentation page has a navigation bar at the top and bottom with links to the table of contents, contents.html; the documentation overview (this file); cgide.html, which contains, in its first section, the list of Common Graphics and IDE documentation; the Release Notes, release-notes.html; the Allegro CL FAQ; the index, index.html; and the permuted index, permuted-index.html. When the file referred to is open, the link is disabled and the background color is yellow instead of aqua (you may see different colors, of course).

### 1.1 Common Graphics and Integrated Development Environment Documentation

The documentation for Common Graphics and the Integrated Development Environment is integrated with the general Allegro CL documentation. Start with cgide.html. The section About Common Graphics and IDE documentation in that document provides a map of CG and IDE documentation.

### 1.2 ANSI Common Lisp and MetaObject Protocol Documentation

The ANSI specification is reproduced in ANSI Common Lisp (the link is to the initial page). See also Allegro CL and the ANSI CL standard and Compliance with the ANSI specification in implementation.html.

Documentation for the MetaObject Protocol (MOP) is in mop/contents.html (the link is to the initial page). The files in the mop/ subdirectory are an HTML version of the description of the MetaObject Protocol in chapters 5 and 6 of The Art of MetaObject Protocol by G. Koczales, J. des Rivieres, and D. Brobrow. The HTML version was prepared by Howard Stearns and copyrighted by the Elwood Corporation, as described in mop/admin.html.

### 1.3 Some notation

- Allegro directory: Used two ways: (1) the directory in which Allegro CL is installed, and (2) the translation of the sys: logical host, which is the directory where files needed while Allegro CL is running are located. We use the same term for both because these are normally the same directory. (sys: in fact translates to the directory containing the Allegro CL executable, usually mlisp or mlisp.exe, usually located in the directory into which Allegro CL was installed.)
- Allegro executable or executable: The file which is invoked to run Allegro CL. This is a small file and is not usually created by users (but see main.html). The executable can be copied and/or renamed as desired, however. There are a number of executables provided, each with an associated image file. These include mlisp (modern, case-sensitive lower, supports international character sets), mlisp8 (modern, case-sensitive lower, does not support international character sets), alisp (ansi, case-insensitive upper, supports international character sets), alisp8 (ansi, case-insensitive upper, does not support international character sets). There are also SMP executables. The freee Express edition has fewer executables supplied than the supported version. On Windows, the executables have type .exe.
- Allegro image file or image: This file contains the bulk of Lisp data. It is typically large and has the extension dxl. The executable can only be run with an image file. Image files can be created by users (with, e.g., build-lisp-image and dumplisp.

## 2.0 The Overview section

### 2.1 Allegro CL documentation table of contents

The document contents.html is an outline of the Allegro CL documentation in table of contents format. The outline is too large to reasonably be included in this document.

### 2.2 Allegro CL documentation: list of overview HTML documents

Here is a list of the files that make up the base Allegro CL documentation:

- AllegroCache: an in-Lisp object database. The documentation for this is not included in the contents.html nor in index.html.
- AllegroGraph: an entity event knowledge graph, a separate product offered by us.
- AllegroServe: An in-Lisp web server.
- basic-lisp-techniques.pdf: an introduction to Lisp and Lisp programming written by David Cooper.
- building-images.html: describes the build-lisp-image functionality and describes how to make custom Lisp images.
- case.html: discusses the issues with case sensitivity in Allegro CL.
- cg-cgjs.html: this document describes how Common Graphics and the Integrated Development Environment (IDE) run in web browsers. Only the web browser version is supported on Linux and the Mac. On Windows, they run either in a web browser or as a Windows desktop app.
- cgide.html: the introductory document to the Common Graphics and the Integrated Development Environment (IDE) documentation. It contains a description of the documentation and the IDE interface (with links), and some essays on aspects of Common Graphics and the Integrated Development Environment.
- clim-ug.pdf: the CLIM User Guide. NOTE: CLIM support has been discontinued. A binary build is included, for supported platforms, as a convenience to our users. The source code for CLIM is available on github, for those who need it. NOTE: CLIM does not work in SMP versions of ACL.
- compiler-explanations.html: describes the explanations provided by the compiler. It also discusses inlining.
- compiling.html: describes the compiler. It provides information on how code generated by the compiler is controlled by the safety, space, speed, and debug optimization qualities. Information is also provided on declarations that will speed up code and tools for determining the effectiveness of declarations.
- cross-reference.html: describes the cross reference facility. This facility can analyze Lisp code and determine what functions call what other functions and what functions are called by other functions.
- date-time.html: describes support for ISO 8601 date/time representation.
- dde.html: DDE (Dynamic Data Exchange) is a Windows-only facility that allows Windows applications to exchange data.
- debugger-api.html: provides information about internals of the Allegro CL debugger to assist application writers who wish to provide customized debugging facilities in their applications. Note that this document does not contain information needed for ordinary use of Allegro CL.
- debugging.html: describes the debugger in Allegro CL.
- defsystem.html: defsystem is a facility for managing files associated with an application.
- delivery.html: describes how to deliver an application written in Allegro CL. There is also a description of how to establish a update system for your application which complements the update system for Allegro CL, and other delivery-related issues.
- dll.html: describes examples showing how to create Lisp-based DLL on Windows. unix-shared-library.html is a similar document describing creating Lisp-based shared libraries on UNIX platforms.
- dns.html: describes support for Domain Naming Systems.
- dom.html: describes Document Object Module (DOM) support.
- dumplisp.html: describes the facility for for saving running Lisp images to disk. See also build-lisp-image.
- ec2.html: This document is no longer available. Contact support if you use the Amazon EC2 API.
- eli.html: describes the Emacs-Lisp interface (ELI) provided with Allegro CL. See also
- environments.html: describes environments functionality, based on the proposal described in section 8.5 of Common Lisp: the Language 2nd ed.
- errors.html: discusses common errors which may be encountered while using Allegro CL, along with, where possible, suggestions for fixing them. The condition system type hierarchy in Allegro CL is also discussed.
- examples.html: general information on Allegro CL examples.
- express-installation.html: describes how to install Allegro Common Lisp Express, the free version of Allegro CL. Installation is similar to installation of regular Allegro CL, but simpler. See installation.html for instructions on installing non-Express versions of Allegro CL.
- flavors.html: describes a pre-CLOS object system, which exists for compatibility reasons.
- foreign-functions.html: describes how to interact with code written in other languages, such as C, C++, etc. See also foreign functions classes, foreign functions variables and foreign functions operators
- ftp.html: describes an FTP Client module, which can be used to communicate with an FTP server. This is unrelated to SFTP.
- ftype.html: describes how foreign types can be defined and used in Lisp.
- fwrappers-and-advice.html: describes the fwrapper facility (and the older, deprecated advice facility), which allow adding code that is run
  around functions.
- gc.html: describes the Lisp garbage collector.
- gray-streams.html: provides details of the implementation of Gray streams in Allegro CL. Gray streams are the older stream implementation. Starting with release 6.0 simple-streams, which have advantages over Gray streams, is the primary stream implementation. Simple-streams are described in streams.html.
- iacl.html: describes International character set support in Allegro CL. Allegro CL can support international character sets on all platforms. Note that non-international executables are also provided, such as mlisp8 and alisp8.
- imap.html: describes the support for the IMAP protocol, and includes support for constructing MIME-compliant email messages.
- implementation.html: provides specific information about the implementation of Allegro CL. Many details of the Common Lisp standard are implementation-dependent and this document says what Allegro CL does. Also discussed are extensions to Common Lisp functions (such as open, make-array, and others where an Allegro-specific enhancement is provided).
- index.html:provides links to other documents, including links to all Allegro CL functions, variables, etc.
- inspector.html:describes the non-windowized inspector. Users on Windows with the Integrated Development Environment get all the functionality described in this document in inspector windows.
- installation.html: describes how to install Allegro CL and related products. Installation of Allegro CL Express is described in express-installation.html.
- introduction.htm: this document.
- jlinker.html: describes our Java/Lisp interface.
- jil.html: describes a Java in Lisp (jil) facility, which allows Lisp programs to run on the Java Virtual Machine (JVM), using syntax familiar to Lisp programmers.
- llm-api.html: describes the Large Language Model interface from Allegro CL.
- loading.html: describes details of the implementation of cl:load. cl:require is also discussed.
- main.html: describes how to define your own C `main()` function.
- miscellaneous.html: describes functionality too limited to need a separate document.
- mop/contents.html: describes the MetaObject Protocol (MOP) in chapters 5 and 6 of The Art of MetaObject
  Protocol by G. Koczales, J. des Rivieres, and D. Brobrow. The HTML version was prepared by Howard Stearns and copyrighted by the Elwood Corporation, as described in mop/admin.html.
- multiprocessing.html: describes the multiprocessing facility, for using lightweight processes.
- mysql.html: describes the API to connect to MySQL.
- ndbm.html: describes the NDBM facility (UNIX only).
- ole.html: describing interfacing to OLE on Microsoft Windows. See also ole_reference.html.
- oracle-interface.html: describes the Allegro Oracle Direct Connect interface to Oracle databases.
- ORBLink: describes the CORBA Object Request Broker (ORB) for Allegro CL.
- os-interface.html: describes how to call OS functionality directly from within Lisp.
- packages.html: provides details of the implementation of packages and includes a description of package locking (which prevents accidental redefinition of Common Lisp and Allegro CL functionality).
- other-programs.html: describes various programs in the bin/ subdirectory of the Allegro CL distribution which perform various service functions.
- pathnames.html: provides information on the implementation of pathnames (including logical pathnames).
- prolog.html: describes the implementation of Allegro Prolog.
- phtml.html and pxml.html: COMING SOON.
- regexp.html: describes the regular expression APIs.
- release-notes.html: describes the changes between releases of Allegro CL.
- rpc.html: describes the Remote Procedure Call (rpc) utility.
- runtime.html: describes the technical solution to the restriction of runtime delivery licenses. It has both legal and technical meanings.
- runtime-analyzer.html: describes the tool for determining the time and space usage of code, and how to make them more efficient. In earlier releases, this tool was called the profiler.
- sax.html: descries our validating parser for XML 1.0 and XML 1.1. The interface to the parser based on the SAX (Simple API for XML) specification.
- shell-module.html: describes a wrapper for shell commands, such as you find on a modern UNIX systems.
- smp.html: describes the changed functionality for managing multiple processes in a Symmetric Multiprocessing (SMP) Lisp.
- socket.html: describes the support for sockets communication. See also socket classes, socket variables and socket operators.
- soap.html: describes the Allegro CL/SOAP API.
- source-file-recording.html: descrbies a facility for querying the location of Lisp defined objects.
- startup.html: describes starting Allegro CL.
- streams.html: provides details of the implementation of simple-streams, the standard stream type.
- string-utilities.html: describes the :util-string module which contains string manipulation functionality.
- test-harness.html: describes a test harness facility.
- top-level.html: describes the Allegro CL REPL (read-eval-print loop) and the associated commands. See also top-level operators, top-level variables and top-level commands.
- unix-shared-library.html: describes examples showing how to create Lisp-based shared libraries on UNIX platforms. See also dll.html for a similar facility for Microsoft Windows.
- uri.html: describes the URI facility. URIs are a superset in functionality and syntax to URLs (Universal Resource Locators) and URNs (Universal Resource Names).
- webactions.html: this is the user guide and reference manual for the Allegro Webactions facility for generating dynamic web pages. See also
  using-webactions.html, which is a general introduction. Webactions works with AllegroServe.
- xml-rpc.html: describes the Allegro CL implementation of XML-RPC, which supports the XML-RPC protocol for remote function calls through HTTP connections.

## 3.0 The Reference section

For Allegro CL-specific functionality, virtually every operator (function, generic function, or macro), every constant and variable, and many classes defined in Allegro CL, other than standard Common Lisp functionality, are described in HTML files called reference files. These files are in the same location as the file you are reading and are named [package-kind.html]

Where:

> [kind] is one of

> - ops (for functions, generic functions, and macros)
> - vars (for variables and constants)
> - classes (for classes and conditions)

> There are also files with top-level commands and ide-menus-and-dialogs.

> [package] is the home package of the symbol being documented (either its name or a nickname). Some packages have no entries under certain kinds.

Here is a list of the references files. Some things are documented in essay files rather than in individual package/type files. All objects are listed in the index.

- acl-socket-classes.html, acl-socket-ops.html, acl-socket-vars.html
- cg-classes.html, cg-menus-and-dialogs.html, cg-ops.html, cg-vars.html
- compiler-ops.html, compiler-vars.html
- cross-reference-ops.html, cross-reference-vars.html
- date-time-classes.html, date-time-ops.html, date-time-vars.html
- dbi-ops.html, dbi-vars.html
- dde-classes.html, dde-ops.html, dde-vars.html
- defsystem-classes.html, defsystem-ops.html, defsystem-vars.html
- excl-classes.html, excl-ops.html, excl-vars.html
- foreign-functions-classes.html, foreign-functions-ops.html, foreign-functions-vars.html
- ide-classes.html, ide-ops.html, ide-vars.html
- jil-ops.html, jil-vars.html
- jlink-classes.html, jlink-ops.html, jlink-vars.html
- multiprocessing-classes.html, multiprocessing-ops.html, multiprocessing-vars.html
- mysql-classes.html, mysql-ops.html, mysql-vars.html
- ndbm-ops.html
- post-office-classes.html, post-office-ops.html
- profiler-ops.html, profiler-vars.html
- rpc-classes.html, rpc-ops.html, rpc-vars.html
- system-ops.html, system-vars.html
- test-ops.html, test-vars.html
- top-level-ops.html, top-level-vars.html, tpl-comms.html
- uri-classes.html, uri-ops.html, uri-vars.html
- windows-ops.html

## 4.0 Assistance available on the internet and the World Wide Web

Franz Inc. maintains a World Wide Web home page (https://franz.com/). Along with much else, the latest update of the Allegro CL documentation, the latest Allegro CL FAQ, and the latest Allegro CL updates can be found in the support section.

### 4.1 The Allegro CL FAQ

FAQ stands for Frequently Asked Questions. The Allegro CL FAQ is a document written in question and answer format containing answers to questions often asked by users of Allegro CL and related products. Franz Inc. updates the FAQ regularly.

faq.html

### 4.2 Patches and updates

A patch is a file (typically a compiled Lisp file or a shared library file) which either corrects some error in the product or provides some enhancement or new feature. Patches are available from the Franz Inc. web site. (Some patches, particularly those which implement an improvement, an enhancement, or a new feature rather than a bug fix, are restricted to supported customers only.)

See Updating Allegro CL and the update program in the Installation Guide for more information and instructions for updating.

## 5.0 Reporting bugs

Before reporting a bug, please study this document and the ANSI CL Standard document.

A report that such and such happened is generally of limited value in determining the cause of a problem. It is very important for us to know what happened before the error occurred: what you typed in, what Allegro CL typed out. A verbatim log may be needed. If you are able to localize the bug and reliably duplicate it with a minimal amount of code, it will greatly expedite repairs.

It is much easier to find a bug that is generated when a single isolated function is applied than a bug that is generated somewhere when an enormous application is loaded. Although we are intimately familiar with Allegro CL, you are familiar with your application and the context in which the bug was observed. Context is also important in determining whether the bug is really in Allegro CL or in something that it depends on, such as the operating system.

To this end, we request that your reports to us of bugs or of suspected bugs include the following information. If any of the information is missing, it is likely to delay or complicate our response.

- dribble-bug or print-system-state output. The function dribble-bug is like dribble but prefaces the transcript with information about the image being run (platform, OS, Allegro CL version, patches loaded, and much else). Please include the output of dribble-bug in the first report of any bug or problem. The function print-system-state prints the information about the platform, patches, etc. that goes into a dribble-bug file. You can use that function to print the data to send to us instead of using dribble-bug, but that information, however, obtained should be included in each bug report.

- Information about you. Tell us who you are, where you are and how you can be reached (an electronic mail address if you are reachable via the Internet, a postal address otherwise, and your telephone number), and in whose name the license is held. It is best to put the email address in the text of the message (in case the mailer program messes up the return address). Please include a telephone number in case an email response bounces.

- A description of the bug or problem. Describe clearly and concisely the behavior that you observe and why it is not what you expect or want.

- Exhibits. Provide us with the smallest, self-contained Lisp source fragment that will duplicate the problem, and a log (e.g. produced with dribble-bug) of a complete session with Allegro CL that illustrates the bug. Note that dribble output does not log certain messages printed by the Operating System or printed by foreign code called by Lisp or routines called by run-shell-command and related functions. If such output is relevant, please capture it in an Emacs buffer or in some similar fashion and include the output with the information you submit.

Use dribble-bug as follows. Entering

    (excl:dribble-bug filename)

causes implementation and version information to be written to the file specified by filename, and then records the Lisp session in the same file. Exiting Lisp or entering

    (dribble)

will close the file after the bug has been exhibited. The following dialog provides a rudimentary template for the kernel of a bug report.

    USER(5) (dribble-bug "dribout")
    USER(6) ;; Now duplicate your bug . . .
    USER(7) (dribble)

It may be that the bug causes failure which prevents getting a dribble transcript showing the bug. We still need the dribble-bug output showing the platform, patches, etc. Get this with

    USER(5) (dribble-bug "dribout")
    USER(6) (dribble)

print-system-state prints the information that goes in a dribble-bug file. You can use that function to get the information if you wish. In either case, send the contents of the file dribout or the output of print-system-state.

Send bug reports to either the electronic mail or postal address given in Where to report bugs and send questions. We will investigate the report and inform you of its resolution in a timely manner.

As we said before, the dribble-bug log does not capture things printed by the operating system or by operating system utilities. These messages may be important. Please be sure you include them in the message.

### 5.1 Where to report bugs and send questions

Send problem reports and technical questions of any type by email to support@franz.com.

### 5.2 Core files: when they are useful and what to do with them

Certain kinds of Allegro CL errors/problems cause failure of the Lisp and can result in the dumping of a core file. Sometimes this occurs when unexpected exceptions from the operating system make continued operation impossible. Sometimes it is due to a GC orm stack error. (GC errors are discussed in gc errors in gc.html.) Often you are asked whether you want a core file with a question like:

    Would you like to dump core for debugging before exiting(y or n)?

If you answer y, then an attempt will be made to produce what is known as a "core file". Core files are usually produced on Unix and Unix-like systems, they have many different shapes and levels of usefulness. In order to make the best use of time spent and space used in preserving and communicating core dumps to Franz, here are some guidelines to follow when a core is produced:

1. If possible, find another way: core files are sometimes large, sometimes incomplete, and often it is hard to glean enough information from a core to figure out what went wrong. A better strategy is to either find a reproducible test case which we can replicate in our offices, or else allow us ftp/vpn access to your machine to reproduce the failure.

2. Send it all: the core file is never complete; it always relies on the original lisp executable (usually called mlisp, mlisp8, alisp, or alisp8, or renamed as your application) and on the "acldll" (which is the Allegro CL shared-library, having either .dll, .so, .sl, or .dylib extensions). It may also rely on a .pll file, which can be found out in a running image by noting the value returned by `(excl:pll-file)` - a null return means that there is no pll file, and a pathname is the location and name of the .pll file (the pathname should also be sent). Note: Even if you believe that we already have the executable file or the shared-library, or even the .pll, include all of it into the directory that you will send us.

3. Don't use email: a usable core and its entourage are much too large to send through email; instead, package it up into a file suitable to send via FTP and contact support@franz.com for instructions on how to send it. (Franz Inc. no longer maintains an anonymous FTP server.)

## 6.0 Contacting Franz Inc. for sales, licensing assistance, and information

Sales and licensing questions should be directed to your account manager. If you are not already a customer (and thus do not yet have an account manager), send email to info@franz.com, or call us (we're in California, USA) at +1 510-452-2000. Please give your email address, phone number, and mailing address. The appropriate Account Manager will contact you.

If you are already a customer, you should have the name and email address of your account manager, but if they are not at hand, use the general ones given above.

General product information is available on our web site, https://franz.com. You can get additional information by sending email to info@franz.com, by calling +1 510-452-2000 or by writing to

>     Franz Inc.
>     3685 Mount Diablo Blvd, Suite 300
>     Lafayette, CA 94549, USA

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0