Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/misc/volume32/ecu/part37

Text File | 1992-09-14 | 57.0 KB | 1,956 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Warren Tucker)
Subject:  v32i072:  ecu - ECU Asynchronous Communications v3.20, Part37/40
Message-ID: <[e-mail]>
X-Md4-Signature: be316a86a0a934c6654e8d45a7a3c6a6
Date: Tue, 15 Sep 1992 15:37:36 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Warren Tucker)
Posting-number: Volume 32, Issue 72
Archive-name: ecu/part37
Environment: SCO,XENIX,ISC,SUNOS,SYSVR4,HDB,Curses
Supersedes: ecu: Volume 21, Issue 53-89

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is ecu320.37 (part 37 of ecu320)
# do not concatenate these parts, unpack them in order with /bin/sh
# file doc/_icmd.txt continued
#
if test ! -r _shar_seq_.tmp; then
    echo 'Please unpack part 1 first!'
    exit 1
fi
(read Scheck
 if test "$Scheck" != 37; then
    echo Please unpack part "$Scheck" next!
    exit 1
 else
    exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test ! -f _shar_wnt_.tmp; then
    echo 'x - still skipping doc/_icmd.txt'
else
echo 'x - continuing file doc/_icmd.txt'
sed 's/^X//' << 'SHAR_EOF' >> 'doc/_icmd.txt' &&
Xor later.  The file ~/.kermrc must be set up to have any desired
Xinitialization parameters you desire (refer to C-Kermit
Xdocumentation for more information).
XThe remote protocol must have been started prior to the
Xexecution of this command.
X
XWARNING: until further notice, avoid suspending Kermit
Xwith ^\Z.  ECU is totally unprepared to act as a job control
Xprocess group leader.
X
X.*s 2 "RS : receive via SEAlink"
X.DS L
Xusage: rs
X.DE
X
XThis command invokes a SEAlink receive protocol.
X
X.*s 2 "RTScts : control RTS/CTS flow control"
X.DS L
Xusage: rtscts [ off | on | no | yes | 0..7 ]
X.DE
X
XThis command controls the RTS/CTS flow control feature of
Xthe line driver (which may or may not work).
XThis is a very confusing area though it should not be.
X
XIf no argument is supplied, the current setting is
Xdisplayed.  Specifying 0 or n disables the facility;
X1 or y causes RTS/CTS flow control to be enabled.
X
XWhat the command does is to manipulate the RTSFLOW and CTSFLOW
Xbits of the termio c_cflag word (see
X.B termio(S) ).
X
XSCO's sio driver before UNIX 3.2v4/ODT 2.0
Xdoes half duplex flow control.
XFAS does hardware flow control based on the device magic
Xnumber, but if you use a device number specifying no hardware flow
Xcontrol, RTSFLOW and CTSFLOW can be used to specify SCO-style flow
Xcontrol.
XCRTSFL offers full duplex line control
Xon 3.2v4 and later ONLY for SCO's sio driver.
X
X.DS I
X arg | RTSFLOW | CTSFLOW    arg | RTSFLOW | CTSFLOW | CRTSFL
X-----+---------+---------  -----+---------+---------+--------
X off |   0     |   0         0  |   0     |   0     |
X on  |   0     |   1         1  |   0     |   1     |
X no  |   0     |   0         2  |   1     |   0     |
X yes |   0     |   1         3  |   1     |   1     |
X                             4  |   0     |   0     |   1
X.DE
XChoice 4 only works on SCO 3.2v4 and ODT 2.0.
XAs you can see, numeric values are masks.
XIf the 4 bit is present in the numeric value, it
Xoverrides the lower-order bits:  Specifying 7 as an argument
Xspecifies CRTSFL is to be used if it is supported, otherwise
XRTSFLOW and CTSFLOW.
X
XUnder System V Release 4, an TCGETX/TCSETX manipulation
Xis performed, modifying the x_hflag bits as follows:
X.DS I
Xargument | RTSXOFF | CTSXON    argument | RTSXOFF | CTSXON
X---------+---------+---------  ---------+---------+---------
X  off    |   0     |   0         0      |   0     |   0
X  on     |   0     |   1         1      |   0     |   1
X  no     |   0     |   0         2      |   1     |   0
X  yes    |   0     |   1         3      |   1     |   1
X.DE
XUnder SunOS 4.1, only CTS support is provided.  You should read
Xthe termio and zs man pages.  Arguments result in the stated
Xmanipulations of the termio element c_cflag:
X.DS I
Xargument | CRTSCTS    argument | CRTSCTS
X---------+---------  ----------+---------
X  off    |   0           0     |   0
X  on     |   1           1     |   1
X  no     |   0
X  yes    |   1
X.DE
X
X.*s 2 "RX : receive via XMODEM/CRC"
X.DS L
Xusage: rx
X.DE
X
XThis command invokes ecurz to receive files from the remote
Xsystem using XMODEM/CRC.
X
XAfter entering the command, you are prompted as to whether
Xor not file CR/LF characters are to be converted to
Xnewlines.  If you are transferring text files from a system
Xwhich contain CR/LF line terminators, you must answer yes
Xto this question.  You should answer no when transferring
Xbinary files, such as executables, .arc files and the like.
XFile transfer progress is presented on a visual display.  To
Xabort the transfer, press your interrupt key (usually DEL
Xunless reset with stty(C)).
X
X
X.*s 2 "RY : receive via YMODEM Batch"
X.DS L
Xusage: ry
X.DE
X
XThis command invokes ecurz to receive files from the remote
Xsystem using YMODEM batch with CRC-16 error correction.  The
XYMODEM is "true YMODEM", not XMODEM-1k.  File transfer
Xprogress is presented on a visual display.  To abort the
Xtransfer, press your interrupt key (usually DEL unless reset
Xwith stty(C)).
X
X
X.*s 2 "RZ : receive via ZMODEM/CRC32"
X.DS L
Xusage: rz
X.DE
X
XThis command invokes ecurz to receive files from the remote
Xsystem using ZMODEM/CRC32.
XThe remote sender must have been started prior to the
Xexecution of this command.
XFile transfer progress is
Xpresented on a visual display.
XTo abort the transfer, press
Xyour interrupt key (usually DEL unless reset with stty(C)).
X
XIf automatic ZMODEM frame detection is enabled and
XECU is in the interactive mode,
Xthis command is executed automatically.
XAutomatic ZMODEM frame detection is NOT supported
Xduring procedure execution.
X
X
X.*s 2 "SDNAME : select screen dump file name"
X.DS L
Xusage: sdname [<filename>]
X.DE
X
XWhen the "cursor 5" key is pressed, the screen contents are
Xdumped to a file.  By default, this file is named '~/.ecu/screen.dump'.
XThis command either displays or changes the current screen
Xdump file name, depending upon whether or not a argument
Xis supplied.
X
XThe actions of this command have no effect on the
Xoperation of the
X.b scrdump
Xprocedure command.
X
XSee the section titled "Screen Dump" for more information.
X
X.*s 2 "SK : send via C-Kermit"
X.DS L
Xusage: sk [<file-list>]
X.DE
X
XThis command invokes C-Kermit to
Xsend
Xfiles. ECU searches the PATH list for 'kermit' or 'ckermit',
Xexpecting to find Columbia University C-Kermit version 5A(173)
Xor later.  The file ~/.kermrc must be set up to have any desired
Xinitialization parameters you desire (refer to C-Kermit
Xdocumentation for more information).
XThe remote protocol must have been started prior to the
Xexecution of this command.
X
XWARNING: until further notice, avoid suspending Kermit
Xwith ^\Z.  ECU is totally unprepared to act as a job control
Xprocess group leader.
X
XAfter entering the command, you are prompted as to whether
Xor not file newline characters are to be converted to CR/LF.
XIf you are transferring text files to a system which
Xrequires CR/LF line terminators, you must answer yes to this
Xquestion.  You should answer no when transferring binary
Xfiles, such as executables, .arc files and the like.  You
Xare prompted to enter a list of files to send, which may
Xcontain one or more wildcard specifications.
X
X.*s 2 "SS : send via SEAlink"
X.DS L
Xusage: ss [<file-list>]
X.DE
X
XThis command invokes a SEAlink file transmission protocol.
X.DS L
X
X .--[ Send SEAlink ]-------- dir: /u1/src/ecu ------------------.
X |                                                              |
X |  File(s) to send:                                            |
X |  ___________________________________________________________ |
X |                                                              |
X |    TAB:next  ^B:prev  END:perform transfer  ESC:abort        |
X `-- enter file(s) to send -------------------------------------'
X.DE
X
X.*s 2 "STat : verbose status summary"
X.DS L
Xusage: stat
X.DE
X
XThis command displays comprehensive status and statistics.
XExample display:
X.DS L
X % stat
XDate: 08-17-1992 05:47:49 (UTC 09:47)
XCommunications line: /dev/tty2b 9600-N-1
XXON/XOFF input on output on
XHardware flow control configuration:
XRTSFLOW off CTSFLOW off CRTSFL off
XNot connected to a remote
XDuplex: full  DCD watcher: off
XConsole: /dev/ttyp7 80x43 <pty>
XAcquired by ecuungetty: /dev/tty2b
XCurrent directory: /u1/src/ecu
XTotal chars transmitted: 234 (since CONNECT 142)
XTotal chars received:    2278 (since CONNECT 1478)
XNo function key set loaded
XSession logging not active
XBell notify is ON
XCR conversion:  incoming CR  outgoing CR
XKeyboard ESC/funckey time constant = 300 msec
XPids: xmtr=20878 rcvr=20882 parent=19476 pgrp=19476
X.DE
X
X.*s 2 "SX : send via XMODEM/CRC"
X.DS L
Xusage: sx [<file-name>]
X.DE
X
XThis command invokes ecusz to send a file to the remote
Xsystem using XMODEM/CRC.
X
XAfter entering the command, you are prompted as to whether
Xor not file CR/LF characters are to be converted to
Xnewlines.  If you are transferring text files from a system
Xwhich contain CR/LF line terminators, you must answer yes
Xto this question.  You should answer no when transferring
Xbinary files, such as executables, .arc files and the like.
X
XYou are prompted to enter a filename to send.  File transfer
Xprogress is presented on a visual display.  To abort the
Xtransfer, press your interrupt key (usually DEL unless reset
Xwith stty(C)).
X.DS L
X .--[ Send XMODEM/CRC ]----- dir: /u1/src/ecu -----------.
X |                                                       |
X |  File to send:                                        |
X |  ____________________________________________________ |
X |                                                       |
X |  Binary: Y (no NL-CR/LF translation)                  |
X |                                                       |
X |   TAB:next  ^B:prev  END:perform transfer  ESC:abort  |
X `-- enter file(s) to send ------------------------------'
X.DE
X
X.*s 2 "SY : send via YMODEM Batch"
X.DS L
Xusage: sy [<file-list>]
X.DE
X
XThis command invokes ecusz to send file(s) to the remote
Xsystem using YMODEM/CRC.
X
XYou are prompted to enter filename(s) to send, which may
Xconsist of one or more wildcard specifications.  File
Xtransfer progress is presented on a visual display.  To
Xabort the transfer, press your interrupt key (usually DEL
Xunless reset with stty(C)).
X.DS L
X .--[ Send YMODEM/CRC ]----- dir: /u1/src/ecu -----------.
X |                                                       |
X |  File to send:                                        |
X |  ____________________________________________________ |
X |                                                       |
X |  Binary: Y (no NL-CR/LF translation)                  |
X |                                                       |
X |   TAB:next  ^B:prev  END:perform transfer  ESC:abort  |
X `-- enter file(s) to send ------------------------------'
X.DE
X
X.*s 2 "SZ : send via ZMODEM/CRC32"
X.DS L
Xusage: sz [<file-list>]
X.DE
X
XThis command sends files to the remote system using ZMODEM/CRC32.
XThe remote receiver must have been started prior to the
Xexecution of this command unless the remote has automatic
XZMODEM frame detection.
X
XYou are prompted to enter filename(s) to send, which may
Xconsist of one or more wildcard specifications.  File
Xtransfer progress is presented on a visual display.  To
Xabort the transfer, press your interrupt key (usually DEL
Xunless reset with stty(C)).
X
XNote: not all ZMODEM receiving software supports transfer of only
Xnewer files or of resuming interrupted transfers.  If the remote
Xreceiver does not support the feature, it may skip (reject) all
Xyour files.  Retry the transfer specifying 'N' to 'Transfer only
Xnewer files' and/or 'Resume interrupted transfer'.
X
X.pp
X.DS L
X.--[ Send ZMODEM/CRC32 ]--- dir: /tmp ---------------------------.
X|                                                                |
X|  File(s) to send:                                              |
X|  ckermit-5a-130                                                |
X|                                                                |
X|  Binary: Y (no NL-CR/LF translation)                           |
X|  Overwrite destination files: Y                                |
X|  Send full pathames:  N                                        |
X|  Transfer only newer files:   N                                |
X|  Resume interrupted transfer: N                                |
X|  Window size: 0                                                |
X|                                                                |
X|     TAB:next  ^B:prev  END:perform transfer  ESC:abort         |
X`-- enter file(s) to send ---------------------------------------'
X`-- Y: no conversion, N: NLs converted to CR/LF -----------------'
X`-- Y: overwrite, N: protect destination files ------------------'
X`-- Y: full pathnames, N: strip directory portion from names ----'
X`-- Y: resume transfer at remote file EOF, N send all -----------'
X`-- Y: send only if source newer than destination, N send all ---'
X`-- window size (max bytes sent before ACK required) 0 = stream -'
X.DE
X
X.*s 2 "TIme : time of day"
X.DS L
Xusage: time
X.DE
X
XThis command displays the local date and time as well as the
Xcurrent UTC.
X
X.*s 2 "TTy : console tty name"
X.DS L
Xusage: tty
X.DE
X
XThis command displays the current console tty name.
X
X
X.*s 2 "XA : hex to ascii char"
X.DS L
Xusage: xa [<hex-val>]
X.DE
X
X<hex-val> is a hexadecimal value between 0 and FF; the
Xparity (sign) bit is stripped and the equivalent ASCII
Xcharacter value is displayed.
X
XIf no argument is supplied, a table of control characters
Xis printed containing decimal, octal, hex, ASCII identifiers
Xand two-character control character identifier.
X
X
X.*s 2 "XON : xon/xoff flow control"
X.DS L
Xusage: xon [<arg>]
Xwhere <arg> is on    input and output flow control
X               off   no flow control
X               in    input flow control
X               out   output flow control
X.DE
X
XThis command enables or disables xon/xoff flow control.
XIf the argument is omitted, the current flow control state is displayed.
X
X.*s 2 "! : execute shell"
X.DS L
Xusage: !
X       !<command>
X.DE
X
XThe '!' command is a shell escape.  The environment variable
XSHELL is read to determine what shell program to execute
X(e.g., /bin/sh, etc).  If '!' is entered by itself, an
Xinteractive shell is started; press ^D to exit back to ECU.
XIf <command> is supplied, it is executed by the shell with
Xan immediate return to ECU.
X
SHAR_EOF
echo 'File doc/_icmd.txt is complete' &&
chmod 0644 doc/_icmd.txt ||
echo 'restore of doc/_icmd.txt failed'
Wc_c="`wc -c < 'doc/_icmd.txt'`"
test 38646 -eq "$Wc_c" ||
    echo 'doc/_icmd.txt: original size 38646, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= doc/_intro.txt ==============
if test -f 'doc/_intro.txt' -a X"$1" != X"-c"; then
    echo 'x - skipping doc/_intro.txt (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting doc/_intro.txt (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'doc/_intro.txt' &&
X.*s 1 "Introduction"
X
XECU (Extended Call Utility) is a personal and research
Xcommunications program originally written for
Xusers of SCO UNIX V.3.2/386 and XENIX V on 80286 and 80386 systems.
XSupport for other systems has been added and further porting
Xis possible with "minor" effort to other systems based on or
Xsimilar to UNIX System V.
XThis preliminary document describes ECU functionality and implementation
Xfrom a technical point of view and provides at least rudimentary
Xdocumentation for its features and commands.
X
XECU provides the classic terminal communications facility of passing
Xkeyboard data to a serial line and incoming data to the computer video
Xdisplay.  In addition, a dialing directory, a function key mapping
Xfeature, and session logging are available.
X
XA very flexible procedure (script) language is also incorporated to
Xautomate many communications tasks.  In addition to
Xaugmenting interactive tasks, by using shell scripts and ECU
Xprocedures, ECU can perform batch-style communications sessions
Xin an entirely "unattended" fashion.
XBecause of limitations of my nroff program, the procedure language
Xis described in a separate document.
X
XECU presents to the host a flexible "ANSI" terminal type, accepting
Xany valid video control sequences from MS-DOS or SCO documentation
Xas of late 1990.  It also fares well, though imperfectly, with
XSun and VT-100 in-band video control sequences.
XStandards are great: everybody should have one, especially if
Xthey call it "ANSI."
XFor more information,
Xrefer to the section below titled "ANSI Filter."
X
XThe program supports almost any local terminal (console) which
Xcan be described in a termcap database entry.
XFor more information, refer to "Supported Terminals."
X
XECU supports numerous file transfer protocols: as of this writing,
XXMODEM, XMODEM/CRC, XMODEM-1K, YMODEM/CRC Batch, ZMODEM/CRC-16,
XZMODEM/CRC-32, Kermit and SEAlink are supported.
XFor more information, refer to the sections describing the
Xindividual interactive and procedure file transfer commands.
X
XThis document is better than that supplied with
XECU 2.0, but is still rough in many places.
XIt attempts to get across to the inquiring mind how ECU
Xworks.  In places, an understanding of the UNIX programming model, UNIX,
XXENIX and UUCP constructs and asynchronous communications techniques
Xis assumed.  In other places, the document goes into tedious detail
Xabout the simplest of concepts.  A great deal of attention has been
Xplaced in accurate and robust coding of the program.  Perhaps, time
Xpermitting, one day I can say the same for this document.
SHAR_EOF
chmod 0644 doc/_intro.txt ||
echo 'restore of doc/_intro.txt failed'
Wc_c="`wc -c < 'doc/_intro.txt'`"
test 2580 -eq "$Wc_c" ||
    echo 'doc/_intro.txt: original size 2580, current size' "$Wc_c"
rm -f _shar_wnt_.tmp
fi
# ============= doc/_p_cmd.txt ==============
if test -f 'doc/_p_cmd.txt' -a X"$1" != X"-c"; then
    echo 'x - skipping doc/_p_cmd.txt (File already exists)'
    rm -f _shar_wnt_.tmp
else
> _shar_wnt_.tmp
echo 'x - extracting doc/_p_cmd.txt (Text)'
sed 's/^X//' << 'SHAR_EOF' > 'doc/_p_cmd.txt' &&
X.*s 1 "Commands"
X
X.*s 2 "autorz"
X
Xusage: autorz [off | on]
X
XECU in the interactive mode (no procedure executing) can interpret a
XSUB, 'B', '0', '0' receive data sequence as a ZMODEM ZRQINIT frame and
Xautomatically begin a ZMODEM receive operation.  This command controls
Xthis feature.  By default, this feature is turned on.
X
X.*s 2 "baud"
X
Xusage: baud <baud-int>
X
XThis command sets the baud rate for the attached line.
XThe integer argument <baud-int> must be one of
X110, 300, 600, 1200, 2400, 4800, 9600, 19200 and 38400.
X
XUsing the 'baud' procedure command in the ECU initialization
Xprocedure "_rc.ep" serves as an exact analog of the -b command.  The
X.B baud
Xcommand with the
X.B setline
Xcommand gives you programatic control over the actual choice of the
Xline and rate or the defaults for the setup screen, depending upon
Xother options.  NOTE: using the baud command in _rc.ep will override
Xany command line -b specification.
X
X.DS L
XExample:
X    baud 9600
X    set $i0=2400; baud $i0
X.DE
X
X.*s 2 "break"
X
Xusage: break
X
XThis command is used inside a
X.B whilei
Xor
X.B whiles
Xcompound statement to exit the loop.
X
XThis is not to be confused with the interactive command
X"break" when sends an asynchronous BREAK signal.  Use the procedure
Xcommand
X.B lbreak
Xfor this purpose.
X
X.DS L
XExample:
X
X    whilei 1=1 #forever unless break command executed
X    {
X        echo -n 'Answer yes or no: '
X        set $s0=%cgets # get answer
X        ifi %instr($s0,'y') == 0 set $i0 = 1; break
X        ifi %instr($s0,'n') == 0 set $i0 = 0; break
X        # got neither 'y' nor 'n' ... keep trying
X    }
X    # now $i0 = 1 if yes, 0 if no
X.DE
X
XNOTE: further examples of
X.B break
Xusage may be found in the example for the
Xelse
Xcommand.
X
X.*s 2 "cd"
X
Xusage: cd <directory-path>
X
XThis command changes ECU's current working directory.
XThe string argument <directory-path> may contain any
Xdirectory pathname specification legal to be submitted to
Xthe shell csh.  Wild card characters may be used, provided
Xthe expansion produces only one pathname.
X
X.DS L
XExample:
X
X    cd '~user/bin'
X    cd %envvar('HOME')+'/bin'
X.DE
X
X.*s 2 "clrx"
X
Xusage: clrx
X
XThis command clears  the attached line's transmitter XOFF state.
XIssuing the command is the equivalent to receiving an XON from
Xthe remote system.
X
X.*s 2 "cls"
X
Xusage: cls
X
XThis command clears the screen.
X
X.*s 2 "color"
X
X.DS L
Xusage: color <normal-foreground> [<normal-background>]
Xusage: color -r <reverse-foreground> [<reverse-background>]
X.DE
X
XThis command changes the current normal or reverse video colors in a
Xmanner similar to the setcolor(C) command.  It has no effect on systems
Xusing other than an SCO multiscreen color monitor.
XIf the second (background) color is
Xomitted, it is assumed to be black.
X
XThe command also forces normal video mode.  Refer to the
X.B vidnorm
Xand
X.B vidrev
Xcommands.
XRefer also to the
X.B vidcolor
Xcommand.
X
X.DS L
XColor names
X   blue      magenta      brown      black
X   lt_blue   lt_magenta   yellow     gray
X   cyan      white        green      red
X   lt_cyan   hi_white     lt_green   lt_red
X.DE
X.DS L
XExample:
X
X    color lt_green  # normal video light green on black
X    color -r red white # reverse video red on white
X.DE
X
X.*s 2 "continue"
X
Xusage: continue
X
XThis command is used inside a
X.B whilei
Xor
X.B whiles
Xcompound statement to skip the remainder of any
Xcommands in the loop and continue execution at the first
Xcommand in the loop.
X.DS L
XExample:
X
X    send '' # send ENTER to get prompt
X    whilei 1=1 # forever unless break command executed
X    {
X        lookfor -e 'login: ' # look for login prompt
X        ifi $i0 == 0         # if we dont get prompt ...
X        {
X            send ''          # send ENTER again
X            continue         # and look for login prompt
X        }
X        send $s_name         # send username
X        lookfor -e 'Password:'
X        send $s_password
X        get -e 0 50          # wait 10 seconds for response
X
X        # if incorrect not found in response, ...
X        if %instr($s0,'incorrect') < 0 # ... must have won
X            break
X
X        # garbled line?: system will send another 'login: '
X    }
X
X.DE
X
XNOTE: further examples of
X.B continue
Xusage may be found in the example for the
X.B else
Xcommand.
X
X.*s 2 "cursor"
X
Xusage: cursor <row> [<col>]
X
XThis command places the cursor at a specified position on
Xthe video screen.  The top left of the scrren is row 0, column 0.
XIf <col> is not specified, it is assumed 0 (left margin).
X.DS L
XExample:
X
X    cls
X    $i0 = 5
X    whilei $i5 < 12
X    {
X        cursor $i5
X        echo 'This is line '+%itos($i5,2d)+' of the display'
X    }
X.DE
X
X.*s 2 "dcdwatch"
X
Xusage: dcdwatch [<dcdwatch-param>]
X
XThis command controls the DCD watcher.  The optional argument may be:
X.DS L
X   y or yes         enable DCD watcher
X   n or no          disable DCD watcher
X   t or terminate   terminate ECU on loss of DCD
X.DE
X
XThe DCD watcher when enabled causes ECU to monitor the DCD line
X(within the limits imposed by the OS with its CLOCAL=0 functionality).
XWhen the watcher is on and DCD drops, ecu automatically performs
Xthe action of the interactive or procedure
X.B hangup
Xcommand.  If the 't'erminate option is chosen, then after
Xhangup processing is complete, the ECU program will terminate.
X
XThe state of the watcher may be changed by the use of the dial
Xcommand which uses a directory entry which changes the
XDCD watcher status.
X
XThe DCD watcher depends upon the tty driver to return zero characters
Xon a read when DCD is low when the termio flag CLOCAL is reset.
XThe tty driver must ignore DCD if CLOCAL is set.
XIf your system offers a "modem" and "direct" choice (by choice
Xof filename), you probably need to use the "modem" choice for
Xthis to work properly.  This decision is made properly for you
Xon SCO if you are using SCO "standard" tty line
Xnaming conventions.  This is true even though ECU appears to force
Xa tty name with trailing upper case characters (modem) to
Xone with a lower case character (direct).
X
X.*s 2 "delline"
X
Xusage: delline
X
XThis command deletes the current line from the video display.
X
X.*s 2 "dial"
X
Xusage: dial <remote>
X
XThis command causes an outgoing call to be placed.  The string
Xargument <remote> can take one of two forms: a numeric telephone
Xnumber or an alphanumeric "logical" number or system name.
X
XA numeric phone number ('1(800)555-1212' or '2345678') must begin
Xwith a digit and must consist entirely of digits, parentheses
Xor hyphens.
XIf a telephone number is supplied, the phone number is
Xdialed; you must first have set the desired baud rate and
Xparity using the 'baud' and 'parity' commands.
X(If the last character of a telephone number is a dollar sign,
Xit is removed and is replaced with the contents of the first line
Xin ~/.ecu/credit.  See the description of the dialing directory.)
X
XIf a logical name is entered, the phone directory (managed by
Xthe interactive
X.B dial
Xcommand) is searched;
Xif the entry is found, the baud rate and parity
Xis automatically set from values in the directory entry; then,
Xthe number in the directory entry is dialed.
X
XUsing the dial command with a directory entry may change the
XDCD watcher (dcdwatch) status.
XSee the section on the
X.B dcdwatch
Xcommand and the section titled "Choosing a Dialout Line" for
Xmore information.
X
XWhen the
X.B dial
Xcommand returns, integer variable $i0 is set to a status code
Xand string variable $s0 has a text message (the modem verbal
Xresult code if the ECU dialer is used, a representation of
Xthe return status code if a uucp dialer is used [see below]).
X.DS L
X.B
XDial Command $i0 Status Codes
X.R
X
X    0  successful connect
X    1  failed to connect (call progress)
X    2  dial interrupted by signal
X    3  modem error (non responsive or commands rejected)
X.DE
X.DS L
X.B
XDial Command $s0 Status Messages (uucp dialer)
X.R
X
X    CONNECT ####           #### = baud rate
X    BUSY                   only some modems
X    NO ANSWER              only some modems
X    NO CARRIER             most generic "fail to connect"
X    NO DIAL TONE           only some modems
X    !Connect bad baud rate modem reported different rate
X    !Interrupted           call interrupted by signal
X    !Invalid arguments     ECU error
X    !Invalid phone number  too long or bad characters
X    !Ioctl error           should not be reported here
X    !Line in use           should not be reported here
X    !Line open error       should not be reported here
X    !Modem Error           modem did not respond
X
XNote: if the ECU dialer is used, the actual modem result code
Xis returned in $s0 or one of the following two strings:
X
X    !Interrupted           call interrupted by signal
X    !Modem Error           modem did not respond
X.DE
X
X.*s 2 "do"
X
Xusage: do <procname> [<arg> ...]
X
XThis command executes a procedure whose name appears as the command's
Xfirst (string) argument.  One or more arguments (up to 19) may be passed
Xto the called procedure; an argument may consist of any valid string
Xexpression, provided, that, when expanded,  the argument does not
Xexceed 256 characters in length.
X
XThe called procedure may read its arguments using the
X.B %argv
Xstring function.  %argv(0) is the name of the procedure.
XThe quantity of arguments may be obtained using the
X.B %argc
Xinteger function.
X
X.DS L
XExample:
X
X    do 'proc' %rname %date+' '+%time %argv(0)
X
XNote: in this example, the called procedure is passed the name
Xof the calling procedure as the last argument.
X.DE
X
X.*s 2 "duplex"
X
X.DS L
Xusage: duplex full | half
X       duplex 'full' | 'half'
X.DE
X
XThis command specifies whether or not ECU is to locally echo
Xcharacters typed by you at the keyboard.  The overwhelming
Xmajority of remote systems provide the echo function, in
Xwhich case full duplex must be used.  For the rare occasions
Xwhen the remote system does not echo your keyboard input,
Xsetting half duplex will allow you to see what you are
Xtyping.
X
XWhen communicating with another terminal in a "teletype
Xconversation", setting half duplex is generally required.
XIn such cases, use of the interactive
X.B nl ,
X.B nlin
Xand
X.B nlout
Xcommands may also be required.
X.DS L
XExample:
X
X    duplex full
X    $s0 = 'full'; duplex $s0
X.DE
X
X
X.*s 2 "echo"
X
Xusage: echo [-n] <string>
X
XThis command prints the contents of the string argument <string>
Xon the screen.  If the -n switch is not present, a newline follows
Xthe output of <string>.
X.DS L
XExample:
X
X    echo 'Procedure '+%argv(0)+' executing at '+%time
X    echo -n 'Enter your first name: '; $s0 = %cgets
X.DE
X
X.*s 2 "eeol"
X
Xusage: eeol
X
XThis command erases the video display to the end of the line.
X
X.*s 2 "else"
X
X.DS L
Xusage: else <statement>
X
X       else
X           <statement>
X
X       else
X       {
X            any kind and number of statements
X       }
X
X       else <if> <statement>
X
X       else <if>
X       {
X            any kind and number of statements
X       }
X
X.DE
X
XThis statement may follow an
X.B ifi
Xor
X.B ifs
Xcommand to specify one or more statements to be executed if
Xthe if-type command condition is false.  Else commands may be
Xchained together in the traditional structured language manner.
X
XFor the purposes of describing this command, <statement> is
Xany single or compound statement
X.B NOT
Xcontaining a
X.B whilei
Xor
X.B whiles
Xcommand.
XIf you wish to have a while-type command executed as part of an
X.B else
Xcondition, the while must occur within braces ("{}").
X
X<if> is an
X.B ifi
Xor
X.B ifs
Xcommand followed by an <if-condition> (see the description of the
X.B ifi
Xor
X.B ifs
Xcommands below).
X.DS L
XExample:
X
X#+------------------------------------------------------
X# finger.ep - procedure to send 'finger' to remote
X# BSD Unix system; print resulting lines in different
X# colors: uucp logins green, root red, others cyan
X#-------------------------------------------------------
X
X    mkvar $icolor; $icolor = %colors
X    mkvar $itimeout
X    $itimeout = 50     # timeout for first line 5 secs
X    send 'ps -aux'     # send command, but do not echo
X    lookfor '\en' 40    # swallow command
X    whilei 1==1        # forever, or until break
X    {
X        lgets 0 $itimeout 1 '\en' #get a line
X        ifi $i0 = 0 break #if no chaacters read
X        $itimeout = 10 #wait 1 sec for later lines
X
X        ifi %instr($s0,'% ') >= 0 # if csh prompt seen
X            break                 # exit while loop
X        else ifi %instr($s0,'Login') >= 0
X            color gray
X        else ifi %instr($s0,'root') >= 0
X            color red
X        else ifi %instr($s0,'uucp') >= 0
X            color green
X        else color cyan
X        echo $s0
X    }
X    icolor $icolor #restore entry colors
X    send ''        #force a new prompt from remote
X
X.DE
X
X.*s 2 "exec"
X
Xusage: exec <string>
X
XThis function executes a string as a procedure statement.
XArgument <string> must contain an ecu statement exactly as
Xmight appear on a procedure line, with a few exceptions.
X
X.DS L
X1. There may be no label: the first command may
X   start in column one.
X2. You should not execute a goto, gosub or return.
X3. You should not code if, while or compound statement
X   brackets.
X.DE
X
XYou are on your honor with regard to items 2 and 3 above.
XIf you stretch it, it will break.
X
X.DS L
XExample:
X
X    $s20 = 'Home';   $s30 = '^H'
X    $s21 = 'End';    $s31 = '^E'
X    $s22 = 'F1';     $s32 = '^A'
X    $s23 = 'F2';     $s33 = '^B'
X    $i10 = 0
X    whilei $i0 < 4
X    {
X        $s0 = 'fkmap '+$s[20+$i10]+' '+$s[30+$i10]
X        exec $s0
X        $i10 = $i10 + 1
X    }
X.DE
X
X.*s 2 "exit"
X
Xusage: exit [<status>]
X
XThis command causes an abrupt termination of the ECU program.
XAny existing connection with a remote system
Xis terminated immediately.
XIf no integer argument <status> is found, ECU exits
Xwith a program exit status of 0.
XIf <status> is found and the value is zero, then ECU exits
Xwith a program exit status of 0.
XIf <status> non-zero,its value must be in the range of 1 to 31,
Xand ECU exits
Xwith a program exit status of 192 plus <status>.
XThis feature allows batch executions of ECU by shell script
Xto detect user-determined ECU execution status.
XSee the section titled "Exit Codes".
X
X.*s 2 "expresp"
X
Xusage: expresp [-v[v...]] <exp-resp-str> [<timeout_msecs>]
X
XThis command emulates the uuchat function as described in the
XSCO HDB UUCP documentation and in the /usr/lib/uucp/Dialers
Xfile.
X
X-v causes the expect-respond conversation between ECU and the
Xremote system to be displayed on the screen.  This switch is
Xautomatically enabled if procdedure tracing is enabled.
X
XMultiple v's (e.g., -vv, -vvv) up to 3 'v's produce
Xmore verbose debug output. -vv causes each base level
Xexpect and respond string to be displayed. -vvv causes
Xa hexadecimal dump of each  interpreted expect string to be
Xdisplayed.
X
XThe majority of procedure tracing features use the current trace
Xstate (from the
X.B ptrace
Xcommand setting) as a binary condition.  That is, either tracing is done
Xor not.  However,
X.B expresp
Xadds the tracing level to the number of -v switches to determine its
Xverbosity level.
X
XEscape sequences allow you to insert special or variable
Xinformation in your expect and respond strings.  Escape sequences
Xbegin with either the backslash or the tilde.  NOTE: remember to
Xuse two backslashes inside a literal string constant to get one
Xbackslash in the resulting string.  The procedure language's
Xstring parser has it's own use for a single backslash followed by
Xanother character.  For instance:
X
X.DS L
X    set $s0='\e\eM' sets $s00 to '\eM'
X.DE
X
XSome of the escape sequnces have meaning in both expect and respond
Xtokens while others have a use in only of of the two types.
X
X.DS L
X   Meaning of the escape sequences:
X   \eD - current phone number
X   \eE - turn on echo checking when sending (for slow devices)
X   \eK - send a BREAK
X   \eM - turn on line CLOCAL
X   \eN - null byte (same as \e000)
X   \eT - current phone number with Dialcodes and
X         character translation
X   \ec - append no new-line to send string (must be last
X            "character" in a send string)
X   \ed - delay (2 seconds)
X   \ee - turn off echo checking when sending
X   \em - turn off line CLOCAL
X   \en - send or expect new-line
X   \ep - pause (approximately 1/4-1/2 second delay)
X   \er - send or expect carriage return
X   \e\e - send or expect backslash (same as \e134)
X   \e~ - send or expect tilde (same as \e176)
X   \e### - send or expect character respresenting three
X           character octal value ### (*MUST* be three digits
X           with leading zeroes as necessary)
X   ~m[##] - set expect timeout to ## milliseconds (NOT
X            SUPPORTED BY DIALERS; SEE BELOW)
X   ~n[##] - nap ## milliseconds (NOT SUPPORTED BY DIALERS;
X           SEE BELOW)
X   ~t[##] - set expect timeout to ## seconds (NOT SUPPORTED
X            BY DIALERS; SEE BELOW)
X   Speed - Hayes-style CONNECT handler (as sole contents of
X           an expect string, equivalent to using CONNECT)
X.DE
X
X<timeout_msecs> specifies an optional timeout in milliseconds
Xfor waiting on expect strings;  it defaults to 10,000 milliseconds
X(10 seconds).
XThe resolution for timeouts is limited to the basic tick time of
Xyour system (HZ, 10 msec for UNIX/386 3.2.0,
X16 (1000/60) msec for 3.2.1 (ODT 1.0) and 3.2v2 (ODT 1.1),
Xback to 10 msec for 3.2v4 (ODT 2.0) and
X20 msec for XENIX/386 and XENIX/286). Whew!
XThe timeout for 'Speed' expects is fixed at 90 seconds.
X
X~t[##] and ~m[##] may appear at the beginning of an expect portion
Xof a script.  They set the expect timeout delay in seconds and
Xmilliseconds, respectively.  The ## is a decimal number; if it is
Xspecified <= 0, there will be no delay.  The initial timeout set
Xfor each execution of the expresp command is 10 seconds.  The
Xtimeout period remains as you set it for the remainder of the
Xscript unless you change it again.
X
X.DS L
XExamples:
X
X    ~t[20]gin:      look for "gin:" for 20 seconds
X    ~m[500]\001     look for STX for 500 milliseconds
X    "" ~t[3]gin:--gin: uname ~t[10]word: secret
X.DE
X
X~n[##] may appear anywhere in a respond portion of a script.
XIt causes ECU to nap the number of milliseconds specified
Xby the decimal ## argument.  This function was served by \em prior
Xto ECU 3.20.  Addition of SVR4 \eM and \em necessitated
Xthe change.
X
X.DS L
XExample:
X
X    a~n[20]b~n[20]c   send "abc" with 20 msec between each
X                      character
X.DE
X
X
XInteger variable $i0 is set to one if the expect-respond script
Xfails, else it is set to 0.
X
X.*s 2 "fchmod"
X
Xusage: fchmod <mode> <filenum>
X
XThis command sets the mode of <filenum> to <mode>.
XThe <mode> argument takes one of two forms, a nine-character
Xmode string (e.g., 'rwxr-xr-x') or an integer value (0755).
XThe <filenum> argument is either a string value forming a
Xfilename or an integer file number representing a file opened with the
X.B fopen
Xcommand.
X
XThe command sets $i0 = 0 if successful, else to the
X.B errno
Xfrom the associated system call (refer to the
X.B %errstr
Xstring function and/or /usr/include/sys/errno.h).
X
X.DS L
XExample:
X
X    fopen 1 '/tmp/123'; fchmod 'rwxrwxrwx' 1
X    fchmod 'rwxrwxrwx' '/tmp/123'
X    fopen 1 '/tmp/123'; fchmod 0777 1
X    $i0 = 0777; fchmod $i0 '/tmp/123'
X
XAll of the above example result in the same result.
X.DE
X
X.*s 2 "fclose"
X
Xusage: fclose <filenum>
X
XThis command closes <filenum>.
XThe <filenum> argument is an
Xinteger file number representing a file opened with the
X.B fopen
Xcommand.
X
XThe command is ignored if <filenum> is not open.
XNo integer variable is modified by
X.I fclose .
X
X.DS L
XExample:
X
X    fclose 1
X.DE
X
X.*s 2 "fdel"
X
Xusage: fdel <filenum>
X
XThis command removes a file.
X
XThe command sets $i0 = 0 if successful, else to the
X.B errno
Xfrom the associated system call (refer to the
X.B %errstr
Xstring function and/or /usr/include/sys/errno.h).
X
X.DS L
XExample:
X
X    fdel '/tmp/123'
X.DE
X
X.*s 2 "fgetc"
X
Xusage: fgetc <filenum> <destination>
X
XThis command reads a character from <filenum>.
XThe <filenum> argument is an
Xinteger file number representing a file opened with the
X.B fopen
Xcommand.
X
XThe argument <destination> is either a string variable
Xor an integer variable.
XIf the file has reached end of file: an integer variable
Xreceives -1; a string variable is returned null.
XOtherwise, the character's numeric value (0-255) is placed
Xin an integer variable or a string variable is returned with a
Xlength of one with the file character as its only character.
X
X.DS L
XExample:
X
X    fgetc 1 $s0
X    fgetc 1 $i_input
X.DE
X
X.*s 2 "fgets"
X
Xusage: fgets <filenum> <strvar>
X
XThis command reads a character from <filenum>.
XThe <filenum> argument is an
Xinteger file number representing a file opened with the
X.B fopen
Xcommand.
X
XThe argument <strvar> is a string variable.
XIf the file has reached end of file, <strvar> is returned null and
Xinteger variable $i0 is set to 1.
XOtherwise, the <strvar> receives input from the file minus
Xthe trailing newline and $i0 is returned zero.
X
X.DS L
XExample:
X
X    fgets 1 $s0
X.DE
X
X.*s 2 "fkey"
X
X.DS L
Xusage: fkey <str>
X       fkey -r
X.DE
X
XThis command selects a function key definition from the ~/.ecu/keys
Xfile.  The -r version resets to the original defaults, plust
Xloads any entry in keys named "default".
X
X.*s 2 "fkmap"
X.DS L
Xusage: fkmap
X       fkmap <keyname>
X       fkmap <keyname> <keylist>
X       fkmap -r
X       fkmap -s <file>
X.DE
X
XThis command manages the mechanism ECU uses to recognize function
Xkeys when they are entered at the console.  Entering the command
Xwith no arguments displays the current mapping in funckeymap format.
X
XIf supplied, the first argument to the command must be the
Xrecognized name of a function key from the list:
X.DS L
X F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12
X Home End PgUp PgDn CUP CUL CU5 CUR CUD
X.DE
XThe case of the entered argument is unimportant.
X
XIf only one argument is supplied, the mapping for the specified key
Xis displayed.  If more than one argument is supplied, the keyboard
Xmapping is changed.  Arguments 2-n are character code specifiers
Xin the format used to define a funckeymap entry.
X.B WARNING :
XIf found to be syntactically correct, a mapping change
Xis installed immediately.  If incorrect mapping of the HOME
Xkey is requested, you may lose control of ECU.
X
XThe -r form rereads the original funckeymap definition (as
Xat program invocation), reseting the mapping.  The -s switch
Xsaves the current mapping to <file>.
X
XNote: the fkmap command line must contain literal text.
XNo variable or expression expansions are not done.
X
X.DS L
XExamples:
X
X    fkmap f10       display F10 mapping
X    fkmap Home ^Z   map Home to ^Z
X                    after this command, type ^Z for Home
X.DE
X
X.*s 2 "flush"
X
Xusage: flush
X
XThis command causes any characters received by the system
Xfrom the line, but not yet read by the procedure to be "forgotten"
Xor flushed.
X
X.*s 2 "fopen"
X
Xusage: fopen [-<mode>] <filenum> <filename>
X
XThis command opens a file named by the string argument <filename>
Xand associates it with the user-chosen file number <filenum> (which
Xmust be an integer value between 0 and 4, inclusive).
X
XThe argument switches govern how a file is opened and must be chosen
Xfrom this list:
X.VL 15 4
X.LI -r
XThe file is opened read-only; if it does not
Xexist, an error occurs.
X.LI -r+
XThe file is opened for reading and writing; if it does not
Xexist, an error occurs.
X.LI -w
XThe file is opened for writing (any previous contents
Xof the file are lost); if it does not
Xexist, it is created.
X.LI -w+
XThe file is opened for reading and writing (any previous contents
Xof the file are lost); if it does not
Xexist, it is created.
X.LI -a
XThe file is opened for appending (writes to the file
Xare added to the previous file contents); if it does not
Xexist, it is created.
XAll writes are appended to the file (the
X.B fseek
Xcommand has no effect).
X.LE
X
XThe switches argument may be omitted; in such cases,
Xthe file is opened as though '-r' had been supplied.  However,
Xif procedure tracing is enabled (see the description of the
Xinteractive and procedure command
X.B ptrace ),
Xa warning message will be issued.
X
XThe command sets $i0 = 0 if successful, else to the
X.B errno
Xfrom the associated system call (refer to the
X.B %errstr
Xstring function and/or /usr/include/sys/errno.h).
X.DS L
XExample:
X
X    fopen 0 -r '/etc/passwd'
X    fopen 1 -w+ '/tmp/123'
X    fopen 2 -a 'tranact.log'
X.DE
X
X.*s 2 "fputc"
X
Xusage: fputc <filenum> <char>
X
XThis command writes character <char> into <filenum>.
XThe <filenum> argument is an
Xinteger file number representing a file opened with the
X.B fopen
Xcommand.
XArgument <char> is a integer value of which the lower eight
Xbits are used or a string value of which the first character is used.
X
XIf a write error occurs, procedure execution is terminated.
X.DS L
XExample:
X
X    $s0='abc'; fputc 1 $s0        writes 'a'
X    $i0=0x30 ; fputc 1 $i0        writes '0'
X.DE
X
X.*s 2 "fputs"
X
Xusage: fputs [-n] <filenum> <str>
X
XThis command writes the string <str> into <filenum>.
XThe <filenum> argument is an
Xinteger file number representing a file opened with the
X.B fopen
Xcommand.
X
XIf the switch '-n' is omitted, a newline is appended after <str>
Xin the file; if present, no newline is written.
X
XIf a write error occurs, procedure execution is terminated.
X.DS L
XExample:
X
X    $s0='abc'; fputc 1 $s0        writes 'a'
X.DE
X
X.*s 2 "fseek"
X
Xusage: fseek <filenum> <position>
X
XThis command sets the file position of <filenum> to <position>,
Xan integer value.
XThe corresponding integer function
X.B %ftell
Xmay be used to determine the current file position.
X
X.B Note :
Xif <filenum> is open for append ('-a'), then the
X.B fseek
Xcommand will have no effect.
X
X.*s 2 "getf"
X
X.DS L
Xusage: getf -x <int-var-spec> <offset>
X
Xwhere: -x ==
X   -b byte
X   -w word (little-endian)
X   -W word (big-endian)
X   -l 32-bits (little-endian)
X   -L 32-bits (big-endian)
X.DE
X
X.*s 2 "gosub"
X
Xusage: gosub <label>
X
XThis command transfers control of procedure to a statement
Xother than the one immediately following.  The <label>
Xargument may be literal text or may be a string, allowing
Xa "computed gosub" feature.
X
XWhen the next return statement is executed, control is
Xreturned to the
Xnext statement after the gosub.
X
X.DS L
XExample:
X
X    gosub GET_NEXT
X    gosub 'GET_NEXT'
X    gosub 'GET'+'_NEXT'
X    $s0 = 'GET_NEXT'; gosub $s0
X    $s0 = 'NEXT'; gosub 'GET_'+$s0
X
XNote: all the above examples cause transfer to the label GET_NEXT.
X.DE
X.DS L
XA switch or case function of sorts may be implemented by something like:
X
X    #$i0 has been set to the "switch" value
X    ifi $i0 < 0 || $i0 > 2  # avoid gosub label not found
X    {
X        echo 'bad my_case state value'+%itos($i0)
X        DO SOMETHING LIKE DIE OR DUMP VARS AND DIE
X    }
X    $s0 = 'my_case_'+%itos($i0,03)
X    gosub $s0
X
Xmy_case_000
X    echo 'handle case 0'
X    return
X
Xmy_case_001
X    echo 'handle case 1'
X    return
X
Xmy_case_002
X    ifi $i_already_did_002
X    {
X        echo 'whoops'
X        return
X    }
X    echo 'handle case 2'
X    $i_already_did_002 = 1
X    return
X.DE
X
X.*s 2 "gosubb"
X
Xusage: gosubb <label>
X
XThis command serves the same function as the
X.B gosub
Xcommand except the programmer is signifying that the label
Xis
X.B b ehind
Xthe current statement, resulting in slightly faster execution.
X(The label is not REQUIRED to be at any specific location
Xin the procedure relative to the
X.B gosubb
Xstatement.)
X
X.*s 2 "goto"
X
Xusage: goto <label>
X
XThis command transfers control of procedure to a statement
Xother than the one immediately following.  The <label>
Xargument may be literal text or may be a string, allowing
Xa "computed goto" feature.
X.DS L
XExample:
X
X    goto GET_NEXT
X    goto 'GET_NEXT'
X    goto 'GET'+'_NEXT'
X    $s0 = 'GET_NEXT'; goto $s0
X    $s0 = 'NEXT'; goto 'GET_'+$s0
X.DE
XNote: all the above examples cause transfer to the label GET_NEXT.
X
X.*s 2 "gotob"
X
Xusage: gotob <label>
X
XThis command serves the same function as the
X.B goto
Xcommand except the programmer is signifying that the label
Xis
X.B b ehind
Xthe current statement, resulting in slightly faster execution.
X(The label is not REQUIRED to be at any specific location
Xin the procedure relative to the
X.B gotob
Xstatement.)
X
X.*s 2 "hangup"
X
Xusage: hangup
X
XThis command causes Data Terminal Ready (DTR)
Xto be dropped momentarily, causing (hopefully)
Xthe termination of any current connection
Xto a remote system.
XThis command is only effective if the attached Data Communications
XEquipment is configured
Xto terminate its connection on loss of DTR.
X
XIf no line is attached, the command is ignored (a warning
Xis generated if procedure tracing is enabled).
X
X.*s 2 "hexdump"
X
X.DS L
Xusage: hexdump [-s] <str>
X       hexdump -t[s] <str1> <str>
X
X<str> buf to dump
X<str1> title (if -t)
X-s short (terse) dump
X.DE
X
XThis command prints a hexadecimal dump of <str> on the screen
X(and to the procedure log file, if logging enabled with the
X.B ptrace
Xcommand).
X
XThe switch '-t' signifies that <str1> is a title to be printed
X.DS L
XExample:
X
X    $s0='The quick brown fox jumped over the lazy dog\e's back'
X    hexdump -t 'Example hex dump' $s0
X---------------------------- Example hex dump ----------------------------
X0000  54 68 65 20 71 75 69 63 6B 20 62 72 6F 77 6E 20 | The quick brown  |
X0010  66 6F 78 20 6A 75 6D 70 65 64 20 6F 76 65 72 20 | fox jumped over  |
X0020  74 68 65 20 6C 61 7A 79 20 64 6F 67 27 73 20 62 | the lazy dog's b |
X0030  61 63 6B                                        | ack              |
X.DE
X.DS L
X    hexdump %left($s0,9)
X0000  54 68 65 20 71 75 69 63 6B                      | The quick        |
X.DE
X.DS L
X    hexdump -ts 'Example hex dump' %left($s0,9)
XExample hex dump
X0000  54 68 65 20 71 75 69 63 6B | The quick |
X.DE
X.DS L
X    hexdump -s %left($s0,9)
X0000  54 68 65 20 71 75 69 63 6B | The quick |
X.DE
X
X.*s 2 "home"
X
Xusage: home
X
XThis command homes the video cursor.
X
X.*s 2 "icolor"
X
Xusage: icolor <int-colors>
X
XThis command sets the normal and reverse foreground
Xand background colors according to <int-colors>, an integer
Xvalue in the format as that returned by the
X.B %colors
Xinteger function.
X
XThis command is provided primarily to be able to save the color
Xstate, modify it temporarily and then restore it.
X.DS L
XExample:
X
X    mkvar $icolor_save; $icolor_save = %colors
X    color red; echo 'Connection seems to be dead'
X    icolor $icolor_save # restore previous colors
X.DE
X
X.*s 2 "ifi"
X
X.DS L
Xusage: ifi <int> <rel-op> <int> <statement>
X       ifi <int> <rel-op> <int>
X           <statement>
X       ifi <int> <rel-op> <int>
X       {
X           any kind or number of statements
X       }
X.DE
X
XThis command selectively executes one or more statements
Xbased on a test of two integer quantities.  See the
Xdescription of the
X.B break ,
X.B continue ,
Xand
X.B else
Xcommmands for examples of how the command is used.
X
X.*s 2 "ifs"
X
X.DS L
Xusage: ifs <str> <rel-op> <str> <statement>
X       ifs <int> <rel-op> <int>
X           <statement>
X       ifs <int> <rel-op> <int>
X       {
X           any kind or number of statements
X       }
X.DE
X
XThis command selectively executes one or more statements
Xbased on a test of two string values.  See the
Xdescription of the
X.B break ,
X.B continue ,
Xand
X.B else
Xcommmands
Xand many other examples throughout the document,
Xfor examples of how the command is used.
X
X.*s 2 "insline"
X
Xusage: insline
X
XThis command inserts a line onto the video screen at the current line.
X
X.*s 2 "lbreak"
X
Xusage: lbreak
X
XThis command transmits a break to the remote system.
XIt is the procedure command analogous to the
X.B break
Xinteractive command.
X
X.*s 2 "lgets"
X
X.DS L
Xusage: lgets [-er] <strvar> <t1-int> <t2-int> [<stop-str>]
X
X-e echo received characters to screen
X-r raw read (retain carriage returns)
X.DE
X
XThis command reads a string from the attached communications
Xline.
X<t1-int> is the number of tenths of seconds before
Xtiming out waiting for the first character to be received.
X<t2-int> is the number of tenths of seconds before
Xtiming out on later characters.
X<stop-str> is an optional argument, which if received, immediately
Xterminates the read.
XInteger variable $i0 is set to the count of characters received.
X
XIf the specified string variable is filled with characters
Xbefore the <stop-str> has been encountered or before a timeout
Xoccurs, then the command returns with $i0 set to the maximum
Xsize of the variable.
X
XMost procedure commands will increase the size of an
Xunumbered string variable as needed until the maximum
Xstring size is reached.
XThe
X.B lgets
Xcommand
X.I does
X.I not .
XYou must start with the command with a string variable whose maximum size
Xis already the desired value.
XRefer to the section on string variables
Xabove and the section describing the
X.B mkvar
Xcommand below for information on the size of string variables.
X
X.*s 2 "logevent"
X
X.DS L
Xusage: logevent <str>
X.DE
X
XThis command writes a log item to ~/.ecu/log.
X
X.DS L
XExample:
X
X    $s0='/tmp/alm.log'
X    log 'appending alarm info to '+$s0
X
Xwrites:
X10-02-1989-17:39-01261-PROC appending alarm info to /tmp/alm.log
X.DE
Xassuming the transmitter process pid is 1261 and you are living in
X1989.
X.*s 2 "lookfor"
X
X.DS L
Xlookfor [-e] [quiet | <str>] [<timeout-int>]
X
X-e echo to screen while "looking"
X.DE
XThis command is used to read from the attached commuications line
Xuntil one of two user-specified conditions occurs.
X
XThe 'quiet' option waits for the line to become
Xquiet for the number of tenths of seconds specified  by <timeout-int>.
X
XThe other option reads the line until <str> is read from the line
Xor until <timeout-int> tenths of seconds elapses.  With this option,
Xinteger variable $i0 is set to 1 if <str> is found within the
Xtimeout period or 0 if not.
X
X.DS L
XExamples:
X
X    lookfor -e quiet 20   wait for quiet line for 2 secs
X    lookfor 'word:' 50    wait for 'word:' for up to 5 secs
X.DE
X.*s 2 "mkvar"
X
X.DS L
Xusage: mkvar [$]i<name>
X       mkvar [$]s<name>(<size>)
X.DE
X
XThis command creates one or more named (temporary)
Xinteger or string variables.
XThe variable type is determines by the first character
Xof the variable, which must be 'i' or 's'.  The size of a string
Xvariable must be specified via the <size> argument.  An optional '$'
Xmay be supplies for neatness, but may be omitted if desired.
X
X.*s 3 "Variable Names"
X
XThe names for created (named, temporary) variables consist of
Xa dollar sign ('$'), an 'i' for integer or 's' for string and
Xup to fifteen characters from the set [A-Za-z0-9_].
X
XThe first character after the 'i' or 's' in <name>
Xmust be non-numeric.  '$sxyz' and '$s_3xyz' are legal, but '$s3xyz'
Xis not (it would be interpreted as '$s3' followed by the illegal
Xcommand sequence 'xyz').
X
XThe <name> space for integer and string variables are separate.
XIt is possible to have an integer variable named '$ixyz' and a string
Xvariable named '$sxyz'.
X
X.*s 3 "Variable Life and Scope"
X
XThe life and scope of created variables is for
Xthe duration of the execution
Xof the creating procedure.  Procedures called
Xby the creating procedure (by 'do') can reference
Xtemporary variables declared by a
Xprevious procedure.  When created, integer variables are set
Xto zero and string variables are set to zero length.
XThese features differ from numbered variables
Xwhich retain their scope and values at all times, even when
Xprocedure execution terminates and ECU returns to interactive mode.
X
XVariables may be created by the same name more than once.
XThe latest mkvar execution specifies the variable referenced.
XThus if proc1 declares '$ixx' and calls proc2 which also declares '$ixx',
Xproc2's variable is distinct from proc1's and disappears when proc2
Xterminates, thus making proc1's available to it again, containing
Xthe same value as it had at the time proc2 was called.
X
X.*s 3 "String Variable Size"
X
XThe maximum value for <size> is 16384.
XRegardless of the size specified in the creation of a string
Xvariable, ECU will usually expand it's size as necessary up to the
Xmaximum.  Check the documentation for the operation you are
Xperforming; if there is no exception noted, ECU will expand
Xthe string maximum size as necessary.  For instance, the
Xset command will grow a string as part of assignment.  However,
Xthe
X.B lgets
Xcommand will not.
X
X.DS L
XExamples:
X
X    mkvar i_count
X    mkvar $i_count
X    mkvar s_20(20),s_80(80),i_timeout,$i_colors
X.DE
X
X.*s 2 "nap"
X
Xusage: nap <int>
X       nap -m <int>
X
XThis command suspends procedure execution for <int> tenths of
Xseconds if
X.B -m
Xis not specified.
XIf -m is used, execution is suspended for <int> milliseconds.
XNote: the actual period execution is suspended depends, as usual,
Xon the scheduling load of the system.  For small -m values, be aware
Xthat the granularity of the nap duration is set by the system,
X20 milliseconds for XENIX 286 and 386, 10 milliseconds for UNIX.
X
XIf you need to know the frequency of the system clock,
Xsomething like
X.DS L
X      $i0 = %stoi(%getenv("HZ"))
X.DE
Xwill obtain the value for you (provided HZ is in the process' environment).
X.DS L
XExamples:
X
X    nap 30
X    nap $i0*$i2
X    nap -m 50
X.DE
X
X.*s 2 "nice"
X
Xusage: nice <int>
X
XThis command sets the nice value of the process.  It behaves
Xexactly like the nice(S) or nice(2) system call. The <int> argument
Xmust be in the range 0 through 39, inclusive.  If the call
Xfails, a warning is printed and the procedure continues to
Xexecute.  The current nice value may be obtained using the
X.B %nice
Xinteger function.  See also the description of the
X.B nice
Xinteractive command.
X
X.*s 2 "parity"
X
X.DS L
Xusage: parity [even | odd | none]
X       parity <str>
X.DE
X
XThis command sets the parity for the attached communications line.
XIf <str> is supplied, the first character must be 'e', 'o' or 'n'.
XUppercase equivalents are also accepted.
X
X.DS L
XExamples:
X
X    parity even
X    parity 'e'
X    parity 'Even now as we speak'
X.DE
X
X.*s 2 "pclose"
X
Xusage: pclose <filenum>
X
XThis command should be issued when a command started by the
Xinteractive
X.B popen
Xcommandf completes.
X
X.*s 2 "plog"
X
X.DS L
Xusage: plog
X       plog <str>
X       plog off
X.DE
X
XThis command controls logging to a file of the screen output during
Xprocedure execution.  With no argument, the command displays the status
Xof logging.  <str> specifies a log file pathname, while the 'off'
Xargument turns logging off.
X
XIf procedure execution terminates due to an error, procedure logging
Xis turned off.  However, if procedure execution terminates
Xnormally while logging is active, erratic and unpredictable portions
Xof interactive mode screen output will continue to be logged to
Xthe current log file.
X
XThe interactive mode command
X.B plog
Xmay also be used to control procedure logging.
SHAR_EOF
true || echo 'restore of doc/_p_cmd.txt failed'
fi
echo 'End of ecu320 part 37'
echo 'File doc/_p_cmd.txt is continued in part 38'
echo 38 > _shar_seq_.tmp
exit 0

exit 0 # Just in case...