REF SYSTEM John Gibson May 1995
COPYRIGHT University of Sussex 1995. All Rights Reserved.
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< POPLOG SYSTEM >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< CONTROL PROCEDURES >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This REF file deals with the top-level procedures and variables which
Poplog uses to start itself up (including the use of saved images and
special flags), execute the language sub-systems, perform runtime
actions, start X, control the memory space and exit. It explains its
relationship to the operating systems which call it and how the Poplog
program is realised.
CONTENTS - (Use <ENTER> g to access required sections)
1 General System Startup
1.1 Saved Images
1.2 Special Flags
1.3 Remaining Arguments
2 Starting up Standard Language Systems
3 Directory Search Paths (popsavepath and popcomppath)
4 Additional Startup Mechanism in Unix
5 Procedures and Variables Concerned with System Startup
6 Runtime Actions
7 Starting up X-Windows Facilities
8 System Exit
9 Store Management
10 Saving and Restoring the System State
10.1 Creating Layered Systems
10.2 Note on VMS Saved Images
... Alpha VMS
11 Incremental Save and Restore
12 System Identification
12.1 Poplog Version
12.2 Machine & Operating System
-------------------------
1 General System Startup
-------------------------
Poplog, like any other program, is invoked by issuing a command to the
operating system command interpreter (DCL on VMS machines, generally the
C-shell on Unix machines).
When Poplog starts up, it converts the command by which it was invoked
into a list of strings, which is assigned to the variable poparglist0.
The first element of this list is always the name under which Poplog was
invoked; this is also assigned to the variable poparg0. In Unix it is
the usual '0-th' argument, while in VMS it is the full name of the
Poplog image file being executed (see poparglist0 below for details of
command line to argument translation in VMS).
The remaining items (if any) in poparglist0 are the arguments to the
command that invoked Poplog, and the sublist from the second element
onwards is assigned to the variable poparglist (from whence each
argument is taken as it is processed, so that poparglist always contains
any remaining unprocessed arguments).
The following two types of special argument may occur at the beginning,
and are always interpreted first by the system:
+filename
where filename is the name of a saved image to restore
%flag
where flag is the name of a special flag
Saved image arguments must come first, followed by special flags.
1.1 Saved Images
-----------------
These are arguments beginning with a + character, and specify a saved
image to restore: the argument (with the + removed) is taken as the name
of the saved image. For filenames not including an explicit directory,
the directories given by the environment variable/logical name
"popsavepath" are searched (see below).
After restoring the image, further arguments beginning with the same
character are taken as layered saved images to be restored on top of the
previous one, and so on. Note that a saved image remembers the arguments
for any previous images it was created on top of, and that these will be
resurrected automatically if omitted. Thus with a sequence of layered
images, only the last need be specified (although startup will be
slightly quicker if all arguments are supplied).
The base Poplog executable together with any saved images then
constitutes the complete `image' being run; where saved image(s) are
present, control will be passed to the last one after any special flags
have been processed.
For example,
pop11 +mysave
(N.B. For upward compatibility reasons, the characters / in VMS and - in
Unix may also be used to indicate saved images, PROVIDING + has not
already been used (i.e. + turns off recognition of these on subsequent
arguments)).
1.2 Special Flags
------------------
Special flags are arguments that start with the character `%` (in VMS
this must be escaped with a preceding `\`, since `%` is a wildcard
character and the argument would undergo filename expansion). The
following flags are recognised:
Flag Action
---- ------
%nort Prevents execution of any `runtime actions' in the
image, and stops the variable pop_runtime being set
true. See Runtime Actions below.
%noinit Assigns true to the variable pop_noinit.
%nobanner Assigns true to the variable pop_nobanner.
%x Assigns nil to the variable popunderx.
The %x argument may optionally be followed by a parenthesised list of
arguments, which is assigned to the variable popunderx instead of the
empty list (as explained below under poparglist0). (In Unix, the
parentheses must must be escaped with a preceding `\` since they are
shell metacharacters).
For example,
pop11 %x \( arg1 arg2 \) (Unix)
pop11 \%x ( arg1 arg2 ) (VMS)
Except for pop_runtime, all the variables associated with command line
flags have a default value of false, assigned if the flag is not
present. They affect subsequent startup behaviour, as described below.
1.3 Remaining Arguments
------------------------
After processing saved image and special flag arguments, any runtime
actions in the image are executed (unless %nort was present), and
control passes to the image. Where saved image(s) are present, control
is passed to the last one (i.e. the syssave or sys_lock_system that
created it will return true).
Thus the argument processing described above applies when any Poplog
image or saved image is run, and the interpretation of any remaining
arguments is in general up to the particular image. However, the
standard Poplog language subsystems (Pop-11, Prolog, CLisp and PML)
accept further arguments allowing them to be run in different modes
(after which as usual, any remaining arguments are in poparglist).
----------------------------------------
2 Starting up Standard Language Systems
----------------------------------------
The base Poplog executable is the file
$popsys/basepop11 (Unix)
popsys:basepop11 (VMS)
This can be invoked directly under the name "basepop11", but more often
than not, entry to Poplog is via one of the four language subsystem
commands:
pop11
prolog
clisp
pml
These are all defined to run the base executable together with one or
more layered saved images appropriate to the particular language.
Command definitions are set up by the Poplog login file:
$usepop/pop/com/popenv (Unix)
usepop:[pop.com]popenv.com (VMS)
The "pop11" command definition is equivalent to:
basepop11 +$popsavelib/startup (Unix)
basepop11 +popsavelib:startup (VMS)
The other languages are layered on top of "pop11": the "pml" command for
example (for running Poplog ML) is equivalent to:
pop11 +$popsavelib/pml (Unix)
pop11 +popsavelib:pml (VMS)
and the "prolog" and "clisp" definitions are similar. (Strictly, the
directory "popsavelib" need not be specified for the saved image
arguments because it is included in the search path "popsavepath"
described below. However, making it explicit reduces startup time.)
All four language systems can be run in three different modes:
(1) execute expression mode
(2) compile file mode
(3) interactive mode
On startup, they all call the procedure syssetup, which checks whether
there is a further as yet unprocessed argument in poparglist, and if so,
processes it as follows:
o If the argument is one of
ved help teach ref doc
then this indicates normal interactive startup but inside the Ved
editor (with the given Ved command). The next argument (if any) is
taken as a filename argument for the Ved command. E.g,
prolog ved myfile.pl
o Otherwise, if the first character of the argument is `:`, mode (1)
is chosen. The rest of the argument is treated as a string of source
text, and is compiled. The system then exits. (Note: arguments
containing `:` usually have to be quoted, on both Unix and VMS
systems). E.g,
pop11 ":1+2=>"
o Any other argument is interpreted as the name of a source file to
compile (i.e. mode (2)). If the filename does not include an
explicit directory, the directories given by the environment
variable 'popcomppath' are searched (see below). Again, the system
exits once the file has been compiled. E.g,
clisp foo.lsp
If there is no argument in poparglist, or if Ved startup was specified,
then mode (3) is selected, and the system sets itself up for interactive
use:
o Unless pop_nobanner has been set true via the %nobanner flag, the
general Poplog banner -- popheader followed by popcopyright -- is
printed, together with any language-specific messages from Prolog,
Common Lisp or Standard ML.
o Unless pop_noinit has been set true via the %noinit flag, all
appropriate "init" files are compiled.
o If popunderx has been set true by the %x flag, the procedure
sysxsetup (described below) is called. This opens a connection to
the X server.
o If Ved startup was specified, then Ved is entered with the given
command.
o Otherwise, setpop is called. This calls pop_setpop_compiler, which
will run the incremental compiler for the appropriate language.
See Subsystem Image Startup in REF * SUBSYSTEM for a more detailed
description of the procedure syssetup. For additional information, see
HELP * INITIAL
-------------------------------------------------------
3 Directory Search Paths (popsavepath and popcomppath)
-------------------------------------------------------
A directory search path mechanism is supported for saved image
filenames, and Pop-11 source file names specified in mode (2). A search
path is an environment variable/logical name whose translation is a
sequence of directory names, separated from one another by ':' (colon)
characters in Unix or "|" (vertical bar) characters in VMS (and in which
an empty directory name is interpreted as the current directory). A
filename that does not include an explicit directory is then searched
for in the given sequence of directories.
For saved images, the search path is given by "popsavepath", whose
standard value is
:$poplib:$poplocalbin:$popsavelib (Unix)
|poplib:|poplocalbin:|popsavelib: (VMS)
(i.e. search the current directory first, then "poplib", then
"poplocalbin", and finally "popsavelib".
For Pop-11 source files, the search path is given by "popcomppath",
whose standard value is
:$poplib:$poplocalauto:$popautolib:$popliblib (Unix)
|poplib:|poplocalauto:|popautolib:|popliblib: (VMS)
(i.e. search the current directory first, then "poplib", then
"poplocalauto", then "popautolib" and finally "popliblib")
---------------------------------------
4 Additional Startup Mechanism in Unix
---------------------------------------
In Unix systems only, there is an additional startup mechanism which
allows the name under which the Poplog image was invoked to be used as
an argument. When the system is invoked under the name X, it looks to
see if there is an environment variable called 'pop_X', and if so, makes
the translation string of that variable the first argument (shifting up
the other arguments if necessary). Thus for example, if you create a
link called 'mysave' to the Poplog image '$popsys/pop11', and define an
environment variable:
setenv pop_mysave "$pop_pop11 +mysave"
then running the command "mysave" will have the same as effect as:
pop11 +mysave
which in turn is equivalent to:
basepop11 +startup +mysave
For this reason, the directory '$popsys' in fact contains the Poplog
image linked under various names (with corresponding 'pop_X' environment
variables defined), thus enabling the system to be invoked as "pop11",
"ved", "prolog", etc.
When this translation occurs, poparglist0 gets altered to reflect the
actual command run. In particular the first element (arg 0) is set to
the string 'basepop11'. However the variable poparg0 contains the
original arg 0 that Poplog was invoked with.
---------------------------------------------------------
5 Procedures and Variables Concerned with System Startup
---------------------------------------------------------
See also Runtime Actions below.
poparglist0 -> list [protected variable]
Contains the arguments with which Poplog was invoked, as a list
of strings (or sub-lists of strings, see below).
The system initially constructs a basic list of strings, the
first element of which is always the name under which the system
was run (in Unix this is the usual 0-th argument; in VMS, it is
the full name of the image file being executed, in lower case.)
In Unix, the remaining argument strings are as passed by the
execve call that initiated the process; in VMS, the basic
argument strings are derived as explained below.
After setting up the basic list of strings, the system then
processes the argument strings '(' and ')' specially. These are
treated as "list brackets", and cause all arguments strings in
between to be gathered into a single sub-list element of
poparglist0 (note that when used in a Unix shell command, both (
and ) must be escaped with backslash). A sub-list can be empty
(i.e. if ')' immediately follows '('), or can contain further
sub-lists delineated by nested occurrences of '(' and ')', etc.
Any non-paired '(' or ')' strings will cause a mishap (and
system exit).
Derivation of Argument Strings in VMS
This simulates a Unix style shell with automatic expansion of
filenames containing wildcards, as follows:
Argument strings are constructed from the DCL foreign command
line by splitting it at whitespace boundaries, all alphabetic
characters being translated to lower case. To get spaces, tabs
or uppercase alphabetic etc, in an argument it must be quoted
with double quotes ", which Poplog then strips off (note that
the trailing quote can be omitted on the last argument). Inside
a quoted argument, two adjacent double quotes are taken to
represent the character ". E.g.
pop11 +MYsave "aBcD" "" " """
will produce the 5-element list
['usepop:[pop.pop]pop11.exe;1' '+mysave' 'aBcD' '' "]
with the last being a string containing a ". Outside of quoted
arguments, a \ (backslash) can also be used to escape the
following character; thus
pop11 +mysave a\Bc\D
will have the same effect as "aBcD" (although note that since
DCL translates all unquoted lower case to upper, a\bc\d produces
the same effect).
Any argument containing the unquoted/unescaped wildcards
* % ...
is then replaced with the filenames produced by sys_file_match
applied to it (with an empty default filename). There must be at
least one matching filename.
In addition (because DCL foreign command lines are limited
to a maximum length of 255 characters), a 'file expansion'
facility is provided to enable larger numbers of arguments to be
passed. An argument of the form
@filename
(i.e. beginning with an unquoted/unescaped @), will be replaced
in the argument list with all arguments read from the text file
filename (or from all the files matched by filename if it
contains wildcards).
The processing of this file is identical to the processing of
the command line described above, except for newlines (which do
not appear in a foreign command line): when not enclosed in
quotes or escaped these are treated as spaces, and therefore
serve to separate arguments. (Also, although unquoted uppercase
alphabetic is still translated to lowercase, the initial DCL
translation of lower to upper is absent -- thus in a file,
a\bc\d will give all lowercase). Files may contain further 'file
expansion' arguments of the same kind.
Note also that in a file of arguments a line containing a single
@ character (and not inside quotes) is taken as end-of-file.
While there is no need to use this when filename is an ordinary
disk file, it is occasionally useful for delimiting the end of
the arguments when using @sys$input in a DCL command stream,
etc.
poparg0 -> string [protected variable]
This is the first element of poparglist0 as it was before
startup processing. (In particular, before any rewriting of
poparglist0 in response to pop_X environment variables in Unix.
If no such rewriting occurred, it is the same as
hd(poparglist0).)
poparg1 -> string [active variable]
This active variable returns the first item from poparglist0
after poparg0 and any subsequent specially flagged arguments
(i.e. those beginning with `+`, `-`, or `%`). If no such item is
present in poparglist0, false is returned instead. Libraries
that take special action if loaded on Poplog startup may need to
examine poparg1 (see LIB * MKREFINDEX for an example).
poparglist -> list [variable]
list -> poparglist
This is a trailing sublist of poparglist0 (possibly empty),
excluding those arguments that have already been processed (as
described in the sections above).
pop_nobanner -> bool [variable]
bool -> pop_nobanner
This variable is set by the %nobanner argument to Poplog. If
set, printing of the Poplog banner is suppressed. Its default
value is false.
pop_noinit -> bool [variable]
bool -> pop_noinit
This variable is set by the %noinit argument to Poplog. If set,
it suppresses the call of "init" files on normal Poplog
language-image startup (see below). This means that 'init.p'
files, etc will not be compiled.
sys_process_poparg1(expr_compiler, file_compiler, extn) [procedure]
This procedure implements standard Poplog argument processing
for expression or file compilation. It examines the first item
in poparglist.
If that item begins with a colon (:), the procedure
expr_compiler is applied to a character repeater that contains
all the characters (except the colon) from all the strings in
poparglist.
Otherwise, the first item in poparglist is considered to be a
filename. If it doesn't include an extension part, extn (which
should be a string) is appended.
If the filename includes a directory part, the procedure
file_compiler is applied to it. Otherwise, for each directory
name specified in the environment variable "popcomppath",
file_compiler is applied to the directory name concatenated with
the filename. In either case, if file_compiler returns a
non-false result, sys_process_poparg1 returns; otherwise, a
mishap results.
On normal Pop-11 startup, sys_process_poparg1 is invoked (from
syssetup) as follows:
sys_process_poparg1(pop11_compile, trycompile, '.p')
sys_parse_poparglist(argspec, arglist) -> (prop, rest) [procedure]
This procedure is used for processing Unix shell-style command
line arguments to Poplog. It assumes that arglist is a list of
the form
[ flag1 arg1 flag2 arg2 ... ]
where arg1, arg2 etc are optional.
sys_parse_poparglist returns two results, a property prop
mapping flags specified in argspec to argument values from
arglist, and rest, a list of the items remaining in arglist
after all the flags and their associated arguments have been
removed.
argspec should be a list of two-element lists or vectors, each
of the form
[ flag 0-or-1 ]
If the second element is 0, then an occurrence of flag in
arglist will cause true to be associated with it in the property
prop. If the second element is 1, then an occurence of flag in
arglist will cause the item following flag to be associated with
it in the property prop.
sys_parse_poparglist will signal errors in the following
situations: if the same flag occurs more than once in arglist,
or if a flag that should be followed by argument is not followed
by one.
An example:
vars p r;
sys_parse_poparglist(
[['-a' 1] ['-b' 0] ['-c' 1]],
['-c' 3 '-a' 1 '-b' 4 5 6]) -> (p, r);
p('-a') =>
** 1
p('-b') =>
** <true>
p('-c') =>
** 3
r =>
** [4 5 6]
sys_parse_poparglist is not used during the standard Poplog
startup sequence; it is intended for library programs that are
run as arguments to Poplog (e.g. LIB * MKIMAGE).
sysinitcomp() [procedure]
Called by the standard Poplog language images on startup to
compile 'init.p' files (except when invoked with expression/file
compilation arguments, etc, or when Poplog was given the %noinit
special flag).
If it exists, '$popsys/init.p' ('popsys:init.p' on VMS, etc) is
first compiled; then if '$poplib/init.p' exists, that is
compiled, otherwise 'init.p' in the current directory if that
exists.
setpop() [procedure]
Resets the Poplog system: unwinds all procedure calls, restoring
dynamic local values, and clears the user stack, etc.
If this is the first setpop (indicated by pop_first_setpop
true), or if standard input (pop_charin_device) is a terminal,
then pop_setpop_compiler is called to (re)start compilation.
Otherwise, sysexit is called to exit the system.
If compilation is restarted, pop_first_setpop is set false, and
the variables cucharout and cucharerr are set to charout and
charerr respectively.
pop_setpop_compiler() [protected procedure variable]
Called by setpop after the system has been reset.
In the base Poplog executable and standard language images, the
default value of this variable is a procedure which (re)starts
compilation for the subsystem specified by the variable
subsystem. That is, it
o Checks that the compiler and other procedures for
subsystem are loaded;
o Calls the subsystem SS_RESET procedure;
o Calls the subsystem SS_COMPILER procedure with charin as
argument.
In addition, the variable pop_compiler_subsystem is locally set
to subsystem (meaning that this represents a compiler-subsystem
barrier). See REF * SUBSYSTEM for information about subsystems.
pop_setpop_compiler is also called by vedsetpop after resetting
'immediate mode' in Ved. (vedsetpop locally redefines it to
perform the same actions as above, but with vederror called
instead of mishap if errors occur, etc.)
(Note however, that in the XVed standalone image, the top-level
value of pop_setpop_compiler does something different. It does
not a run a top-level compiler, but merely waits for and
processes XVed events.)
pop_first_setpop -> bool [variable]
bool -> pop_first_setpop
true before setpop is first called, and thereafter false.
(Although setting it back to true will force the next setpop to
reset, regardless of whether pop_charin_device represents a
terminal.)
------------------
6 Runtime Actions
------------------
Poplog compilers generally allow source files to contain `top-level'
code, that is, code which is executed at compile-time to perform various
setting-up actions.
However, when compiling source code to produce a saved image (or
compiling with Popc to produce an executable image, etc), the
compile-time execution of some kinds of action may be inappropriate
because they depend on the run-time environment in which the image will
actually be used (for example, a procedure that sets up for a particular
type of terminal).
The system therefore provides a mechanism whereby such actions can be
automatically deferred until the appropriate time. Essentially, this
comes down to a global list of procedures (pop_runtime_actions), which
are executed whenever an image or saved image starts up -- UNLESS that
image is run with the special argument %nort. That is, the system
assumes that `now' is `run-time' except when this argument is present.
Action procedures are accumulated in the first place (in
pop_runtime_actions) by the procedure sys_runtime_apply. This tests the
boolean variable pop_runtime to determine whether an action should be
executed immediately or added to pop_runtime_actions. However,
pop_runtime can only be set by the system on image startup, because when
one image is being built on another, all actions from the first image
must go un-executed into the new image (together with any new ones).
Thus pop_runtime is only false when the current image was run with
%nort. Running an image without %nort sets it true, as well as executing
any existing actions.
pop_runtime -> bool [protected variable]
This boolean variable indicates whether `now' is `runtime' or
not. It will have a true value unless the current image/saved
image being run was given the startup argument %nort.
When true, its value is either the boolean true or the word
"undef" ; the latter value indicates that the image did not have
any runtime actions. Thus true indicates that actions have
actually been run.
(N.B. Rather than setting it false, %nort actually leaves the
value of pop_runtime unaltered. Thus %nort doesn't actually
guarantee that pop_runtime is false, since it may have been true
already in the image. However, this can only happen when running
a `compromised' saved image, i.e. one created after runtime
actions have been run, and will NOT occur with any of the
standard Poplog saved images or the base system.)
pop_runtime_actions -> list [protected variable]
The list of action procedures to be executed at runtime. If
pop_runtime is true this list will always be empty, since any
existing actions will have been run already, and no new ones
will accumulate.
(Note that when running action procedures on image startup, this
list is tailed before running each procedure; thus an action
procedure can determine which procedures are yet to be run.)
sys_runtime_apply(action_p) [procedure]
This procedure `applies' a runtime-action procedure action_p.
That is, if pop_runtime is already true it simply calls
apply(action_p)
Otherwise, if pop_runtime is false, it adds action_p to the end
of the list of procedures in pop_runtime_actions.
-----------------------------------
7 Starting up X-Windows Facilities
-----------------------------------
As explained above the command line flag %x can be used to assign a
non-false value to popunderx. This also causes sysxsetup to be run.
Instead of using the command line, users who expect always to be running
Poplog under X windows may put into their init.p files something like:
unless islist(popunderx) do
[] -> popunderx;
sysxsetup();
endunless;
popunderx -> list_or_false [variable]
list_or_false -> popunderx
This variable is set to a list if the %x command line flag is
used when Poplog is started up, as described above. Otherwise it
is assigned the default value false.
If %x is followed in the command line by a bracketed list of
arguments i.e. between `(` and `)`, then a corresponding list of
strings is constructed and assigned to popunderx. If %x is not
qualified, nil is assigned to popunderx. If popunderx has a
non-false value, various procedures will assume that Poplog is
running under X. (This may cause obscure errors if no X server
is available.)
sysxsetup() [procedure variable]
This procedure is run by syssetup if popunderx is non-false (eg,
when Poplog is invoked with the %x flag.) Its default value is a
procedure which simply calls XptDefaultSetup to create an
application context with name derived from -poparg0- and class
'Poplog' (for use in app-defaults, .xrdb files etc), and then to
create a single display connection. These are stored in
XptDefaultAppContext and XptDefaultDisplay (initially, they are
false).
The user's init.p file, or some other program can directly run
sysxsetup or XptDefaultSetup whether or not the %x flag has been
used. Knowledgeable users may set up connections to an X server
in other ways. See also HELP * X
Since syssetup calls sysxsetup after sysinitcomp, sysxsetup can
be redefined in init.p or initx.p if desired.
--------------
8 System Exit
--------------
sysexit() [procedure]
Exits the Poplog system: closes all files and returns to the
operating system: the variable procedure popexit is called
before doing this. sysexit is called by setpop when it reads
<termin> from the standard input.
popexit() [procedure variable]
Holds a procedure to be run on exit from the system, i.e. when
sysexit is called (thus the procedure in popexit may prevent the
system from actually exiting, e.g. by doing a setpop). Default
value is identfn.
(Note that in Unix Poplog, sysexit is called in certain 'fatal'
conditions where the system is forced to exit, for example by
HUP or TERM signals (see REF * ASYNC). Since attempting to do
I/O on terminals in this state may cause the process to hang,
any of the standard devices popdevin/out/err and poprawdevin/out
which represent a terminal are replaced by null devices. popexit
procedures which attempt to do terminal I/O should therefore
take this into account, by first testing whether the appropriate
device is in fact a terminal (and do nothing if not). The
correct test to use in this context is
systrmdev(dev) == true
which will be true only if dev is a terminal and, in systems
with Berkeley job control, only if the process is a foreground
job -- see REF * SYSIO.)
pop_exit_ok -> bool [variable]
bool -> pop_exit_ok
Controls the status value returned by sysexit to the operating
system: if false, the standard error code (1 in Unix, SS$_ABORT
in VMS) is returned, otherwise the standard success code (0 in
Unix, SS$_NORMAL in VMS).
The default value is true, but note that a call of mishap will
set it false if the standard input is not a terminal (since the
default value of interrupt under these circumstances is sysexit,
this guarantees that a mishap will result in an error status
being returned). It is also set false by the default signal
handlers for HUP and TERM (see popexit above).
fast_sysexit() [procedure]
Exits the Poplog system without doing any of the tidying actions
described above. That is, it does not flush internal buffers,
does not call popexit and does not write unwritten Ved files.
-------------------
9 Store Management
-------------------
popgcratio -> int [variable]
int -> popgcratio
Controls the weighting of garbage collection time in determining
memory allocation for the system. After each garbage collection,
the decision as to whether expand or contract memory is made by
computing
(average automatic GC CPU time) * popgcratio
-------------------------------------------- - 1
(average program CPU time between GCs)
and then expanding or contracting by an amount proportional both
to this value, and to the amount of new memory used for
structures since the last garbage collection.
The maximum permitted value for popgcratio is 1024, default
value is 40.
popmemlim imposes an absolute upper limit on the amount of
expansion. If this is set too low, the frequency of garbage
collections may be far greater than necessary.
Also see * popgctrace.
popmemlim -> int [variable]
int_or_false -> popmemlim
This (active) integer variable specifies the (approximate)
maximum number of words to which the system should expand the
combined memory area for the heap and user stack. When reached,
(or on some occasions, slightly exceeded), the system will not
expand further, and the mishap
'ROM: MEMORY LIMIT (popmemlim) EXCEEDED (using XXXX space)'
results. Here XXXX is 'heap', 'stack' or 'fixed' to indicate
whether the memory allocation request that caused the mishap was
for an ordinary heap structure, the user stack, or a
fixed-address heap structure.
The default value is 300000 (but higher defaults are used by the
Prolog and Lisp systems); if this is not large enough for your
program, you should experiment with increasing it gradually
(e.g. in steps of 100000, or doubling it, etc). Increasing it by
too large an amount may cause garbage collections to become
slower, by virtue of there being insufficient extra memory
available to use the copying algorithm (see pop_gc_copy and
popgctrace below).
Assigning false (or a positive biginteger) to popmemlim is the
same as assigning the maximum possible value (i.e. the largest
simple integer).
Note that, regardless of popmemlim, the mishap
'ROM: NO MORE MEMORY AVAILABLE (needing XXXX space)'
may also occur. This indicates that the system can expand no
further, because no more memory can be allocated from the
operating system (either because of a set limit on process size,
or through a lack of swap space, etc).
popmemlim cannot be set smaller than the current size of the
heap/user stack area; any value less than this will be replaced
with the current size.
(See also pop_callstack_lim in REF * PROCEDURE and
pop_prolog_lim in REF * PROLOG.)
popminmemlim -> int [variable]
int -> popminmemlim
This (active) integer variable specifies the minimum number of
words at which the system should maintain the combined heap/user
stack memory area. When below this limit, the system will expand
up to it at the next garbage collection (if it can); thereafter,
it will never contract below this limit.
sysgarbage() [procedure]
Forces the system to do a garbage collection. (Note that the
time for such a user-invoked garbage collection is not included
in the automatic GC time total -- see popgcratio below).
(For information on user-specified actions to be performed when
a structure is about to be garbage collected, see
REF * sys_destroy_action.)
pop_after_gc() [procedure variable]
The procedure in this variable is run after every garbage
collection (default value identfn).
pop_gc_copy -> bool [variable]
bool -> pop_gc_copy
If this variable is true (the default), then garbage collections
use a 'copying' algorithm, which temporarily requires the
allocation of extra memory in which to copy all non-locked heap
structures; otherwise (or if the required extra memory is not
available), a 'non-copying' algorithm is used.
The non-copying algorithm is generally 25% - 50% slower than the
copying one (although in some situations it may be faster, and
therefore worth setting this variable false). (Note however that
at certain times the system needs to be able to shift heap
structures up in memory, and requires the copying algorithm to
do this; thus copying collections may still occur when
pop_gc_copy is false.)
popgctrace -> bool_or_int [variable]
bool_or_int -> popgctrace
If this variable (default value false) is true then a message is
output after each garbage collection, giving the GC time and
details of memory allocation (the characters of the message are
output through cucharout).
The first line of the message has the form
GC-code(X) time MEM: u used + f free + s stack = total
where code is a 4-letter code indicating why the GC happened,
and time is the time for the garbage collection in seconds. X is
a letter indicating which garbage collection algorithm was used
(C = copying, N = non-copying).
Values for code are as follows:
code Reason Indicated
---- ----------------
auto The combined area for relocatable structures and the
user stack was full.
fixd The area for fixed-address structures was full.
ftbl The internal table of open files/devices was full
when trying to open a device. (A GC can free space
in this table by closing and removing garbage
devices.)
fopn The operating-system imposed limit on the number of
open devices was reached when trying to open a
device. (By closing garbage devices, a GC can make
more available.)
plog The combined area for the Prolog trail and
continuation stack was full.
save GC done by syssave.
lock GC done by sys_lock_system.
user Direct call of sysgarbage from a user program.
If popgctrace has any non-false value other than an integer,
only the first line is output. Additional information is
obtained by giving it an integer value, whose bits select
further message lines as follows:
Bit Meaning
--- -------
0 Same as setting both bits 2 and 3 (for upward
compatibility in assigning 1 to get the callstack
and Prolog information).
1 Fixed-address structures; prints
FIXED: u used + fb freeblks + f free = total
where used is the number of words used by fixed
structures, freeblks the number used up in
(discontiguous) free blocks, free the number of
(contiguous) free, and total the total. These values
are included in the first-line totals, freeblks and
free being subsumed together under total words free.
(Note that space for fixed-address structures is
allocated from free blocks if possible, but because
of fragmentation a given figure for freeblks doesn't
imply that that much is actually usable in any
context.)
2 Callstack; prints
CALLSTACK: cstack
where cstack is the number of words used by
procedure-call stack frames.
3 Prolog store area; prints
PROLOG: trail trl + free free + contn ctn = total
where trl is the number of words used by the trail,
free the number free, ctn the number used by the
continuation stack, and total the total.
The MEM figures refer to totals for all heap segments: used is
the number of words used by structures, free the number free,
stack the number taken by the user stack, and total the total.
If the heap is locked with sys_lock_heap then an additional
l lock figure precedes used, i.e.
GC-code(X) time MEM: l lock + u used + f free + s stack = total
where lock is the total number of words in the locked part of
the heap (note this includes both used and unused space).
popgctime -> int [protected variable]
Contains the total cpu time spent doing non user-invoked garbage
collections, in 1/100ths second. Also see popgctrace and
systime.
popmemused -> int [protected variable]
Contains the total number of words of heap memory in use at the
last garbage collection.
sys_lock_heap() [procedure]
Tells the system to 'lock' the heap at its current endpoint. The
effect of this is that all structures in the heap before this
point will automatically be treated as non-garbage (considerably
reducing the amount of work needed to be done on them during a
garbage collection). Structures created after the sys_lock_heap
will be treated normally.
It is sensible to call sysgarbage before sys_lock_heap. E.g. at
the end of a file which compiles a lot of procedures which are
not going to be edited, do
sysgarbage(); sys_lock_heap();
See also sys_lock_system below.
sys_unlock_heap() [procedure]
Reverses the effect of sys_lock_heap, so that all structures
previously locked in now participate fully in the next garbage
collection.
pop_malloc_min_alloc -> Nbytes [variable]
Nbytes -> pop_malloc_min_alloc
(Unix Only) This active variable controls the minimum amount of
memory that Poplog's version of UNIX * malloc should request
from the operating system each time it requires further new
memory.
Continual malloc requests for new memory (i.e. resulting from
external procedure calls) may lead to excessive segmentation of
the Poplog heap if they alternate too frequently with Poplog
heap expansion, and may eventually result in Poplog's heap
segment table overflowing (with the mishap 'MEMORY SEGMENT TABLE
FULL').
Assigning a higher value to pop_malloc_min_alloc will cure this
problem.
-----------------------------------------
10 Saving and Restoring the System State
-----------------------------------------
There are two procedures that create Poplog saved images: syssave and
sys_lock_system. The latter is always to be preferred for creating a
proper `system' image (even without other layers on top), and is
described in the next section.
Note that from Version 14.1 of Poplog, there is an essential interaction
between saved images and runtime actions (see Runtime Actions above).
Basically, this means that any saved image created after runtime actions
have been executed is `deficient' or `compromised' in the sense that it
may fail to work properly in one or more respects (or indeed, at all).
This happens when the system in which you are saving the image was NOT
started with the special argument %nort.
If you are just using e.g. syssave to save some work informally, this
may or may not matter (and in any event, cannot be helped). To use
either procedure to create a `proper' (or `production quality') saved
image, you MUST run the image in which you compile your system with the
%nort argument (which allows runtime actions to accumulate and go
unexecuted into your saved image).
(Runtime actions are particularly relevant to certain uses of externally
loading -- in fact, the main purpose for which they were introduced. See
REF * EXTERNAL.)
syssave(filename) -> restored [procedure]
Saves the total state of the Poplog system in a file called
filename (this includes the state of external loading -- for
details see REF * EXTERNAL).
The result of this procedure is false on immediate return; on
restoring the file with sysrestore (qv) the result will be true.
filename may be either a word or a string: if a word, '.psv' is
appended.
(In VMS, see Note on VMS Saved Images below.)
sysrestore(filename) [procedure]
sysrestore(filename, mode)
Restores the Poplog system to be in the state it was at the time
the saved image specified by the filename filename was created
(with syssave or sys_lock_system). Note however that
¤ The standard files (popdevin, popdevout, popdeverr);
¤ poparglist and popenvlist;
¤ poppid and popusername.
all remain as they were before the call of sysrestore.
When this procedure exits, it will be as if the call of syssave
or sys_lock_system that created the file had returned, but with
true as result instead of false.
By default, a mishap will result if either (a) filename does not
exist, or (b) the identification string from filename does not
match the current value of pop_system_version (i.e. filename may
only be restored into the same system environment in which it
was created).
The optional boolean argument mode can be used to prevent a
mishap occurring in either of these cases. false means no mishap
for case (a), true means no mishap for either (a) or (b).
Instead of producing a mishap, sysrestore will simply return to
its caller (with no result).
filename may be either a word or a string: if a word, '.psv' is
appended.
VMS Note: If filename is a shareable image created by
sys_lock_system the nonwriteable part of filename will be shared
between all users in the same group, unless filename has been
installed with sys_install_image to be shareable system-wide
(i.e. there is a permanent system global section for it).
pop_after_restore() [procedure variable]
The procedure in this variable is run by sysrestore immediately
after a successful restore and before returning (default value
identfn).
10.1 Creating Layered Systems
------------------------------
The procedure sys_lock_system makes possible the creation of layered
systems in Poplog. It takes the current heap endpoint to be the boundary
of a self-contained 'system' on top of which other layers will be built,
and is similar to a sys_lock_heap combined with an (optional) syssave to
create a saved image for the new system. However, its behaviour differs
from this in two important respects:
First, the locking of the current contents of the heap is permanent,
and cannot be undone; the structures locked in cease to be 'part of the
heap', and become 'part of the system'. Second, all (relocatable)
structures are partitioned into two areas of memory: writeable and
nonwriteable (the structures put in the nonwriteable area become
physically write-protected, so that any subsequent attempt to update a
field in one of them will cause an error). The importance of this
partitioning is that
(a) nonwriteable structures mean that garbage collection time is
reduced (since the garbage collector can just ignore them);
(b) if a saved image is being created, the area of nonwriteable
structures can (at least in principle) be made shareable by all
users of the saved image;
(c) it is unnecessary for the nonwriteable area to be saved when
creating further saved images on top of the new system (either
with syssave or with another sys_lock_system).
(Note that a major consequence of (c) is that subsequent saved images
created on top of the new system can only be restored into the
environment of that system, and NOT into basic Poplog -- i.e. one saved
image must be layered on top of another.)
The above considerations make it desirable that as many structures
as possible go into the nonwriteable area. To facilitate this, and to
provide means to ensure that structures that must be writeable are kept
so, there is a 3-level mechanism for specifying which structures should
be put where:
(1) At an individual level, with the property sys_writeable_prop
(and the operators writeable and nonwriteable which assign to
it, see below). An individual structure can be marked as
definitely writeable or definitely nonwriteable.
(2) A class default, with an optional "writeable" or "nonwriteable"
attribute for the key of a class of structures (see conskey in
REF * KEYS). If present, this default is used for any structure
of the class not individually marked in (1).
(3) A general default specified directly to sys_lock_system, for
anything not covered by (1) or (2).
Of the data structures built into the system, all the 'non-specialised'
types such as pairs (and so lists), and the vector-classes (strings,
full vectors, etc), have neither a writeable or nonwriteable class
default. They are thus governed by the general default given to
sys_lock_system, and for this to be nonwriteable you may need to apply
writeable to some individual structures of this type (as system and
library code does). (The one exception to this is single-element
references: these have a writeable class default).
Otherwise, specialised built-in types have a default which reflects
their function, e.g words and variable identifiers are always kept
writeable; numbers such as bigintegers, ratios and complex which have no
updateable fields are nonwriteable, etc. Certain specific structures the
system knows cannot be updated are also made nonwriteable (such as the
strings of word records). The default for any existing key can be
determined with class_attribute (see REF * KEYS).
One class requiring special mention is procedures (and closures in
particular). These have a nonwriteable default, and so the pdprops and
updater fields become non-assignable in any procedure not individually
marked writeable; for closures this applies to the pdpart and frozval
fields also. However (since they are sometimes used in a 'data
structure' mode where the frozvals need to be updated), sys_lock_system
allows a writeable default for closures to be specified.
(N.B. None of the above applies to fixed-address structures used
with external procedures. These cannot be moved into nonwriteable areas,
and so always remain writeable.)
sys_lock_system(false, mode_flags, system_id) [procedure]
sys_lock_system(filename, mode_flags, system_id) -> restored
Permanently locks the current heap as a new 'system',
partitioning all relocatable heap structures into writeable and
nonwriteable memory areas, and optionally saves the system state
in a saved image (see the general description of this procedure
above).
(Note that the variable pop_record_writeable should usually be
set true before commencing compilation of a program to be saved
with sys_lock_system -- see Note 1 below.)
The arguments are as follows:
filename
false in the first form, or a filename string in the second.
If filename is supplied, then following the
writeable/nonwriteable partitioning, a 'special' call of
syssave with filename argument filename creates a saved
image to preserve the initial state of the new system. The
result of syssave is returned as the result of this
sys_lock_system, i.e. false after saving, true on restoring.
(The call is 'special' in the sense that it saves the
nonwriteable area, whereas any subsequent syssave or
sys_lock_system will not.)
When the argument is false, no saved image is created, and
no result is returned.
mode_flags
An integer argument, in which bits 0 - 2 have the following
meanings:
Bit Meaning
--- -------
0 On restoring the saved image, this bit controls
whether the memory into which the nonwriteable area
is mapped will be shared by all users of the image
(but see Note 4 below):
0 = unshared, 1 = shared
1 This bit determines the default placement for all
structures not individually or class-marked as
writeable/nonwriteable:
0 = writeable, 1 = nonwriteable
2 Normally, closures not individually marked
writeable/nonwriteable default to nonwriteable
(since they are procedures, and procedures are
class-marked nonwriteable). Setting this bit allows
user closures (but not protected system ones) to
default to writeable:
0 = closures nonwriteable, 1 = closures writeable
(N.B. For compatibility with older versions of Poplog, the
mode_flags argument may also be a boolean, true being
equivalent to 2:001 and false to 2:000, i.e. general default
writeable/closure default nonwriteable, with or without
sharing.)
system_id
A system identification string. As mentioned above,
subsequent saved images created in the new system
environment can be only restored into the same environment
(either without ever leaving it or after restoring the
system saved image). To ensure that any attempt to do
otherwise is trapped as an error, the variable
pop_system_version holds an identification string for the
current system, this being recorded on any saved image
created therein. sysrestore will produce an error if asked
to restore an image whose identification does not equal the
current value of pop_system_version.
For the new system being created, pop_system_version is set
to the system_id string 'timestamped' by concatenating
sysdaytime() onto the end.
Notes
(1) The variable pop_record_writeable should usually be set true
before commencing compilation of a program to be saved with
sys_lock_system. This is because many system and library
routines rely on the writeable operator to ensure that
individual structures they use are kept writeable (which
becomes ineffective when pop_record_writeable is false).
To guard against this, sys_lock_system will mishap if any
necessary call to writeable was ignored owing to
pop_record_writeable being false. 'Necessary' in this sense
means that (with the given mode_flags argument) the
structure(s) for which writeable was ignored would become
nonwriteable.
(2) After processing the entries in sys_writeable_prop, the
property is cleared (since the entries are of no further
use). In addition, pop_record_writeable is set to false
afterwards.
(3) To reflect the fact that the nonwriteable and writeable
areas have been removed from the heap, popmemlim and
popminmemlim are reduced by their total size (but for
popmemlim, not below 32K words).
(4) Although bit 0 in the mode_flags argument may always take
either value, whether or not sharing actually happens
depends upon the operating system. Currently (May 1995),
sharing is possible in VMS, Sun0S and OSF1 (but not HP-UX).
(In addition in VMS, sharing is only between users in the
same group unless the procedure sys_install_image is used to
make the image globally shareable, see below. Don't make a
VMS image shared unless it really needs to be, i.e. will be
used concurrently by several users on a regular basis, since
shared images consume VMS system resources.)
(5) In VMS, see also Note on VMS Saved Images below.
sys_writeable_prop(item) -> status [procedure]
status -> sys_writeable_prop(item)
This is a temporary property whose entries are scanned by
sys_lock_system (and Popc compilation) to determine
writability/non-writability for individual structures (after
which the property is cleared).
If an entry exists for a given item, its status value must be a
boolean, true meaning writeable, false meaning nonwriteable (the
default value of the property, when no entry exists, is the word
"undef").
N.B. Any entry in the property for a non-heap structure or
simple object will be ignored.
writeable item -> item [operator 1]
nonwriteable item -> item [operator 1]
These two operators provide a convenient way of making entries
for individual structures in sys_writeable_prop, but doing so
only when sys_lock_system is going to be used (as indicated by
pop_record_writeable being true).
If pop_record_writeable is true, item is marked with an
appropriate entry in sys_writeable_prop, true for writeable and
false for nonwriteable. However, there are two special cases:
¤ If item is a pair whose back is another pair, then the
back pair is also marked (and so on recursively, allowing
all pairs in a list to be marked writeable/nonwriteable);
¤ If item is an array procedure, then the arrayvector of
item is marked, not item itself (since this is what will
actually be updated if the array is assigned to).
In any event, both operators return the argument item as result.
This allows them to be used e.g. in front of constructor
expressions like
constant list = writeable [%1, 2, 3, 4%];
etc.
pop_record_writeable -> bool [variable]
bool -> pop_record_writeable
Unless sys_lock_system is going to be used, entries made in
sys_writeable_prop are wasted space. This variable allows
writeable and nonwriteable to be used freely in programs
(including system and library code), while preventing them
making sys_writeable_prop entries except when necessary.
Since its default value is false, it should usually be set true
before commencing compilation of a program to be saved with
sys_lock_system. (It is automatically set true during
compilation of a file with Popc.) sys_lock_system will in fact
mishap if any necessary call to writeable was ignored owing to
pop_record_writeable being false (see Note 1 under
* sys_lock_system above).
sys_install_image(filename, install) [procedure]
This procedure is currently available only in VMS systems. In
VMS, the nonwriteable part of a shareable saved image created by
sys_lock_system is by default shared only between users in the
same group; this procedure enables or disables its sharing by
all users in the system. To operate, however, the Poplog process
running the procedure must have the privileges
SYSGBL (create/delete system global section)
PRMGBL (create/delete permanent global section)
If the boolean argument install is true, the image specified by
filename is 'installed', i.e. made shareable system-wide. (The
blocks comprising the nonwriteable area are made a permanent
system global section.)
If install is false, filename is de-installed and will revert to
group sharing. (An existing permanent system global section for
filename is deleted.)
10.2 Note on VMS Saved Images
------------------------------
Poplog, in common with other VMS programs, uses VMS shareable images.
Certain standard shareable images are already in use in the basic Poplog
system (popsys:basepop11.exe), and others may be externally loaded while
the system is running (see REF * EXTERNAL). In both cases, the shareable
images reside in fixed size memory areas inside Poplog, and this is
reflected in the saved images produced by both syssave and
sys_lock_system: when a saved image is restored, the shareable images
are activated and mapped into their appropriate areas.
However, in new releases of VMS, standard shareable images can grow
in size (through addition of new facilities or extensions to existing
ones). If the total growth in a new release is too much, one or more
images may overflow the area Poplog had allowed for them at the time a
saved image was created, and in this event the saved image cannot be
restored. (Thus a saved image may work in the VMS release in which was
created, but fail to work in a later release.) If this happens, the
mishap
crsv: CAN'T RESTORE - VMS SHAREABLE IMAGES HAVE EXPANDED,
NEED TO REBUILD SAVED IMAGE
occurs.
Although there is no complete solution to this problem, the system
does allow you to control the `safety margin' of space it leaves free
for shareable image expansion. This is specified by giving the logical
name
pop_shrim_margin
an integer percentage value; the system will then leave that percent of
the shareable images' size free for expansion. For example, the DCL
command
$ define pop_shrim_margin 20
will allow 20% for expansion. (If "pop_shrim_margin" is not set, the
default is 10%.)
The mishap above also tries to be helpful in this respect by printing
out
INVOLVING: 'expansion margin allowed A%, needed N%'
where A was the expansion margin allowed for when the saved image was
built, and N is the (minimum) margin that would have actually been
needed for the saved image to restore successfully.
Note that as regards those shareable images already in use in the
basic Poplog executable, "pop_shrim_margin" is only effective for a
saved image created directly on top of basic Poplog. For example, if you
are creating a saved image on top of the standard Prolog saved image,
and you wish to give it a bigger safety margin, you must first remake
the standard Prolog image with "pop_shrim_margin" set accordingly (and
then rebuild your image on top -- for which "pop_shrim_margin" becomes
irrelevant unless your program involves other externally-loaded
shareable images).
Unfortunately, there is no way of predicting by how much shareable
images will expand in any given release of VMS. A 10% expansion margin
is probably sufficient to cope with at least one new release, and
possibly two or three, but this cannot be guaranteed.
... Alpha VMS
--------------
In Alpha VMS, "pop_shrim_margin" applies only to those shareable images
used by the basic Poplog executable popsys:basepop11.exe (at least, for
`proper' saved images created with %nort).
This is because when compiling code to create a saved image on top of
another Poplog image started with %nort, a request to externally-load a
new shareable image does not actually result in that image being
activated; rather, the shareable image is only activated when the
created saved image is run (i.e, run without %nort).
Hence the externally-loaded shareable image does not occupy any memory
locations in the saved image, and the "pop_shrim_margin" problem does
not occur.
--------------------------------
11 Incremental Save and Restore
--------------------------------
(Note that the procedures in this section are defective, in that they do
not cope with Pop-11 sections and a number of other things. Their use is
therefore deprecated.)
syssaveincr(filename, item) [procedure]
Saves, in a file called filename, all structures that can traced
from the item item, i.e. item, all structures that item
references, that those structures reference, and so on.
However, although references to any structure which is part of
the system are saved, anything referenced BY that system
structure will not be saved. Thus, for example, if cucharout has
been given a particular value, this value will not be saved. To
obviate this problem, if item is a list then the following
happens: item and all structures traceable from it will be
saved, but in addition, permanent identifiers associated with
any system words occurring in item will also be saved. Thus
every system word required to be saved must be mentioned
explicitly in the list item.
See sysrestoreincr for what happens when the file is restored.
Example:
vars list = [1 2 3 4];
syssaveincr("save", "list");
saves the word "list", its identifier and the list it contains,
in a file called 'save.psi'.
filename may be either a word or a string: if a word, '.psi' is
appended.
sysrestoreincr(filename) [procedure]
sysrestoreincr(filename, mode)
Restores all the structures saved with syssaveincr in the file
filename. Any words that were in the dictionary at the time of
saving are restored to the dictionary if not already there,
associated permanent identifiers being set to their saved
values. Any system words explicitly saved also have associated
permanent identifiers restored. E.g. restoring the example given
in syssaveincr:
sysrestoreincr("save");
list =>
** [1 2 3 4]
restores the file called 'save.psi', i.e. the word "list", its
identifier and the list it contains.
filename may be either a word or a string: if a word, '.psi' is
appended.
The optional mode argument is the same as for sysrestore, qv.
-------------------------
12 System Identification
-------------------------
12.1 Poplog Version
--------------------
pop_internal_version -> int [constant]
This is a simple integer defining the version of the Poplog
system in use, in the form
(major * 10000) + minor
where major is the major version number and minor the minor
version number within the former.
popversion -> string [protected variable]
Contains an identification string giving the version number and
creation date of this Poplog system, e.g.
'(Version 12.3 Thu Nov 20 20:54:11 GMT 1987)'
Note that the version number appearing in this string is derived
as
pop_internal_version/10000.0
pop_system_version -> string [protected variable]
Contains the identification string for the current system and
version, used by syssave and sys_lock_system to record the
identity of the system in which a saved image is being created,
and by sysrestore to check that identity when restoring. Only
sys_lock_system alters this variable; in the base Poplog system,
it has the same value as popversion.
popheader -> string [variable]
string -> popheader
This is a banner string, normally printed out when Poplog starts
up in normal mode (i.e. when not invoked with arguments), and
thereafter made false to indicate that the banner has been
printed. The string is constructed as
'Sussex Poplog ' <> popversion
e.g.
'Sussex Poplog (Version 12.3 Thu Nov 20 20:54:11 GMT 1986)'
popcopyright -> string [constant]
The Poplog copyright string, printed after the banner.
12.2 Machine & Operating System
--------------------------------
sys_host_id() -> host_id_list [procedure]
Returns a list of one or more items identifying the host
machine, or false if this cannot be determined.
Under Unix System V Release 4, the result is a 1-element list
containing the result returned by a call to UNIX * sysinfo with
command SI_HW_SERIAL. In general this will be a string, but
where the string consists only of decimal digits it is converted
to a (big)integer before being returned.
On Berkeley Unix systems, the result is a 1-element list
containing the integer returned by the UNIX * gethostid system
call; on the HP Bobcat, the result is false (since HP-UX
currently has no gethostid call).
On VMS, the result is a 2-element list containing the integers
returned by the sys$getsyi system service for the function codes
SYI$_SID (System Identification) and SYI$_CPU (CPU type).
sys_host_name() -> host_name [procedure]
Returns the name of the host machine as a string, or false if
this cannot be determined.
Under Unix System V Release 4, this procedure returns the result
of a call to UNIX * sysinfo with command SI_HOSTNAME.
On Berkeley Unix systems (including the HP Bobcat), it returns
the result of the UNIX * gethostname system call.
On VMS, it returns the translation of the logical name
"sys$node".
sys_machine_type -> list [constant]
This is a list of words and numbers describing the generic
machine type on which Poplog is running. Current possible values
are:
[vax]
[sun3]
[sun4]
[hp9000 300]
[hp9000 700]
[iris]
[decstation]
[alpha]
sys_os_type -> list [constant]
This is a list of words and numbers giving attributes of the
operating system under which Poplog is running. Current possible
values for the start of this list are:
[vms 5.5] ;;; VMS VAXs
[vms 6.1] ;;; VMS Alphas/VAXs
[unix sunos 4.1 ...] ;;; Sun workstations
[unix sunos 5.3 ...] ;;; Sun workstations (Solaris 2.3)
[unix hpux 9.0 ...] ;;; Hewlett-Packard 9000
[unix irix 4.0 ...] ;;; Silicon Graphics IRIS
[unix ultrix 4.3 ...] ;;; DEC RISC
[unix osf1 3.0 ...] ;;; Alpha OSF1
In Unix systems, the list also contains another two elements,
viz
[... posix vector]
where vector is a full vector whose N-th element gives the
revision date of the POSIX-N standard available on this platform
(or false if POSIX-N is not available). For example:
[unix sunos 5.3 posix {199309}]
[unix osf1 3.0 posix {199009 199209}]
(Note that vector is only as long as its last non-false
element.)
You should be careful when making comparisons against the
floating-point version number which appears in this list:
representation and rounding errors mean that the = operator will
not always return true for numbers which appear to be equal. The
secure method for doing comparisons is by using the macro DEFV:
see HELP * DEFV
(You should also be careful not to assume the current last
element of the list will always be last, since further elements
may be added in the future.)
sys_processor_type -> list [constant]
This is a list of words and numbers describing the processor on
which Poplog is running. Current possible values are:
[vax]
[sparc]
[mips]
[hppa]
[68020]
[68010]
[68000]
[80386]
[alpha]
pophost(word) -> attribute [procedure]
This procedure is a property that supplies more complete
information about the underlying system on which Poplog is
running than do sys_machine_type, sys_os_type and
sys_processor_type. Currently, there are entries in this
property for the following keywords:
Keyword Meaning
------- -------
os operating system name
osversion operating system version
machine host machine
machinetype generic machine type (eg 'vax')
systemname the local name of the machine
memory approximate amount of memory
machineserialnumber serial number of machine
site where the machine is
sitemailname electronic mail address for site
fullsitename official site address
All attribute values are strings or numbers, generally in
lowercase only, with the default for entries being false. You
should examine the library file that defines this property
(LIB * POPHOST) to find the format of the information you
require before writing programs to use it.
+-+ C.all/ref/system
+-+ Copyright University of Sussex 1995. All rights reserved.