PSL Manual                    7 February 1983              System Interface
section 19.0                                                      page 19.1

                                CHAPTER 19
                                CHAPTER 19
                                CHAPTER 19
                        OPERATING SYSTEM INTERFACE
                        OPERATING SYSTEM INTERFACE
                        OPERATING SYSTEM INTERFACE




     19.1. Introduction .  .  .  .  .  .  .  .  .  .  .  .  .  .  .    19.1
     19.2. System Dependent Functions  .  .  .  .  .  .  .  .  .  .    19.2
     19.3. TOPS-20 Interface  .  .  .  .  .  .  .  .  .  .  .  .  .    19.2
          19.3.1. User Level Interface .  .  .  .  .  .  .  .  .  .    19.2
          19.3.2. The Basic Fork Manipulation Functions  .  .  .  .    19.5
          19.3.3. File Manipulation Functions.  .  .  .  .  .  .  .    19.6
          19.3.4. Miscellaneous Functions .  .  .  .  .  .  .  .  .    19.7
          19.3.5. Jsys Interface .  .  .  .  .  .  .  .  .  .  .  .    19.8
          19.3.6. Bit, Word and Address Operations for Jsys Calls .   19.10
          19.3.7. Examples .  .  .  .  .  .  .  .  .  .  .  .  .  .   19.12
     19.4.  New Vax Specific Interface .  .  .  .  .  .  .  .  .  .   19.13
          19.4.1. Setting Your .LOGIN and .CSHRC files.  .  .  .  .   19.13
          19.4.2. Important PSL executables  .  .  .  .  .  .  .  .   19.14
          19.4.3. Creating the Init Files .  .  .  .  .  .  .  .  .   19.14
          19.4.4.  Directories and Symbols   .  .  .  .  .  .  .  .   19.15
          19.4.5.  Miscellaneous Unix Interface Functions   .  .  .   19.18
          19.4.6.  Oload   .  .  .  .  .  .  .  .  .  .  .  .  .  .   19.18
          19.4.7. Calling oloaded functions  .  .  .  .  .  .  .  .   19.20
          19.4.8. OLOAD Internals.  .  .  .  .  .  .  .  .  .  .  .   19.21
          19.4.9.  I/O Control functions  .  .  .  .  .  .  .  .  .   19.24




19.1. Introduction
19.1. Introduction
19.1. Introduction

  From  within  each  PSL  implementation, there will be a set of functions
that permit the user to access specific operating system services.  On  the
DEC-20  and VAX these include the ability to submit commands to be run in a
"lower fork", such  as  starting  an  editor,  submitting  a  system  print
command,  listing  directories, and so on.  We will attempt to provide such
       EXEC     CMDS
       EXEC     CMDS
calls (EXEC and CMDS) in all PSL implementations.  We also will provide  as
clean  an interface to Low-level services as possible.  On the DEC-20, this
         Jsys
         Jsys
is  the  Jsys  function.    Appropriate  support  functions  (such  as  bit
operations,  byte-pointers,  etc.)  are also used by the assembler.  On the
                        SYSCALL
                        SYSCALL
VAX we will provide the SYSCALL capability.



19.2. System Dependent Functions
19.2. System Dependent Functions
19.2. System Dependent Functions


 If_System
 If_System ___ ____ __  ____ ____ ___  _____ ____ ___   ___          ______
(If_System SYS-NAME:id, TRUE-CASE:any, FALSE-CASE:any): any          cmacro

     This is a compile-time  conditional  macro  for  system-dependent
              _____ ____                                      ___ ____
     code.    FALSE-CASE can be omitted and defaults to NIL.  SYS-NAME
System Interface              7 February 1983                    PSL Manual
page 19.2                                                      section 19.2

     must  be  a  member of the fluid variable System_List!*.  For the
     Dec-20, System_List!* is (Dec20 PDP10 Tops20 KL10).  For the  VAX
     it is (VAX Unix VMUnix).  An example of its use follows.  

        PROCEDURE MAIL();
        IF_SYSTEM(TOPS20, RUNFORK "SYS:MM.EXE",
            IF_SYSTEM(UNIX, SYSTEM "/BIN/MAIL",
                      STDERROR "MAIL COMMAND NOT IMPLEMENTED"));



19.3. TOPS-20 Interface
19.3. TOPS-20 Interface
19.3. TOPS-20 Interface


19.3.1. User Level Interface
19.3.1. User Level Interface
19.3.1. User Level Interface

                                      DoCmds
                                      DoCmds
  The  basic  function of interest is DoCmds, which takes a list of strings
as arguments, concatenates them together, starts a lower fork, and  submits
this string (via the Rescan buffer).  The string should include appropriate
<CR><LF>,  "POP"  etc.    A  global  variable,  CRLF,  is provided with the
<CR><LF> string.  Some additional entry points, and common calls have  been
defined to simplify the task of submitting these commands.


 DoCmds
 DoCmds _ ______ ____   ___                                            ____
(DoCmds L:string-list): any                                            expr

     Concatenate  strings  into a single string (using ConcatS), place
     into the rescan buffer using PutRescan,  and  then  run  a  lower
     EXEC, trying to use an existing Exec fork if possible.


      __________                                                     ______
CRLF [Initially: "<cr><lf>"]                                         global

     This  variable  is  "CR-LF",  to  be  appended  to or inserted in
     Command strings for  fnc(DoCmds).  It is STRING(Char CR,Char LF).


 ConcatS
 ConcatS _ ______ ____   ______                                        ____
(ConcatS L:string-list): string                                        expr

     Concatenate string-list into a single string, ending with CRLF.

     [??? Probably ConcatS should be in STRING, we add final  CRLF  in
     PutRescan ???]


 Cmds
 Cmds  _ ______    ___                                                _____
(Cmds [L:string]): any                                                fexpr

     Submit a set of commands to lower EXEC

     E.g. CMDS("VDIR *.RED ", CRLF, "DEL *.LPT", CRLF, "POP");.

  The following useful commands are defined:
PSL Manual                    7 February 1983              System Interface
section 19.3                                                      page 19.3

 VDir
 VDir _ ______   ___                                                   ____
(VDir L:string): any                                                   expr

     Display  a  directory  and  return  to  PSL,  e.g.  (VDIR "R.*").
     Defined as DoCmds LIST("VDIR ",L,CRLF,"POP");


 HelpDir
 HelpDir    ___                                                        ____
(HelpDir ): any                                                        expr

     Display  PSL  help  directory.    Defined  as  DoCmds   LIST("DIR
     PH:*.HLP",CRLF,"POP").


 Sys
 Sys _ ______   ___                                                    ____
(Sys L:string): any                                                    expr

     Defined as DoCmds LIST("SYS ", L, CRLF, "POP");


 Take
 Take _ ____   ___                                                     ____
(Take L:list): any                                                     expr

     Defined as DoCmds LIST("Take ",FileName,CRLF,"POP");


 Type
 Type _ ______   ___                                                   ____
(Type L:string): any                                                   expr

     Type out files.  Defined as DoCmds LIST("TYPE ",L,CRLF,"POP");

  While  definable  in  terms of the above DoCmds via a string, more direct
execution of files and fork  manipulation  is  provided  by  the  following
functions.  Recall that file names are simply Strings, e.g. "<psl>foo.exe",
and that ForkHandles are allocated by TOPS-20 as large integers.


 Run
 Run ________ ______   ___                                             ____
(Run FILENAME:string): any                                             expr

     Create  a fork, into which file name will be loaded, then run it,
     waiting for completion.  Finally Kill the fork.


 Exec
 Exec    ___                                                           ____
(Exec ): any                                                           expr

     Continue a lower EXEC, return with POP.  The Fork will be created
     the first time this is run, and the ForkHandle preserved  in  the
     global variable ExecFork.


 Emacs
 Emacs    ___                                                          ____
(Emacs ): any                                                          expr

     Continue  a lower EMACS fork.  The Fork will be created the first
     time this is run, and the  ForkHandle  preserved  in  the  global
     variable EmacsFork.

     [??? Figure out how to pass a buffer to from Emacs ???]
System Interface              7 February 1983                    PSL Manual
page 19.4                                                      section 19.3

 MM
 MM    ___                                                             ____
(MM ): any                                                             expr

     Continue  a  lower  MM  fork.  The Fork will be created the first
     time this is run, and the  ForkHandle  preserved  in  the  global
     variable MMFork.

       [???  MM  looks  in the rescan buffer for commands, so fairly
       [???  MM  looks  in the rescan buffer for commands, so fairly
       [???  MM  looks  in the rescan buffer for commands, so fairly
       useful  mailers  (e.g.  for  BUG  reports)  can  be  created.
       useful  mailers  (e.g.  for  BUG  reports)  can  be  created.
       useful  mailers  (e.g.  for  BUG  reports)  can  be  created.
       Perhaps make MM(s:string) for this purpose. ???]
       Perhaps make MM(s:string) for this purpose. ???]
       Perhaps make MM(s:string) for this purpose. ???]


 Reset
 Reset    ____ ________                                                ____
(Reset ): None Returned                                                expr

     This function causes the system to be restarted.


19.3.2. The Basic Fork Manipulation Functions
19.3.2. The Basic Fork Manipulation Functions
19.3.2. The Basic Fork Manipulation Functions


 GetFork
 GetFork ___ _______   _______                                         ____
(GetFork JFN:integer): integer                                         expr

     Create a fork handle for a file; a GET on the file is done.


 StartFork
 StartFork __ _______   ____ ________                                  ____
(StartFork FH:integer): None Returned                                  expr

     Start a fork running, don't wait, do something else.  Can also be
     used to Restart a fork, after a WaitFork.


 WaitFork
 WaitFork __ _______   _______                                         ____
(WaitFork FH:integer): Unknown                                         expr

     Wait for a running fork to terminate.


 RunFork
 RunFork __ _______   _______                                          ____
(RunFork FH:integer): Unknown                                          expr

     Start and Wait for a FORK to terminate.


 KillFork
 KillFork __ _______   _______                                         ____
(KillFork FH:integer): Unknown                                         expr

     Kill a fork (may not be restarted).


 OpenFork
 OpenFork ________ ______   _______                                    ____
(OpenFork FILENAME:string): integer                                    expr

     Get a file into a Fork, ready to be run.
PSL Manual                    7 February 1983              System Interface
section 19.3                                                      page 19.5

 PutRescan
 PutRescan _ ______   _______                                          ____
(PutRescan S:string): Unknown                                          expr

     Copy  a string into the rescan buffer, and announce to system, so
     that next PBIN will get this characters.  Used  to  pass  command
     strings to lower forks.


 GetRescan
 GetRescan     ___ ______                                              ____
(GetRescan ): {NIL,string}                                             expr

     See  if  there  is a string in the rescan buffer.  If not, Return
     NIL, else extract that string and return it.  This is useful  for
     getting  command line arguments in PSL, if MAIN() is rewritten by
     the user.  This will also include the program name,  under  which
     this is called.


19.3.3. File Manipulation Functions
19.3.3. File Manipulation Functions
19.3.3. File Manipulation Functions

  These mostly return a JFN, as a small integer.


 GetOldJfn
 GetOldJfn ________ ______   _______                                   ____
(GetOldJfn FILENAME:string): integer                                   expr

     Get a Jfn on an existing file.


 GetNewJfn
 GetNewJfn ________ ______   _______                                   ____
(GetNewJfn FILENAME:string): integer                                   expr

     Get a Jfn for an new (non-existing) file.


 RelJfn
 RelJfn ___ _______   _______                                          ____
(RelJfn JFN:integer): integer                                          expr

     Return Jfn to TOPS-20 for re-use.


 FileP
 FileP ________ ______   _______                                       ____
(FileP FILENAME:string): boolean                                       expr

     Check  if  FILENAME  is  existing  file; this is a more efficient
     method than the kernel version that uses ErrorSet.


 OpenOldJfn
 OpenOldJfn ___ _______   _______                                      ____
(OpenOldJfn JFN:integer): integer                                      expr

     Open file on Jfn to READ 7-bit bytes.


 OpenNewJfn
 OpenNewJfn ___ _______   _______                                      ____
(OpenNewJfn JFN:integer): Unknown                                      expr

     Open file on Jfn to write 7 bit bytes.
System Interface              7 February 1983                    PSL Manual
page 19.6                                                      section 19.3

 GtJfn
 GtJfn ________ ______ ____ _______   _______                          ____
(GtJfn FILENAME:string,BITS:integer): integer                          expr

     Get a Jfn for a file, with standard Tops-20 Access bits set.


 NameFromJfn
 NameFromJfn ___ _______   ______                                      ____
(NameFromJfn JFN:integer): string                                      expr

     Find the name of the File attached to the Jfn.


19.3.4. Miscellaneous Functions
19.3.4. Miscellaneous Functions
19.3.4. Miscellaneous Functions


 GetUName
 GetUName    ______                                                    ____
(GetUName ): string                                                    expr

     Get USER name as a string


 GetCDir
 GetCDir    ______                                                     ____
(GetCDir ): string                                                     expr

     Get Connected DIRECTORY


 InFile
 InFile  ____ __ ____    _______                                      _____
(InFile [FILS:id-list]): Unknown                                      fexpr

     Either  solicit  user  for file name (InFile), and then open that
     file, else open specified file, for input.


19.3.5. Jsys Interface
19.3.5. Jsys Interface
19.3.5. Jsys Interface

      Jsys
      Jsys
  The Jsys interface and jsys-names (as symbols  of  the  form  jsXXX)  are
defined in the source file PU:JSYS0.RED.

  The  access  to  the  Jsys  call  is modeled after IDapply to avoid CONS,
register reloads.  These could easily be done Open coded

  The following SYSLISP calls, XJsys'n', expect W-values in the  registers,
R1...R4,  a W-value for the Jsys number, Jnum and the contents of the 'nth'
register.  Unused registers should be given 0.  Any  errors  detected  will
               JsysError
               JsysError
result  in the JsysError being called, which will use the system ErStr JSYS
                                      StdError
                                      StdError
to find the error string, and issue a StdError.


 XJsys0
 XJsys0 __ _ _______  __ _ _______  __ _ _______
(XJsys0 R1:s-integer, R2:s-integer, R3:s-integer,
        __ _ _______  ____ _ _______   _ _______                       ____
        R4:s-integer, Jnum:s-integer): s-integer                       expr

     Used if no result register is needed.
PSL Manual                    7 February 1983              System Interface
section 19.3                                                      page 19.7

 XJsys1
 XJsys1 __ _ _______  __ _ _______  __ _ _______
(XJsys1 R1:s-integer, R2:s-integer, R3:s-integer,
        __ _ _______  ____ _ _______   _ _______                       ____
        R4:s-integer, Jnum:s-integer): s-integer                       expr


 XJsys2
 XJsys2 __ _ _______  __ _ _______  __ _ _______
(XJsys2 R1:s-integer, R2:s-integer, R3:s-integer,
        __ _ _______  ____ _ _______   _ _______                       ____
        R4:s-integer, Jnum:s-integer): s-integer                       expr


 XJsys3
 XJsys3 __ _ _______  __ _ _______  __ _ _______
(XJsys3 R1:s-integer, R2:s-integer, R3:s-integer,
        __ _ _______  ____ _ _______   _ _______                       ____
        R4:s-integer, Jnum:s-integer): s-integer                       expr


 XJsys4
 XJsys4 __ _ _______  __ _ _______  __ _ _______
(XJsys4 R1:s-integer, R2:s-integer, R3:s-integer,
        __ _ _______  ____ _ _______   _ _______                       ____
        R4:s-integer, Jnum:s-integer): s-integer                       expr

  The  following functions are the LISP level calls, and expect integers or
strings for the arguments, which  are  converted  into  s-integers  by  the
          JConv
          JConv
function  JConv, below.  We will use JS to indicate the argument type.  The
                      _______
result returned is an integer, which should  be  converted  to  appropriate
type  by  the  user, depending on the nature of the Jsys.  See the examples
below for clarification.


 Jsys0
 Jsys0 __ __  __ __  __ __  __ __  ____ _ _______   _______            ____
(Jsys0 R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer            expr

     Used is no result register is needed.


 Jsys1
 Jsys1 __ __  __ __  __ __  __ __  ____ _ _______   _______            ____
(Jsys1 R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer            expr


 Jsys2
 Jsys2 __ __  __ __  __ __  __ __  ____ _ _______   _______            ____
(Jsys2 R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer            expr


 Jsys3
 Jsys3 __ __  __ __  __ __  __ __  ____ _ _______   _______            ____
(Jsys3 R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer            expr


 Jsys4
 Jsys4 __ __  __ __  __ __  __ __  ____ _ _______   _______            ____
(Jsys4 R1:JS, R2:JS, R3:JS, R4:JS, Jnum:s-integer): integer            expr

      JConv
      JConv
  The JConv converts the argument type, JS, to  an  appropriate  s-integer,
representing either an integer, or string pointer, or address.


 JConv
 JConv _  _______ ______    _ _______                                  ____
(JConv J:{integer,string}): s-integer                                  expr

        _______
     An integer J is directly converted to a s-integer, by Int2Sys(J).
         ______
     A   string  J  is  converted  to  a  byte  pointer  by  the  call
     Lor(8#10700000000,Strinf(J)).  Otherwise  a  StdError,  "'J'  not
     known in Jconv" is produced.

  Additional  convertions  of  interest  may  be performed by the functions
Int2Sys  Sys2Int
Int2Sys  Sys2Int
Int2Sys, Sys2Int, and the following functions:
System Interface              7 February 1983                    PSL Manual
page 19.8                                                      section 19.3

 Str2Int
 Str2Int _ ______   _______                                            ____
(Str2Int S:string): integer                                            expr

     Returns  the  physical address of the string start as an integer;
     this can CHANGE if a GC takes  place,  so  should  be  done  just
     before calling the jsys.


 Int2Str
 Int2Str _ _______   ______                                            ____
(Int2Str J:integer): string                                            expr

     J  is  assumed to be the address of a string, and a legal, tagged
     string is created.


19.3.6. Bit, Word and Address Operations for Jsys Calls
19.3.6. Bit, Word and Address Operations for Jsys Calls
19.3.6. Bit, Word and Address Operations for Jsys Calls


 RecopyStringToNULL
 RecopyStringToNULL _ _ ______   ______                                ____
(RecopyStringToNULL S:w-string): string                                expr

     S is assumed to be the address of a string, and a  legal,  tagged
     string  is  created,  by  searching  for  the  terminating  NULL,
     allocating a HEAP string, and copying  the  characters  into  it.
     This  is  used  to ensure that addresses not in the LISP heap are
     not passed around  "cavalierly"  (although  PSL  is  designed  to
     permit this quite safely).


 Swap
 Swap _ _______   _______                                              ____
(Swap X:integer): integer                                              expr

     Swap  half  words of X; actually Xword(LowHalfWord X,HighHalfWord
     X).


 LowHalfWord
 LowHalfWord _ _______   _______                                       ____
(LowHalfWord X:integer): integer                                       expr

     Return  the  low-half  word  of  the  machine  representation  of
     X. Actually Land(X,8#777777).


 HighHalfWord
 HighHalfWord _ _______   _______                                      ____
(HighHalfWord X:integer): integer                                      expr

     Return  the  Upper  half  word as a small integer, of the machine
     word           representation           of            X. Actually
     Lsh(Land(X,8#777777000000),-18).


 Xword
 Xword _ _______ _ _______   _______                                   ____
(Xword X:integer,Y:integer): integer                                   expr

     Build       a       Word      from      Half-Words,      actually
     Lor(Lsh(LowHalfWord(X),18),LowHalfWord Y).
PSL Manual                    7 February 1983              System Interface
section 19.3                                                      page 19.9

 JBits
 JBits _ ____   _______                                                ____
(JBits L:list): integer                                                expr

     Construct  a  word-image  by  OR'ing  together  selected  bits or
     byte-fields.  L is list of integers or integer pairs.   A  single
     integer  in  the range 0...35, BitPos, represents a single bit to
     be turned on.  A pair of integers,  (FieldValue  .  RightBitPos),
     causes  the  integer  FieldValue  to  be  shifted  so  its  least
     significant bit (LSB) will fall  in  the  position,  RightBitPos.
     This  value  is  then  OR'ed into the result.  Recall that on the
     DEC-20, the most significant bit (MSB), is bit 0 and that the LSB
     is bit 35.


 Bits
 Bits _ ____   _______                                                _____
(Bits L:list): integer                                                macro

     A convenient access to Jbits:  JBits cdr L. 


19.3.7. Examples
19.3.7. Examples
19.3.7. Examples

  The  following  range  of  examples  illustrate  the  use  of  the  above
functions.  More examples can be found in PU:exec0.red.



Jsys1
Jsys1
Jsys1(0,0,0,0,jsPBIN);
        % Reads a character, returns the ASCII code.

Jsys0
Jsys0
Jsys0(ch,0,0,0,jsPBOUT);
        % Takes ch as Ascii code, and prints it out.

Procedure OPENOLDJfn Jfn;        %. OPEN to READ
 JSYS0(Jfn,Bits( (7 . 5),19),0,0,jsOPENF);

Lisp procedure GetFork Jfn;      %. Create Fork, READ File on Jfn
   Begin scalar FH;
      FH := JSYS1(Bits(1),0,0,0,jsCFork);
      JSYS0(Xword(FH ,Jfn),0,0,0,jsGet);
      return FH
   END;

Procedure GetOLDJfn FileName; %. test If file OLD and return Jfn
   Begin scalar Jfn;
      If NULL StringP FileName then return NIL;
      Jfn := JSYS1(Bits(2,3,17),FileName,0,0,jsGTJfn);
         % OLD!MSG!SHORT
      If Jfn<0 then return NIL;
      return Jfn
   END;

Procedure GetUNAME;      %. USER name
 Begin Scalar S;
System Interface              7 February 1983                    PSL Manual
page 19.10                                                     section 19.3

   S:=Mkstring 80;              % Allocate a 80 char buffer
   JSYS0(s,JSYS1(0,0,0,0,jsGJINF),0,0,jsDIRST);
   Return RecopyStringToNULL S;
                % Since a NULL may be appear before end
 End;

Procedure ReadTTY;
Begin Scalar S;
        S:=MkString(30);    % Allocate a String Buffer
        Jsys0
        Jsys0
        Jsys0(S,BITS(10,(30 . 35),"Retype it!",0,jsRDTTY);
               % Sets a length halt (Bit 10),
               % and length 30 (field at 35) in R2
               % Gives a Prompt string in R3
               % The input is RAISE'd to upper case.
               % The Prompt will be typed if <Ctrl-R> is input
        Return RecopyStringToNULL S;
               % Since S will now possibly have a shorter
               % string returned
end;



19.4. New Vax Specific Interface
19.4. New Vax Specific Interface
19.4. New Vax Specific Interface

  Most of this information depends on the use of the Berkeley c-shell (csh)
and  will need modification (or might not work) if the Bourne shell (sh) is
your command shell of choice.  Extensive use is made of  csh  variables  to
                                                      1
describe path-names to the various PSL subdirectories. 


19.4.1. Setting Your .LOGIN and .CSHRC files
19.4.1. Setting Your .LOGIN and .CSHRC files
19.4.1. Setting Your .LOGIN and .CSHRC files

  During  installation of PSL, a file "psl-names" defining these path-names
will have been edited and tested by the installer. The  message  announcing
the  location of PSL on your system should indicate where this file is.  It
is often placed on "~psl" or "~psl/dist".

  It is absolutely essential that you place the line 


        source ~psl/psl-names


in your .login and .cshrc files. If you do not have either of  these,  they


_______________

  1
   This  section  was contributed by Russ Fish.  The source for most of the
functions mentioned is "$pv/system-extras.red".
PSL Manual                    7 February 1983              System Interface
section 19.4                                                     page 19.11

should  be  created.  After  execution  of  this  statement,  a  set  of "$
variables" will be available to refer to  files  of  interest  in  the  PSL
system from the c-shell, from editors, and from within PSL.

  You  may  have to add another directory to the search path of your shell,
in the definition of path in your .login file, which gives the location  of
the  PSL  executable  files.  This  should  be  done after the line "source
~psl/psl-names", and is a line of the form 


        set path=(. $psys /bin /usr/bin)


  $psys is the c-cshell variable defined in psl-names to point at  the  psl
"executables".


19.4.2. Important PSL executables
19.4.2. Important PSL executables
19.4.2. Important PSL executables

  "psl"  is  the PSL executable with a LISP syntax toploop. "rlisp" runs an
RLISP (Algol-like) toploop syntax. At some  installations,  "bare-psl"  and
"pslcomp"  also exist, particularly if "psl" has had many modules preloaded
for local customization.

  There are also a set of c-shell scripts that can be run as if  they  were
exectable  programs.  These  include a "build" utility to recompile utility
modules, "oload" to permit dynamic loading of non-LISP code into  PSL,  and
"cmds.csh" to define some useful PSL related aliases.


19.4.3. Creating the Init Files
19.4.3. Creating the Init Files
19.4.3. Creating the Init Files

  On  startup  PSL,  RLISP,  and PSLCOMP look for LISP syntax init files on
your home (login) directory, respectively named  ".pslrc",  ".rlisprc"  and
".pslcomprc",  which  are  executed  in  the PSL before it prompts for user
                                                  SaveSystem
                                                  SaveSystem
input. Other PSL based programs that are saved by SaveSystem  can  also  be
made to look for .xxxrc files of their own.

  These  files  typically  contain  code  to  load modules of interest, set
various switches, such as !*BREAK, etc.


19.4.4.  Directories and Symbols
19.4.4.  Directories and Symbols
19.4.4.  Directories and Symbols

  The specific locations of subtrees  of  PSL  files  is  left  up  to  the
installer,  to  reflect  the  conventions  of  local  usage and file system
layout.  This section discusses the use of c-shell variables ($  variables)
for system-invariant navigation. To use these, the lines 


        source ~psl/psl-names
        source $pvsup/cmds.csh
System Interface              7 February 1983                    PSL Manual
page 19.12                                                     section 19.4

        source lisp-psl-names


should be placed in your login.cmd file

  The  root  of  the PSL distribution tree is (usually) located in the home
directory of a pseudo-user named  "psl",  and  hence  may  be  accessed  as
"~psl/dist".    During  installation,  links in ~psl are often also made to
startup files in the vax support directory, "$pvsup".    (These  should  be
SYMBOLIC links in Berkeley 4.1a VmUnix and above.)

  Note  -  the  c-shell  expands "~user" and "$variable" in filenames.  The
current version  of  PSL  3.1  will  also  permit  these  constructions  in
filenames,  though  in  a  somewhat  limited form. Future PSL releases will
integrate this more fully. Currently, a file of psl-names in LISP systax is
generated by the "source lisp-psl-names", and it must be read into PSL, etc
via the .xxxrc files.

  File "~psl/psl-names" defines c-shell symbols for the whole hierarchy  of
distributed PSL directories.

  File $pvsup/cmds.csh contains c-shell commands useful in conjunction with
PSL.    As  of  this  writing,  there are only two commands (c-shell alias)
defined there:


   a. "lisp-psl-names".  When run from the .login file, it  creates  a
      file  "psl-names.sl" on your home directory.  This file contains
      a series of PUT statements to associate the full Unix path names
      with ids that have the same name as the C-shell aliases  created
      by various set commands in your .login. Each entry has the form 


         (PUT (quote ID) (quote pslname) "pathname")


      It is suggested that the line 


              lisp-psl-names


      be  placed  at  the  end  of your .login if you wish to use this
      feature.  The file "psl-names.sl" should then be read  into  the
      various PSL, RLISP, etc by placing a line 


              (load vax!-path)


      into your .pslrc, .rlisprc, etc. This loads the VAX-PATH module,
      and  reads  the  file  "psl-names.sl"  which  was created by the
PSL Manual                    7 February 1983              System Interface
section 19.4                                                     page 19.13

      "lisp-psl-names"  command  on  your  "home" directory, which can
      also be loaded to give a procedure PATH that builds files  names
      using a "$ID/.." syntax, and also a modified OPEN.

   b. "lisp-csh-vars".    An  older  form of lisp-psl-names.It returns
      LISP syntax assignments  for  all  of  the  directory  variables
      defined  in the c-shell in which it is executed.  Its output may
      be directly put into files ".pslrc" and ".rlisprc" in your  home
      directory by placing this command in your .login file:  


              lisp-csh-vars | tee .pslrc 


      .rlisprc  >  after  which  any  directory  variables set in your
      c-shell startup will be known in your PSL as arguments for "cd".
      There are innumerable variations on this, of course.


 cd
 cd ___ ______   _______                                               ____
(cd DIR:string): boolean                                               expr

     Like the shell "cd" command, sets the current directory (".")  of
                                 cd
                                 cd
     the  running  PSL.   Unless cd is executed, the current directory
                                                                __ ___
     will remain the same as the current directory of the shell at the
     ____ ___ ___ ___ _______
     time the PSL was started.  (Unix filenames are paths relative  to
                                                                    Cd
                                                                    Cd
     the  current  directory  unless  they  begin  with  a slash.)  Cd
     returns T if it successfully found the  directory  given  in  the
     argument as a path, NIL otherwise.


 pwd
 pwd    ______                                                         ____
(pwd ): string                                                         expr

     Like  the  "pwd" unix command, meaning "print working directory".
     Returns the current directory of the PSL as a string,  terminated
     with  a  slash so filenames may be direcly "concat"ed to it.  The
                                  cd
                                  cd
     trailing slash is ignored by cd.


 path
 path _ ______   ______                                                ____
(path S:string): string                                                expr

     Examines the argument string; if it starts with $,  extracts  the
     next  string up to the / (if any), converts it to (an upper-case)
     __
     id. Then an associated string is looked for under  the  indicator
     'pslnames.    If  an  associated string is not found, an Error is
                    _
     generated.  If S does not start with $, it is returned unchanged.

     Thus CD PATH "$PU"; will work.

     When VAX-PATH is loaded, OPEN is redefined to apply PATH  to  the
     file-name. Thus OPEN, IN, DSKIN, OUT, FILEP and and LAPIN can use
     $vars  in  file  names without calling PATH explicitly. LOAD-PATH
     also   reads   the   "psl-names.sl"   files   from   the   user's
System Interface              7 February 1983                    PSL Manual
page 19.14                                                     section 19.4

     home-directory.


19.4.5.  Miscellaneous Unix Interface Functions
19.4.5.  Miscellaneous Unix Interface Functions
19.4.5.  Miscellaneous Unix Interface Functions


 ExitLisp
 ExitLisp    _________                                                 ____
(ExitLisp ): undefined                                                 expr

     Since  "quit"  uses  the Berkeley job-control facility to the PSL
     (like a ^Z at the keyboard), a separate function is  needed  when
                                            ExitLisp
                                            ExitLisp
     you really want the PSL to terminate.  ExitLisp does it.  (A "^\"
     from  the  keyboard  has  the same effect, assuming you have your
     core-dump limit set low.)


 GetEnv
 GetEnv __________ ______   ______                                     ____
(GetEnv ENVVARNAME:string): string                                     expr

     Returns value of the specified Unix  environment  variable  as  a
     string, or NIL if the argument is not a string or the environment
     variable is not set.


 System
 System _______ ______   _________                                     ____
(System UNIXCMD:string): undefined                                     expr

     Starts  up  a sub-shell and passes the Unix command to it via the
     Unix "system" command.  The working directory of the command will
     be the same as the PSL.


19.4.6.  Oload
19.4.6.  Oload
19.4.6.  Oload



oload( LdSpec:String )                             c-shell-script
----------------------                             --------------


  Oload is a means of linking Unix .o and .a files into a running Vax  PSL.
It  was  developed  to  get  access to existing C code driver libraries for
graphics devices, but should work for any Unix compiled code with C calling
conventions.

  The single  argument  to  the  oload  function  is  a  string  containing
arguments  to the Unix "ld" loader, separated by blanks.  File names ending
in ".o" are compiled relocatable code files.   ".a"  files  are  "ar"  load
libraries,  which  are assumed to contain a set of ".o" files, all of which
are to be  loaded.    Other  loader  arguments  should  follow,  specifying
whatever  libraries  are  necessary to satisfy all external references from
the ".o" and ".a" files mentioned.  Library specs are in the  form  "-lfoo"
to search the "libfoo.a" library on /lib, /usr/lib, or /usr/local/lib, e.g.
"-lc" for the C library.
PSL Manual                    7 February 1983              System Interface
section 19.4                                                     page 19.15

  This is an "incremental" (-A flag) load.  Symbols which are already known
in the running PSL will be linked to the existing addresses.

  If  the  load string argument is NIL, an attempt is made to re-oload from
an existing .oload.out file.  This can only be done if the BPS  and  WARRAY
base  addresses  are  EXACTLY the same as they were on the previously done,
full oload.  An error message results if the BPS locations  are  different.
This is meant to facilitate rapidly repeating an oload at startup time.

  Alternately,  a  customized  version  of PSL may be saved by the function
SaveSystem
SaveSystem
SaveSystem, after first performing oloads and loading or compiling  in  PSL
code including functions which interface to the oloaded code.

  Oload returns a status code of T if it succeded, or NIL if not.


19.4.7. Calling oloaded functions
19.4.7. Calling oloaded functions
19.4.7. Calling oloaded functions

  All entry points and global data objects in ".o" and ".a" files mentioned
are  made known to the PSL system.  C functions may be called from compiled
code ONLY, and are flagged 'ForeignFunction  by  oload.    Data  areas  are
flagged  'ForeignData,  with  a  property  containing  a  pair  of the data
location and size in bytes for use by SYSLISP interface code.

  Currently, foreign function calls may not be compiled into Fasl files, so
                                                             Compile
                                                             Compile
the compilation must be done incrementally, via "on Comp" or Compile.

                       C
                       C
  The names of oloaded C functions within PSL are the "true"  names,  which
have  an  underscore  ("_")  prefixed to the C name.  This makes it easy to
make a compiled "pass through" interface function which gives the same name
within PSL as the C names.  e.g. "procedure foo(); _foo();"

  Functions which take integer arguments can be called directly, due to the
invisible tagging of integers up to +-2^^27 in Vax PSL.  Similarly, integer
return values will be  passed  back  from  the  C  functions.    String  or
structured arguments will require a bit of conversion code in the interface
functions, using SYSLISP functions to remove tags on arguments and add them
                                      ImportForeignString
                                      ImportForeignString
to  return  values.    The  function  ImportForeignString constructs a LISP
string, given a C string (char *).

  Warning: currently, foreign function  calls  may  have  no  more  than  5
arguments and floating point and struct arguments and return values are not
supported.   This will be remedied in the compiler eventually.  In the mean
time, both of these restrictions may  be  easily  circumvented  by  putting
arguments  in  work  areas  and  passing the address of the work area as an
argument to an intermediate C  "kluge  function"  which  unpacks  the  real
arguments and passes them on to the target C function.

  If  work  areas are needed in SYSLISP interface code, as when arrays must
be passed to the C code, use a LispVar to hold the address of a word  block
              GtWArray                        GtWrds
              GtWArray                        GtWrds
acquired  via GtWArray (for static arrays) or GtWrds (for dynamic blocks in
                                              C
                                              C
the heap).  Pass the array  address  to  the  C  function  as  the  pointer
System Interface              7 February 1983                    PSL Manual
page 19.16                                                     section 19.4

argument.


19.4.8. OLOAD Internals
19.4.8. OLOAD Internals
19.4.8. OLOAD Internals

  Oload  invokes  the  Unix "ld" loader through a c-shell script to convert
the relocatable code in .o files inwto absolute form, then  reads  it  into
space  allocated  within the BPS area of the PSL.  The text segment goes at
the low end of BPS, and the data and bss  segments  go  at  the  high  end,
following the BPS storage allocation conventions of the LISP compiler.

  Since  an  incremental  (-A) load is done, oload needs a filename path to
the executable file containing the loader  symbol  table  of  the  previous
load.        The   variable   SymbolFileName!*   tells   both   Oload   and
SaveSystem/DumpLisp the file name string  to  use  (for  this  reason,  the
executable files should be publicly readable.)

  When PSL is started, SymbolFileName!* is automatically set to the name of
the  executed PSL file.  This is done by importing the Unix argument string
to variable UnixArgs!*.  UnixArgs!*[0] is the (possibly  partial)  path  to
the  PSL  file  which  was  executed.    The unix environment variable PATH
contains a set of path prefixes to which partial paths are appended,  until
a  valid  filename  results.    "."    refers  to  the  path to the current
directory, which is returned by pwd().  [ Unix system  interface  functions
are contained in file $pv/system-extras.red. ]

  SymbolFileName!*  is  set  to  ".oload.out"  by  oload, so that succesive
oloads will accumulate a loader symbol table, and so that unexec, called by
DumpSystem
DumpSystem
DumpSystem, will get the right symbol table in the saved PSL.  (It  may  be
useful  to  know  that  the  initial  value of SymbolFileName!* is saved in
StartupName!*.)

  A number of work files are created on the current directory by the  oload
script,  with  file  names  that  begin  ".oload".   The .oload.out file in
particular is quite large because it spans the gap of unused space in  BPS.
It  is a good idea to remove those files if you do not intend to repeat the
oload exactly.  This can be done  from  your  rlisp,  via  the  command  ''
system( "rm .oload.*" ); ''.


 ImportForeignString
 ImportForeignString _ ______ ____   ______                            ____
(ImportForeignString C_STRING:word): string                            expr

     Constructs  and  returns a LISP string, given a C string (char *)
     returned from a C ForeignFunction.  A NULL (0) string pointer  is
     returned as NIL.


                  __________                                         ______
SYMBOLFILENAME!* [Initially: ]                                       global

     Gives  the name of the PSL executable file to be examined by both
     Oload and SaveSystem/DumpLisp to find the Unix  symbol  table  of
     the  PSL.    Set  to the executed PSL file at startup, changed to
PSL Manual                    7 February 1983              System Interface
section 19.4                                                     page 19.17

     ".oload.out" by Oload.


               __________                                            ______
STARTUPNAME!* [Initially: ]                                          global

     The  path  to  the  originally  executed PSL file, as returned by
              GetStartupName
              GetStartupName
     function GetStartupName, based on UnixArgs!*[0].


            __________                                               ______
UNIXARGS!* [Initially: ]                                             global

     A vector of strings, passed to the PSL on  startup  by  the  Unix
     shell.  Imported by function "getUnixArgs".


19.4.9.  I/O Control functions
19.4.9.  I/O Control functions
19.4.9.  I/O Control functions


 EchoOff
 EchoOff    _________                                                  ____
(EchoOff ): undefined                                                  expr


 EchoOn
 EchoOn    _________                                                   ____
(EchoOn ): undefined                                                   expr

     EchoOff
     EchoOff
     EchoOff  enters  raw,  character-at-a-time  input mode for Emode,
                                                                EchoOn
                                                                EchoOn
     Nmode, and  similar  keystroke  oriented  environments.    EchoOn
     returns to normal, line oriented input mode.


 CharsInInputBuffer
 CharsInInputBuffer    _______                                         ____
(CharsInInputBuffer ): integer                                         expr

     Returns  the number of characters waiting for input from the TTY,
     including those still in the Stdio buffer and those not yet  read
     from Unix.


 FlushStdOutputBuffer
 FlushStdOutputBuffer    ____ ________                                 ____
(FlushStdOutputBuffer ): None Returned                                 expr

     The  standard output from PSL is in Stdio line-buffered mode, and
     is normally flushed to the TTY whenever an end-of-line is printed
     or  before  waiting  for  input.    In   screen-oriented   output
     environements   like   Emode/Nmode   which   use   screen  cursor
     positioning, it is necessary to explictly  flush  the  buffer  at
     appropriate  times.    It  may  also be desireable to see partial
     lines of output at other times.


 ChannelFlush
 ChannelFlush ____ __ _______   ____ ________                          ____
(ChannelFlush Chnl:io-channel): None Returned                          expr

     Flushes any channel, as FlushStdOutputBuffer does for StdOut!*.
System Interface              7 February 1983                    PSL Manual
page 19.18                                                     section 19.5

19.5. Apollo System Calls
19.5. Apollo System Calls
19.5. Apollo System Calls

  PSL  contains  a syscall package for use on the Apollo PSL.  See the USCG
operating note "Apollo Syscall Package for PSL", by S. Lowder,  G. Maguire,
and J. W. Peterson.
