Star Sapphire Common LISP Home

Download Star Saphire
Index

25. MISCELLANEOUS FEATURES

This chapter contains the following sections:

25.1 The Compiler

25.2 Documentation Facilities

25.3 Debugging tools

25.4 Environment Inquiries

25.5 Identity Function

In this chapter are described various things that don't seem to fit neatly anywhere else in this text: the compiler, the documentation function, debugging aids, environment inquiries and the identity function.

Some of the supporting facilities described in this file are described more completely in the Star Sapphire Users Manual. (q.v.).

 

25.1 The Compiler

The compiler is a program that may make code run faster by translating programs into an implementation-dependent form that can be executed more efficiently by the computer. Most of the time you can write programs without worrying about the compiler.

Of the following functions, compile-file is most useful,as it generates a compiled file which will load much more quickly than loading raw LISP source:

compile

compile-file

disassemble

 

25.2 Documentation Facilities

The documentation string for a function, macro, or other form is available through the following function:

documentation

set-documentation

 

25.3 Debugging tools

The following debugging tools are available in Star Sapphire:

trace

untrace

mtrace

tracef

step

describe

inspect

room

ed

name-editor

help

qhelp

apropos

apropos-list

 

25.4 Environment Inquiries

Environment inquiry functions provide information about the environment in which a Common LISP program is being executed. They are described here in two categories: first, those dealing with determination and measurement of time, and second, all the others, most of which deal with identification of the computer hardware and software.

Refer to the following articles:

24.4.1 Time Functions

25.4.2. Other Environment Inquiries

 

25.4.1 Time functions

The following time functions and constants are supported by Star Sapphire:

time

get-decoded-time

get-universal-time

decode-universal-time

encode-universal-time

internal-time-units-per-second

get-internal-run-time

get-internal-real-time

sleep

time-of-day

phase-of-moon

Note the added two enhancements to the time facility, one quite useful, the other just for fun. The implementation specific time-of-day function allows the current or some arbitrary universal time to be converted to a human readable string. The phase-of-moon function allows access to lunar time.

Time is represented in three different ways in Common LISP: Decoded Time, Universal Time and Internal Time.

The first two representations are used primarily to represent calendar time and are precise to one second. Internal Time is used primarily to represent measurements of computer time (such as run time) and is precise to an implementation dependent fraction of a second. Decoded time format is used only for absolute time indications. Universal and Internal time formats are used for both absolute and relative times.

Decoded Time format represents calendar time broken down into seconds, minutes, hours, day of the month, month, year, day of the week, and daylight-savings-time-p and time-zone.

All of these, except for daylight-savings-time-p are represented by small integers. The second, minute and hour are 0 based integers in 24 hour time format. The day of the month and month are represented as one based integers. The year is specified either as an A.D. date or in a short format as follows.

If the year is specified as a number between 0 and 99, the year referred to is equal to the integer modulo 100 within 50 years of the current year (inclusive backwards and exclusive forwards). Thus in the year 1984, year 34 is 1934, but year 33 is 2033. The day of the week is stored as an integer from 0 to 6, where 0 is Monday. The daylight-savings-time-p flag is nil if daylight savings is not in effect and in effect if non-nil.

The time-zone can be specified in hours west of GMT (Greenwich Mean Time). Thus the timezone in California is 8. The timezone may be specified as a fractional number, to allow for timezones which are fractionally offset from GMT; thus the time zone for Madras can be written -55/10.

To set the default timezone for Star Sapphire, you must have an environment variable named 'TZ' in your DOS environment. Note that the default time zone can be overridden using arguments to functions which accept it.

If this environment variable is not set, the timezone defaults to EST5EDT.

For instance, to set your TZ environment variable for the west coast of North America, you should issue the following DOS command (at the DOS, not the LISP prompt).

set TZ=PST8

in daylight savings time this will be

set TZ=PST8PDT

This environment variable must have the following format:

A three letter time zone name (e.g. PST); followed by the an optionally signed integer which represents hours offset from Greenwich (e.g. 8); followed by an optional suffix which indicates that daylight savings time is present (e.g. PDT).

The number if positive is a westward displacement from GMT; if negative an eastward displacement.

Note that the presence of the optional suffix will cause daylight-savings-time-p to be t, and if not present nil.

Universal Time represents time as a single non-negative integer. This is the number of seconds since midnight, 1/1/1900 GMT. This takes into account leap years but not 'leap seconds'; in other words Common LISP years are considered to be exactly 86400 seconds long.

Internal time is specified in this implementation in two ways; by seconds since 1/1/1970 (returned by get-internal-run-time) and by clock ticks since midnight (returned by get-internal-real-time). The latter value is that used by the time macro.

 

25.4.2. Other Environment Inquiries

The following functions allow identification of the machine on which a given Common LISP implementation resides. A typical use of these is when benchmarking various systems; the output from these functions can be placed in the benchmark report automatically so as to unabmigously identify the system where a given set of results were produced.

Plausible versions of these functions are defined in init0.lsp; you can of course alter these to anything you want.

These functions all return a string, whose contents describe the given characteristic. For any of the following functions, if no appropriate and relevant result can be produced, nil is specified to be returned instead of a string.

lisp-implementation-type

lisp-implementation-version

machine-type

machine-version

machine-instance

software-type

software-version

short-site-name

long-site-name

25.5 Identity Function

This function is occasionally useful as an argument to other functions that require functions as arguments:

identity