HELP PARAMETERS                                   Aaron Sloman, Dec 1989
                                         Updated Simon Nichols, Dec 1990

Running POP11 with parameters.

         CONTENTS - (Use <ENTER> g to access required sections)

 -- Introduction
 -- 1. Invoking a saved image from DCL
 -- 1.1 Search path for saved images: POPSAVEPATH
 -- 1.2 Additional arguments to saved images
 -- 1.3 Actions performed when a saved image starts up
 -- 1.4 Invoking layered saved images
 -- 1.5 Changing POPSAVEPATH
 -- 2. Special arguments
 -- 3. Executing an expression specified on the command line
 -- 4. Invoking a program file from the command line
 -- 4.1. Changing POPCOMPPATH
 -- Related Documentation


-- Introduction -------------------------------------------------------

POP11 may be invoked from DCL with command line arguments if it is
defined as a VMS "foreign" command -- for example, by means of the DCL
command:

    pop11 :== $usepop:[pop.pop]pop11

These arguments fall into four categories, distinguished by the flag
character which is the first character of the argument:

    1) An argument beginning with `+` or `/` causes a saved image to be
       restored.

    2) An argument beginning with `%` modifies POP11 startup behaviour.

    3) A string beginning with '":' causes the remainder of the string
       (after the double quote and the colon) to be interpreted as a
       string of source text to be executed.

    4) Any other argument is treated as the name of a program file to be
       compiled.

These four kinds of arguments are described in detail below.

Notes:

1) It is possible to have a single argument list containing arguments
   of kinds 1, 2 and 3 or of kinds 1, 2 and 4, but kinds 3 and 4 are
   mutually exclusive.

2) The initialisation files ('init.p', 'init.pl', 'init.lsp', 'init.ml',
   'vedinit.p', etc.) are not compiled automatically if arguments of
   kinds 1, 3 or 4 are supplied. Therefore, user programs (including
   saved images) can decide whether to compile them or not; see section
   1 for details. The %noinit flag can be used to suppress the
   compilation of initialisation files when no argument is supplied; see
   section 2 for details.


-- 1. Invoking a saved image from DCL ---------------------------------

A saved image in the file image.psv can be invoked from DCL in either of
the following two forms:

    pop11 /myimage
or
    pop11 +myimage

The latter is preferred as it now also works with Unix Poplog.

Either command will cause POP11 to try to restore a saved image. E.g.

    pop11 +myimage

will search for a saved image called 'myimage.psv', in directories that
are specified in the logical name POPSAVEPATH.

If the saved image name contains a full path name then -popsavepath- is
not used. If the name ends in '.psv' then the suffix is not added.

Thus, because the following includes a full path name,

    pop11 +[me.lib]myimage.psv

it will try only to restore 'myimage.psv' located in the directory
'[me.lib]'.


-- 1.1 Search path for saved images: POPSAVEPATH ----------------------

POPSAVEPATH is a logical name whose value is a string giving directory
specifications, separated by vertical bars. An empty component ("|" at
the beginning or end of the string, or "||" in the middle) means the
current working directory. POPSAVEPATH is defined in the file
'popcom:popenv.com' as follows:

    $ assign/trans=terminal -
        "|poplib:|popsavelib:|poplocalbin:" -
        popsavepath

This starts with an empty string before the first "|" so the first place
to look is the current directory.

For example,

    pop11 /myimage
or
    pop11 +myimage

will try to restore a saved image called MYSAVED.PSV in the current
directory, and if it isn't there it will look in the user's library
directory (POPLIB), and if there isn't one it will look in the local
library directory POPLOCALBIN which defaults to 'poplocal:[local.bin]'
(to be created by local system manager). If it cannot be found there, it
is sought in the POP11 library directory POPSAVELIB, normally set to
'usepop:[pop.lib.psv]'.


-- 1.2 Additional arguments to saved images ---------------------------

When a saved image is invoked, additional arguments can be specified,
separated by spaces. A list of strings containing these arguments will
be available in *POPARGLIST when the image is restored. For example, the
command

    pop11 +myimage arg1 arg2 arg3

will cause -poparglist- to be the list

    ['arg1' 'arg2' 'arg3' ]


-- 1.3 Actions performed when a saved image starts up -----------------

When a saved image is restored it does not automatically compile either
the user's 'init.p', or the SYSTEM version in POPSYS. Compilation can be
forced by invoking the procedure SYSINITCOMP. This can be specified in
the command that creates the saved image, e.g.

    if syssave('...') then
        ...
        sysinitcomp();
        ...
    endif;

as the instructions between "then" and "endif" are executed whenever the
saved image is restored. Alternatively various initialisation files can
compiled, if they exist, using -trycompile-, which is like -compile-
except that it returns a boolean indicating whether the file existed or
not.

Similar start-up procedures can be specified with layered saved images
created using -sys_lock_system-, described in REF * SYSTEM.


-- 1.4 Invoking layered saved images ----------------------------------

Saved images created using -sys_lock_system- can be used as a basis for
creating new saved images which will not duplicate the contents of the
original image. (the locked image can even be mapped into shared memory
when run by different users.) The standard POPLOG saved images, such as
prolog, clisp and pml, are created as locked images.

If 'image1.psv' is a locked image, and 'image2.psv' is another locked
image created relative to it, and 'image3.psv' is created relative to
'image2.psv', then the command

    pop11 +image1 +image2 +image3 arg1 arg2 arg3

can be used to restore 'image3.psv' with ['arg1' 'arg2' 'arg3'] assigned
to -poparglist-.

For example, the command

    pop11 +prolog +logic

runs the Prolog image then invokes the saved image contained in the file
'logic.psv'. The latter file is created by the DCL command file
'popcom:mklogic.com'.

In fact this can be abbreviated to

    prolog +logic

because 'prolog' is defined as a suitable logical name on startup in the
file 'popcom:popenv.com'.


-- 1.5 Changing POPSAVEPATH -------------------------------------------

You can change the default search path for saved images simply by
changing the POPSAVEPATH logical name. In VMS, this is done by the
ASSIGN command. For example:

    $ assign "[me.aaa]|[me.aaa.bbb]|popsavelib:||[me.ccc]" popsavepath

will make POP11 look for saved images first in a sub-directory '[.aaa]'
of the directory '[me]', then in a sub-sub-directory '[.aaa.bbb]' of the
directory '[me]', then in the POP11 library directory, then in the
current working directory and finally in a sub-directory '[.ccc]' of the
directory '[me]'. If the string starts with "|" then it will look first
in the current directory. For the default assignment, see the file
'popcom:popenv.com'.


-- 2. Special arguments -----------------------------------------------

POP11 recognises the following special arguments, all of which begin
with a `%` character, and cause the associated actions to be performed:

    %nobanner   suppresses printing of the banner

    %noinit     prevents compilation of initialisation files

    %x          tells POP11 to start-up under X

The %noinit argument also prevents the X startup procedure
-sys_xstartup- from being run, even if %x is specified.

The %x argument may optionally be followed by a bracketed list of X
arguments, which is assigned to the variable -popunderx-.

For example,

    pop11 %nobanner %x \( -display cx010:0.0 \)

causes POP11 to startup under X without printing the banner. The
variable -popunderx- will have the value:

    ['-display' 'cx010:0.0']

These X specific arguments may be passed on to the X server.

See REF * SYSTEM for details.


-- 3. Executing an expression specified on the command line -----------

If POP11 is invoked with a string starting with '":', the string after
the colon is treated as a POP11 expression and is compiled and executed
as soon as POP11 starts up. POP11 then exits. For example, the following
will print the sum of 99 and 55:

    pop11 ":99 + 55 =>

Note that there should be NO closing double quote. To prevent POP11 from
exiting as soon as it has evaluated the expression, the expression can
assign -setpop- to -interrupt- (or call a procedure which does this).
For example, the following will print the sum of 99 and 55 and then
perform a setpop, leaving you at the POP11 prompt:

    pop11 ":setpop -> interrupt; 99 + 55 =>

When VED is invoked from DCL, -setpop- is assigned to -interrupt-.
However, argument(s) supplied on the command line are not compiled
before entering ved or after leaving it; instead they is treated as the
name of a file. Hence,

    ved ":99 + 55 => temp

will attempt to edit a file called ':99 + 55 => temp'. This will cause a
mishap, since the file name is (unsurprisingly) invalid on VMS.

When POP11 is run in this mode, it does not compile either the user's
'init.p', nor the system version in POPSYS. Compilation can be forced by
calling -sysinitcomp-. Thus, the DCL command VED is defined in
'popcom:popenv.com' as

    $ ved :== $popsys:pop11 """:sysinitcomp(); ved

(The three quotes are needed to specify a literal double quote character
to DCL; otherwise DCL interprets a double quote specially.)


-- 4. Invoking a program file from the command line -------------------

Invoking POP11 as follows:

    pop11 file arg1 arg2 arg3

will cause POP11 to search in the directories specified by the logical
name POPCOMPPATH for a program file whose name is 'file.p'. The file
will be compiled, with the POP11 variable *POPARGLIST bound to a list of
the form:

    ['arg1' 'arg2' 'arg3']

If the first argument is not 'file' but a full path name, e.g.
'[aaa.bbbb]file', then POPCOMPPATH is not used, and if the name ends in
'.p' that is not added.


-- 4.1. Changing POPCOMPPATH ------------------------------------------

This search path is set up in the same way as POPSAVEPATH, and in the
same login initialisation command file. POPCOMPPATH is defined in
'popcom:popenv.com' as follows:

    $ assign/trans=terminal -
        "|poplib:|poplocalauto:|popautolib:|popliblib:" -
        popcomppath

The leading bar "|" indicates an initial null path name, standing for
the current directory. Thus, this search path specifies that the current
directory is to be searched first, followed by the user's POPLIB, then
POPLOCALAUTO, POPAUTOLIB and finally POPLIBLIB. It can be altered in
your 'login.com' file in the same way as POPSAVEPATH (see above).


-- Related Documentation ----------------------------------------------

HELP * SYSSAVE      - creating saved images
HELP * SYSRESTORE   - running them
REF  * SYSTEM       - general information on running Poplog, saved
                      images etc.
REF  * sys_lock_system  - layered saved images
HELP * INITIAL      - Tailoring POPLOG and its subsystems, via login
                      command files, init.p vedinit.p etc.
HELP * INITIAL.EX   - some examples of users' tailoring files
DOC  * SYSSPEC      - overview of Poplog's directory structure
DOC  * PUG          - Poplog User Guide


--- C.vms/help/parameters
--- Copyright University of Sussex 1990. All rights reserved. ----------
