{Begin SubSec Cjsys}
{Title Cjsys}
{Text
{note The cjsys package was written by L. M. Masinter.}
{it
Note: Cjsys is a LispUsers package that is contained on the file {lisp CJSYS.COM}. It only works with Interlisp-10.
}
{index *BEGIN* cjsys package}
{Tag CJSYS}
This package provides assistance to Interlisp-10 users who wish to make direct calls on the operating system (via JSYSes). It also makes the coding of certain common {fn ASSEMBLE} constructions more convenient. The package defines the following functions:
{FnDef {FnName JS} {FnArgs JSYSNAME AC1 AC2 AC3 RESULT}
{Type NLAMBDA}
{Text
All arguments are evaluated except for {arg JSYSNAME}. Like {fn JSYS} (see {PageRef Fn JSYS}), loads the unboxed values of {arg AC1}, {arg AC2}, and {arg AC3} into the appropriate registers, and executes the JSYS {arg JSYSNAME}. {fn JS} differs from {fn JSYS} in that the JSYS may be indicated by its {it symbolic} name, not just by its number. {fn JS} also generates slightly cleaner code than {fn JSYS}. {fn JS} also differs from {fn JSYS} in that:
(a) if any argument is supplied as {lisp NIL}, then it is not loaded at all, i.e. the corresponding {lisp AC} will contain garbage. ({fn JSYS} loads the {lisp AC} with 0.)
(b) if {arg RESULT} is {lisp NIL}, then no value is loaded (interpreted, {fn JS} returns the string {lisp "garbage result from JS"}).
(c) {arg RESULT} can be {lisp T}, meaning return {lisp T} if the JSYS skips, {lisp NIL} if not.
Because of these differences, caution must be exercised in turning {fn JSYS} calls into {fn JS} calls.
The symbolic JSYS name is looked up on the list {var JSYSES}{index JSYSES Var}, an association-list with elements of the form {lisp ({arg JSYSNAME} {arg JSYSNUMBER} {arg #SKIPS})}. If no entry is found, then the file {lisp STENEX.MAC} (or {lisp SYS:MONSYMS.MAC} for Tops-20) is scanned.
}}
Examples: {lisp (JS BIN (OPNJFN {arg FILE}) NIL NIL 2)} returns the value of {lisp AC2} after doing a {lisp BIN} from the JFN of {arg FILE}.
{lisp (JS BOUT (OPNFJN {arg FILE}) 3)} sends a control-C to {arg FILE}. The value of this {fn JS} call is garbage.
{FnDef {FnName XWD} {FnArgs N{sub 1} N{sub 2}}
{Text
Returns {lisp (LOGOR (LLSH {arg N{sub 1}} 18) (LOGAND {arg N{sub 2}} 777777Q))}, i.e. the word with {arg N{sub 1}} in the left half and {arg N{sub 2}} in the right.
}}
{FnDef {FnName BIT} {FnArgs BIT# WORD}
{Type NOSPREAD}
{Text
If {arg WORD} is not specified, {arg BIT} simply returns a number with bit {arg BIT#} set to 1 and all other bits 0. If {arg WORD} is given, then {fn BIT} is a predicate that returns {lisp T} if {arg BIT#} is set in {arg WORD}. Bits are numbered from left to right.
Examples: {lisp (BIT 32)} is 8 (=10Q), {lisp (BIT 32 8)} is {lisp T}.
}}
{FnDef {FnName JSYSERROR} {FnArgs ERRORN}
{Type NLAMBDA}
{Text
Returns the TENEX/TOPS-20 error number for {arg ERRORN}. For example, {lisp (JSYSERROR GJFX23)} is {lisp 600103Q}. {fn JSYSERROR} compiles open as a constant.
}}
This package also defines the following {fn ASSEMBLE} macros:
{Begin LabeledList ASSEMBLE macros}
{Label {lisp (JS {arg JSYSNAME})}}
{Item
{index JS (ASSEMBLE macro)}Can be used in {fn ASSEMBLE} statements instead of {lisp (JSYS {arg JSYSNUMBER})}.
}
{Label {lisp (CV {arg EXPR})}}
{Item
{index CV (ASSEMBLE macro)}Expands to {lisp (CQ (VAG (FIX {arg EXPR})))}, which unboxes {arg EXPR} to {lisp AC1}.
}
{Label {lisp (CV2 {arg EXPR})}}
{Item
{index CV2 (ASSEMBLE macro)}Expands to {lisp (CQ2 (VAG (FIX {arg EXPR})))}, which unboxes {arg EXPR} to {lisp AC2}, saving {lisp AC1}.
}
{End LabeledList ASSEMBLE macros}
{index *END* cjsys package}
}{End SubSec Cjsys}
{Begin SubSec Nobox}
{Title Nobox}
{Text
{index *BEGIN* Nobox package}
{note The {lisp NOBOX} package was written by R. M. Kaplan with assistance from B. A. Sheil and M. Kay.}
{it
Note: Nobox is a LispUsers package that is contained on the file {lisp NOBOX.COM}. It only works with Interlisp-10.
}
This package contains facilities for subverting the normal manner of dynamically allocating and collecting {fn CONS} cells, large integer boxes, and floating boxes in Interlisp-10 by using static, compile-time allocation. Storage allocation is controlled by allocating the memory for temporary results (e.g. a list that will be thrown away or a floating number that will not exist outside a local computational context) at compile-time or load-time. This "static" storage will be reused whenever the given line of code is re-executed. Because functions which use these facilities may exhibit bizarre behaviour if they are called recursively or if values escape outside of them, these facilities must be used with extreme caution, and should be reserved for those cases where the normal method of storage allocation and garbage collection is not workable or practical. Note: compiled functions need no run-time support for these facilities, i.e. {lisp NOBOX} does not have to be loaded to execute compiled code.
{Begin SubSec CONS Cells}
{Title CONS Cells}
{Text
The function {fn CBOX}{index CBOX FN} may be used to avoid allocation of {fn CONS} cells. When run interpreted, {fn CBOX} is exactly equivalent to the function {fn CONS}. Compiled, {fn CBOX} operates like {fn CONS}, except that the {fn CONS} cell returned is constructed (once) at compile or load time. New values for {fn CAR} and {fn CDR} are smashed into the cell at each execution.
The function {fn LBOX}{index LBOX FN} performs an analagous role for {fn LIST}. When run interpreted, {fn LBOX} is exactly equivalent to {fn LIST}. Compiled, the corresponding {fn CONS} cells are allocated at compile or load time. For example, {lisp (LBOX A B C)} will cause a 3-element static list to be included with a compiled function's literals. Each time the corresponding compiled code is executed, those three cells will be returned containing the current values of the variables {lisp A}, {lisp B}, and {lisp C}.
{fn LBOX} allocates as many cells as there are arguments in the corresponding form, i.e. the number of scratch cells is determined at compile time. The iterative statement operator {index SCRATCHCOLLECT (I.S. Operator)}{lisp SCRATCHCOLLECT} enables avoiding {fn CONS}es when the length of a list is not known at compile-time. {lisp SCRATCHCOLLECT} is used in iterative statements exactly as {lisp COLLECT}. Each time it is executed, it reuses the cells that it returned on previous executions, which it remembers as an internal scratch list. The length of this scratch list is always the length of the longest value that was ever returned; new cells are allocated whenever the scratch list runs out, and they are permanently remembered.
The {lisp SCRATCHCOLLECT} i.s.opr and the function {fn SCRATCHLIST} ({PageRef Fn SCRATCHLIST}) have similar applications. With {fn SCRATCHLIST}, the user makes explicit the origin of the list getting smashed, while with the {lisp SCRATCHCOLLECT} i.s.opr, the scratch list is hidden (and there is a different scratch-list for each occurence of the i.s.opr).
}{End SubSec CONS Cells}
{Begin SubSec Number Boxes}
{Title Number Boxes}
{Text
The functions {fn IBOX}, {fn FBOX}, and {fn NBOX}, and the record declarations {lisp IBOX} and {lisp FBOX} are provided to improve the efficiency of arithmetic computations.
They permit information to be given to the Interlisp-10 compiler that will inhibit the allocation (and subsequent collection) of number boxes needed for holding temporary results of numeric computations.{foot
In the latter respect, these duplicate some of what {fn SETN} ({PageRef Fn SETN}) does, except that they are more convenient to use and are executed with less run-time checking (i.e. {fn SETN} will never smash random memory locations).
}{comment endfootnote}
In addition, access time to variable-values that are known to be large integers or floating point numbers is improved.
The records {lisp IBOX}{index IBOX (record declaration)} and {lisp FBOX}{index FBOX (record declaration)} essentially describe the structure of large integer and floating point boxes respectively.
{lisp IBOX} consists of a single field, called {lisp I}, which corresponds to the actual contents of the large integer box.
{lisp FBOX} consists of a single field, called {lisp F}, which corresponds to the contents of the floating point box.
For example, the user can create a large integer box containing a given value and assign it to {lisp X} by saying {lisp (SETQ X (create IBOX I ← {arg FORM}))}.
Even if the value of {arg FORM} is a {it small} integer, the result will be stored in a new, large number box.
This seeming inefficiency is important because if {it some} values of {arg FORM} might be large, making {it all} values large means that the compiler can be told how to treat all references to {lisp X} without generating run-time tests to discover how to do the unboxing. Thus, wherever the value of {lisp X} is to be referenced, the user simply writes {lisp (fetch I of X)}. In compiling this expression, the compiler generates a single {lisp MOVE} instruction without any type-testing whatsoever. The user can reuse that number box by saying {lisp (replace I of X with (FOO))}, which is equivalent to, but much more efficent than, {lisp (SETN X (FOO))}. In other words, once it is known that {lisp X} is bound to a large integer, {lisp (replace I of {ellipsis})} can be used in all number-contexts to inform the compiler of that fact.
The facilities described so far do nothing to suppress the creation of unnecessary boxes; indeed, the {lisp (create IBOX --)} will produces boxes for small numbers that would not be allocated otherwise. The functions (not records) {fn IBOX},{index IBOX FN} {fn FBOX},{index FBOX FN} and {fn NBOX}{index NBOX FN} are used to suppress unnecessary boxing of temporaries. Effectively, they cause "constant" or "static" boxes of the appropriate type to be allocated and stored in a function's literals when a function is compiled or loaded. Those boxes can be used (and reused) to hold temporary results.
{fn IBOX} and {fn FBOX} can be called with 0 or 1 arguments. If no arguments are specified (as opposed to a single argument whose value is {lisp NIL}), then the value of the function is a large-integer or floating number box which is allocated statically. For example, these might be used to construct an initial binding for a variable into which temporary values will be stored using the {lisp I} or {lisp F} assignments. For example:
{lispcode
(PROG ((X (IBOX))) (replace I of X with (FOO)) {ellipsis})}.
If an argument is specified for {fn IBOX} or {fn FBOX}, then a static box of the appropriate type will be allocated at compile- or load-time, and the value of the argument will be stored in that box whenever the {lisp IBOX} statement is executed. For example, suppose the user wanted to set a file pointer to 1 past a given byte position. The expression
{lispcode
(SETFILEPTR FILE (ADD1 POS))}
would generate a new number box on each execution for which {lisp POS} happened to be a large number. That box would be passed into {fn SETFILEPTR} and then returned as its value. Since the value is not saved, the box would be thrown away, to be collected later. The expression
{lispcode
(SETFILEPTR FILE (IBOX (ADD1 POS)))}
would store the desired position in a constant box, and no allocations would take place.
As another example, consider a complicated integer expression whose value must be saved in a variable to be used a little further down in a program:
{lispcode
(SETQ X (IPLUS 2000 (ITIMES FOO (IQUOTIENT FUM 5))))
.
.
.
(SETQ Z (IPLUS X (GETFILEPTR FILE)))}
The Interlisp-10 compiler is smart enough to suppress the boxing inside the {lisp (IPLUS 2000 &)} expression, but it will generate a box when it comes to do the {fn SETQ}. This box can be suppressed by writing
{lispcode
(SETQ X (IBOX (IPLUS 2000 (ITIMES FOO (IQUOTIENT FUM 5)))))}
Furthermore, since it is known that {lisp X} is bound to a large integer, the {lisp Z} assignment can be speeded up by writing
{lispcode
(SETQ Z (IPLUS X:I (GETFILEPTR FILE)))}
The function {fn FBOX} behaves the same as {fn IBOX}, except that it uses constant floating boxes. Note that if the argument of {fn IBOX} is {lisp FLOATP}, then it will be {fn FIX}ed; if the argument of {fn FBOX} is {lisp FIXP}, it will be {fn FLOAT}ed.
The function {fn NBOX}{index NBOX FN} is a generic function for copying unknown values into constant number boxes. It allocates two constant boxes, one integer and one floating, and stores the value of its argument in the one compatible with the value's type. {fn NBOX} is useful if the argument value is a constant number box (but one of unknown type) that needs to be copied (see caution (2) below).
}{End SubSec Number Boxes}
{Begin SubSec Cautions}
{Title Cautions}
{Text
There are some dangers in using these facilities. The user of this package should be particularly aware of the following:
(1) The {lisp F} and {lisp I} fields aim at efficiency more than validity. This means that they {it do not check the type} of the pointer that they smash into. For example, if {lisp X} is bound to {lisp NIL}, the expression {lisp (replace I of X with Z} will clobber {fn CAR} and {fn CDR} of {lisp NIL}! The user must be very careful that the arguments given for replacing do indeed point to cells that unboxed numbers can be smashed into. Note: the {lisp DECL} package ({PageRef Tag DECL}) can be used to generate the {lisp replace}s, {fn IBOX}es, {fn FBOX}es automatically in a safe and efficient way.
(2) {fn CBOX}, {fn LBOX}, {lisp SCRATCHCOLLECT}, {fn IBOX}, and {fn FBOX} all allocate constant boxes, and those boxes will be reused (i.e. smashed with new values) every time the code containing that function call is executed. If that box is saved in a variable or data-structure (e.g. by a {fn SETQ}) as a way of preserving the value it contains, and then the code is re-executed, the value that was saved will be smashed. Thus, the user must beware of using constant boxes to save information in loops or recursions that can get back to the same statement. In these situations, the values must be copied into other cells, perhaps a constant associated with some other line of code, or into cells allocated in the ordinary way. The user must also be careful about returning a constant box as the value of a function, since the caller might unknowingly save the value and re-invoke the box-returner.
(3) Because the constant boxes are allocated only in compiled code, {it these functions will work quite differently compiled and interpreted}. Side effects which occur because of inadvertent smashing of shared structures will only occur when running compiled definitions and will not be detectable when running interpreted.
}{End SubSec Cautions}
{index *END* nobox package}
}{End SubSec Nobox}
{Begin SubSec Dateformat}
{Title Dateformat}
{Text
{note The dateformat package was written by M. Yonke.}
{it
Note: Dateformat is a LispUsers package that is contained on the file {lisp DATEFORMAT.COM}. It only works in Interlisp-10.
}
{index *BEGIN* dateformat package}
{Tag DateFormat}
Dateformat is a small file (one function) which provides assistance for constructing format bits for the {lisp ODTIM} JSYS (output date/time) as required by {fn DATE} and {fn GDATE} ({PageRef Fn DATE}).
{FnDef {Name DATEFORMAT} {Args KEY{sub 1} {ellipsis} KEY{sub N}}
{Type NLAMBDA NOSPREAD}
{Text
{arg KEY{sub 1}} {ellipsis} {arg KEY{sub N}} are a set of keywords (unevaluated). {fn DATEFORMAT} returns a number suitable as a parameter to {fn DATE} and {fn GDATE}. The variable {var DATEFORMAT.DEFAULT}{index DATEFORMAT.DEFAULT Var} is the number used as the initial value to work with. Therefore, to switch any of the defaults, set the variable {var DATEFORMAT.DEFAULT} to be the value of a call to {fn DATEFORMAT} with the appropriate keys.
}}
The keywords are given below (usually in pairs) and can be thought of as switches (i.e. turn on or off a particular format feature). If no keyword is given for a particular pair, the default is used.
The variable {var DATEFORMAT.KEYS}{index DATEFORMAT.KEYS Var} is a list of the keywords used for spelling correction.
{Begin LabeledList DATEFORMAT keywords}
{Name {lisp DATE} (default)}
{Name {lisp NO.DATE}}
{Text Do/don't include the date information.}
{Name {lisp NAME.OF.MONTH} (default)}
{Name {lisp NUMBER.OF.MONTH}}
{Text Show the month as a name ({lisp NAME.OF.MONTH}) or a number ({lisp NUMBER.OF.MONTH}).}
{Name {lisp MONTH.LONG}}
{Name {lisp MONTH.SHORT} (default)}
{Text If the name of the month was requested, spell it out ({lisp MONTH.LONG}) or abbreviate it ({lisp MONTH.SHORT}).}
{Name {lisp YEAR.LONG}}
{Name {lisp YEAR.SHORT} (default)}
{Text Print four digit year, e.g. 1978 ({lisp YEAR.LONG}) or two digit year, e.g. 78 ({lisp YEAR.SHORT}).}
{Name {lisp DAY.OF.WEEK}}
{Name {lisp NO.DAY.OF.WEEK} (default)}
{Text Do/Don't include the day of the week in the date information.}
{Name {lisp DAY.LONG}}
{Name {lisp DAY.SHORT} (default)}
{Text If the day of the week was included, spell it out ({lisp DAY.LONG}) or abbreviate it ({lisp DAY.SHORT}).}
{Name {lisp DASHES} (default)}
{Name {lisp SLASHES}}
{Name {lisp SPACES}}
{Text Separate the <day>, <month>, and <year> fields with dashes/slashes/spaces.}
{Name {lisp USA.FORMAT}}
{Name {lisp EUROPE.FORMAT} (default)}
{Text Print the date in the order <month> <day> <year> ({lisp USA.FORMAT}) or in the order <day> <month> <year> ({lisp EUROPE.FORMAT}).}
{Name {lisp LEADING.SPACES} (default)}
{Name {lisp NO.LEADING.SPACES}}
{Text If {lisp LEADING.SPACES} is specified, the <day> field will always be two characters long. If {lisp NO.LEADING.SPACES}, the <day> field can be one character for dates earlier than the 10th.}
{Name {lisp TIME} (default)}
{Name {lisp NO.TIME}}
{Text Do/Don't include the time information.}
{Name {lisp TIME.ZONE}}
{Name {lisp NO.TIME.ZONE} (default)}
{Text Do/Don't include the time zone in the time specification.}
{Name {lisp SECONDS} (default)}
{Name {lisp NO.SECONDS}}
{Text Do/Don't include the seconds.}
{Name {lisp CIVILIAN.TIME}}
{Name {lisp MILITARY.TIME} (default)}
{Text Use 12 hour time with AM or PM ({lisp CIVILIAN.TIME}) or 24 hour time ({lisp MILITARY.TIME}).}
{End LabeledList DATEFORMAT keywords}
{index *END* dateformat package}
}{End SubSec Dateformat}
{Begin SubSec Exec}
{Title Exec}
{Text
{index *BEGIN* exec package}
{note The Exec package was written by L. M. Masinter, D. C. Lewis and J. J. Vittal.}
{it
Note: The Exec package is a LispUsers package that is contained on the file {lisp EXEC.COM}. The Exec package uses the passwords package (see {PageRef Tag PasswordPackage}). Loading {lisp EXEC.COM} will load {lisp PASSWORDS.COM} if it has not already been loaded. Note: some of the facilities described below will work correctly only on TENEX systems, others only on TOPS-20. The system will inform the user when he attempts to use a facility not supported by his particular operating system.
}
This package defines a set of programmer's assistant commands which resemble features of the Tenex EXEC. It also defines functions that provide certain EXEC capabilities for Interlisp programs, e.g. changing the connected directory, detaching the job, etc.
{Begin SubSec Exec Commands}
{Title Exec Commands}
{Text
{Def {Type (Exec Command)} {Name DA}
{Text
Prints out the current time and date.
}}
{Def {Type (Exec Command)} {Name LD} }
{Def {Type (Exec Command)} {Name SY} }
{Def {Type (Exec Command)} {Name WHE}
{Text
Prints SYSTAT information, just like the {lisp LD} subsystem. Jobs are sorted in inverse order of CPU utilization.
}}
{Def {Type (Exec Command)} {Name LD} {Args USERNAME} {NoParens}
{Text
Prints information for the specified user only.
}}
{Def {Type (Exec Command)} {Name LD ALL}
{Text
Like {lisp LD}, but includes system jobs.
}}
{Def {Type (Exec Command)} {Name DET}
{Text
Detaches the current job.
}}
{Def {Type (Exec Command)} {Name QU}
{Text
Does a {lisp (LOGOUT)}. Does not go on history list.
}}
{Def {Type (Exec Command)} {Name LINK} {Args USER} {NoParens} }
{Def {Type (Exec Command)} {Name TALK} {Args USER} {NoParens}
{Text
Mimics the exec link command. If {arg USER} has multiple jobs logged in, asks which tty to link to.
}}
{Def {Type (Exec Command)} {Name BR}
{Text
Breaks links.
}}
{Def {Type (Exec Command)} {Name CONN} {Args DIR PWD} {NoParens}
{Text
Connects to the directory {arg DIR}. If the password {arg PWD} is not given and is required, {lisp CONN} will prompt. {arg DIR} can be abbreviated; if omitted, it defaults to the user's login directory. If {arg PWD} is given in command line, it is removed from the history list so that {lisp ??} will not print it out. Password prompting is handled by {fn GETPASSWORD} from the passwords package ({PageRef Tag PasswordPackage}).
}}
{Def {Type (Exec Command)} {Name NDIR} {Args FILEGROUP} {NoParens}
{Text
Prints the files in {arg FILEGROUP} in a multi-column format.
}}
{Def {Type (Exec Command)} {Name DEL} {Args FILEGROUP} {NoParens}
{Text
Deletes specified files. Uses {fn DIRECTORY} ({PageRef Fn DIRECTORY}). Note that if <esc> is specified, {it all} files that match will be deleted. This command is undoable.
}}
{Def {Type (Exec Command)} {Name UND} {Args FILEGROUP} {NoParens}
{Text
Undeletes the specified files (undoably).
}}
{Def {Type (Exec Command)} {Name DELVER} {Args FILEGROUP} {NoParens}
{Text
Deletes all but 1 version of the filegroup specified. Uses {fn DIRECTORY} ({PageRef Fn DIRECTORY}), so {arg FILEGROUP} may utilize any of the options allowed for directory filegroup specifications.
}}
{Def {Type (Exec Command)} {Name EXP} {Args DIR} {NoParens}
{Text
Expunges directory {arg DIR}. If the user does not have access to {arg DIR}, a message is printed.
}}
{Def {Type (Exec Command)} {Name TY} {Args FILE OUTFILE BYTESIZE} {NoParens} }
{Def {Type (Exec Command)} {Name SEE} {Args FILE OUTFILE BYTESIZE} {NoParens}
{Text
Copies {arg FILE} to {arg OUTFILE}, or to {lisp T} if {fn OUTFILE} is not given. Assumes that the bytes of {arg FILE} are {arg BYTESIZE} bits wide ({arg BYTESIZE}={lisp NIL} defaults to 7). Suppresses blank lines and control character sequences used to indicate font changes.
}}
{Def {Type (Exec Command)} {Name DSK} {Args DIR DAYS} {NoParens}
{Text
Prints out disk allocation and usage for the directory {arg DIR} using {fn DSKSTAT}. Also prints total size of files untouched in days {arg DAYS} (90 if {arg DAYS} not specified).
}}
{Def {Type (Exec Command)} {Name FI}
{Text
Like the EXEC {lisp FILESTAT} command, prints out status of all currently assigned JFNS for the current job.
}}
{Def {Type (Exec Command)} {Name FI} {Args JFN} {NoParens}
{Text
Prints information for {arg JFN} only.
}}
}{End SubSec Exec Commands}
{Begin SubSec EXEC Functions}
{Title EXEC Functions}
{Text
{FnDef {FnName JOB#} {FnArgs }
{Text
Returns the job number for the logged in job.
}}
{FnDef {FnName TTY#} {FnArgs }
{Text
Returns the teletype-number of the current job.
}}
{FnDef {FnName DETACH} {FnArgs }
{Text
Detaches the current job.
}}
{FnDef {FnName DETACHEDP} {FnArgs }
{Text
Returns {lisp T} if the current program is running detached.
}}
{FnDef {FnName LINKTOTTY} {FnArgs TTY#}
{Text
Generates a two-way link between the controlling terminal of the user's job and {arg TTY#}. Returns {lisp T} if the link was successful, otherwise prints an error message and returns {lisp NIL}.
}}
{FnDef {FnName LINKTOUSER} {FnArgs USER}
{Text
Links the controlling terminal to a terminal associated with {arg USER}. Generates an error if the user is not logged in or not attached.
If {arg USER} has more than one attached job, then a systat of his jobs is printed, and the user is asked to provide the proper tty number for the job. Returns {lisp T} if successful.
}}
{FnDef {FnName BREAKLINKS} {FnArgs }
{Text
Breaks all links to the user's controlling terminal.
}}
{FnDef {FnName CNDIR} {FnArgs DIR PASSWORD}
{Text
Implements the {lisp CONN} command.
}}
{FnDef {FnName /DELFILE} {FnArgs FILE}
{Text
Undoable version of {fn DELFILE}.
}}
{FnDef {FnName /UNDELFILE} {FnArgs FILE}
{Text
Undeletes a single file (undoably).
}}
{FnDef {FnName EXPUNGE} {FnArgs DIR}
{Text
Expunges directory {arg DIR}. On TENEX, {arg DIR} is ignored. and the connected directory is expunged. On TOPS20, if the user does not have access to {arg DIR}, a message is printed.
}}
{FnDef {FnName COPYALLBYTES} {FnArgs FROMFILE TOFILE BYTESIZE}
{Text
Implements the {lisp SEE} command.
}}
{FnDef {FnName DSKSTAT} {FnArgs DIR PRINTIFOVER PRINTSYS PRINTDEL PRINTOLD}
{Text
Prints disk usage statistics for directory {arg DIR} (either a name or number).
If {arg PRINTIFOVER} is {lisp NIL}, this means always print. If {arg PRINTIFOVER} is {lisp T}, this means only print if {arg DIR} is over allocation. If {arg PRINTIFOVER} is a number, this means only print if {arg DIR} has more than that many pages in use.
If {arg PRINTSYS} is {lisp T}, this means print system disk statistics too.
If {arg PRINTDEL} is {lisp T}, this means print total size of deleted files for {arg DIR} (this is slow).
If {arg PRINTOLD} is {lisp T} or a number, this means print total size of files untouched in 90 (or {arg PRINTOLD}) days.
}}
{FnDef {FnName MEMSTAT} {FnArgs PG1 PGN FORK}
{Text
Prints the status of the memory pages {arg PG1} (0 if {arg PG1}={lisp NIL}) to {arg PGN} (the last page of memory if {lisp NIL}) in fork {arg FORK}. {arg FORK} is either {lisp NIL}, meaning the current fork, or a fork handle.
}}
}{End SubSec EXEC Functions}
{index *END* exec package}
}{End SubSec Exec}
{Begin SubSec Passwords}
{Title Passwords}
{Text
{Tag Passwordpackage}
{index passwords package}
{note The passwords package was written by L. M. Masinter.}
{it
Note: Passwords is a LispUsers package that is contained on the file {lisp PASSWORDS.COM}. It only works with Interlisp-10.
}
{FnDef {FnName GETPASSWORD} {FnArgs DIRECTORYNAME}
{Text
Prompts the user for the password for the given directory. The user's response is not echoed. {fn GETPASSWORD} remembers the password so that it need not ask again; however, saved information is cleared before {fn SYSOUT}, so that the {fn SYSOUT} contains no passwords.
}}
}{End SubSec Passwords}
{Begin SubSec Telnet}
{Title Telnet}
{Text
{index telnet package}
{note The telnet package was written by L. M. Masinter.}
{it
Note: Telnet is a LispUsers package that is contained on the file {lisp TELNET.COM}. It only works with Interlisp-10. Since the telnet package uses the net package, loading {lisp TELNET.COM} will also load {lisp NET.COM} unless it has already been loaded.
}
This package makes it possible to interact with connections created via the net package ({PageRef Tag NetPackage}) without leaving Interlisp. In addition, all typeout is included in the {fn DRIBBLE} file. It permits connections to ARPANET hosts (a la TELNET).
{FnDef {FnName TELNET} {FnArgs CONNECTION TYPE SKT {anonarg}}
{Text
{arg CONNECTION} may be an instance of a {lisp CONNECTION} record (as created by {fn MAKENEWCONNECTION}, {PageRef Fn MAKENEWCONNECTION}). Alternatively, if {arg CONNECTION} is a litatom, {fn TELNET} uses {lisp (MAKENEWCONNECTION {arg CONNECTION} {arg TYPE} {arg SKT})} for the connection. In any case, {fn TELNET} returns the connection as an instance of the {lisp CONNECTION} record, so that it is possible to {fn TELNET} back.
}}
}{End SubSec Telnet}
{Begin SubSec Ftp}
{Title Ftp}
{Text
{index ftp package}
{note The ftp package was written by L. M. Masinter.}
{it
Note: Ftp is a LispUsers package that is contained on the file {lisp FTP.COM}. It only works with Interlisp-10. Since the Ftp package uses the net and passwords packages, loading {lisp FTP.COM} will also load {lisp NET.COM} and {lisp PASSWORDS.COM} if they are not already loaded.
}
The ftp package makes it possible to deal with files at other hosts on the Arpa network almost as if they were files on the user's local machine, i.e. the files can be opened via {fn INFILE}, {fn OUTFILE}, {fn OPENFILE}, read from and printed to by the ordinary reading and printing functions, and closed in the standard way.
{index curly brackets (use with ftp package)}
{index brackets (use with ftp package)}
Files on remote hosts are designated by including the host name between
curly brackets, {bracket}, at the front of the ordinary file name. Since curly brackets are illegal characters in regular file names,{note in Interlisp-D?} a {lisp BAD FILE NAME} error is generated. This error is intercepted by an entry on {var ERRORTYPELST} (see {PageRef Var ERRORTYPELST})
which then establishes the appropriate network connections.{foot
Note: it is fairly expensive to open a network connection as compared with the time to open a local file, e.g. an order of magnitude slower.
}{comment endfootnote}
For example, {lisp (INFILE '{bracket BBN-D}<LEWIS>INIT.LISP)} will open the file {lisp <LEWIS>INIT.LISP} on the host {lisp BBN-D} and make it be the primary input file. The user could then say {lisp (READ)} to obtain the first expression on that file. The ftp package extends the functions {fn PACKFILENAME}, {fn UNPACKFILENAME}, and {fn FILENAMEFIELD} so that they will associate the curly bracket syntax with the new file field {lisp HOST}{index HOST (as a file name field)}. Thus, {lisp (PACKFILENAME 'HOST 'BBND 'NAME 'INIT)} will return {lisp {bracket BBND}INIT}.
Remote files have certain properties that limit how they may be used:
(1) {fn RANDACCESSP} is {lisp NIL} for such files, and {fn SETFILEPTR} may not be applied to them. This means, for example, that functions and variables may not be loaded from such files via {fn LOADFNS}.
(2) The open bytesize of a remote file may not be changed (e.g. by {fn SETFILEINFO}). This means that Interlisp-10 compiled files may not be loaded from remote hosts.
(3) The remote host may close the connection spontaneously (e.g. because of
a timeout if the file is not referenced for some length of time, or because of
a crash). If this happens, the next attempt at reading or writing on the file will
generate {lisp FILE DATA ERROR}{index FILE DATA ERROR Error}. Note: it is unwise to keep a remote file open for long periods of time.{foot
For input files, these limitations may be skirted conveniently in the following way: if a colon appears between the last character of the host name and the right curly bracket (e.g. {lisp {bracket BBND:}<LEWIS>INIT.LISP}), then the remote file will be copied to a temporary {it local} file when it is opened, and all subsequent references will be to that local file.
}{comment endfootnote}
When the connection for the remote file is first established, a password for the
remote machine/directory may be required. The user will be asked to supply
one via the passwords package ({PageRef Tag Passwordpackage}). Alternatively, if the host name has on its property list the property {prop LOGIN}{index LOGIN Prop} with value of the form {lisp ({arg NAME} {arg PASSWORD} {arg ACCOUNT})}, then the indicated {arg NAME}, {arg PASSWORD}, and {arg ACCOUNT} will be used to log the user into the remote host.{foot
If the value is of the form
{lisp ({arg NAME} NIL {arg ACCOUNT})},
then {lisp (GETPASSWORD {arg NAME})} will be used for the password. If the {arg ACCOUNT} field is {lisp NIL}, no account will be supllied to the remote host. If no {prop LOGIN} property is supplied, {lisp ANONYMOUS} will be used as the user name.
}{comment endfootnote}
{FnDef {FnName FTP} {FnArgs HOST FILE ACCESS USER PASSWORD ACCOUNT BYTESIZE}
{Text
Opens a network connection to the ftp server at {arg HOST}. If {arg ACCESS}={lisp INPUT} or {lisp OUTPUT}, {fn FTP} works like {fn OPENFILE}: value is a literal atom of the form
{lisp {bracket {arg HOST}}{arg FILE}}
which can then be used as a file name by all Interlisp input and output functions, e.g. {fn READ}, {fn PRINT}, {fn COPYBYTES}, etc.{foot
In reality, this "file" is a network connection to the host's ftp server. This "file" has a {fn WHENCLOSE} attribute ({PageRef Fn WHENCLOSE}) associated with it so that when Interlisp closes the file, the correct terminating sequence will be performed.
}{comment endfootnote}
For example, {lisp (FTP 'SU-AI 'YUMYUM%[P,DOC%] 'INPUT)} will allow the Stanford Restraurant Guide to be read. Note that {arg FILE} must satisfy the file name conventions of the remote host.
If {arg ACCESS}={lisp DIRECTORY}, then {fn FTP} will print on the terminal the names of all files which match {arg FILE}, e.g. {lisp (FTP 'PARC-MAXC2 '<NETLISP>*.SAV 'DIRECTORY)}.
{arg USER}, {arg PASSWORD}, and {arg ACCOUNT} are used for logging in to the remote host. If not supplied, the values are obtained from the {prop LOGIN} property (if any) as described above. {arg BYTESIZE} is the byte size in which to open the connection. Byte sizes of 7, 8, 16, 32 and 36 are supported. {arg BYTESIZE}={lisp NIL} defaults to 7.
}}
}{End SubSec Ftp}
{Begin SubSec Net}
{Title Net}
{Text
{index *BEGIN* net package}
{Tag NetPackage}
{note The net package was written by L. M. Masinter.}
{it
Note: Net is a LispUsers package that is contained on the file {lisp NET.COM}. It only works with Interlisp-10.
}
This package contains functions for establishing ARPANET connections from an Interlisp-10 job. A connection is described by and is an instance of the record {lisp CONNECTION}. The only fields of interest to the user in this record are {lisp IN} and {lisp OUT}, which are guaranteed to be {fn CAR} and {fn CADR}, respectively. {lisp IN} is a file name which can be read from, {lisp OUT} a file name which can be printed to.
{FnDef {FnName MAKENEWCONNECTION} {FnArgs HOST TYPE SKT SCRATCHCONN WAITFLG}
{Text
Makes a connection to {arg HOST}. For {arg TYPE}={lisp ARPA}, {arg HOST} is the name of the host to which the connection is to be made. For {arg SKT}={lisp NIL} (the normal case), the connection will be to the telnet server of {arg HOST}; connections to other servers can be made by supplying the appropriate value for {arg SKT}.
The value of {fn MAKENEWCONNECTION} is a {lisp CONNECTION}. If {arg WAITFLG} is non-{lisp NIL}, {fn MAKENEWCONNECTION} waits until its request for connection is acknowledged. Otherwise, {fn CHECKCONNECTION} must be called on the result before it is used (this allows additional processing to be done while waiting for the remote host to respond).
If {arg SCRATCHCONN} is non-{lisp NIL}, it is a scratch connection which is reused.
}}
For example, {lisp (MAKENEWCONNECTION 'BBND)} makes an ARPA connection to BBND, {lisp (MAKENEWCONNECTION 'SU-AI 'ARPA 'FINGER)} makes a connection to the Stanford {fn WHEREIS} service.
{FnDef {FnName CLOSECONNECTION} {FnArgs CONNECTION}
{Text
Closes the given {arg CONNECTION} and replaces the {lisp IN} and {lisp OUT} fields with {lisp NIL}.
}}
{FnDef {FnName CHECKCONNECTION} {FnArgs CONNECTION}
{Text
Checks to make sure that the given connection is still open (e.g. it hasn't been closed remotely). If the connection is valid, {arg CONNECTION} is returned. If the connection is in an in-between state, i.e. in the process of being opened or closed, {fn CHECKCONNECTION} waits to see what happens before returning. Otherwise the connection is cleaned up (as if a {fn CLOSECONNECTION} were performed) and {fn CHECKCONNECTION} returns {lisp NIL}.
}}
{FnDef {FnName NETSERVER} {FnArgs ARPA# WAITFLG}
{Text
Initiates a "server" connection. This is a connection which will talk to a "user" connection. If {arg WAITFLG} is non-{lisp NIL}, waits for a user to connect; if {arg WAITFLG}={lisp NIL}, returns immediately (and {fn CHECKCONNECTION} must be called on the connection before the connection is actually used). {arg ARPA#} defaults to 0.
}}
{FnDef {FnName NETUSER} {FnArgs HOST USER ARPA# WAITFLG}
{Text
Initiates the other half of an Arpa connection. {arg ARPA#} defaults to 0 and must be the same as the argument given the corresponding call to {fn NETSERVER}. {arg USER} must be the {lisp USERNUMBER} (directory number) under which the server job is logged in.
}}
For example, to establish an ARPANET connection between two Interlisp jobs (which can then be written to and read from like files), do {lisp (SETQ CONN (NETSERVER))} in one job and {lisp (SETQ CONN (NETUSER {arg HOST} {arg USER}))} in the other job, where {arg HOST} is the machine on which the first job is running and {arg USER} is the directory number under which the first job is logged in (obtainable through the function {fn USERNUMBER}). Then, perform {lisp (CHECKCONNECTION CONN)} in each job; when these return, the connection is ready to be used.
{FnDef {FnName FORCEOUT} {FnArgs CONNECTION/FILE}
{Text
Normally, characters sent to the {lisp "OUT"} of a connection are buffered locally. The function {fn FORCEOUT} can be used to force partially filled packets of bytes to be sent across the connection. The argument to {fn FORCEOUT} can either be the {lisp CONNECTION} record or the {lisp OUT} filename.
}}
{index *END* net package}
}{End SubSec Net}