{Begin SubSec Higher-level PUP Protocol Functions}
{Title Higher-level PUP Protocol Functions}
{Text

This section describes some of the functions provided in Interlisp-D to perform protocols above Level One.  Level One functions are described in a later section, for the benefit of those users who wish to program new protocols.


The following functions provide assorted network services.



{FnDef {Name ETHERHOSTNUMBER} {Args NAME}
{Text
Returns the number of the named host.  The number is 16-bit quantity, the high 8 bits designating the net and the low 8 bits the host.  If {arg NAME} is {lisp NIL}, returns the number of the local host.
}}


{FnDef {Name ETHERPORT} {Args NAME ERRORFLG MULTFLG}
{Text
Returns a port corresponding to {arg NAME}. A "port" is a network address that represents (potentially) one end of a network connection, and includes a socket number in addition to the network and host numbers.  Most network functions that take a port as argument allow the socket to be zero, in which case a well-known socket is supplied.  A port is currently represented as a dotted pair {lisp ({arg NETHOST} . {arg SOCKET})}.

{arg NAME} may be a litatom, in which case its address is looked up, or a port, which is just returned directly.  If {arg ERRORFLG} is true, generates an error "host not found" if the address lookup fails, else it returns {lisp NIL}.  If {arg MULTFLG} is true, returns a list of alternative port specifications for {arg NAME}, rather than a single port (this is provided because it is possible for a single name in the name database to have multiple addresses).  If {arg MULTFLG} is {lisp NIL} and {arg NAME} has more than one address, the currently nearest one is returned.  {fn ETHERPORT} caches its results.

The {arg SOCKET} of a port is usually zero, unless the name explicitly contains a socket designation, a number or symbolic name following a {lisp +} in {arg NAME}, e.g., {lisp PHYLUM+LEAF}.  A port can also be specified in the form "net#host#socket", where each of net, host and socket is a sequence of octal digits; the socket, but not the terminating #, can be omitted, in which case the socket is zero.

}}


{FnDef {Name ETHERHOSTNAME} {Args PORT USE.OCTAL.DEFAULT}
{Text
Looks up the name of the host at address {arg PORT}.  {arg PORT} may be a numeric address, a {lisp ({arg NETHOST} . {arg SOCKET})} pair returned from {fn ETHERPORT}, or a numeric designation in string form, "net#host#socket", as described above.  In the first case, the net defaults to the local net.  If {arg PORT} is {lisp NIL}, returns the name of the local host.  If there is no name for the given port, but {arg USE.OCTAL.DEFAULT} is true, the function returns a string specifying the port in octal digits, in the form {lisp "{arg NET}#{arg HOST}#{arg SOCKET}"}, with {arg SOCKET} omitted if it is zero.  Most functions that take a port argument will also accept ports in this octal format.
}}

{Note Documentation for MAILCHECK removed.  If this goes back, it should be with Lafite}


{FnDef {Name PRINTERSTATUS} {Args PRINTERNAME}
{Text
Returns status of {arg PRINTERNAME}, the name of a Press Printer, in the form {lisp ({arg CODE} . "readable string")}.  Returns {lisp NIL} if the printer does not respond in a reasonable time, which can occur if the printer is very busy, or does not implement the printer status service.  {arg CODE} is interpreted as follows:

{Begin Labeledlist}

{Indent 20}

{Label 1}
{Text Printer is not spooling (down for servicing)}

{Label 2}
{Text Printer is idle}

{Label 3}
{Text Printer is busy (printing or accepting a file)}

{End Labeledlist}

}}


{FnDef {Name EFTP} {Args HOST FILE PRINTERFLG #SIDES}
{Text
Transmits {arg FILE} to {arg HOST} using the {lisp EFTP} protocol.  The {arg FILE} need not be open on entry, but in any case is closed on exit.  The principal use of the {lisp EFTP} protocol is for transmitting Press files to a printer.  If {arg PRINTERFLG} is non-{lisp NIL}, assumes that {arg HOST} is a printer and {arg FILE} is a press file, and takes additional action: it performs a {fn PRINTERSTATUS} for {arg HOST} and prints this information to the prompt window; and it fills in the "printed-by" field on the last page of the press file with {var USERNAME}, and the "copies" field with
{lisp (OR (FIXP {arg PRINTERFLG}) 1)}.  For printers capable of duplex printing, {arg #SIDES} may be 1 or 2, meaning print one- or two-sided, respectively; {lisp NIL} means use the printer's default.  {fn EFTP} returns only on success; if {arg HOST} does not respond, it keeps trying.
}}

}{End SubSec Higher-level PUP Protocol Functions}