{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.



{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 {lisp "{arg NET}#{arg HOST}#{arg SOCKET}"}, where each of {arg NET}, {arg HOST} and {arg SOCKET} is a sequence of octal digits; the socket, but not the terminating {lisp #}, 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, {lisp "{arg NET}#{arg HOST}#{arg 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 EFTP} {Args HOST FILE PRINTOPTIONS}
{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.  {fn EFTP} returns only on success; if {arg HOST} does not respond, it keeps trying.


The principal use of the {lisp EFTP} protocol is for transmitting Press files to a printer.  If {arg PRINTOPTIONS} is non-{lisp NIL}, {lisp EFTP} assumes that {arg HOST} is a printer and {arg FILE} is a Press file, and takes additional action: it calls {fn PRINTERSTATUS} ({PageRef 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 the value of {fn USERNAME} ({PageRef Fn USERNAME}).  Also, {arg PRINTOPTIONS} is interpreted as a list in property list format that controls details of the printing.  Possible properties are as follows:

{Begin labeledlist SEND.FILE.TO.PRINTER options}

{Label {lisp #COPIES}}
{Text
Value is the number copies of the file to print.  Default is one.
}

{Label {lisp #SIDES}}
{Text
If the value is 2, select two-sided printing (if the printer can print two-sided copies).
}

{Label {lisp DOCUMENT.CREATION.DATE}}
{Text
Value is the document creation date to appear on the header page (an integer date as returned by {fn IDATE}).
}

{Label {lisp DOCUMENT.NAME}}
{Text
Value is the document name to appear on the header page (as a string).  Default is the full name of the file.
}

{End labeledlist SEND.FILE.TO.PRINTER options}

}}

}{End SubSec Higher-level PUP Protocol Functions}