1 LISP LIBRARY PACKAGES MANUAL 1 LISP LIBRARY PACKAGES MANUAL RS232 1 COMMUNICATIONS/NETWORK 1 RS232 6 The 1108, 1185, and 1186 each support two RS232 ports. One of these ports is configured as ┅Data Terminal Equipment,构 and is intended to be connected to modems or terminal ports on other computers (on the 1108, this port is available only with the addition of the E30 option). The other port is configured as ┅Data Communication Equipment,构 and is meant to drive low-speed printers or terminals. In this document, the DTE port is called the ┅RS232构 port, and the DCE port is called the ┅TTY构 port. The 1108 and 1185/1186 user's guides describe the wiring configuration of these ports. The software described in this document can be used only in ┅Koto构 or later versions of Interlisp-D, and is not compatible with the Xerox 1100 or Xerox 1132 workstations. Interlisp-D provides a stream-oriented interface to the RS232 hardware. Users' programs can open streams to the ┅hosts构 {RS232} or {TTY}, and perform input or output using standard Interlisp-D I/O functions, such as BIN, BOUT, READP, etc. Programs need not treat RS232 streams or TTY streams specially; however, the RS232 port is preferred over the TTY if the application expects to handle large amounts of input data. In the 1108, 1185, and 1186, data entering the RS232 port is buffered independently of Lisp by the I/O processor. The 1108 can buffer about 2,000 characters before the Lisp processor needs to read the data; similarly, the 1185 and 1186 can buffer about 5,000 characters. In addition, the Interlisp-D RS232 service provides an additional layer of character buffering, freeing users' programs from having to monitor the RS232 hardware frequently. Unfortunately, no independent buffering is provided for data entering the TTY port. As a result, Interlisp-D cannot guarantee to catch all characters received on this port. For this reason, we suggest that the TTY port be used primarily to drive output devices, such as printers. The following sections of this document describe the Interlisp-D interface to the RS232 port and the TTY port. 2 Using the RS232 Port 1 Support for the RS232 port is contained on DLRS232C.DCOM. Before using the RS232 port, it is necessary to program the RS232 hardware, and the function RS232C.INIT is provided for this purpose: (RS232C.INIT BaudRate BitsPerSerialChar Parity NoOfStopBits FlowControl) [Function] The arguments correspond to the desired baud rate (baud rates of 50 baud through 19,200 baud are supported on all machines, and baud rates of up to 57,600 are supported on the 1108), the number of bits per serial character (e.g., seven or eight), whether or not to use the eighth bit as a parity bit (and if so, then this argument must be either ODD or EVEN), the number of ┅stop构 bits per character (which should normally be one, except in unusual cases), and the flow control setting on the port (see below). Alternatively, the BaudRate argument can be an instance of the RS232C.INIT record. If BaudRate is NIL, the value of the global variable RS232C.DEFAULT.INIT.INFO is used in its place. This provides a means of automatically initializing the RS232 hardware without user intervention. RS232C.DEFAULT.INIT.INFO [Variable] This variable controls default initialization of the RS232 port. Its value may be set in the site INIT.LISP file, or in a user's INIT.LISP file. If RS232C.DEFAULT.INIT.INFO is not set when the RS232 package is loaded, its fields will be set to the following default values: BaudRate: 1200 BitsPerSerialChar: 8 Parity: NONE NoOfStopBits: 1 FlowControl: XOnXOff Programs may use OPENSTREAM as an alternative to calling RS232C.INIT directly, with the parameters bundled up into the PARAMETERS argument as shown below. For example, (RS232C.INIT 9600 8) can also be achieved by: (OPENSTREAM '{RS232} 'INPUT NIL '((BaudRate 9600) (BitsPerSerialChar 8)) In addition, applications may change the settings of the RS232 hardware while the RS232 port is in use. For this purpose, the following function is provided: (RS232C.SET.PARAMETERS PARAMETERLIST) [Function] PARAMETERLIST is an association list of parameter names and values. The following example sets the baud rate to 9,600 baud, and the character length to eight bits: (RS232C.SET.PARAMETERS '((BaudRate . 9600) (BitsPerSerialChar . 8))) The following is a list of legal parameter names and values: BaudRate: 50, 75, 110, 150, 300, 600, 1200, 2400, 3600, 4800, 7200, 9600, 19200 (1108 only: 28880, 38400, 48000, 56000, 57600). BitsPerSerialChar: 5, 6, 7, 8. Parity: NONE, ODD, EVEN. NoOfStopBits: 1, 2 (This parameter should be 1 except at 110 baud). FlowControl: NIL, XOnXOff. For applications requiring XOn and XOff characters other than ^Q and ^S respectively, this parameter may be supplied as a list in the form: (1 ), where and are replaced by the character values of the XOn and XOff characters. The leading ┅1构 signifies that flow control should be enabled; a leading ┅0构 will program the RS232 port with the appropriate XOn and XOff characters, but leave flow control disabled. ModemControl: This parameter should be a list of modem control signals to be enabled. The only legal signal names are DTR (data terminal ready) and RTS (request to send). The functions RS232MODEMCONTROL, RS232MODEMSTATUSP, and RS232MODIFYMODEMCONTROL provide finer control over the settings of modem signals. DTR: This parameter enables or disables the data terminal ready signal; it may be specified as T or NIL. RTS: This parameter enables or disables the request to send signal; it may be specified as T or NIL. The current settings for the RS232 port may be obtained at any time by calling RS232C.GET.PARAMETERS: (RS232C.GET.PARAMETERS PARAMETERLIST) [Function] PARAMETERLIST should be a list of parameter names. RS232C.GET.PARAMETERS returns an association list of parameter names and values, in a format acceptable to RS232C.SET.PARAMETERS. The RS232 port is turned off by calling RS232C.SHUTDOWN: (RS232C.SHUTDOWN) [Function] This function disables the RS232 port. Using RS232 Streams 1 Programs may open streams to the RS232 port by calling OPENSTREAM with the file name {RS232}. The ACCESS argument to OPENSTREAM controls whether an INPUT or OUTPUT stream is returned. RS232 streams are unidirectional; to obtain a second stream open for the opposite access, call the function RS232C.OTHER.STREAM. Only one pair of RS232 streams may be open at a time. (RS232C.OTHER.STREAM STREAM) [Function] STREAM should be an RS232 stream. If STREAM is open for INPUT, an RS232 stream open for OUTPUT is returned; conversely, if STREAM is open for OUTPUT, an RS232 stream open for INPUT is returned. The following functions are defined to work on RS232 streams open for the appropriate access: BIN, BOUT, READP, OPENP, CLOSEF, and FORCEOUTPUT. RS232 streams are buffered. Input and output are performed in units of packets of data. The I/O processor collects incoming data into a packet, and makes that packet available to Interlisp-D when one of the following conditions is true: The packet is filled. Currently, input packets are 578 characters long. The ┅frame timeout构 has expired. The frame timeout is the number of centiseconds that are allowed to occur between the reception of single characters. This parameter is automatically set by the RS232 package. Its value depends on the baud rate of the RS232 port. If the value is set too large, interactive applications such as RS232CHAT will suffer from uneven typeout; if the value is too small, a larger number of shorter packets may be exchanged between Interlisp-D and the I/O processor, resulting in increased processing overhead. Interlisp-D buffers data for output in packets of up to 578 characters. Output packets are sent to the RS232 port when one of the following conditions is true: The current output packet is full. The user program calls the FORCEOUTPUT function to force the current output packet to be sent. Applications that generate a large amount of output slowly may wish to reduce the size of outgoing packets. Although this will require additional processing overhead, it will cause output to occur more frequently without the program's explicitly calling FORCEOUTPUT. (RS232C.OUTPUT.PACKET.LENGTH NEWVALUE) [Function] This function returns the current setting of the variable that controls the maximum size of output packets. If NEWVALUE is supplied, the setting is changed to NEWVALUE. NEWVALUE may currently be a number between 1 and 578. Many RS232 applications are time-dependent. File transfer protocols such as Kermit and Modem depend on one or both sides of a file transfer detecting connection problems through means of timeouts. In order for user programs to efficiently detect timeout conditions, the following function is available: (RS232C.READP.EVENT STREAM) [Function] STREAM should be an RS232 stream open for input. This function returns an event that a program may wait upon for input data to become available on the stream. The following example illustrates how a program could wait up to 10 seconds for a character to become available: [LAMBDA (STREAM) (LET ((EVENT (RS232C.READP.EVENT STREAM)) (TIMER (SETUPTIMER 10000))) (until (OR (READP STREAM) (TIMEREXPIRED? TIMER)) do (AWAIT.EVENT EVENT TIMER T) finally (RETURN (COND ((READP STREAM) (BIN STREAM] Using Modems 1 The following functions are useful for controlling modems: (RS232SENDBREAK EXTRALONG?) [Function] This function sends the out-of-band BREAK signal, for a period of 0.25 seconds; if the optional argument EXTRALONG? is non-NIL, then the period is extended to 3.5 seconds. (RS232MODEMCONTROL SIGNALSONLST) [Function] This function is a lambda-nospread function that sets the modem control lines to be ┅on构 for the signals named in the list SIGNALSONLST; it returns the former setting of the lines. If SIGNALSONLST is not supplied (which is not the same as supplying NIL), then the control lines remain unchanged. The entries in SIGNALSONLST are litatom names for standard modem control lines; currently usable signal names are DTR and RTS. (RS232MODIFYMODEMCONTROL SIGNALSONLST SIGNALSOFFLST) [Function] Changes only those modem control lines specified in the union of the two arguments; those in SIGNALSONLST are set to be on, and those in SIGNALSOFFLST are set off. Returns the former state just as (RS232MODEMCONTROL) does. (RS232MODEMSTATUSP SPEC) [Function] Returns non-null if the reading of the modem status lines is consistent with the boolean form specified by SPEC; modem status signals currently supported are CTS, DSR, RI, and RLSD. SPEC may be any AND/OR/NOT combination over the signal names. Example: (RS232MODEMSTATUSP '(AND CTS (NOT RLSD))). (RS232MODEMHANGUP) [Function] This function takes whatever steps appropriate to cause the modem to ┅hang up构; generally, this means turning the DTR signal down for about three seconds, or until the DSR signal has gone down. Error Condition Reporting 1 The RS232 port detects parity errors, character framing errors, lost characters, and a number of other unusual conditions. As the I/O processor delivers each input packet to Interlisp-D, it reports when the packet was received without error. If an error did occur while the packet was being received, Interlisp will report this fact by writing a message to RS232C.ERROR.STREAM. RS232C.ERROR.STREAM [Variable] RS232 error conditions are reported on this stream. This stream is initially the PROMPTWINDOW. (RS232C.REPORT.STATUS NEWVALUE) [Function] There are circumstances in which the RS232 hardware believes it has encountered an error, when in fact it has not. A frequent cause is an incorrect parity setting in the RS232 port. Continually reporting RS232 errors is likely to slow RS232 processing severely. In cases where error reporting is not important, it is possible to disable error reports with the RS232C.REPORT.STATUS function. This function returns the current setting of status reporting, which may be one of the following: T: Errors are reported on both input and output. NIL: Errors are never reported. OUTPUT: Errors are reported on output only. INPUT: Errors are reported on input only. In addition, if NEWVALUE is supplied, the current setting of status reporting is changed to NEWVALUE. The RS232CHAT Package 1 The RS232CHAT package is a facility that permits the Interlisp-D generic Chat system to communicate over the RS232 port. No user-callable functions or user-settable variables are available in this package. Once it is loaded, users may chat to the host named RS232 to open a ┅connection构 to the RS232 port. RS232CHAT is contained on the file RS232CHAT.DCOM. The RS232CMENU Package 1 RS232CMENU is a utility that provides a FREEMENU interface to controlling the settings of the RS232 port. When loaded along with RS232CHAT, this utility may be invoked by choosing the ┅Set Line Parameters构 entry in the options menu that appears if you select ┅Options构 in the middle-button Chat menu. ]0xx繾C0x xx髝繾0 0lx髲<踐闱/嵯^跍髄8s装鐝mNy捡砑x鐾钝`砿0sm扼3踡倍踶屰m独x魍掇`髆0;矶>髮鹠倍踡焬价m独x矶鹠 钝1忱胢倍踡樫燠mx黲<蘞1耥摅髄|{w兼蟳弝假缂x 0 `0 `0x 00xxxxx0 x鱻1 p=` `x隼1 $a``x鲛n穹兼 $y_堵1a鐣泱攁0"cx鲉m贬櫠$6檬I a睖ff躢m锻癉敀@x鲛m狈欚!$y< y a窓鎔豤矶蛝'旘@x鲻m苯檧A$贈A a經ffc 锻$侤x鳛>駰岞xy櫂媚9 =窓3貀頌m懊坮@x0x0<xxxxx0 x靼<x0悜@6 !x3沜=阺`坷<鐔咣N6s/*湺N釴!8x鞫踓 段踐BB櫠菦3I$<踡欢炻D扗!$x6咩 短E俣欺8I<6鹠 36D扗!$x6堂 短H悜俣欺I 6胢 36D扗!$x3屃6lsa釮岀嚈2{1彸塘崞崞$x`xxx The RS232 menu The following commands are available in the RS232 menu: Apply! A momentary item that changes the RS232 port settings according to the values of the fields in the rest of the menu. No changes are made to the RS232 hardware until this command is given. Abort! Closes the RS232 menu and aborts any changes that could have been made. SendBreak! Sends a normal (0.25 second) break signal. Requires confirmation, as this command could cause the modem connection to be broken. SendLongBreak! Sends a long (3.5 second) break signal. As above, requires confirmation. Hangup! Tries to hang up the modem (by dropping DTR). Requires confirmation. The following fields are FREEMENU NCHOOSE items; when their labels are buttoned with the mouse, a menu of possible values for the field appears. Choosing a value from the menu will change the field; buttoning off the menu will leave the field unchanged. Baud Rate: Changes the BaudRate of the RS232 port. Parity: Changes the Parity setting of the RS232 port. Character Length: Changes the BitsPerSerialChar setting of the RS232 port. Flow Control: Changes the FlowControl setting of the RS232 port. Stop Bits: Changes the NoOfStopBits setting of the RS232 port. Report Errors: Changes the RS232C.REPORT.STATUS setting of the RS232 port. File Transfer Using RS232 1 Files may be transferred using RS232CHAT and either the Kermit or Modem protocols (both protocols are available by loading the file KERMIT.DCOM). As Kermit and Modem may be used with any Chat protocol, they are documented separately. 2 Using the TTY Port 1 Support for the TTY port is contained on the file DLTTY.DCOM. The TTY port is designed to support low-speed communications with RS232 devices. The I/O processor offers no low-level support for input buffering. As a result, it is quite possible for newly received input characters to overwrite previously received but unread characters in the input hardware. The TTY port provides exactly one character's worth of buffering%each character must be read by Interlisp before the next character is completely received. No hardware flow control is provided on the TTY port. The Interlisp TTY port service routines will obey received flow control commands, but will not generate flow control commands in response to increased input data rate. Before using the TTY port, the TTY hardware must be programmed with the proper characteristics for your application; the function TTY.INIT is provided for this purpose: (TTY.INIT BaudRate BitsPerSerialChar Parity NoOfStopBits FlowControl) [Function] This function is very similar to the function RS232C.INIT. The arguments correspond to the desired baud rate, the number of bits per serial character (e.g., seven or eight), whether or not to use the eighth bit as a parity bit (and if so, then this argument must be either ODD or EVEN), the number of ┅stop构 bits per character (which should normally be one, except in unusual cases), and the flow control setting on the port. Alternatively, the BaudRate argument can be an instance of the RS232C.INIT record. If BaudRate is NIL, the value of the global variable TTY.DEFAULT.INIT.INFO is used in its place. This provides a means of automatically initializing the TTY port hardware without user intervention. TTY.DEFAULT.INIT.INFO [Variable] This variable controls default initialization of the TTY port. Its value may be set in the site INIT.LISP file, or in a user's INIT.LISP file. If TTY.DEFAULT.INIT.INFO is not set when the TTY package is loaded, its fields will be set to the following default values: BaudRate: 1200 BitsPerSerialChar: 8 Parity: NONE NoOfStopBits: 1 FlowControl: XOnXOff Programs may use OPENSTREAM as an alternative to calling TTY.INIT directly, with the parameters bundled up into the PARAMETERS argument as shown below. For example: (OPENSTREAM '{TTY} 'BOTH NIL '((BaudRate 9600) (BitsPerSerialChar 8)) In addition, applications may change the settings of the RS232 hardware while the RS232 port is in use. For this purpose, the following function is provided: (TTY.SET.PARAMETERS PARAMETERLIST) [Function] PARAMETERLIST is an association list of parameter names and values. The following example sets the baud rate to 9600 baud, and the character length to eight bits: (TTY.SET.PARAMETERS '((BaudRate . 9600) (BitsPerSerialChar . 8))) The following is a list of legal parameter names and values: BaudRate: 50, 75, 110, 150, 300, 600, 1200, 2400, 3600, 4800, 7200, 9600, 19200. BitsPerSerialChar: 5, 6, 7, 8. Parity: NONE, ODD, EVEN. NoOfStopBits: 1, 2 (This parameter should be 1 except at 110 baud). FlowControl: NIL, XOnXOff. For applications requiring XOn and XOff characters other than ^Q and ^S respectively, this parameter may be supplied as a list in the form:(1 ), where and are replaced by the character values of the XOn and XOff characters. The leading ┅1构 signifies that flow control should be enabled; a leading ┅0构 will program the RS232 port with the appropriate XOn and XOff characters, but leave flow control disabled. DSR: This parameter enables or disables the data set ready signal; it may be specified as T or NIL. CTS: This parameter enables or disables the clear to send signal; it may be specified as T or NIL. The current settings for the TTY port may be obtained at any time by calling TTY.GET.PARAMETERS: (TTY.GET.PARAMETERS PARAMETERLIST) [Function] PARAMETERLIST should be a list of parameter names. TTY.GET.PARAMETERS returns an association list of parameter names and values, in a format acceptable to TTY.SET.PARAMETERS. The TTY port is turned off by calling TTY.SHUTDOWN: (TTY.SHUTDOWN) [Function] This function disables the TTY port. Using TTY Streams 1 Programs may open streams to the TTY port by calling OPENSTREAM with the file name {TTY}. The ACCESS argument to OPENSTREAM may be INPUT, OUTPUT, or BOTH. Unlike RS232 streams, TTY port streams are not buffered, and a single stream may be used for both input and output. The generic Interlisp-D input/output functions BIN, BOUT, READP, OPENP, and CLOSEF may be used on TTY port streams. The TTYCHAT Package 1 TTYCHAT is a package that enables the generic Interlisp-D Chat system to communicate over the TTY port. No user-callable functions or user-settable variables are available in this package. Once it is loaded, users may chat to the host named TTY to open a ┅connection构 to the TTY port. TTYCHAT is contained on the file TTYCHAT.DCOM. Because the TTY port does no low-level input buffering, it is quite likely that many input characters will be lost while chatting at 1200 baud or higher. This package should only be used for non-critical applications, such as testing connections between the TTY port and low-speed printers. The RS232CMENU Package 1 The RS232CMENU package, documented above, is compatible with the TTY port as well. Certain RS232 port commands, such as SendBreak! are not available with the TTY port, and hence do not appear in the menu.(LIST ((PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC) STARTINGPAGE# 209) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (270 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 618) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD LEFT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (54 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGV) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE VERSOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL))) (PAGE NIL (PAPERSIZE Letter FOLIOINFO (ARABIC)) (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD RIGHT) CHARLOOKS (SUPERSCRIPT 0 INVISIBLE OFF SELECTPOINT OFF PROTECTED OFF SIZE 10 FAMILY MODERN OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF EXPANSION REGULAR SLOPE REGULAR WEIGHT MEDIUM INVERTED OFF USERINFO NIL STYLE NIL) FORMATINFO (ARABIC)) (270 12 288 36) NIL) (HEADING NIL (HEADINGTYPE FOOTINGR) (54 27 558 36) NIL) (HEADING NIL (HEADINGTYPE RECTOHEAD) (54 762 558 36) NIL) (TEXT NIL NIL (54 54 504 684) NIL)))))..ZZ(xx(xx/T/T*2TT/2T.. /T/T...)T(( )T)TB PAGEHEADING VERSOHEADB PAGEHEADING RECTOHEADA PAGEHEADINGFOOTINGVA PAGEHEADINGFOOTINGR(MODERNMODERNMODERN MODERN MODERN ?1(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8))  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERN  HRULE.GETFNMODERNto HRULE.GETFNMODERN HRULE.GETFNMODERN #3   < $        I     E =  !  F  9 k g f    9 '   HRULE.GETFNMODERN  b     PB   K !  % b    p(0 1   jhvex   HRULE.GETFNMODERN  <      } 2 t d S  ]   J k+    HRULE.GETFNMODERN  | `   3 " . , D   HRULE.GETFNMODERN  k   HRULE.GETFNMODERN  3L BMOBJ.GETFN3MODERN  8  R  \ Q  5 8 M C A M   HRULE.GETFNMODERN   HRULE.GETFNMODERN   HRULE.GETFNMODERN ]   "+   <!         F     B = S !  F  f e a   4 %   HRULE.GETFNMODERN     HRULE.GETFNMODERN  Q %   HRULE.GETFNMODERN  Y縵