Common Questions And Answers
Here is a list of answers to common (and some not so common) tech support issues and other questions asked about Star Sapphire. If you need help or advice about LISP, or simply want to let us know what you like or don't like about the product, please don't hesitate to contact Sapiens at the number listed in front of the manual.
However, read this file first; it may save you a call.
Q: I am confused by the help system.
A: Consult the topic How to use the Help System.
If you are having trouble with help, one possibility is that you have a monochrome monitor and did not select the monochrome color combination at startup. Exit LISP and run lispcnf.exe from the DOS command line. Select a better color combination.
Q: I just want help on one topic, and don't want to load the whole @?%!^& help system.
A: Use (qhelp 'topic'), where 'topic' is the thing you want help with. The qhelp function will pop up a viewer window for just the file you need, positioned on the hypertext link for that topic.
The disadvantage is that you need to know in advance whether the specified topic is in the help system.
Q: How can I get help on LISP inside EMACS?
A: Note that Alt-H brings up the help system inside EMACS.
Q: I try interrupting using Ctrl-C; it just gets echoed to the screen. How can I stop a running process?
A: Use Ctrl-Break instead. Be aware that the system may take a few seconds to respond to Ctrl-Break because LISP waits to process the break until it is not adjusting any internal data structures, reading from disk, etc. In order to do this, we had to process but not on Ctrl-C. Before we took this approach, Ctrl-Break was sometimes trashing LISP because some data structure (such as the swapper tables or a hash table) would be left in an inconsistent state.
Note: If you want to break out of a garbage collection, you must also answer 'y' to the prompt. We are not sure at this time whether answering 'y' while interrupting a GC will corrupt the system,so we let you choose. Please let us know if interrupting a GC causes mysterious system errors.
Q: I have some problem with my code; I'm not sure where it is blowing up/going wrong/heading south/etc. I'm pretty sure it's my code and not a system bug, but it runs for quite a while and nothing happens.
A: The trace function is helpful in this regard. As a first pass, you might want to run it with
(ftrace t)
just prints out the function calls without the arguments.
Once you have an idea where you are having trouble, you might want to trace a specific function. Turn off trace (to turn off ftrace) and then trace with an argument of a specific symbol name.
Remember to dribble the output to a file if it runs for a awhile. You can then print out that file or inspect it later.
If you do find a bug in the system, let us know about it immediately so we can fix it in the next version.
Q: Why does defstruct take so long?
A: It has to build, compile and evaluate defuns for the constructor, predicate, copier for the defstruct, as well as two functions and a defsetf for each slot (one accessor, one reader, and the setf method). Furthermore, it is a macro, so its own macro expansion adds some time.
Once you have a defstruct in place though, making a structure instance is almost instantaneous.
To supress the creation of copiers, you can specify just the :copier keyword, likewise the predicate; to supress the generation of slot accessors you can specify that a slot should be read-only. This will save some time for each defstruct if you don't need these facilities.
To get reports on defstruct's progress, use the undocumented and Star Sapphire specific :verbose option.
For instance:
(defstruct (dfs-boa
(:verbose t)
(:constructor make-dfs-boa (a b c))
(:constructor create-dfs-boa
(a &optional b (c 'cc) &rest d &aux e (f 'ff))))
a b c d e f)
Runs a defun which may take awhile; it prints out the names of functions which it is constructing along the way.
Also:
(defstruct
(foo (:copier)(:predicate))
(bar nil :read-only t)
(baz nil :read-only t))
Makes a (somewhat useless) struct named foo with two fields bar and baz and no copier, predicate or accessor functions.
Q: I tried using setf and got a message that there was no setf method for some function. Or it said that setf has no functional definition.
A: You have to run the defsetf for the function. All standard defsetf methods can be found in init0.lsp. Only the defsetfs for car, cdr, get and aref are executed at startup since running all thirty defsetfs specified by the Common LISP language takes a long time.
For instance, the defsetf for caar is
(defsetf caar (x) (y) `(progn (rplaca (car ,x) ,y) ,y))
You have to either type the defsetf form, or put it in a file (such as init.lsp) and load it.
If you got the message that setf has no functional definition, then you need to load defsetf.fsl.
Q: I tried using the graphics functions and it kicked me out.
A: You need to run initgraph to load the driver and set up graphics before using any of the graphics functions. If you didn't install a driver for your display adaptor, you can run the install program and just request that the appropriate driver be installed without reinstalling completely. If that doesn't work, please note that initgraph has to get the correct path to the driver to work correctly.
While we're on the subject, you also need to run closegraph when you're done. Not all of the text mode interface elements will run in graphics mode.
Q: How do I print text in fonts in graphics mode? I tried using format, but I just got an ugly string in a hard to read font.
A: Use set-font and outtextxy. Note that the set-font function needs to have the correct path to the font files. Note also that you can use format to hand off a string to outtextxy by giving nil as the first argument to format (rather than t as usual). This formats into a string, which is then passed to outtextxy. For example:
(outtextxy 30 30 (format nil "there are ~d ~a ~s" 3 'black "sheep"))
Q: The parend matcher (Ctrl-PgUp, Ctrl-PgDn) in EMACS doesn't work.
A: It gets confused if you have mismatched parenthesis. We are trying to improve this. The blinking parenthesis in EMACS is our way of making up for this for now. The phenomena seems to occur when you have deleted a bunch of stuff; we are still trying to figure out the exact circumstances.
Q: I tried loading init0.lsp and I got an error.
A init0.lsp is not meant to be loaded in its entirety; also not everything in it has been tested. You should just load what you need. It is made up of spare parts from various sources.
------------
Q: I tried using the shell escape and I got the DOS error 'file or directory not found'.
A: Check your 'COMSPEC' (see your DOS manual). This tells shell escapes where command.com can be found. Sometimes it gets set wrong (installation programs which edit config.sys are the prime culprits). The error message means that command.com was not found (DOS is trying to load a copy of itself; to do that it needs to read command.com from disk; at that point, command.com is just another file, so it is 'not found'. Not much we can do about this; I would sure like it if DOS reported *which* file was not found. We wasted about five long distance phone calls before we figured this one out.
The COMSPEC must be set in your config.sys file (you can find config.sys in your root directory on your boot device). It should be the full pathname of the file command.com. My comspec looks like this:
COMSPEC=C:\COMMAND.COM
It also helps if your shell command is set. My shell command looks like this:
SHELL=C:\COMMAND.COM /E:3000 /P
Note: The most common reason for the shell escape failing is that you may not have enough memory to run a given command. This will manifest itself in other ways.
Q: I ran out of memory in a shell escape -- I have eight megabytes on my system! I also want to use my own editor, but it needs a lot of memory.
A: Star Sapphire is running in real mode. In real mode you are limited to 1 megabyte of main address space, of which 'only' 640 kilobytes are usable. Star Sapphire takes up about 550 kilobytes of that, so go figure.
The best solution is to run Star Sapphire as one task and EMACS (or some other editor) as another in a Windows DOS box.
Q: I got the message 'internal: hash table corrupted' and then the system just hung (or LISP exited).
A: This can happen if you run out of a system resource such as disk space breaking down because it cannot add another page to the swap file. It has no way of anticipating this in advance, so it can't produce a more specific error in certain cases.
If a virtual memory error occurs that normally shouldn't happen, LISP checks disk space and will let you know that you just ran out of room. Note that the swap file will be deleted at this point, so after LISP exits you will have plenty of room. There is no way to recover gracefully; you will be back at the DOS prompt. Then you need to free up some room on disk and give it another shot.
This can also occur if you are swapping to a RAM disk in extended memory and run out of 'disk space' on the RAM disk.
Under some circumstances, running out of disk space will simply cause LISP to freeze up. There is no particular workaround for this.
Q: I tried running factorial 100 and got a stack overflow.
A: There is a limitation which is built into DOS of 64K of physical stack (as opposed to the LISP stack). There is nothing we can do about this at the present. Try a tail recursive definition:
(defun tail-recursive-factorial(n)
(let ((i n))
(loop
(if (= n 1)
(return i)
(setq n (1- n)
i (* n i))))))
This can do as big a factorial as you like, within the system limit for bignum width (see below). Of course large values of n can take awhile.
This approach can be used for many problems involving deep recursion.
Q: I got a stack overflow, but it was a LISP or display stack overflow.
A: You can increase the size of these internal stacks using the -l and -d command line flags.
Q: Is there any limit on bignums?
A: Yes, a bignum can 'only' have 256 digits at present.
Q: Are there any other limits on the size of objects?
A: Symbol names are limited at read-time to 256 characters of print name. Strings can be any length (in theory, up to 2 billion characters); the reader special cases them so you can have arbitrary length strings in input files. Bit vectors at read-time are limited to 256 digits; however, it is possible to build larger bit vectors using various functions and print them.
Vectors and arrays of other kinds are also unlimited in size, both at read and print time. Arrays can have over 64 thousand dimensions,and each dimension can have values of over 4 billion. Of course, there is an absolute limit of 8 megabytes of virtual memory, so you will run out of virtual memory first.
Q: Why the limits? The specification says they have to be unlimited.
A: We could store the intermediate results of building symbols, bignums or bit-vectors in virtual memory; however it produces an unacceptable speed degradation. The intermediate values in bignum calculations are stored on the stack for just this reason, which is why there is an absolute limit on their size. It's a tradeoff.
Q: I got a message that something couldn't be converted from a bignum. How do I convert something from a bignum?
A: Some conversions are not yet implemented (such as converting a REALLY big bignum to floating point). We are working on this. This is a purely internal issue, so there is no workaround.
Q: My program gets into an infinite loop; to break out I have to reboot. My free hard disk space keeps shrinking mysteriously!
A: Run chkdsk /f when you reboot. When LISP crashes, if it is swapping to a file, that file is left in an inconsistent state; although it is still using up disk space, it does not belong to the file system and cannot be referenced or deleted by normal DOS commands. chkdsk /f will turn the remnants of the dead swap file into a file with a .chk extension in the root directory.
You can then safely delete the .chk file, which will reclaim the disk space for further use.
Note that if you encounter any files prefixed with ~cl and with a .tmp extension you can delete them as well; these are the names of the temporary swap files and if you have crashed while running LISP, you can end up with a zero length file with that prefix and extension. These files are normally deleted when you exit LISP normally. You can safely delete any files with that name (as long as LISP is not running!).
Q: I have a circular list and it prints out forever.
A: Set *print-circle* to t. When this is on, circular structures (including lists and arrays) print using the #n# #n= syntax as specified in Chapter 22 of Common LISP, The Language. However, due to the need to check for circularity, this slows print output down quite a bit; thus the startup value of *print-circle* is nil.
The #n# #n= syntax can be used at read time at any time.
To stop an out of control print, use Ctrl-Break.
Q: I have a class with a slot value referencing the same class; it prints out recursively forever.
A: Set *print-depth* to some small number such as 3; *print-depth* and *print-level* now work with class instances, as well as lists, structs, vectors and arrays.
Q: In the tutorial in the hypertext it says to print out the tutorial -- how do I do this? Also, how do I print out a specific hypertext file or files?
A: All of the help files are associated with their topics by the file flist.doc which is installed in your LISP installation directory. For instance, the first line in that file says:
doc\cl0.doc # 0. Tutorial
This means that the tutorial is the file in the doc subdirectory under your installation directory named cl0.doc.
In general, the files have names which either start with 'cl' or a letter of the alphabet. The files which start with 'cl' are followed by numbers which relate to the chapter in Common LISP, the Language. If a chapter is long or has some logical breakdown, these will sometimes have several subsections with letters following them.
The files which start with a letter of the alphabet are the alphabetized manual pages. If there is more than one chapter for a given letter, it will have digits starting with '0' following the letter.
To print out a file you can send it to your printer by whatever means you normally print ASCII files. The files are normal ASCII files without any highbit characters. There are some Ctrl-_, Ctrl-P and Ctrl-Q characters in the files; these should not present any problem.
Q: Can I edit the help files?
A: Do not alter the help files! The exact position of all the hypertext links is hardwired. If you have to, use a copy of the file.
Q: How about a bibliography?
A: It's included with the bug report form.
Q: How do I report bugs?
A: Preferably in writing. Use a copy of the form provided.
Q: What is Star Sapphire written in?
A: C, specifically, Borland C++.
Q: Where does the pirate keep his treasure in the maze of twisty passages?
A: From Y2 go East; then N-E-W-S.