![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to xchat.man CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [MW Coherent from dump] / coherent / g / usr / lib / uucp / tay104 / contrib|
Return to xchat.man CVS log | Up to [MW Coherent from dump] / coherent / g / usr / lib / uucp / tay104 / contrib |
1.1 root 1: .TH xchat 8
2: .SH NAME
3: xchat - Extended chat processor
4: .SH SYNOPSIS
5: .BI "xchat " "scriptfile"
6: .RI " [ " parameter... " ] "
7: .PP
8: where
9: .I scriptfile
10: is the name of a file containing an
11: .I xchat
12: script. If
13: .I scriptfile
14: begins with ``/'', then it is assumed to be a full path name for the
15: script file. If not, a configuration-dependent default directory path
16: (usually
17: .B "/usr/local/conf/uucp/"
18: ) is prepended to the script file name. Normally, the default path
19: is the same as that for the Taylor UUCP configuration files.
20: .SH DESCRIPTION
21: .I Xchat
22: is a general-purpose dialing and login program designed for use
23: with Taylor UUCP as a ``chat-program'', taking the place (or
24: augmenting) the built-in chat scripting facility. It provides the
25: ability to closely control timeouts, multiple simultaneous ``expect''
26: strings with separate actions, extended terminal control, modem
27: command character pacing, and more.
28: .PP
29: When used in conjunction with Taylor UUCP's
30: configuration features,
31: .I xchat
32: can provide you the ability to manage the most intricate login,
33: dial and hangup needs. The scripts are written in a shell-like (well,
34: sort-of) style with labels, commands, and parameters, easing the task
35: of writing procedures for complex terminal communications situations.
36: .PP
37: Because
38: .I xchat
39: assumes that it is connected to the terminal device via stdin/stdout,
40: you can easily debug scripts by invoking it from the shell and
41: responding to the script from the keyboard. A debug logging facility
42: is included, with the debug output going to a separate user-specified
43: file. This makes it easy to debug connection problems without wading
44: through large
45: .I uucico
46: log and debug files.
47: .PP
48: Formally, a script describes a state machine;
49: .I xchat
50: interprets the script and does what the state machine
51: tells it to. This section will be much easier to understand
52: if you obtain listings of the script files supplied with
53: .I xchat.
54: .SH "SCRIPT FILE FORMAT"
55: Script files are ordinary text files containing comments, labels,
56: and statements. Blank lines are ignored.
57: Comments are denoted by leading ``#''
58: characters. Some statements (those which do not end with an
59: ``extended string'' argument; see below) can also have trailing
60: comments.
61: .PP
62: .I Labels
63: begin in column one and are ended by colons (:). A label
64: specifies a state name. All lines between a pair of labels are
65: the statements for a single state.
66: .PP
67: Processing always begins at the head of the script (no leading
68: state name is necessary).
69: .PP
70: .I Statements
71: are divided into two categories, ``action'' and ``expect''.
72: When a state is entered, all of its actions are performed in the
73: order in which they appear in the file.
74: .PP
75: A
76: .I transition
77: to another state may occur for any of three reasons:
78: .IP (1) 5
79: One of the actions may cause a transition to
80: another state, in which case the rest of the
81: current state's actions are skipped.
82: Processing resumes with the first action
83: statement of the new state.
84: .IP (2) 5
85: If none of the actions cause a state
86: transition, and there are no expects in the
87: state, processing ``falls through'' to the next
88: state in the file.
89: .IP (3) 5
90: If none of the actions cause a state
91: transition, but there are expects in the
92: state, the state machine pauses until one of
93: the expects is ``satisfied''. It then transitions
94: to the state named in the expect
95: statement.
96: .PP
97: Finally, there are two action statements which, when executed,
98: cause the script to exit.
99: .SH "SCRIPT FILE STATEMENTS"
100: This section describes all of the statements that may appear in script
101: files, except for a few special action statements. Those are described
102: in a later section, ``Overriding Defaults''.
103: .PP
104: Some statements accept one or two arguments, referred to in the
105: following descriptions as
106: .IR int ", " ns ", " str ", or "
107: .IR xstr ", to"
108: indicate whether the argument is an integer, a new state name, a
109: string, or an ``extended string'' (described in a later section).
110: .PP
111: For all statements that accept two arguments, the first is the
112: name of a new state, and the second specifies a condition or
113: reason for changing to the new state.
114: .SS "Termination And Informational Statements"
115: These statements are used to place entries into the Taylor UUCP
116: .I Log
117: file, and to cause
118: .I xchat
119: to exit with successful or failure status. It is also possible to open a
120: separate
121: .I debug
122: log file and control the level of tracing and error reporting that will go
123: into that log file. This is very useful in debugging
124: .I xchat
125: scripts.
126: .br
127: .ta 1.0i 1.5i 2.0i
128: .TP 2.0i
129: .B failed
130: Exit script with ``failed'' status. This causes
131: .I xchat
132: to exit with status 0.
133: .TP 2.0i
134: .B success
135: Exit script with ``success'' status. This causes
136: .I xchat
137: to exit with status 1.
138: .TP 2.0i
139: .BI "log " xstr
140: Send informational message
141: .I xstr
142: to standard error. When used with Taylor UUCP, this is the
143: .I Log
144: file for the
145: .I uucico
146: program.
147: .TP 2.0i
148: .BI "logerr " xstr
149: Send message
150: .I xstr
151: to standard error, with ``ERROR:'' indicator. When used
152: with Taylor UUCP, this is the
153: .I Log
154: file for the
155: .I uucico
156: program.
157: .TP 2.0i
158: .BI "dbgfile " xstr
159: Open script debugging file
160: .I xstr.
161: If
162: .I xstr
163: begins with ``/'', it is assumed to be an absolute path name for the
164: debugging file. If not, then a configuration-dependent default directory
165: path (usually
166: .B "/usr/spool/uucp"
167: ) is prepended to
168: .I xstr.
169: Normally the default path is that of the directory where Taylor UUCP
170: puts its log files.
171: The debugging file is used to capture a detailed log of the data sent
172: and received, errors encountered, and a trace of script execution.
173: The various types of logging are controlled by the
174: .I "debug mask,"
175: described next.
176: .B Note:
177: A new log file is created each time
178: .I xchat
179: runs. Use the
180: .B log
181: and
182: .B loge
183: commands to log
184: continuous information onto standard out, which is connected
185: to the Taylor UUCP
186: .I Log
187: file when
188: .I xchat
189: is run by the Taylor
190: .I uucico.
191: .TP 2.0i
192: .BI "dbgset " int
193: Set the bits specified in
194: .I int
195: in the debugging mask. The value in
196: .I int
197: is ``or''ed into the mask. Set bit 0 (value \= 1) for error messages,
198: bit 1 (value \= 2) for dial, login and init errors, bit 2 (value \= 4)
199: for dial, login and init trace with character I/O, and bit 3 (value \= 8)
200: for script processing internals. Normally, you will just turn it all on
201: with a value of 15.
202: .TP 2.0i
203: .BI "dbgclr " int
204: Clear the bits specified in
205: .I int
206: from the debugging mask.
207: .TP 2.0i
208: .BI "debug " xstr
209: Write
210: .I
211: xstr
212: into the debug log. The entry will be enclosed in angle brackets.
213: .TP 2.0i
214: .BI "debuge " xstr
215: Write
216: .I xstr
217: into the debug log with ``ERROR: '' prepended. The entry will be enclosed
218: in angle brackets.
219: .SS "Sending Data"
220: These statements are used to transmit data to standard out (the tty or TCP
221: port when used with Taylor UUCP).
222: .I
223: No implied carriage returns are sent.
224: You must include a \\r if you want a carriage return in the string
225: sent by the
226: .B send
227: command. If you want a return sent after
228: .B dial
229: or
230: .B sendstr,
231: you must send it with a separate
232: .B send
233: command.
234: .TP 2.0i
235: .B dial
236: Send the string previously set by the
237: .B telno
238: command to the serial port.
239: .B W
240: and
241: .B P
242: characters in the phone number are
243: converted as described under
244: .B
245: Dial Strings,
246: below. This statement also sets a default
247: timeout value, as described under the
248: .B timeout
249: statement.
250: .TP 2.0i
251: .BI "send " xstr
252: Send the string
253: .I xstr
254: to the serial port.
255: .TP 2.0i
256: .BI "sendstr " int
257: The argument of this statement is a digit from 0
258: through 7. Send the corresponding string
259: parameter as passed to
260: .I xchat
261: following the script file name. The parameter is interpreted
262: as an extended string.
263: .SS "Special Terminal Control Statements"
264: These statements are used to cause the terminal port to perform some special action, or to change the mode of the port.
265: .I
266: The modes of the port are restored to their original settings
267: .I
268: by xchat before it exits.
269: .TP 2.0i
270: .B flush
271: Flush the terminal port's input buffer.
272: .TP 2.0i
273: .B break
274: Send a break signal.
275: .TP 2.0i
276: .B hangup
277: Momentarily drop Data Terminal Ready (DTR) on the
278: serial port, causing the modem to hang up. (Not
279: usually needed, since
280: .I uucico
281: does this at the end of each call.)
282: .TP 2.0i
283: .B 7bit
284: Change the port to strip incoming characters to 7 bits.
285: .I
286: This is the default mode.
287: This mode
288: is implied when the port has parity enabled, since parity characters
289: are 7-bits wide.
290: .TP 2.0i
291: .B 8bit
292: Change the port to allow incoming 8-bit characters to be passed
293: to the script processor. This mode has no effect if parity is
294: enabled, since parity characters are 7-bits wide.
295: .TP 2.0i
296: .B nopar
297: Change the port to 8-bits, no parity.
298: .I
299: This is the default mode.
300: .TP 2.0i
301: .B evenpar
302: Change the port to 7-bits, even parity.
303: .I
304: Incoming characters with parity errors are discarded.
305: .TP 2.0i
306: .B oddpar
307: Change the port to 7-bits, odd parity.
308: .I
309: Incoming characters with parity errors are discarded.
310: .SS "Counting, Branching, Timing and Testing Statements"
311: These statements are used to control the flow of the
312: .I xchat
313: script itself, including branching, delays, and counter manipulation.
314: .TP 2.0i
315: .BI "sleep " int
316: Delay for
317: .I int
318: milliseconds.
319: .TP 2.0i
320: .B zero
321: Clear the counter.
322: .TP 2.0i
323: .B count
324: Add one to the counter.
325: .TP 2.0i
326: .BI "ifgtr " "ns int"
327: Go to state
328: .I ns
329: if counter greater than
330: .I int.
331: .TP 2.0i
332: .BI "goto " ns
333: Go to state
334: .I ns
335: unconditionally.
336: .TP 2.0i
337: .BI "ifstr " "ns int"
338: Go to state
339: .I ns
340: if string parameter
341: .I int
342: is nonempty.
343: .TP 2.0i
344: .BI "ifnstr " "ns int"
345: Go to state
346: .I ns
347: if string parameter
348: .I int
349: is empty.
350: .TP 2.0i
351: .BI "ifblind " ns
352: Change to state
353: .I ns
354: if the port is ``blind'' without carrier (CD) asserted.
355: .I
356: This is not yet implemented, the test always fails.
357: .TP 2.0i
358: .BI "ifblgtr " "ns int"
359: Change to state
360: .I ns
361: if the port is ``blind'' without carrier (CD) asserted, and counter
362: is greater then
363: .I int.
364: .I
365: This is not yet implemented, the test always fails.
366: .SS "Expect Statements"
367: Expect statements are usually the last statements that appear in a
368: given state, though in fact they can appear anywhere within the
369: state. Even if they appear at the beginning, the script processor
370: always does all of the action statements first. As a practical
371: matter, the order of these statements is not significant; they are
372: all interpreted ``in parallel''.
373: .TP 2.0i
374: .BI "expect " "ns xstr"
375: Change to state
376: .I ns
377: if the string specified by
378: .I xstr
379: is received from standard input (usually the serial port).
380: Case is significant, but high-order bits are not
381: checked.
382: .TP 2.0i
383: .BI "ifcarr " ns
384: Change to state
385: .I ns
386: if Carrier Detect (CD) is true.
387: .I
388: Not currently implemented. Always changes state.
389: .TP 2.0i
390: .BI "ifhang " ns
391: Change to state
392: .I ns
393: if a data set hangup occurs (SIGHUP signal received).
394: .TP 2.0i
395: .BI "timeout " "ns int"
396: Change to state
397: .I ns
398: if the time (in milliseconds)
399: given by
400: .I int
401: has elapsed without satisfying any
402: expects. If the time specified is 0, a default
403: timeout value (calculated from the length and
404: other characteristics of the most recent dial
405: string) is used.
406: .SH "SCRIPT PROCESSING DETAILS"
407: .SS "Extended Strings"
408: In the statements that accept string arguments, the strings are
409: interpreted as
410: .I
411: extended strings.
412: Extended strings begin with
413: the first nonblank character and continue, including all imbedded
414: and trailing blanks and other whitespace, until (but not
415: including) the end of the line in the script file. (There is no
416: provision for line continuation.) No trailing spaces should be
417: present between the last ``desired'' character of the string and the
418: end of the line, as they will be included in the stored string and
419: sent or expected, just as they appear in the script file. And,
420: obviously, no trailing comments are permitted! They will just be
421: stored as part of the string.
422: .PP
423: Within an extended string, the following ``escape sequences'' will
424: be converted as indicated before being sent or expected:
425: .br
426: .nf
427: .in +0.5i
428: \fB\\d\fR EOT character (control-D)
429: \fB\\N\fR null character
430: \fB\\n\fR line feed
431: \fB\\r\fR carriage return
432: \fB\\s\fR space
433: \fB\\t\fR tab
434: \fB\\\-\fR hyphen
435: \fB\\\\\fR backslash
436: \fB\\ooo\fR character with value ooo (in octal)
437: .in -0.5i
438: .fi
439: .PP
440: Since extended strings in scripts can include embedded spaces,
441: tabs, etc., these escape sequences are only required in strings
442: appearing in systems entries, though they may be used in script
443: files to improve readability.
444: .PP
445: The octal-character specification (\\ooo) may have from one to
446: three octal digits; it is terminated either after the third digit
447: or when a non-octal character is encountered. But if you want to
448: specify one of these followed by something that happens to be a
449: valid octal character (for example, a control-A followed by a 7)
450: make sure to include all three digits after the \\ . So \\0017
451: would become a control-A followed by the Ascii character ``7'', but
452: \\17 or \\017 would become a control-Y (decimal value 25). \\1S
453: would convert to a control-A followed by an ``S''.
454: .PP
455: Extended strings are stored without a trailing carriage return
456: unless one is explicitly present in the string (via \\r).
457: .SS "String Parameters"
458: The
459: .B sendstr
460: statement sends (after conversion from extended string
461: format) one of the parameters given on the
462: .I xchat
463: command line following the script file name.
464: The parameter is selected by the integer
465: argument of the statement.
466: .PP
467: This allows ``generic'' script files to serve
468: for many different systems; the string parameters
469: provide the phone number, username, password, etc. Character
470: substitutions described under ``extended strings'' above are
471: performed on these strings.
472: .PP
473: The ifstr and ifnstr statements allow further generality in script
474: files, by testing whether a particular parameter is present in the
475: systems entry. For example, a single script can be
476: used both for those systems that require a password and
477: those that do not. The password is specified as the last argument
478: in the
479: .xchat
480: command; the script can test for this
481: parameter's existence and skip the password sequence if
482: the parameter is empty.
483: .SS "``Wait'' And ``Pause'' Characters In Dial Strings"
484: An additional conversion is performed on dial strings. Dial strings
485: are interpreted as extended strings. Then the characters
486: .B W
487: and
488: .B P
489: within a dial string are interpreted as ``wait for dial
490: tone'' and ``pause'', and may be converted to other characters. By
491: default,
492: .B W
493: is left alone, and
494: .B P
495: is converted to a comma (,);
496: these are appropriate for Hayes-type modems. The script may
497: specify other substitutions (see below).
498: .PP
499: .B NOTE:
500: The Taylor UUCP documentation states that the ``wait'' and ``pause''
501: characters are ``='' and ``-'', respectively. These are actual characters
502: understood by some modems. When using
503: .I xchat
504: you should put
505: .B W
506: and
507: .B P
508: in the dial strings you specify in the Taylor configuration files.
509: This way, the
510: .I xchat
511: processor can make the substitution appropriate for the particular
512: modem in use. Make a separate
513: .I xchat
514: script for each modem type, e.g.,
515: .I "dial.hayes"
516: and specify the translation there. This way, the phone number strings
517: in the Taylor configuration files can be used with a variety of modems.
518: .SS "Default Timeouts For Dial Strings"
519: When a
520: .B dial
521: statement is executed, a default timeout value is set.
522: This is the timeout value used by a subsequent timeout statement
523: if the statement specifies a timeout value of 0.
524: .PP
525: The default timeout is given by:
526: .br
527: .nf
528: .in +2
529: \fIctime\fR + (\fIndigits\fR * \fIdgttime\fR) + (\fInwchar\fR * \fIwtime\fR) + (\fInpchar\fR * \fI ptime\fR)
530: .in -2
531: .fi
532: .PP
533: where
534: .I
535: ndigits, nwchar,
536: and
537: .I npchar
538: are the number of digits, wait characters, and pause characters in
539: the dial string, and
540: .I ctime, dgttime, wtime,
541: and
542: .I ptime
543: are 45 seconds, 0.1 seconds, 10 seconds, and 2 seconds,
544: respectively.
545: All of these times may be changed as specified below under
546: ``Overriding Defaults.''
547: .SS "Trailing Carriage Returns Not Assumed"
548: In the
549: .B dial
550: and
551: .B sendstr
552: statements, the dial string or
553: parameter is sent with no trailing carriage return;
554: if a carriage return must be sent after one of these, a separate
555: send statement must provide it.
556: .SH "OVERRIDING DEFAULTS"
557: The script processor sets several default values. The following
558: statements, which override these defaults, may be useful in
559: certain circumstances.
560: .TP 2.0i
561: .BI "chrdly " int
562: Since many modems cannot accept dialing commands
563: at full ``computer speed'', the script processor
564: sends all strings with a brief inter-character
565: delay. This statement specifies the delay time,
566: in milliseconds. The default is 100 (0.1 second).
567: .TP 2.0i
568: .BI "pchar " str
569: Specifies the character to which
570: .BR P s
571: in the
572: dial string should be converted. Default is
573: ``,'', for use with Hayes-type modems.
574: .TP 2.0i
575: .BI "ptime " int
576: Specifies the time, in milliseconds, to allow in
577: the default timeout for each pause character in
578: the dial string. Default is 2000 (2 seconds).
579: .TP 2.0i
580: .BI "wchar " str
581: Specifies the character to which
582: .BR W s
583: in the
584: dial string should be converted. Default is
585: ``W'', for Hayes modems.
586: .TP 2.0i
587: .BI "wtime " int
588: Specifies the time, in milliseconds, to allow in
589: the default timeout for each wait-for-dialtone
590: character in the dial string. Default is 10000
591: (10 seconds).
592: .TP 2.0i
593: .BI "dgttime " int
594: Specifies the time, in milliseconds, to allow in
595: the default timeout for each digit character in
596: the dial string. Default is 100 (0.1 second).
597: .TP 2.0i
598: .BI "ctime " int
599: Specifies the time, in milliseconds, to allow in
600: the default timeout for carrier to appear after
601: the dial string is sent. Default is 45000 (45
602: seconds).
603: .SH "SEE ALSO"
604: uucico(8) for Taylor UUCP, and documentation for Taylor UUCP.
605: .SH AUTHOR
606: Robert B. Denny ([email protected])
607: .SH HISTORY
608: This program is an adaptation of the dial/login script processing
609: code that is a part of DECUS UUCP for VAX/VMS, written by Jamie
610: Hanrahan, et. al.
611: .SH BUGS
612: This version (1.1) does not support BSD terminal facilities. Anyone
613: volunteer to add this?
614:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.