XC(L)				  XENIX/UNIX		      (printed 4/13/93)

Name
	xc - communications program

Syntax
	xxxxcccc [----lllldevice] [----ssssscript	| ----tttt]

Description
	XXXXcccc calls out over a serial port	to another computer. It	can manage an
	interactive session or be called from ccccrrrroooonnnn(C).	It has various means
	for transferring files between computers, and can be partially or
	totally	under the control of scripts.

	XXXXcccc starts up by	reading	the file ._x_c, which is sought for in this
	order: in "XC_PATH", in	the current directory, in your _H_O_M_E directory,
	or in a	default	directory defined at compile time. This	startup	file
	may contain any	of the valid _S_E_T commands described below. XXXXcccc then
	displays the current settings, and presents an <_X_C> prompt, unless
	either the ----tttt or ----ssss option was present.

   _O_p_t_i_o_n_s
	----llll_d_e_v_i_c_e Use the specified _d_e_v_i_c_e, which need not be the full pathname,
		 e.g. "/dev/tty1A" or "tty1A" are equally acceptable.  The line
		 could either be directly connected to another computer, or
		 have a	modem on it. In	either case (if	a value	was defined for
		 DIDO at compile time),	xxxxcccc attempts to suspend a ggggeeeettttttttyyyy(M) pro-
		 cess that might be on that line, and then use the uuuuuuuuccccpppp(C)
		 _L_C_K.._f_i_l_e mechanism to	lock the line.

	----ssss_s_c_r_i_p_t Execute the specified _s_c_r_i_p_t after program startup.

	----tttt	 Go directly to	terminal mode. The default is to go to command
		 mode on program startup. This option is incompatible with the
		 ----ssss option.

   _E_n_v_i_r_o_n_m_e_n_t
	If the environment contains a variable called "MODEM", then the	value
	of that	variable will be the default device. As	with the ----llll flag, this
	need not be the	full pathname. To set such a variable, in the Bourne
	shell, you might say:

		MODEM=tty01; export MODEM

	or, in the C shell,

		setenv MODEM tty01

	If the environment contains a variable called "BYEttyxx", where	"ttyxx"
	stands for the basename	of the modem line selected either by the MODEM
	variable or by the "-l"	command	option,	then the value of that variable
	will be	sent to	the modem when the program terminates. This is useful
	for setting the	modem back to some preselected state. Example:

		BYEtty01=ATZ ; export BYEtty01

	Whatever string	is contained in	the "Byexxxxx" variable	will be	sent to
	the modem preceded and followed	by a carriage-return.

	Newer modems can be preset to revert to	a predetermined	state when the
	DTR signal of the computer is dropped, and so would not	need to	avail
	themselves of this feature. Furthermore, ggggeeeettttttttyyyy programs	which have been
	suspended, and which restart as	xxxxcccc exits, will reset a modem using
	dialers	or chat	scripts	referred to in the /usr/lib/uucp/Devices file.

	The environment	may contain a variable called "XC_PATH", consisting of
	colon separated	absolute paths to directories. If this variable	is set
	to, say, "/usr/joe/xc:/usr/lib/xc", then those two directories are the
	first places searched for any scripts.


   _C_o_m_m_a_n_d _M_o_d_e
	When entering characters in command mode (that is, at the <_X_C> prompt),
	control	characters echo	as ^x, where "x" is the	control	character that
	was entered. Backspacing (using	whatever key is	defined	in the current
	environment) backspaces	over both positions of the displayed control
	character, as expected.

	An "interpreted" key can be added in a manner similar to that of vvvviiii(C);
	simply type ^V followed	by the character to insert (backspace, delete,
	carriage return, or newline).

	The following commands are available at	the <_X_C> command prompt:

	cccc
	cccciiiissss	       Respond to an ENQ signal	for a CIS B-Plus protocol
		       transfer. This command is used for both uploading and
		       downloading from	CompuServe.

	dddd
	ddddiiiiaaaallll	       Enter the dial directory. Returns to the	<_X_C> prompt if
		       exited without dialing, but returns to terminal mode
		       after dialing or	running	a script.

	ssss _f_i_l_e
	ssssccccrrrriiiipppptttt _f_i_l_e    Execute _f_i_l_e, which contains appropriate	xxxxcccc script com-
		       mands. Returns to terminal mode when the	script is com-
		       plete.

	rrrrbbbb _f_i_l_e	       (XMODEM binary receive)
	rrrrtttt _f_i_l_e	       (XMODEM text receive) Receive _f_i_l_e from the remote sys-
		       tem.

	ssssbbbb _f_i_l_e	       (XMODEM binary send)
	sssstttt _f_i_l_e	       (XMODEM text send) Transmit _f_i_l_e	to the remote system.

	sssseeeetttt [_o_p_t_i_o_n_s]  Display or set the transmission parameters used by xxxxcccc.
		       See below.

	tttt
	tttteeeerrrrmmmm	       Enter terminal mode.

	xxxx
	qqqq
	eeeexxxxiiiitttt
	qqqquuuuiiiitttt	       Exit program. Return to invoking	program/shell.

	hhhh
	hhhhaaaannnngggguuuupppp	       Hang-up the modem.

	%%%%pppp _l_o_c_a_l__n_a_m_e  [_r_e_m_o_t_e__n_a_m_e] Transmit (put) a file to a	remote Unix
		       system. This command uses standard Unix utilities on the
		       other end. _R_e_m_o_t_e__n_a_m_e defaults to the same pathname as
		       _l_o_c_a_l__n_a_m_e if not otherwise specified.

	%%%%tttt _r_e_m_o_t_e__n_a_m_e [_l_o_c_a_l__n_a_m_e] Receive (take) a file from a remote	Unix
		       system. This command uses standard Unix utilities on the
		       other end. _L_o_c_a_l__n_a_m_e defaults to the same pathname as
		       _r_e_m_o_t_e__n_a_m_e if not otherwise specified.

	????

	hhhheeeellllpppp	       Displays	a brief	summary	of xxxxcccc commands,	the SET
		       options,	and terminal-escape commands.

	[Note: a compile-time option can disable the following three options to
	prevent	any access to shells or	other programs outside of xxxxcccc.]

	!!!! _c_o_m_m_a_n_d      Execute the specified _c_o_m_m_a_n_d as	a child	process. If
		       _c_o_m_m_a_n_d is omitted, execute a local interactive shell.
		       (A space	is required between the	!!!! and the _c_o_m_m_a_n_d.)

	!!!!!!!!	       Re-execute the last shell command string.

	$$$$ _c_o_m_m_a_n_d      Execute a shell _c_o_m_m_a_n_d with stdin and stdout redirected
		       to the modem port. This effectively puts	the computer
		       into a "host" mode.  (A space is	required between the $$$$
		       and the _c_o_m_m_a_n_d.)

   _U_s_i_n_g _t_h_e _S_E_T _C_o_m_m_a_n_d
	The _S_E_T	command	is used	to display and set/reset xxxxcccc's tunable parame-
	ters. Any of these commands may	be placed in the ._x_c file which	is read
	upon starting up xxxxcccc.

	Used alone, _S_E_T	displays xxxxcccc's current parameters.

	The following parameters can be	set (note that except in the case of
	_n_a_m_es, these commands are case-_i_nsensitive, and	that there alternative
	forms of the commands shown on the XC help screen):

	set auto on|off	 Sets the auto-capture feature.	When entering terminal
			 mode, capturing commences without the necessity to
			 manually request it.

	set bps	_v_a_l_u_e
	set baud _v_a_l_u_e	 Set the desired bits/second rate. Supported bps rates
			 are 300, 1200,	2400, 9600 (and, if included at	compile
			 time, 19200 and 38400).

	set cfile _n_a_m_e	 Set the _n_a_m_e of the capture file.

	set cis	on|off	 Set response to a CompuServe file transfer request
			 (<ENQ>). An "on" value	specifies that when in terminal
			 mode, an <ENQ>	character will launch a	CIS B-Plus pro-
			 tocol transfer. This parameter	should be set "off"
			 when not connecting to	CompuServe, as phone line noise
			 may cause a bogus file	transfer request.

	set cr on|off	 In uploads using B-Plus protocol, setting this	option
			 "on" will insert a carriage-return after each newline
			 in an ASCII file. If you expect your ASCII upload to
			 be captured by	DOS users, it is best to set cr	"on".
			 If your ASCII upload is meant strictly	for Unix users,
			 then you may set cr "off".  The B-Plus	protocol imple-
			 mentation used	by xxxxcccc will always strip	end-of-line
			 carriage-returns from incoming	ASCII files.

	set hdplx on|off Sets the half-duplex flag. If this flag is set, then
			 all characters	typed at the keyboard while in terminal
			 mode will be echoed to	the screen as well as sent to
			 the modem line. Useful	for remote systems that	don't
			 echo characters.






	set menu on|off	 By default, a one-line	menu is	displayed above	the
			 <_X_C> prompt to	remind the user	of options most	fre-
			 quently chosen	at this	point: "[d]ial directory
			 [t]erminal mode [q]uit	[s]cript [?]help".  Setting the
			 option	"off" turns off	this display.

	set nl on|off	 If this option	is set "on", then newlines are sent as
			 carriage-returns. If this option is set "off",	then
			 newlines are sent as newlines (carriage-returns are in
			 any case always sent as carriage-returns).  This
			 option	applies	to input from the keyboard, or from a
			 disk file using the "XXXXCCCCAAAAPPPPEEEE FFFF" facility	or a script
			 "type"	command	(See below).  This option has no effect
			 on built-in XMODEM or B-Plus protocol transmissions,
			 and has no effect on incoming data.

	set pfile _n_a_m_e	 Set the _n_a_m_e of the phone directory.

	set proto _v_a_l_u_e	 This refers to	the serial port	character protocol, not
			 to a file transfer protocol. The possible values are
			 8N1, 7E2, or 7O2, (case insensitive) which respec-
			 tively	set the	modem port to a	character size of 8
			 with no parity, or a character	size of	7 with either
			 even or odd parity. During B-Plus or XMODEM transfers,
			 the port protocol is set to 8N, and reverts to	its
			 prior setting thereafter.

	set xcape _c_h_a_r
	set escape _c_h_a_r	 Set the XXXXCCCCAAAAPPPPEEEE character (see below) to	_c_h_a_r. This
			 should	be set to some non-printing character (other
			 than backspace, tab, newline, of course).  The	charac-
			 ter may be entered by depressing the Control key first
			 and then typing a letter, or by typing	a carat	(^)
			 followed by a letter.

	set xon	on|off
	set xoff on|off	 Set XON/XOFF flow control flag. If "on", the program
			 will honor the	XOFF control character and wait	until
			 an XON	character is received before transmitting any
			 more information. If "off", the program will ignore
			 XOFF/XON requests.

   _T_e_r_m_i_n_a_l _M_o_d_e
	In terminal mode, all characters typed at the keyboard are sent	to the
	modem, except that newline characters (0x0A) are translated to
	carriage-returns (0x0D)	when you have "set nl 'on'"; all characters
	received from the modem	are displayed on the local terminal screen.

	XXXXCCCCAAAAPPPPEEEE is a key that will, when typed in	terminal mode, introduce an xxxxcccc
	"escape" command. Don't	confuse	XXXXCCCCAAAAPPPPEEEE with the <ESCAPE>	key.  The
	default	definition for XXXXCCCCAAAAPPPPEEEE is	ASCII 1, or Control-A. It can be rede-
	fined at run time with the "set	escape _C" command (or it can be	rede-
	fined in the ._x_c startup script).

	When the XXXXCCCCAAAAPPPPEEEE key is typed in terminal	mode, the program will examine
	the next key pressed. If this key has been "bound" to perform a	certain
	function, that function	will be	performed; otherwise, the second char-
	acter is sent to the modem. Thus, to send the XXXXCCCCAAAAPPPPEEEE character through
	the modem, it is necessary to press the	key TWICE.

	Thus the ESCAPE	key itself would be a terrible choice for XXXXCCCCAAAAPPPPEEEE,
	because	it is used so often by other programs: if you were logged into
	a remote system	and running, say, vvvviiii, it would be a great annoyance to
	have to	hit ESCAPE twice to get	it transmitted once.

	The following keys (case _i_nsensitive) are bound	at startup time. Others
	may be added through the binding commands available in xxxxcccc scripts.

	Command	 Function     Description

	XXXXCCCCAAAAPPPPEEEE ////	 Help	      Display the table	of bound keys
	XXXXCCCCAAAAPPPPEEEE ????	 Help	      Display the table	of bound keys

	XXXXCCCCAAAAPPPPEEEE bbbb	 _BREAK	      Send a MODEM BREAK signal	(a sustained null).

	XXXXCCCCAAAAPPPPEEEE dddd	 _Directory    Display the phone	directory.

	XXXXCCCCAAAAPPPPEEEE ffff	 _File	      Send a file through the modem (ASCII transfer).

	XXXXCCCCAAAAPPPPEEEE ssss	 _Script	      XXXXcccc will request the name of a script to execute.

	XXXXCCCCAAAAPPPPEEEE hhhh	 _Hangup	      Tell the modem to	go on-hook.

	XXXXCCCCAAAAPPPPEEEE yyyy	 Capture _Yes  Open the capture file in APPEND mode (text
			      received over the	port accumulates at the	end of
			      the file). If the	file is	already	open, a	mes-
			      sage is printed to that effect.

	XXXXCCCCAAAAPPPPEEEE nnnn	 Capture _No   Close the	capture	file. If it wasn't open, a
			      message of regret	is printed.

	XXXXCCCCAAAAPPPPEEEE xxxx	 e_Xit	      Exit terminal mode back to _<_X_C_> command mode.

	XXXXCCCCAAAAPPPPEEEE qqqq	 _Quit	      Quit xxxxcccc altogether.

   _P_h_o_n_e_l_i_s_t
	XXXXcccc looks for a ._p_h_o_n_e_l_i_s_t file in the following	order: in the current
	directory, in your home	directory as defined by	the $HOME environment
	variable, or in	the LIBDIR as defined at compile time in _x_c._h. However
	in command mode, any filename can be substituted, using	the SET	PFILE
	command, so long as it has the following characteristics:

	It is ASCII text (lines	of text	separated by newlines).

	The first field	of data	in each	line (after any	whitespace and up to
	the next occurence of whitespace) is a phone number in a valid format
	for the	modem being used.

	Descriptive text may follow the	phone number. Spaces may be included in
	this text, but a <TAB> must terminate this text.

	The following three definitions	may then follow	in any order:

	PROTO=sss   (sss=7e2|7o2|8n1) Set the serial port protocol for 7-bit
		    characters with either even	or odd parity and two stop
		    bits, or for 8-bit characters with no parity and one stop
		    bit.

	BPS=nnnn    (n=300|1200|2400|9600|19200|38400) Set the bits/second rate
		    to the specified value.

	SCRIPT=file Immediately	after sending the autodial string, execute the
		    script file	specified. (Note that the specified filename is
		    CASE SENSITIVE!)

	The following definition, if used, must	be the LAST field on the line.

	PREFIX=xxxxxxxx	(e.g., PREFIX=ATs110=0s111=0)

	The PREFIX="string" allows you send your modem a different setup string
	for each situation (default: no	special	setup).	This is	helpful	for MNP
	and Telebit modems which require special attention for contacting non-
	MNP modems and other Telebits.

   _S_c_r_i_p_t_s
	The xxxxcccc script language is intended to be closely similar to the	Unix
	Bourne shell language. Unfortunately, it isn't identical to the	Bourne
	shell, so it has the same problem that the aaaawwwwkkkk(C) program does for
	those experienced in the C language: an	aaaawwwwkkkk script LOOKS like C, but it
	isn't, really; and in the same way, an xxxxcccc script LOOKS like a Bourne
	shell script, but isn't. So the	operation of the Bourne	shell, if
	you're familiar	with it, is useful as an analogy in understanding the
	xxxxcccc script language, but	only as	an analogy.

	An xxxxcccc script consists of lists of commands. Commands are set off from
	each other within a list by either a newline ('\n') or a semicolon (;),
	as is the case with the	Bourne shell. The semicolon and	the newline
	have identical effect as command separators, so	(anticipating a	bit
	here) you could	say either

	    if counter morethan	5
	    then
	       transmit	"bye^M"
	       quit
	    endif

	or

	    if counter morethan	5; then	transmit "bye^M"; quit;	endif

	and the	result will be the same	either way. The	newline	and the	semi-
	colon are treated the same way as in the Bourne	shell, except that a
	newline	cannot be quoted so as to remove its interpretation as a com-
	mand terminator	(in other words, a quoted string cannot	contain	a new-
	line).

	Commands are composed of _w_o_r_ds separated by spaces or tab characters,
	and a _w_o_r_d can be one of the following:

	*  One of the xxxxcccc script	language keywords, which are listed below, with
	   appropriate explanations.

	*  A number, meaning a sequence	consisting only	of digits, with	an
	   optional leading minus sign to indicate a negative number.

	*  A literal string of characters surrounded by	double-quotation marks
	   ('"'); such a string	can be no longer than 80 characters. A double-
	   quotation mark can be imbedded within the string by preceding it
	   with	a backslash ('\"'); when the string is interpreted, the
	   backslash is	disregarded and	the double-quotation mark is treated as
	   part	of the string. Mismatched quotation marks result in a syntax
	   error.

	*  The name of a user variable,	which can have either a	string or a
	   numeric value.  The name of a user variable must begin with an
	   alphabetic character.

	*  The name of a shell environment variable, preceded by a dollar sign
	   ('$'). The xxxxcccc script	language examines the Unix environment for the
	   specified variable and, if such a variable exists, substitutes the
	   value of that variable. The result is treated as if it were a quoted
	   literal string, and,	therefore, should not be more than 80 charac-
	   ters	long, or else it will be truncated to its first	80 characters.
	   Similarly, such an environment variable should not contain a	new-
	   line.

	*  An expression surrounded by back-quotation marks ('`'). This	sort of
	   expression operates similarly to the	Bourne shell's command-substi-
	   tution mechanism: the contents of the back-quotes are passed	to the
	   Bourne shell, and the standard output of the	back-quoted command is
	   treated as if it were a quoted literal string. Therefore, the
	   command's output should not be more than 80 characters long,	nor
	   contain a newline. Also, the	contents of the	back-quotes cannot be
	   longer than 80 characters, nor contain a newline.

	*  An expression introduced by a pound-sign (or	number-sign: '#'),
	   which is treated as a comment. All characters from the '#' until the
	   end of the physical line are	ignored. This comment mechanism	is the
	   same	as in the Bourne shell.

	*  A limitation	of the script language is that only one	character
	   string can be passed	as an argument to any of the script commands.
	   The _b_i_n_d__f_u_n_c_t_i_o_n, _b_i_n_d__s_c_r_i_p_t, and _b_i_n_d__s_t_r_i_n_g commands thus need
	   to use a decimal digit to represent the key that is to be bound. The
	   ASCII value of the the key is employed. As an example, Control-C is
	   identified as 3, Control-Z is 26, the ESCAPE	key is 27, a space is
	   32, the number "1" is 49; letters are case-_i_nsensitive so that iden-
	   tifying the bound key as "65" or as "97" will always	bind _b_o_t_h "a"
	   and "A" to the same command.

	Quoted literal strings (and the	two other mechanisms that act like
	quoted literal strings,	shell environment variables and	back-quoted
	shell commands)	may be up to 80	characters long. All other words must
	be no longer than 16 characters, and are treated case-independently
	(which is to say, uppercase is the same	as lowercase); note, though,
	that the names of shell	environment variables are case-dependent
	(uppercase must	match uppercase	and lowercase must match lowercase),
	because	they are case-dependent	in the shell.

	Any word not recognizable within the foregoing categories is treated as
	the name of a new user variable. Such a	word, if longer	than 16	charac-
	ters, is considered to be a syntax error.

	User variables are created with	the 'assign' script keyword, and may
	have either numeric or string values. The type of a user variable is
	determined by how it's created;	if it's	assigned to a string, it's a
	string variable, and if	it's assigned to a number, it's	a numeric vari-
	able. The value	of any user variable can be changed with another
	'assign' command, and numeric variables	can be changed to string vari-
	ables and vice-versa. Shell environment	variables cannot be changed
	within an xxxxcccc script, but the value of a	shell environment variable can
	be assigned to a user variable,	and the	value of the user variable can
	thereafter be changed.

	Scripts	are contained in ASCII text disk files,	one script to a	file. A
	script can invoke another script as a subroutine with the 'call' key-
	word; up to 5 scripts can be nested in this way	at any single time.

	With all this said, the	following list of xxxxcccc script language commands
	should be comprehensible. The format "<something>" means that a	token,
	or word-type, of the "something" type is meant rather than the literal
	sequence 'something'.

   _S_c_r_i_p_t _L_a_n_g_u_a_g_e _C_o_m_m_a_n_d_s
	Note that all the commands are case-_i_nsensitive!

	_a_f_f_i_r_m
	    Syntax: affirm

	    Reads a string from	the terminal, and returns TRUE if the string
	    begins with	'y' or 'Y'; otherwise, returns FALSE.  Used in evaluat-
	    ing	conditional expressions. The string must be terminated by a
	    newline or carriage-return.

	    Example:

		echo -n	"Continue (y/n)? "
		if affirm
		then
		    continue
		else
		    break
		endif

	_a_s_s_i_g_n
	    Syntax: assign <varname> eq	<number>
		    assign <varname> eq	"string"
		    assign <varname1> eq <varname2>
		    assign <varname> eq	<script-command>

	    Assigns to user variable <varname> the value following "eq"; if
	    that value is a number, then <varname> becomes a numeric user vari-
	    able; if that value	is a string, then <varname> becomes a string
	    user variable. If <varname>	does not already exist as a user vari-
	    able, it is	created. Variable space	is allocated dynamically, but
	    running out	of memory space	for variables is unlikely. All vari-
	    ables are global across scripts that run at	the same time via the
	    'call' keyword, and	all variables vanish when a script, called
	    directly from xxxxcccc as	opposed	to called from another script, exits.
	    In other words, variable values are	not static except during 'call'
	    execution. Variable	names cannot be	longer than 8 characters. Suc-
	    cessive 'assigns' are permissible, and the type of the variable
	    changes according to the type of the value following "eq". A user
	    variable is	destroyed with the 'unassign' keyword.

	    If a variable is assigned the value	of a script command, then it
	    becomes a numeric variable with value TRUE or FALSE, depending on
	    the	status returned	by the script command. If a variable is
	    assigned the value of a back-quoted	command, it becomes a string
	    variable with the value of the first 80 characters of the back-
	    quoted command. If a variable is assigned equal to an environment
	    variable, it becomes a string variable with	the value of the first
	    80 characters of the value of the environment variable.

	    Examples:

		assign numvar eq 5
		assign strvar eq "This variable	is a string"
		assign mydir eq	$HOME
		assign numvar2 eq numvar
		assign strvar2 eq strvar
		assign numvar eq true
		assign today eq	`date`;	echo "today is " today

	_b_e_e_p
	    Syntax: beep

	    Sends a Control-G to the terminal. Useful for alerting the user
	    that some event has	occurred, for example a	CONNECT	after a	lengthy
	    redialing session.

	_b_i_n_d__f_u_n_c_t_i_o_n
	    Syntax: bind_function _c_o_d_e "function"

	    Bind the character identified by the number	specified by _c_o_d_e to
	    the	xxxxcccc builtin function "function".

	    The	"function" may be one of the following (case is	ignored):

		BRKCHAR	 Send modem BREAK signal
		CAPTEND	 Turn off terminal mode	capture
		CAPTYES	 Turn on terminal mode capture
		DIALCHR	 Dial from phonelist
		DIVCHAR	 Send file through modem
		DOSCRPT	 Execute script	file (prompts interactively)
		EMITSTR	 Emit string
		ENDCHAR	 Exit terminal mode
		HLPCHAR	 Display terminal mode key bindings
		HUPCHAR	 Hang up modem
		QUITCHR	 Quit program
		SCRPCHR	 Prompt	for script file

	    Example:

		bind_function 26 "quitchr"

	    This binds Control-Z to quit the XC	program.

	_b_i_n_d__s_c_r_i_p_t
	    Syntax: bind_script	_c_o_d_e "scriptname"

	    Bind the character identified by the number	specified by _c_o_d_e to
	    execute the	script named by	"scriptname".

	    Upon termination of	the script, the	program	will resume terminal
	    mode, unless the "quit" script function was	executed.

	    Examples:

		bind_script 18 "/usr/lib/xc/.rz"

	    This binds Control-R to execute the	script /usr/lib/xc/.rz.	The .rz
	    script supplied with the source code contains:

		tty "on"
		echo -n	"What files are	to be received?	"
		read FILES
		transmit "sz -y	"
		transmit FILES
		transmit "^M"
		echo "Starting ZMODEM Receive (rz -y)"
		pipe "rz -y"

	    Pressing XXXXCCCCAAAAPPPPEEEE ^^^^RRRR will ask for some	file name(s), and start	an sssszzzz
	    command on the remote system, and an rrrrzzzz on the local system	to
	    receive the	file(s).

		bind_script 19 "/usr/lib/xc/.sz"

	    This binds Control-S to execute the	script /usr/lib/xc/.sz.	The .sz
	    script supplied with the source code contains:

		tty "on"
		echo -n	"What files are	to be sent? "
		read FILES
		echo "Starting ZMODEM send (sz -y " FILES ")"
		pipe "sz -y " FILES

	    Pressing XXXXCCCCAAAAPPPPEEEE ^^^^SSSS will ask for some	file name(s), and then launch
	    sssszzzz on the current system.  SSSSzzzz will itself start an rrrrzzzz process on
	    the	remote system.


	_b_i_n_d__s_t_r_i_n_g
	    Syntax: bind_string	_c_o_d_e "string"

	    Bind the character identified by the number	specified by _c_o_d_e to
	    emit the string specified by "string".

	    The	string is sent to the modem untranslated; eg, it is not	exam-
	    ined for embedded terminal mode escapes.

	    Example:

		bind_string 49 "AAATZ^M"

	    This binds "1" to send the sequence	to reset the modem.

	_b_r_e_a_k
	    Syntax: break

	    Exits from the immediately enclosing 'while' loop. Identical to the
	    C language 'break',	and to the Bourne shell	'break'	except that the
	    xxxxcccc script language 'break' does not	take a numeric argument. Don't
	    confuse this with the script keyword 'xmitbrk', which sends	a BREAK
	    signal to the modem	port.

	_c_a_l_l
	    Syntax: call "scriptname"

	    Suspends execution of the current script, and attempts to load and
	    run	the specified scriptname. The scriptname must be a quoted
	    literal string. There is no	xxxxcccc analogue of the Bourne shell	"exec"
	    command; all subscripts in xxxxcccc are treated as sub-routines. All
	    variables are global across	subscripts, so if a subscript changes
	    the	value of a variable, then that change will remain in effect
	    after return to the	parent script. Shell environment variables can-
	    not	be changed by any xxxxcccc script.

	_c_a_p_t_u_r_e
	    Syntax: capture "on"
		    capture "off"

	    Turns the file-capture function on or off. Note that the arguments
	    must be quoted literal strings. Note also that when	the script
	    exits into terminal	mode, the file-capture function	is turned off.
	    If you have	'set auto "on"', then you will begin capturing immedi-
	    ately upon entering, or returning to, terminal mode. If not, then
	    you	must manually type "XXXXCCCCAAAAPPPPEEEE YYYY" to	start capturing	when entering
	    terminal mode.

	_c_o_n_t_i_n_u_e
	    Syntax: continue

	    Resumes execution at the top of the	immediately enclosing 'while'
	    loop.  Identical to	the C language 'continue' instruction, and to
	    the	Bourne shell 'continue'	command	except that no numeric argument
	    is accepted.

	_d_e_b_u_g
	    Syntax: debug "on"
		    debug "off"

	    If the 'debug' option is on, then xxxxcccc will make many	parenthetical
	    comments about what	it's doing while it runs the script. These com-
	    ments can sometimes	be helpful in debugging	script logic. Note that
	    the	argument must be a quoted literal string.

	    While debugging a script containing	a password, turn this option
	    off, then on again,	to reduce the excitement-level of any col-
	    leagues collected circa your screen.

	_d_e_c_r
	    Syntax: decr <numeric-variable>

	    Decrements the value of the	specified numeric user variable	by 1.
	    Useful in controlling loop execution. If the specified variable
	    isn't numeric, or doesn't exist, a syntax error results.

	_d_i_a_l
	    Syntax: dial "number-string"

	    Dials the specified	number,	using modem-command strings defined in
	    xc.h.

	_e_c_h_o
	    Syntax: echo "string" <variable> ...
		    echo -n "string" <variable>	...

	    This command sends its arguments to	the user's terminal. The number
	    of arguments is optional, except that the total result may not
	    exceed 80 characters. Variables and	back-quoted shell commands are
	    expanded as	necessary.

	    If the "-n"	switch is present, then	no carriage-return/newline
	    sequence is	appended to the	output.

	    Examples:

		echo "The time and date	are now	" `date`
		echo "My terminal type is " $TERM
		echo "My terminal type is " $TERM " today."

	    Note that whitespace isn't echoed unless it's part of a quoted
	    literal string.

	_e_x_i_t
	    Syntax: exit

	    Terminates execution of the	current	script.	If a script reaches its
	    end, it exits automatically, so 'exit' is useful mainly to ter-
	    minate a script prematurely.

	_f_a_l_s_e
	    Syntax: false

	    Same as the	Unix 'false' command. Does nothing, but	returns	a FALSE
	    status value. Useful within	conditional expressions.

	    Example:

		if waitfor "CONNECT" 30	eq false
		then
		    quit
		endif

	    Note that above example could be rewritten using the negating
	    modifier "!":

		if ! waitfor "CONNECT" 30
		then
		    quit
		endif

	    and	note too that the "!" must be separated	from its argument by
	    whitespace.

	_f_i_l_e
	    Syntax: file <script-command>

	    The	standard output	of the specified script	command	is sent	to the
	    current capture file. If the "capture" option is not set, then an
	    error message is displayed,	but script execution continues.

	    Examples:

		file echo "--------- CUT HERE ----------"

	    Sends the output of	the 'echo' command to the current capture file,
	    provided that the "capture"	option is now "on".

		file echo `date`

	    Sends a timestamp to the current capture file, provided that the
	    "capture" option is	now "on". The same thing could have been done
	    with

	       file shell "date"


	_h_a_n_g_u_p
	    Syntax: hangup

	    Tells the modem to go on-hook.


	_i_f
	    Syntax: if <list1>;	then <list2>; [	else <list3>; ]	endif

	    If <list1> evaluates as TRUE, performs <list2>; otherwise, if
	    <list3> is specified, performs <list3>; then resumes execution
	    immediately	following 'endif'. To accommodate those	whose minds
	    wander while writing scripts, 'fi' is an acceptable	synonym	for
	    'endif'.

	    Each list may consist of any number	of script commands separated by
	    semicolons or newlines. The	value of <list1> is determined by
	    inclusively	OR'ing the value of each directive in the list,	so that
	    if any of the directives in	<list1>	evaluates as TRUE, then	so will
	    <list1>. <list1> is	performed in its entirety regardless of	the
	    value of any of its	component commands.

	    The	keywords 'then', 'else', and 'endif' (or 'fi') must be immedi-
	    ately preceded by command separators, either a semicolon or	a new-
	    line, just as is the case in the Bourne shell.

	    For	conditional evaluation in 'if' and 'while' constructions, the
	    following comparators are available	in addition to the script
	    directives mentioned elsewhere:

		<varname1> eq "string"
		<varname1> eq <number>
		<varname1> eq <varname2>
		<varname1>
		"string"

	    evaluates as TRUE if the value of user variable <varname1> is the
	    same as that of a specified	string or numeric constant or of a
	    specified second variable name. If the variable name <varname1> is
	    not	followed by anything else, then	the expression evaluates as
	    TRUE if the	variable is numeric and	has a non-zero value, or if the
	    variable is	a string variable and has a non-zero length; otherwise,
	    the	expression evaluates as	FALSE. Comparing a string variable to a
	    numeric variable, or vice-versa, causes a syntax error.

	    If a conditional expression	consists only of a quoted literal
	    string, the	expression evaluates as	TRUE if	the string's length is
	    non-zero, and otherwise evaluates to FALSE.	Because	environment
	    variables and back-quoted shell commands are treated as if their
	    output/value were quoted literal strings, this allows direct test-
	    ing	of a shell command or of an environment	for non-zero length.
	    Nonexistent	environment variables are treated as if	they exist with
	    the	value "" (a string of zero length).

		<varname1> neq "string"
		<varname1> neq <number>
		<varname1> neq <varname2>

	    evaluates as TRUE if the value of user variable <varname1> is not
	    equal to that of a specified string	or numeric constant or of a
	    specified second variable name. Comparing a	string variable	to a
	    numeric variable, or vice-versa, causes a syntax error.

		<varname1> lessthan "string"
		<varname1> lessthan <number>
		<varname1> lessthan <varname2>

	    evaluates as TRUE if the value of user variable <varname1> is less
	    than that of a specified string or numeric constant	or of a	speci-
	    fied second	variable name.	String variables are compared lexically
	    according to ASCII value.

		<varname1> morethan "string"
		<varname1> morethan <number>
		<varname1> morethan <varname2>

	    operates identically to 'lessthan',	except in reverse.

	    The	value of any conditional expression may	be negated by preceding
	    it with an exclamation point followed by a space or	tab.

	    Examples:

		if counter eq 0; then break; endif;
		if var1	eq var2; then echo "identical";	endif
		if counter morethan 20;	then break; endif;
		if counter lessthan 0; then break; endif;
		if ! counter; then echo	"counter is " counter; endif

	    To perform a list if any of	a set of conditions exist:

		if counter morethan 5;
		    counter eq brkvalue;    # a	second comparator
		then break;
		endif;

	    i.e., perform the 'break' directive	if the value of	numeric	user
	    variable 'counter' is greater than the numeric constant 5, or if
	    the	value of 'counter' is equal to that of the user	numeric	vari-
	    able 'brkvalue'.

	_i_n_c_r
	    Syntax: incr <numeric-variable>

	    Increments the value of the	specified numeric user variable	by 1.
	    The	opposite of 'decr'.

	_l_i_n_k_e_d
	    Syntax: linked

	    'linked' is	a pseudo-function that evaluates as TRUE if the	current
	    script has been invoked from the dialing directory,	and as FALSE
	    otherwise.

	    Example:

		if ! linked; then
		    dial "5551212"
		endif

	_p_a_u_s_e
	    Syntax: pause <number>

	    Suspends execution for the specified <number> of SECONDS. Identical
	    to Unix "sleep."

	_p_i_p_e
	    Syntax: pipe "<shell-command>"

	    The	standard input and standard output of the specified shell com-
	    mand are connected to the modem port, and the command is executed.
	    This is the	equivalent of the command mode "$" command.

	    Examples:

		pipe "echo \"\177\""

	    sends a DELETE character to	the modem.

		pipe "rz"

	    performs a file receive via	ZMODEM,	assuming that Chuck Forsberg's
	    'rz/sz' programs reside on your system.


	_p_o_r_t_n_a_m_e
	    Syntax: portname

	    This isn't a command, but a	synonym	for the	current	modem terminal
	    device, treated as if it were a quoted string. Useful if modems of
	    differing types are	attached to different terminal lines and need
	    different dialing or initialization	sequences. To compare the value
	    of 'portname' to some other	string,	you must first assign a	user
	    variable equal to 'portname'.

	    Examples:

		assign myport eq portname
		if myport eq "/dev/tty01"
		then
		    transmit "AT&E0^M"
		endif

	_q_u_i_t
	    Syntax: quit

	    Exits the script and terminates xxxxcccc entirely. Any LCKfile will be
	    removed if possible	and the	user's terminal	will be	restored to the
	    state it was in when xxxxcccc was	invoked.

	_r_e_a_d
	    Syntax: read <variable-name>

	    Takes a string from	the user's keyboard and	places it into the
	    specified user variable. Any previous value	of the specified vari-
	    able is discarded.

	_r_e_d_i_a_l
	    Syntax: redial

	    Redials the	number most recently dialed with the 'dial' command.

	_s_e_e_n
	    Syntax: seen "string" <number>

	    Evaluates as TRUE if "string" has occurred within the last <number>
	    characters received	during the most	recent 'waitfor' command. Only
	    up to 2048 characters are remembered at any	one time during	'wait-
	    for' processing. If	no <number> is specified, then all the charac-
	    ters received during the most recent 'waitfor' command are exam-
	    ined, up to	a maximum of 2048. The 'seen' buffer is	reset at the
	    beginning of each 'waitfor'	command. This is useful	to tell	which
	    of several strings has been	received.

	    Example:

		if waitfor "string1" 20
		then
		    echo "Received 'string1'."
		else
		    if seen "string2"
		    then
			echo "Received 'string2' instead."
		    endif
		endif

	_s_e_t
	    Syntax: set	<xxxxcccc-set-option>	<value>

	    This command is the	same as	the command-mode xxxxcccc 'set' command, such
	    as "set bps	1200", "set cis	on", and so forth, except that a string
	    <value> must be enclosed within double-quotation marks.

	    Examples:

		set cis	"on"
		set cfile "newfilename"
		set auto "on"
		set bps	2400

	_s_h_e_l_l
	    Syntax: shell "<shell-command>"

	    The	shell command enclosed within the double-quotation marks is
	    executed. This is similar to the xxxxcccc	command-mode "!" command.
	    Remember that if the shell command contains	double-quotation marks,
	    they must be escaped with backslashes.

	_t_i_m_e_o_u_t
	    Syntax: timeout <number>

	    If <number>	is greater than	zero, starts a timer which will	cause
	    the	MOST DEEPLY NESTED script to exit when <number>	of MINUTES
	    expire. If <number>	is zero, then any pending timeout is cancelled.
	    If <number>	is negative, nothing happens.

	    Expiration of the specified	timeout	causes the most	deeply nested
	    script to exit, not	to terminate xxxxcccc.  To cause the program to quit
	    if a timeout expires, use a	subscript.

	    Example:

		'script1' contains:

		    call "script2"
		    if expired
		    then
			quit
		    endif
		    # more commands


		'script2' contains:

		    assign expired eq 1
		    timeout 5		# limit	of 5 minutes
		    while ! waitfor "login:" 30
		    do
			xmitbrk
		    done
		    assign expired eq 0
		    exit

	    When 'script2' exits, the numeric variable 'expired' will be set to
	    1 if 'script2' timed out, and will be 0 otherwise. 'script1' can
	    act	on this	information accordingly.

	_t_r_a_n_s_m_i_t
	    Syntax: transmit "string"

	    Sends a string to the modem. The string is sent with brief pauses
	    between characters,	to accommodate modems that cannot accept rapid
	    command input, and within the string, any alphabetic character pre-
	    ceded by a caret (^) is translated to the corresponding Control-
	    character.

	    Example:

		transmit "ATDT 5551212^M"

	    sends the string "ATDT 5551212" to the modem, followed by a
	    carriage-return character.

	_t_r_u_e
	    Syntax: true

	    Does nothing, but always evaluates as TRUE.	Useful in conditional
	    expressions. The opposite of 'false'.

	_t_t_y
	    Syntax: tty	"on"
		    tty	"off"

	    Ordinarily,	during script execution, characters received from the
	    modem port are echoed to the user's	terminal screen. This happens
	    only during	'waitfor' and 'type' execution,	so it may be a bit
	    choppy. This echoing can be	turned off with

		tty "off"

	    and	turned back on with

		tty "on"

	    Note that "on" and "off" must be enclosed in quotation marks.

	_t_y_p_e
	    Syntax: type "<filename>"

	    Sends the specified	ASCII file to the modem	port. This is the same
	    as the xxxxcccc terminal-mode "send ASCII	file" escape.

	_u_n_a_s_s_i_g_n
	    Syntax: unassign <variablename>

	    Erases the specified user variable.	The variable may be either
	    numeric or string type. The	variable name must not be enclosed in
	    quotation marks, because variable names are	considered to be xxxxcccc
	    script keywords, and not literal strings.

	_w_a_i_t_f_o_r
	    Syntax: waitfor "string" <number>

	    Scans input	from the modem port for	an occurrence of the specified
	    string, which must be enclosed in quotation	marks. The scanning
	    continues for the specified	<number> of SECONDS or until the speci-
	    fied string	is identified in the modem input stream, whichever
	    comes first. This command evaluates	as TRUE	if the specified string
	    is found, and as FALSE if the specified <number> of	SECONDS	elapses
	    and	the string isn't found within that time. The default time, if
	    no <number>	is specified, is roughly 30 seconds.

	    String matching is performed on a case-_i_nsensitive basis.  Within
	    the	string,	any alphabetic character preceded by a caret (^) is
	    translated to the corresponding Control-character.

	    Examples:

		assign counter eq 1
		while !	waitfor	"login:" 15
		do
		    xmitbrk; incr counter; if counter morethan 5
		    then
			quit
		    endif
		done

	    If in a CompuServe Forum the "prompt character" has	been set by the
	    user to be a backspace, this test will log off if the main prompt
	    is not seen	in the next sixty seconds:

		if ! waitfor "forum !^H" 60
		then
		    transmit "bye^M"; quit
		endif

	    If the 'cis' option	has been set to	"on", either in	the ._x_c	startup
	    script, or by a direct 'set' command from command mode, or with

		set cis	"on"

	    within a current script, and if during 'waitfor' processing	a CIS
	    B-Plus protocol file transfer request is received, then the	B-Plus
	    protocol transfer is performed, the	<number> argument is reset to
	    its	original value,	and 'waitfor' processing continues. This allows
	    automatic B-Plus protocol file transfers from within a script.

	_w_h_i_l_e
	    Syntax: while <list1>; do <list2>; done

	    Operates similarly to the 'if' command, except that	<list2>	is exe-
	    cuted repeatedly so	long as	<list1>	evaluates as TRUE. All the con-
	    ditional comparators and rules for comparisons that	apply for the
	    'if' command also apply to 'while'.	(Note that 'while' loops can be
	    nested within 'if' commands	and vice-versa.)

	_x_m_i_t_b_r_k
	    Syntax: xmitbrk

	    Sends a BREAK signal to the	modem port.

   _F_i_l_e	_T_r_a_n_s_f_e_r_s
	When transferring files	using the XMODEM protocol, the file mode is
	specified in the upload/download command. A TEXT mode transfer enables
	translation of the transmitted or received file	to support CP/M	and
	MS-DOS end-of-line characters.	When transmitting a file using TEXT
	mode, all newlines are converted to carriage-return/newline sequences.
	When receiving a file using TEXT mode, all carriage-return/newline
	sequences are converted	to just	a newline. A BINARY mode transfer
	transmits the file "as is" without any such conversion.

	When transferring files	using CompuServe B-Plus	protocol, the format of
	the file is specified by the host. An ASCII mode will force xxxxcccc to per-
	form TEXT mode translation; a BINARY mode will not do any translation.
	This means that, in either direction, a	BINARY mode will send bytes "as
	is", whereas in	ASCII mode, an incoming	file will always be stripped of
	end-of-line carriage-returns, while an ASCII file being	uploaded may or
	may not	have carriage-returns added after each newline,	depending on
	the "on" or "off" setting of the "cr" option.

	When using either the "%t" (take) command, an XMODEM receive command,
	or a CompuServe	B-Plus download	command, xxxxcccc will check if the file name
	you specify already exists on your system, and ask for an OK to
	overwrite the file, or for an alternative name.	In the CompuServe case,
	there will also	be an option to	"Resume" a download. If	the CRC	check-
	sum of the bytes that you already have in the file matches CompuServe's
	checksum on the	the same initial bytes in its version of the file, file
	transfer will proceed from that	point onwards. This saves connect time
	when a very large download has been interrupted	during a prior session.

	Script-driven file transfers using the CompuServe B-Plus protocol are
	more or	less built into	the xxxxcccc script language,	since during 'waitfor'
	processing, a file transfer request from the modem port	will trigger a
	B-Plus transfer	if the "cis" mode is set.  The difficulty in performing
	such transfers isn't in	the transfer itself, but rather	in the
	maneuvering required to	get into position to transfer the correct file,
	and is something that probably only experienced	script writers should
	wrestle	with. However, if we assume that in the	midst of a script,
	you've reached a point where you can issue a "download"	command	to Com-
	puServe, for instance a	"Disposition" prompt during a File Library
	"BROWSE" command, and you want to download the present file, which is
	"XCALL.C" on CompuServe, and "xcall.c" does not	exist in your current
	working	directory, you'd use the following sequence of script commands
	to do it:

	    set	cis on	     # can't do	auto file B-Plus transfer otherwise
	    transmit "dow^M"
	    pause 2	     # wait for	CIS to display protocol	menu
	    transmit "6^M"   # B-Plus is number	6 on that menu
	    transmit "xcall.c^M"  # "file name for your	computer:"
	    waitfor "Disposition"

	During the final "waitfor" processing, the CompuServe ENQ character
	will be	recognized and the transfer will proceed automatically.	Then
	'waitfor' will continue	waiting	for the	"Disposition" prompt, after
	which your script can proceed. The same	sort of	thing can be done with
	file uploads, but once again, the difficulty isn't with	the transfer,
	but rather with	setting	things up so that the transfer will be
	requested at the correct place.

	A shell	script,	cccciiiissssddddoooowwwwnnnnllllooooaaaadddd provided with the distribution, can
	automatically retrieve a single	file from a CompuServe library.

	For XMODEM, YMODEM, and	ZMODEM transfers via scripts, there's no
	mechanism built	into the xxxxcccc script language to use the built-in, 128-
	byte-packet XMODEM in xxxxcccc.  Instead, we strongly	recommend that you
	obtain Chuck Forsberg's	excellent, shareware utility called "RZSZ",
	which can handle XMODEM, XMODEM-1K, YMODEM, and	ZMODEM transfers and
	which can be used from within xxxxcccc with the 'pipe' command, or from com-
	mand mode with the '$' command,	or using the examples under the
	_b_i_n_d__s_c_r_i_p_t command above.

Exit Codes
	0000  Successful, uneventful completion.

	1111  Error in command-line arguments.

	2222  Failure in forking to execute a command or run a shell.

	3333  No modem port specified on the command line,	or contained in
	   the environment variable MODEM.

	4444  Inability to	create a LCK..file for the specified port.

	5555  Inability to	open the specified port.

	6666  No environment variable TERM	has been set.

	7777  No entry for	the current TERM setting in /etc/termcap.

	8888  Problem caused by the 'ungetty' program.

Ccpyright
	XXXXcccc and its source files	and sample scripts and manual page are Copy-
	right 1993 by Jean-Pierre Radley.

	Permission is granted to the public to use this	code in	any manner,
	without	any warranty, implied or otherwise, of fitness for a particular
	purpose.

	By virtue of a restriction previously placed upon all code derivative
	from xxxxccccoooommmmmmmm, the	xxxxcccc code	and associated files may not be	sold by	anyone
	to anyone, nor incorporated into any product that is not also free.
	It's OK	to transfer them for free.

Authors
	This manual page was written by	Fred Buck (1989) and Jean-Pierre Radley
	(1990, 1991, 1992, 1993).  XXXXcccc itself is	the product of many synergistic
	wise minds. See	the README document.

Version
	This edition of	the manual is for XC version 4.1 JPRadley 10 April
	1993.













