Path: utzoo!mnetor!uunet!ccicpg!felix!dhw68k!macintosh
From: jdb@mordor.s1.gov (John Bruner)
Newsgroups: comp.sources.mac
Subject: UW v4.2 (part 2 of 9)
Message-ID: <6497@dhw68k.cts.com>
Date: 5 Apr 88 02:13:52 GMT
References: <6493@dhw68k.cts.com>
Sender: macintosh@dhw68k.cts.com
Organization: Lawrence Livermore National Laboratory, S-1 Project
Lines: 1142
Approved: bytebug@dhw68k.cts.com (Roger L. Long)

[UW v4.2 - part 2 of 9]

---
#! /bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #! /bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh (not csh) to create the files:
#	doc/uwproto.ms
#	doc/uwplot.l
#	doc/uwterm.l
#	doc/uwtitle.l
#	doc/uwtool.l
# This archive created: Mon Apr  4 07:51:45 1988
# By:	Roger L. Long (macintosh@dhw68k.cts.com)
export PATH; PATH=/bin:$PATH
if test ! -d doc
then
	echo shar: mkdir doc
	mkdir doc
fi
echo shar: extracting "'doc/uwproto.ms'" '(24952 characters)'
if test -f 'doc/uwproto.ms'
then
	echo shar: will not over-write existing file "'doc/uwproto.ms'"
else
sed 's/^X//' << \SHAR_EOF > 'doc/uwproto.ms'
X.\" This file should be processed by nroff or troff with the -ms macro set
X.ds uw "\s-2UW\s0
X.de T=
X.ie t .ta 8n 28n 36n 44n
X.el .ta 8n 24n 32n 40n
X..
X.DA September 30, 1986
X.TL
XUW Protocol
X.AU
XJohn D. Bruner
X.SH
XIntroduction
X.PP
X\*(uw is a multiple-window interface to UNIX.\**
X.FS
XUNIX is a registered trademark of American Telephone and Telegraph.
X.br
XMacintosh is a trademark of McIntosh Laboratories,
Xand is licensed to Apple Computer.
X.br
XADM-31 is a trademark of Lear Siegler, Inc.
X.br
XVT52 is a trademark of Digital Equipment Corporation.
X.br
XThe Tektronix 4010 is a graphics terminal manufactured
Xby Tektronix, Inc.
X.FE
XIt comprises two parts:
Xa program which runs on a Macintosh
X(referred to hereafter as ``the client'')
Xand a server program which runs on the UNIX system
X(``the host'').
XThese two programs exchange information by sending
Xdata across a serial communications line.
XThis information consists of data
Xand control and status messages relating to its presentation.
XThe structure of this information is defined by
Xthe \*(uw protocol
Xand is the subject matter of this document.
X.PP
X\*(uw version 3 actually defines three protocols.
XInternally they are assigned numbered,
Xwhile the user interface and documentation refer to them
Xby name.
XThe correspondence is as follows:
X.IP 0
XProtocol 0 is referred to as the ``serverless protocol''
Xor ``single terminal emulator protocol,''
Xbecause its use does not require a server on the host.
X.IP 1
XProtocol 1 is called the ``original \*(uw protocol,''
Xbecause it was the only protocol supported by the first
Xversions of \*(uw
X(versions 1.6 and 2.10).
X.IP 2
XProtocol 2 is called the ``extended \*(uw protocol,''
Xor (sometimes)
Xthe ``\*(uw version 3 protocol.''
X.SH
XProtocol 0 \(em The Serverless Protocol
X.PP
XProtocol 0 is not really a \*(uw protocol at all.
XThe client speaks protocol 0 when it is communicating
Xdirectly with a host,
Xrather than communicating through a server program
Xrunning on the host.
XProtocol 0 is simply 7-bit or 8-bit ASCII.
XEvery byte transmitted in protocol 0 represents itself,
Xwith the possible exception of the two flow-control characters
XXON (control-Q)
Xand
XXOFF (control-S).
XProtocol 0 does not specify whether these characters are
Xto be used for flow-control purposes or for data transmission.
XThe client program on the Macintosh and the host's terminal driver
Xcan be configured to use or ignore flow-control.
X.PP
XProtocol 0 does not specify whether data is transmitted
Xusing 8-bit ASCII or 7-bit ASCII.
XThe user must choose the appropriate transmission format
Xand is reponsible for configuring both the client and the host
Xaccordingly.
X.SH
XProtocol 1 \(em The Original \*(uw Protocol
X.PP
XProtocol 1 was the only protocol which was used in
Xthe first versions of \*(uw
X(versions 1.6 and 2.10).
XIt defines seven ``windows,''
Xeach of which is an independent data stream.
XThrough the transmission of appropriate commands,
Xwindows may be created or destroyed,
Xand data may be directed to a particular window.
XData which is transmitted from the client to the host
Xis referred to as ``input data,''
Xwhile data transmitted from the host to the client
Xis referred to as ``output data.''
XIn each direction a ``current window'' specifies
Xthe recipient of data bytes.
X(For example,
Xif the client wishes to send data to window 4,
Xit first sends a ``select window 4 as input window''
Xcommand and then sends the data.
XUntil the client sends another ``select input window'' command,
Xall further data that it transmits will be received
Xas data for window 4.)
XThe current input window and current output window may be different.
X.PP
XProtocol 1 encodes all information into 7-bit symbols;
Xit does not depend upon the value of the most-significant bit
X(sometimes used for parity purposes).
XCommands are encoded into two bytes:
Xa prefix byte (P1_IAC)
Xand a command byte.
XBit 7
X(the second most-significant bit, octal 0100)
Xspecifies whether the command was sent from the host to the client or
X.I "vice versa:"
X.DS
X.T=
X#define	P1_IAC	0001	/* intrepret following byte as a command */
X#define	P1_DIR	0100	/* command direction: */
X#define	P1_DIR_HTOM	0000	/*	from host to Mac (client) */
X#define	P1_DIR_MTOH	0100	/*	from Mac (client) to host */
X.DE
XThe command's function is encoded into the next three bits.
XThere are only seven commands:
X.DS
X.T=
X#define	P1_FN	0070	/* function code: */
X#define	P1_FN_NEWW	0000	/*	create new window */
X#define	P1_FN_KILLW	0010	/*	kill (destroy) window */
X#define	P1_FN_ISELW	0020	/*	select window for input data */
X#define	P1_FN_OSELW	0030	/*	select window for output data */
X#define	P1_FN_META	0050	/*	add META to next data character */
X#define	P1_FN_CTLCH	0060	/*	send control character as data */
X#define	P1_FN_MAINT	0070	/*	perform "maintenance function" */
X.DE
X(The client does not send the P1_FN_OSELW command;
Xsimilarly,
Xthe host does not send the P1_FN_ISELW command.)
X.PP
XThe least-significant three bits of the command byte
Xspecify an argument to the function.
XFor the ``new window'' (P1_FN_NEWW),
X``kill window'' (P1_FN_KILLW),
X``select input'' (P1_FN_ISELW),
Xand
X``select output'' (P1_FN_OSELW)
Xcommands,
Xthe low three bits specify a window number.
XWindow number zero is not used.
X.PP
XThere are no arguments to the P1_FN_META command.
XIt directs that the next data byte to be transmitted
Xbe considered a ``meta'' character;
X.I i.e.
Xa byte with the most-significant bit
X(octal 0200)
Xset.
X.PP
XThe P1_FN_CTLCH command is used to encode three
Xdata characters which cannot be transmitted directly as data.
XThese are P1_IAC
X(which,
Xif encountered in a transmission,
Xindicates the start of a two-character command),
Xand the flow-control characters XON (021)
Xand XOFF (023).
XThe low-order three bits of the command byte specify the character:
X.DS
X.T=
X#define	P1_CC	7	/* control character specifier: */
X#define	P1_CC_IAC	1	/*	P1_IAC (001) */
X#define	P1_CC_XON	2	/*	XON (021) */
X#define	P1_CC_XOFF	3	/*	XOFF (023) */
X.DE
XA meta-control character is transmitted as a P1_FN_META
Xcommand followed by the appropriate P1_FN_CTLCH command.
XThus,
Xthe octal character 0201 would be transmitted from the
Xhost to the client as
Xa four-byte sequence:
X.DS
X.T=
X0001	(P1_IAC)
X0050	(P1_DIR_HTOM|P1_FN_META)
X0001	(P1_IAC)
X0061	(P1_DIR_HTOM|P1_FN_CTLCH|P1_CC_IAC)
X.DE
XNote that since the host does not send P1_FN_OSELW commands
Xand the client sends commands with the 0100 bit set,
Xthe XON and XOFF control characters will never be sent as command bytes.
X.PP
X``Maintenance functions'' are defined for operations
Xwhich are performed infrequently.
XProtocol 1 defines two maintenance functions:
X.DS
X.T=
X#define	P1_MF	7	/* maintenance functions: */
X#define	P1_MF_ENTRY	0	/*	start up */
X#define	P1_MF_EXIT	7	/*	exit */
X.DE
XThe server sends the P1_MF_ENTRY command when it starts up.
XThe client responds to this by killing any windows that it
Xhas created
X(silently,
X.I i.e.
Xwithout sending P1_FN_KILLW messages to the host).
XEither the client or the server may send the P1_MF_EXIT command
Xto terminate the session.
XWhen the server on the host receives P1_MF_EXIT
Xit terminates;
Xwhen the client receives this command it will reset to a
Xsimple known state.
X.SH
XProtocol 2
X.PP
X\*(uw version 3 provides a number of capabilities
Xthat earlier versions of \*(uw did not.
XAmong these is an expansion of the host-client interaction.
XIn order to accomodate the increased flow of information
Xit was necessary to extend the \*(uw protocol.
XOne of the significant extensions in protocol 2
Xis support for a concept called ``window options.''
XWindow options are described in more detail in the next section.
X.PP
XProtocol 2 is very similar to protocol 1.
XLike protocol 1,
Xprotocol 2 multiplexes a single communications stream
Xamong a maximum of seven windows.
XCommand bytes in protocol 2 are encoded in the same
Xfashion as in protocol 1:
Xa prefix byte
X(P2_IAC)
Xfollowed by a command byte.
XHowever,
Xunlike protocol 1,
Xsome protocol 2 commands require more than one command byte.
X.PP
XThe protocol 2 functions are:
X.DS
X.T=
X#define	P2_FN	0070	/* function code: */
X#define	P2_FN_NEWW	0000	/*	create new window */
X#define	P2_FN_KILLW	0010	/*	kill (destroy) window */
X#define	P2_FN_ISELW	0020	/*	select window for input data */
X#define	P2_FN_OSELW	0030	/*	select window for output data */
X#define	P2_FN_WOPT	0040	/*	communicate window options */
X#define	P2_FN_META	0050	/*	add META to next data character */
X#define	P2_FN_CTLCH	0060	/*	send control character as data */
X#define	P2_FN_MAINT	0070	/*	perform "maintenance function" */
X.DE
XThe P2_FN_KILLW,
XP2_FN_ISELW,
XP2_FN_OSELW,
Xand P2_FN_CTLCH
Xcommands are identical to their counterparts in protocol 1.
X.PP
XThe low-order three bits of the P2_FN_META command
Xrepresent a control character.
X(The low-order three bits of the P1_FN_META command are ignored.)
XThe encoding is identical to the encoding
Xfor the P2_FN_CTLCH command:
X.DS
X.T=
X#define	P2_CC	7	/* control character specifier: */
X#define	P2_CC_IAC	1	/*	P2_IAC (001) */
X#define	P2_CC_XON	2	/*	XON (021) */
X#define	P2_CC_XOFF	3	/*	XOFF (023) */
X.DE
XIf the low-order three bits are zero,
Xthen the P2_FN_META command acts like the P1_FN_META command \(em
Xthe META bit is set in the next data byte.
XIf the low-order three bits are not all zero,
Xthe the P2_FN_META command specifies a META-control character.
XThus, the following are all equivalent:
X.DS
XP1_IAC\ \ P1_FN_META\ \ P1_IAC\ \ P1_FN_CTLCH|P1_CC_IAC
XP2_IAC\ \ P2_FN_META\ \ P2_IAC\ \ P2_FN_CTLCH|P2_CC_IAC
XP2_IAC\ \ P2_FN_META|P2_CC_IAC
X.DE
X.PP
XThe P2_FN_NEWW command differs from the P1_FN_NEWW command
Xin that the protocol 2 command includes an extra byte.
XThe byte following the command byte
Xspecifies the type of the window that is being created.
XThe numeric value of the window type is
Xadded to the ASCII value for a space (blank);
Xhence,
Xthe window type is always represented by a printable character.
XAs an example,
Xif the host wishes to create window 2
Xwith window type 1 (VT-52),
Xthe command sequence is:
X.DS
X.T=
X0001	(P2_IAC)
X0002	(P2_DIR_HTOM|P2_FN_NEWW|2)
X0041	(`!')
X.DE
X.PP
XThe following maintenance functions (P2_FN_MAINT) are defined:
X.DS
X.T=
X#define	P2_MF	7	/* maintenance functions: */
X#define	P2_MF_ENTRY	0	/*	start up */
X#define	P2_MF_ASKPCL	2	/*	request protocol negotiation */
X#define	P2_MF_CANPCL	3	/*	suggest protocol */
X#define	P2_MF_SETPCL	4	/*	set new protocol */
X#define	P2_MF_EXIT	7	/*	exit */
X.DE
XThe representations of
XP2_MF_ENTRY and P2_MF_EXIT are identical to those in protocol 1.
XThe definition of the ``entry'' function is extended
Xslightly in protocol 2.
XIn protocol 1,
Xthe P1_MF_ENTRY command is only sent by the server when it starts up.
XThe client recognizes this command and initializes itself.
XIn protocol 2,
Xthe client is permitted to send the P2_MF_ENTRY command
Xto the server.
XUpon receipt of this command,
Xthe server issues the sequence of P2_FN_NEWW commands
Xand P2_FN_WOPT commands
X(described below)
Xwhich will reconstruct all of the existing windows
Xon the client in their current state.
XThe client uses this command to ``restart'' itself after a crash
Xor other interruption on its end of the connection.
XThe three new maintenance functions are used for protocol negotiation.
XProtocol negotiation is described in detail below.
X.PP
XProtocol 2 defines the new command
XP2_FN_WOPT
Xto transmit window option information
Xbetween the client and server.
XThe P2_FN_WOPT command is followed by a variable-length
Xstring of bytes which encode the window options information.
XThe next section describes the meaning and encoding of
Xwindow option information.
X.SH
XWindow Options
X.PP
XWindow options are window attributes
X(the latter is a more meaningful name).
XFor each window,
Xa maximum of 31 window options may be defined.
XThese are divided into two categories:
Xgeneric and emulation-specific.
XGeneric window options are attributes which are common
Xto all window emulation types.
XEmulation-specific options are meaningful only for some
Xsubset of the available emulation types.
XThe following options are generic:
X.DS
X.T=
X#define	WOG_END	0	/* [used as an endmarker] */
X#define	WOG_VIS	1	/* visibility */
X#define	WOG_TYPE	2	/* window emulation type */
X#define	WOG_POS	3	/* window position on screen */
X#define	WOG_TITLE	4	/* window title */
X#define	WOG_SIZE	5	/* window size (in pixels) */
X#define	WOG_6	6	/* [unassigned, reserved] */
X#define	WOG_7	7	/* [unassigned, reserved] */
X.DE
XTerminal emulations define the following emulation-specific options:
X.DS
X.T=
X#define	WOTTY_SIZE	8	/* (row,col) terminal size */
X#define	WOTTY_FONTSZ	9	/* font size index */
X#define	WOTTY_MOUSE	10	/* mouse interpretation */
X#define	WOTTY_BELL	11	/* audible, visual bell */
X#define	WOTTY_CURSOR	12	/* cursor shape */
X.DE
XWindow option values are structured types composed
Xof the following primitive types:
X.DS
Xfixed-length character vectors
Xvariable-length character strings
Xspecified-width unsigned integer data
X.DE
X.PP
XThe host and client may exchange the following commands
Xregarding window options:
X.DS
X.T=
X#define	WOC_SET	0	/* change value of option */
X#define	WOC_INQUIRE	2	/* ask about current option value */
X#define	WOC_DO	4	/* do report changes to option */
X#define	WOC_DONT	5	/* don't report changes to option */
X#define	WOC_WILL	6	/* will report changes to option */
X#define	WOC_WONT	7	/* won't report changes to option */
X.DE
XThe ``set'' command is sent by either the client or the host
Xto specify the current value of a window option.
XThe ``inquire'' command is sent by either the client or the host
Xwhen it wishes to know the current value of an option.
XThe recipient of an ``inquire'' command responds with a
X``set'' command that specifies the current option value.
X.PP
XThe remaining four window option commands
Xare used by the host
Xto set up automatic reporting by the client
Xwhen the value of a window option changes.
XIf the host wishes to be informed
Xwhen the value of a window option changes
X(\fIe.g.\fP when a window is retitled),
Xit sends a ``do'' command to the client.
XThe client responds to the ``do'' command
Xwith a ``will'' command
Xfollowed immediately by a ``set'' command
X(reporting the current value of the option).
XThereafter,
Xwhenever the value of that option changes
Xthe client will send a ``set'' command with the new value
Xto the host.
XIf the host wishes the client to stop sending
Xthese ``set'' commands,
Xthe host sends the client a ``don't'' command.
XThe client responds with a ``won't'' message.
X.PP
XThe reporting status of generic window options is not affected
Xif the window emulation types changes;
Xhowever,
Xif the emulation type changes,
Xthen reporting for emulation-specific options is ended.
XIf the host wishes the client to continue
Xreporting changes in some emulation-specific window options,
Xit must send the appropriate ``do'' commands.
X.PP
XWindow option commands are grouped together and transmitted
Xcollectively as part of a P2_FN_WOPT command.
XThat is,
Xthe P2_IAC and P2_FN_WOPT command are immediately
Xfollowed by a variable-length string of bytes
Xwhich contain window option commands for one or
Xmore options.
XThe end of a sequence of window option (sub)commands
Xis indicated by a command which specifies window option zero
X(WOG_END).
X.PP
XAll window option commands begin with a one or two
Xbyte command specifier.
XThe one-byte form is called the ``short'' form,
Xwhile the two-byte form is the ``long'' form:
X.DS
X.ta 8n 32n 48n
X#define	WONUM_MIN	1	/* minimum option number */
X#define	WONUM_GENERIC	7	/* maximum generic option number */
X#define	WONUM_SHORT	14	/* maximum short option number */
X#define	WONUM_MAX	31	/* maximum option number */
X#define	WONUM_MASK	(017<<3)	/* mask for extraction */
X#define	WONUM_SENCODE(n)	(((n)&017)<<3)	/* short encoding function */
X#define	WONUM_SDECODE(b)	(((b)>>3)&017)	/* short decoding function */
X#define	WONUM_LPREFIX	(017<<3)	/*long encoding prefix */
X#define	WONUM_LENCODE(n)	((n)+' ')	/* long encoding function */
X#define	WONUM_LDECODE(c)	(((c)&0177)-' ')	/* long decoding function */
X.DE
XCommands
Xspecifing options whose numbers are in the range WONUM_MIN to WONUM_SHORT
Xmay use the short form.
XIn this case,
Xthe window option number is encoded according to WONUM_SENCODE:
Xit is shifted left by three bits.
XThe command byte consists of a bitwise ``or'' of
Xthe window option command
X(\fIe.g.\fP WOC_INQUIRE)
Xand the encoded short option number.
X.PP
XCommands which specify options whose numbers are greater than WONUM_SHORT
Xmust use the long form.
X(The long form may be used for options whose numbers are less than WONUM_SHORT,
Xbut there is no reason to do so.)
XIn this case,
Xthe first byte contains a bitwise ``or'' of
Xthe window option command
X(\fIe.g.\fP WOC_INQUIRE)
Xand the special prefix WONUM_LPREFIX.
XThe second byte is encoded by WONUM_LENCODE:
Xthe window option number is added to the ASCII code for a space
X(thus this byte is always printable).
X.PP
XAll of the window option commands begin with the
Xone or two byte option command specifier.
XUnlike the other window option commands
X(which use no additional bytes),
Xthe WOC_SET command is followed by encoded data
X(the value of the option).
XOption values are constructed from three primitive
Xdata types
X(as noted above).
X.IP chars 8n
XThe simplest type of data is a fixed-length character vector.
XThis is represented directly.
XThe vector must consist of printable characters.
X[This restriction may be eliminated in the future.
XThe current implementation is able to process non-printable
Xcharacters
X(including XON and XOFF)
Xcorrectly.]
X.IP string
XLike character vectors,
Xstrings have a maximum length.
XHowever,
Xunlike character vectors,
Xstrings may contain non-printing characters.
XAlso,
Xwhile all characters in a character vector are sent,
Xa string may be shorter than its maximum length.
XIt is terminated by a null (000) byte.
X[Hence,
Xa string may not contain an embedded null byte.]
X.IP udata
XThe remaining data type is unsigned integer data.
XThis data has a fixed width measured in bits.
XThe value is encoded in ``little-endian'' fashion
Xinto the low six bits of successive characters.
XThe (octal) 0100 bit of each character is set.
XThe number of characters required to hold an integer
Xvaries from one
X(for data which is one to six bits wide)
Xto six
X(for data which is thirty-two bits wide).
X.PP
XThe window options defined above have arguments as follows
X(all integers are unsigned):
X.IP WOG_VIS 20n
XThis is a 1-bit integer
Xwhich is nonzero iff the window is visible.
X.IP WOG_POS
XThis consists of two 12-bit integers
Xwhich respectively specify the vertical and horizontal
Xoffsets of the window on the client's screen.
X.IP WOG_TITLE
XThis is a string of maximum length 256
Xwhich specifies the window's title.
X.IP WOG_SIZE
XThis consists of two 12-bit integers
Xwhich respectively specify the vertical and horizontal
Xsize of the window on the client's screen
X(in pixels).
X.IP WOTTY_SIZE
XThis consists of two 12-bit integers
Xwhich respectively specify the window size in rows and columns.
X.IP WOTTY_FONTSZ
XThis is a 6-bit integer which is a font size index.
XAt present,
Xit specifies a ``small'' font if zero
Xand a ``large'' font if nonzero.
X.IP WOTTY_MOUSE
XThis is a 1-bit integer
Xwhich is nonzero iff
Xmouse events are to be encoded and sent
Xas data to the host.
X.IP WOTTY_BELL
XThis is a 2-bit integer.
XThe low-order bit is set iff the window should
Xdisplay bells visually;
Xthe other bit is set iff the client should report
Xbells within this window audibly.
X.IP WOTTY_CURSOR
XThis is a 1-bit integer
Xwhich is zero if the window is using a block cursor
Xand nonzero if the window is using an underscore cursor.
X.PP
XOne design decision which the author now regrets
Xis an overloading of the WOTTY_SIZE option.
XIf the host can handle window size changes on pseudo-terminals
X(\fIe.g.\fP 4.3BSD can),
Xthen the client is capable of changing the view size of a window
Xor its actual size,
Xaccording to the user's preference.
XIf the host cannot handle window size changes,
Xthe client does not allow the view size to be changed.
XThe client assumes that the host can handle window size
Xchanges if it receives a WOC_DO command for the WOTTY_SIZE option.
X.SH
XProtocol Negotiation
X.PP
XIt is possible that at some time the versions of a \*(uw server
Xand client will not match;
X.I e.g.
Xa version 2.10 client will be used with a version 3.4 server.
XIt is desirable that such combinations will work ``correctly'' \(em
Xthat the server will communicate with the client using protocol 1
Xrather than trying to use protocol 2.
XIn order to accomplish this,
Xthree new maintenance functions
Xare defined by which the server and client
Xmay negotiate the protocol which is to be used.
XVersion 3 clients and servers recognize these maintenance
Xfunctions in both protocol 1 and protocol 2.
XOlder clients and servers do not recognize these functions
Xat all.
X.PP
XThe protocol negotiation maintenance functions were
Xdescribed above for protocol 2.
XThey are repeated here for protocol 1
X(the encodings are identical):
X.DS
X.T=
X#define	P1_MF_ASKPCL	2	/*	request protocol negotiation */
X#define	P1_MF_CANPCL	3	/*	suggest protocol */
X#define	P1_MF_SETPCL	4	/*	set new protocol */
X.DE
XP1_MF_ASKPCL is encoded in a single command byte
X(following P1_IAC).
XThe P1_MF_CANPCL and P1_MF_SETPCL command bytes are
Xfollowed by an additional byte which names a protocol.
XFor the purposes of protocol negotiation,
Xprotocols 1 and 2 are represented by the ASCII
Xcharacters space and exclamation-mark,
Xrespectively.
X.PP
XThe client and server always start operation in protocol 1.
X(The user may have instructed the client to use protocol 2;
Xnonetheless,
Xit will use protocol 1 until protocol negotiations are complete.)
XWhen the server is started
Xit will send a P1_MF_ENTRY maintenance command to the client.
XIf the client knows about protocol 2 and wishes to use it,
Xit will send a P1_MF_ASKPCL to the server.
XIf the client does not know about protocol 2,
Xit will not send P1_MF_ASKPCL,
Xprotocol negotiation will never be started,
Xand both sides will continue to use protocol 1.
X.PP
XIf the server can support something other than protocol 1
Xit will respond to the P1_MF_ASKPCL with a
XP1_MF_CANPCL which names the most extensive protocol that it can support.
X(At present,
Xthis will be protocol 2;
Xhowever,
Xin the future it might name some other protocol.)
XOld servers,
Xwhich do not recognize P1_MF_ASKPCL,
Xwill ignore the maintenance function.
XThe client will time out after five seconds
Xand retry several times
X(three in the present implementation);
Xif the server never responds
Xthe client will ``give up'' and will
Xcontinue to use protocol 1 indefinitely.
X.PP
XWhen the client receives P1_MF_CANPCL from the server,
Xit will examine the server's suggested protocol.
XIf this protocol is unacceptable to the client,
Xit will respond with its own P1_MF_CANPCL,
Xnaming the most extensive protocol that it can support.
XThe server,
Xupon receipt of this P1_MF_CANPCL,
Xwill examine the client's suggested protocol.
XIf it is unacceptable to the server,
Xit will name the second-most extensive protocol that it can support.
XEach time that the client or server receives a
XP1_MF_CANPCL that names a protocol it cannot support,
Xit will respond with a different,
Xless extensive suggestion of its own.
XSince the number of protocols is finite,
Xeventually someone will suggest protocol 1,
Xwhich both sides are required to support.
X.PP
XWhen the client or server receives a P1_MF_CANPCL
Xthat names a protocol that it
X.I can
Xsupport,
Xit will instruct its counterpart to start using that protocol
Xby sending a P1_MF_SETPCL that names that protocol.
XHenceforth,
Xthe new protocol will be used.
X.PP
XProtocol 2 allows the client to send a P2_MF_ENTRY
Xmaintenance command to the server.
X(This is encoded identically to a P1_MF_ENTRY command.)
XIf the server receives this maintenance command and
Xit is using a protocol other than protocol 1,
Xit will immediately respond with a P1_FN_SETPCL which
Xnames the protocol that it is using.
XIt will then proceed to send ``new window'' and
X(if applicable)
X``window option'' commands to the client
Xto reconstruct the client's current state.
X.SH
XPostscript
X.PP
XThere are a number of obvious problems with the mechanism
Xfor protocol negotiation.
XIt is possible for one party to send a SETPCL
Xcommand and begin listening for input in a new protocol
Xwhile it is still receiving buffered commands in the old protocol
Xfrom the other party.
XIt probably would have been better to have established
Xa ``current protocol'',
Xsimilar to the ``current window'' scheme used for data transfer.
XThis scheme was born out of the desire to allow
Xold servers and clients to work with new ones.
XIt ``works'' if things are relatively quiescent,
Xas they are when the server first starts up
X(before it creates its first window).
X.PP
XThis document is still incomplete.
XAt this time it is more useful as a conceptual guide
Xto the \*(uw protocol
Xthan a definitive reference.
X.SH
XCopyright
X.LP
XThis document copyright 1986 by John D. Bruner.
XPermission to copy is given,
Xprovided that the copies are not sold
Xand that this copyright notice is included.
SHAR_EOF
if test 24952 -ne "`wc -c < 'doc/uwproto.ms'`"
then
	echo shar: error transmitting "'doc/uwproto.ms'" '(should have been 24952 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'doc/uwplot.l'" '(2042 characters)'
if test -f 'doc/uwplot.l'
then
	echo shar: will not over-write existing file "'doc/uwplot.l'"
else
sed 's/^X//' << \SHAR_EOF > 'doc/uwplot.l'
X.TH UWPLOT 1 "28 April 1987"
X.UC 4
X.SH NAME
Xuwplot \- plot filter for use with UW
X.SH SYNOPSIS
X.B uwplot
X[
X.BI \-t title
X] [
X.BI \-n serveraddr
X]
X.SH DESCRIPTION
X.I Uwplot
Xis a utility program for use with the
X.I uw
Xmultiple-window interface to UNIX.
XIt creates a window,
Xreads plotting instructions from the standard input,
Xand displays the result in the window.
X(The plotting commands are produced by programs
Xwhich use the standard UNIX
X.I plot
Xpackage.)
X.PP
XThe title of the newly-created window may be
Xspecified with the `\-t' option.
XIf this option is omitted,
Xthe title will be the name of the command
Xwhich created it
X(\fIi.e.\fP `uwplot').
X.PP
XNormally
X.I uwplot
Xwill examine the environment for the variable `UW_INET'
Xand will connect to the
X.I uw
Xserver with that address.
XThe `\-n' flag can be used to specify an alternate
Xserver network address.
XThe address should have the form `xxxxxxxx.ddd'
Xwhere `x' is a hexadecimal digit
Xand `d' is a decimal digit.
XThe hexadecimal number is the host's Internet address
Xand the decimal number is the port on which the
Xserver is listening for connections.
X.PP
X`linemod' commands in the plot file are
Xintended to select the color in which the
Xplot is drawn;
Xhowever, this feature is untested.
XThe old-model Quickdraw colors may be
Xspecified by name
X(all lower-case).
XThe standard plot linemod names are mapped to
Xcolors as follows:
X.sp
X.nf
X.ta 1i
Xblack	solid
Xred	shortdashed
Xgreen	dotdashed
Xblue	longdashed
Xyellow	dotted
X.fi
X.PP
XThe present implementation on the Macintosh
Xis a square window with vertical and horizontal
Xdimensions of 300 pixels.
XArcs are not drawn correctly when
Xthe vertical and horizontal scaling factors
Xare unequal.
X.SH LIMITATIONS
X.I Uwterm 
Xis of no use on unix unless 
Xthe server is running and
X.I uw
Xis being run on the Macintosh.
X.SH SEE ALSO
Xplot(1G), plot(3X), plot(5), uw(L)
X.br
X.I uw
XMacintosh documentation
X(`UW \(em A Multiple-Window Interface to UNIX')
X.br
X`The UW Programmer's Library'
X.SH AUTHOR
XJohn Bruner, Lawrence Livermore National Laboratory, 10/86.
SHAR_EOF
if test 2042 -ne "`wc -c < 'doc/uwplot.l'`"
then
	echo shar: error transmitting "'doc/uwplot.l'" '(should have been 2042 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'doc/uwterm.l'" '(2858 characters)'
if test -f 'doc/uwterm.l'
then
	echo shar: will not over-write existing file "'doc/uwterm.l'"
else
sed 's/^X//' << \SHAR_EOF > 'doc/uwterm.l'
X.TH UWTERM 1 "20 September 1986"
X.UC 4
X.SH NAME
Xuwterm \- (possibly remote) terminal emulation for UW
X.SH SYNOPSIS
X.B uwterm
X[
X.BI \-w type
X] [
X.BI \-t title
X] [
X.BI \-n serveraddr
X] [
X.BI \-l loginname
X] [ host ]
X.SH DESCRIPTION
X.I Uwterm
Xis a utility program for use with the
X.I uw
Xmultiple-window interface to UNIX.
XIt creates a window in which a terminal session
Xis conducted.
XIf no arguments are given
Xthe terminal is created on the local machine.
XA hostname may be specified;
Xin this case,
Xthe terminal is created on the remote host.
X.RI ( Uwterm
Xmust be installed on the remote host
Xand permissions for
X.I rsh
Xmust have been set up correctly
Xin order for this to work.)
X.I Uwterm
Xexamines the `SHELL' environment variable
Xand executes the program named there.
XThe `\-l' option
Xcan be used to specify the login name under which
Xthe remote process will be executed
X(the default is the current account).
X.PP
XUnlike
X.IR uwtool ,
X.I uwterm
Xdoes not exit until the window it has created
Xis destroyed;
Xhence,
Xit will usually be desirable to run it in the background.
X.PP
XNormally,
Xthe terminal type of the new window is inherited from
Xthe window in which
X.I uwterm
Xis run.
XIt is possible to override this with the `\-w' option
X(`w' stands for `window emulation type').
XThe window types are the same as those accepted by the
X.I uwtool
Xprogram.
X.PP
XThe title of the newly-created window may be
Xspecified with the `\-t' option.
XIf this option is omitted,
Xthe title will be the host name.
X.PP
XNormally
X.I uwterm
Xwill examine the environment for the variable `UW_INET'
Xand will connect to the
X.I uw
Xserver with that address.
XThe `\-n' flag can be used to specify an alternate
Xserver network address.
XThe address should have the form `xxxxxxxx.ddd'
Xwhere `x' is a hexadecimal digit
Xand `d' is a decimal digit.
XThe hexadecimal number is the host's Internet address
Xand the decimal number is the port on which the
Xserver is listening for connections.
XThe `\-n' flag is used by
X.I uwterm
Xitself:
Xit creates a remote terminal by invoking itself on
Xthe remote machine
X(using
X.IR rsh )
Xand specifying the network address
Xof the local server.
X.SH LIMITATIONS
X.I Uwterm 
Xis of no use on unix unless 
Xthe server is running and
X.I uw
Xis being run on the Macintosh.
X.br
XIf there is a stream of output in one window there will be lag in 
Xrecognizing characters typed in another.
X.br
XThere are so many levels of buffering
Xthat user-entered CTL-S/CTL-Q flow control is
Xpractically useless,
Xeven at relatively low baud rates.
X.SH SEE ALSO
Xrsh(1), uw(L), uwtitle(L), uwtool(L)
X.br
X.I uw
XMacintosh documentation
X(`UW \(em A Multiple-Window Interface to UNIX')
X.br
X`The UW Programmer's Library'
X.SH AUTHOR
XJohn Bruner, Lawrence Livermore National Laboratory, 9/86.
X.SH BUGS
XThere are so many levels of buffering that typing
XXON and XOFF
Xto suspend output within a window
Xis futile.
SHAR_EOF
if test 2858 -ne "`wc -c < 'doc/uwterm.l'`"
then
	echo shar: error transmitting "'doc/uwterm.l'" '(should have been 2858 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'doc/uwtitle.l'" '(850 characters)'
if test -f 'doc/uwtitle.l'
then
	echo shar: will not over-write existing file "'doc/uwtitle.l'"
else
sed 's/^X//' << \SHAR_EOF > 'doc/uwtitle.l'
X.TH UWTITLE 1 "14 September 1986"
X.UC 4
X.SH NAME
Xuwtitle \- retitle UW window
X.SH SYNOPSIS
X.B uwtitle
X[
X.BI \-i id
X]
Xstring ...
X.SH DESCRIPTION
X.I Uwtitle
Xis a utility program for use with the
X.I uw
Xmultiple-window interface to UNIX.
XIt retitles an existing window.
XThe title is specified as one or more
Xstrings
X(in the same fashion as arguments to the
X.I echo
Xprogram).
XThe `\-i' option can be used to specify
Xthe ID of the window to be retitled;
Xotherwise,
Xthe current window will be affected.
X.SH LIMITATIONS
X.I Uwtitle 
Xis of no use on unix unless 
Xthe server is running and
X.I uw
Xis being run on the Macintosh.
X.SH SEE ALSO
Xecho(1), uw(L), uwtool(L), uwterm(L)
X.br
X.I uw
XMacintosh documentation (`UW \(em A Multiple-Window Interface to UNIX')
X.br
X`The UW Programmer's Library'
X.SH AUTHOR
XJohn Bruner, Lawrence Livermore National Laboratory 9/86
SHAR_EOF
if test 850 -ne "`wc -c < 'doc/uwtitle.l'`"
then
	echo shar: error transmitting "'doc/uwtitle.l'" '(should have been 850 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'doc/uwtool.l'" '(2334 characters)'
if test -f 'doc/uwtool.l'
then
	echo shar: will not over-write existing file "'doc/uwtool.l'"
else
sed 's/^X//' << \SHAR_EOF > 'doc/uwtool.l'
X.TH UWTOOL 1 "14 September 1986"
X.UC 4
X.SH NAME
Xuwtool \- command-in-window utility for UW
X.SH SYNOPSIS
X.B uwtool
X[
X.BI \-w type
X] [
X.BI \-t title
X] [
X.B \-v
X] [ command [ arg1 arg2 ...  ] ]
X.SH DESCRIPTION
X.I Uwtool
Xis a utility program for use with the
X.I uw
Xmultiple-window interface to UNIX.
XIf no arguments are given,
Xit creates a new `terminal' running the shell named in the
Xenvironment variable `SHELL'.
XIf a process is named,
Xit will create a new window with that process running in it,
Xand when that process is terminated the window will disappear.
X(i.e. `uwtool vi foo' will create a new window with vi,
Xediting the file foo,
Xbut the window will go away when vi is exited)  
XAny arguments after the process name are passed as arguments to that process.
X.I Uwtool
Xexits as soon as the window is created.
X.PP
XNormally,
Xthe terminal type of the new window is inherited from
Xthe window in which
X.I uwtool
Xis run.
XIt is possible to override this with the `\-w' option
X(`w' stands for `window emulation type').
XThe following values are recognized:
X.TP 8n
Xadm31
XLear Siegler ADM-31
X.TP
Xadm3a
XLear Siegler ADM-3a (uses ADM-31)
X.TP
Xtek4010
XTektronix 4010
X.TP
Xtek
XTektronix 4010
X.TP
Xvt52
XDigital Equipment Corporation VT-52
X.TP
Xansi
XANSI-compatible terminal
X.TP
Xaaa-24
X24-line Ann Arbor Ambassador
X(uses ANSI emulation)
X.PP
XIf an unknown type is specified,
Xthe ADM-31 emulation will be used.
X.PP
XThe title of the newly-created window may be
Xspecified with the `\-t' option.
XIf this option is omitted,
Xthe window title will be the command name.
X.PP
XThe `\-v' flag causes
X.I uwtool
Xto print the 32-bit window identifier on
Xthe standard output.
XThis value can be used as an argument to a subsequent
Xcommand,
Xfor example
X.IR uwtitle .
X.SH LIMITATIONS
X.I Uwtool 
Xis of no use on unix unless 
Xthe server is running and
X.I uw
Xis being run on the Macintosh.
X.br
XIf there is a stream of output in one window there will be lag in 
Xrecognizing characters typed in another.
X.SH SEE ALSO
Xuw(L), uwtitle(L), uwterm(L)
X.br
X.I uw
XMacintosh documentation
X(`UW \(em A Multiple-Window Interface to UNIX')
X.br
X`The UW Programmer's Library'
X.SH AUTHOR
XProgram written by John Bruner, Lawrence Livermore Laboratories 7/85,11/85,9/86
X.br
XThis document is based upon a document created by
Xby Chris Borton, UC San Diego 11/13/85,
Xedited 9/86 by John Bruner.
SHAR_EOF
if test 2334 -ne "`wc -c < 'doc/uwtool.l'`"
then
	echo shar: error transmitting "'doc/uwtool.l'" '(should have been 2334 characters)'
fi
fi # end of overwriting check
#	End of shell archive
exit 0
--- end of part 2 ---