


XC(L)							XC(L)


NNaammee
       xc - communications program

SSyynnttaaxx
       xxcc [--lldevice] [--ssscript | --tt] [--ww ]] [--pp ]]

DDeessccrriippttiioonn
       XXcc  calls  out  over a serial port to another computer. It
       can manage  an  interactive  session  or	be  called  from
       ccrroonn(C).	It  has  various  means  for transferring files
       between computers, and can be partially or  totally  under
       the control of scripts.

       XXcc  starts up by reading the file _x_c_._i_n_i_t, 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 ( for Linux  /usr/local/lib/xc/xc.init  ).
       This  startup  file  may contain any of the valid _S_E_T com-
       mands described below.  XXcc then displays the current  set-
       tings,  and  presents an _<_X_C_> prompt, unless either the --tt
       or --ss option was present.

   _O_p_t_i_o_n_s
       --ll_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/cua1"  or "cua1" 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), xxcc attempts to
		suspend a ggeettttyy(M) process that might be on  that
		line,  and  then use the uuuuccpp(C) _L_C_K_._._f_i_l_e mecha-
		nism to lock the line.

       --ss_s_c_r_i_p_t Execute	the  specified	_s_c_r_i_p_t	after	program
		startup.

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

       --ww	Disables  call	waiting for duration of each con-
		nection.

       --pp	Use pulse dialing instead of touch tone.


   _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 --ll flag, this need  not  be	the  full
       pathname. To set such a variable, in the Bourne shell, you
       might say:

	      MODEM=cua1; export MODEM



								1





XC(L)							XC(L)


       or, in the C shell,

	      setenv MODEM cua1

       If the environment contains a variable  called  "BYEcuax",
       where  "cuax"  stands  for  the basename of the modem line
       selected either by the MODEM variable or by the "-l"  com-
       mand  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:

	      BYEcua1=ATZ ; export BYEcua1

       Whatever string is contained in	the  "Byexxxxx"	variable
       will  be sent to the modem preceded and followed by a car-
       riage-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, ggeettttyy programs which have been suspended, and
       which restart as	xxcc  exits,  will  reset  a  modem  using
       dialers	or	chat   scripts	referred   to	in   the
       /usr/lib/uucp/Devices file.

       Note that under Linux the proper device for call-out is	a
       "cua"  device and *NOT* a "tty" device. A "cua" device can
       point to the same port as a "tty" device	but  the  kernel
       handles	call-out  devices  differently. The "cua" devices
       use a major number of 5 whereas the "tty"  devices  use	a
       major  number  of  4.  If you don't currently have a "cua"
       device in your /dev directory,  you  can	make  them  with
       these commands:

		mknod /dev/cua0 c 5 64 cua0
		mknod /dev/cua1 c 5 65 cua1
		mknod /dev/cua2 c 5 66 cua2
		etc ...
		etc ...

       The  environment	may contain a variable called "XC_PATH",
       consisting of colon separated absolute paths  to	directo-
       ries.	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



								2





XC(L)							XC(L)


       character, as expected.

       An "interpreted" key can be added in a manner  similar  to
       that of vvii(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:

       cc
       cciiss	    Respond  to  an  ENQ  signal  for	a CIS B-Plus protocol
		      transfer. This command is used for  both	uploading  and
		      downloading from CompuServe.

       dd
       ddiiaall	   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.

       ss _f_i_l_e
       ssccrriipptt _f_i_l_e    Execute  _f_i_l_e, which contains appropriate xxcc script com-
		      mands. Returns to terminal mode when the script is  com-
		      plete.

       rrxx _f_i_l_e	(XMODEM  binary  receive)	Receive  _f_i_l_e from the remote
		      system.  Note that packet size and checksum/crc is auto-
		      matically negotiated with the sender. Xc will always try
		      to negotiate crc and 1K byte packet size first.

       ssoo _f_i_l_e	( 1K XMODEM binary send)
       ssxx _f_i_l_e	( 128 byte XMODEM binary send) Send _f_i_l_e to  the	remote
		      system.  Note that for send mode, packet size depends on
		      whether 'so' or 'sx' is invoked.	However,  checksum/crc
		      is  automatically	negotiated  with  the remote. Xc will
		      always try to negotiate crc error checking  first.  When
		      in  'so' mode, if there are fewer than 896 bytes left at
		      the end off a file transmission, packet size will	auto-
		      matically	switch	to  128 bytes to avoid excessive file
		      size padding. Note that 1K XMODEM protocol is  sometimes
		      known as "old YMODEM".

       rrtt _f_i_l_e	(obsolete XMODEM receive mode)
       sstt _f_i_l_e	(obsolete XMODEM send mode) receive/transmit "text" _f_i_l_e
		      from/to the remote system.  This	mode  is  rarely  used
		      nowadays	and  should be avoided. Unix systems generally
		      make no distinction between "binary" and	"text"	files.
		      Use 'rx' or 'so' or 'sx' instead.

       sseett [_o_p_t_i_o_n_s]  Display  or  set the transmission parameters used by xxcc.
		      See below.

       tt
       tteerrmm	   Enter terminal mode.




								3





XC(L)							XC(L)



       xx
       qq
       eexxiitt
       qquuiitt	   Exit program. Return to invoking program/shell.

       hh
       hhaanngguupp	 Hang-up the modem.

       %%pp _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.

       %%tt _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.

       ??
       hheellpp	   Displays	a  brief  summary  of  xxcc  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 xxcc.]

       !! _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.)	Note:	this  is  usually  used  when
		      invoking	external  protocols  such as rz/sz ZMODEM from
		      the command line (i.e. "$ sz foobar.tar.gz").

   _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 xxcc's tun-
       able  parameters.  Any  of these commands may be placed in
       the _._x_c file which is read upon starting up xxcc.

       Used alone, _S_E_T displays xxcc'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):






								4





XC(L)							XC(L)


       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 xxcc  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 "XXCCAAPPEE FF"	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.







								5





XC(L)							XC(L)


       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 XXCCAAPPEE 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. You probably want this set 'off' if
			 you have rts/cts flow control enabled. See next entry.

       set rtscts on|off Enable your comm port to use hardware flow control. If
			 you select this option, you must also tell your  modem
			 to use rts/cts too. See your modem manual for details.
			 Generally, this is the preferred method of  flow  con-
			 trol.

       set del2bs on|off Because the Linux backspace key does not actually send
			 the backspace character but '177'  (delete  character)
			 instead, XC can trap it and translate it to its proper
			 value if you issue the command "set  del2bs  on".   If
			 you  issue the command "set del2bs off", the backspace
			 key will echo '177' the DEL character.	Normally  this
			 is  only  of interest when connecting to a VAX machine
			 which usually prefers the delete character. Most  pub-
			 lic  dial-in  services	and  BBS  prefer the backspace
			 charcter (^H). Enable this by 'set del2bs on'.

       set msdos on|off	Sets translation of ASCII characters from  the	MS-DOS
			 screen codes to LINUX screen codes. Set this mode "on"
			 when connected to DOS BBSs.  Note that LINUX does  not
			 support  all the special characters and symbols avail-
			 able under MS-DOS. Where  no  exact  match  is	avail-
			 able,	the  best  possible  substitution is made. Note
			 that under LINUX that special characters can be  typed
			 by holding down the <alt> key and typing another regu-
			 lar key. For example, typing <alt> <i> on  a  US  key-
			 board will produce an accented e', <alt> <I> will pro-
			 duced an accented E'.




								6





XC(L)							XC(L)



       set autozm on|off This option enables or disables the  automatic	recep-
			 tion  of  files via the ZMODEM protocol. You must also
			 set the proper command string using the 'zmcmd' option
			 below.

       set zmcmd command Use  this option to specify the command line used when
			 xc automatically invokes your external ZMODEM	receive
			 protocol, for example "set zmcmd rz -v".

   _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.

       XXCCAAPPEE  is  a  key  that will, when typed in terminal mode,
       introduce an xxcc "escape" command. Don't confuse XXCCAAPPEE with
       the  <ESCAPE>  key.   The  default definition for XXCCAAPPEE is
       ASCII 1, or Control-A. It can be	redefined  at	run  time
       with the "set escape _C" command (or it can be redefined in
       the _._x_c startup script).

       When the XXCCAAPPEE 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 character is sent to
       the modem. Thus, to send the XXCCAAPPEE character  through  the
       modem, it is necessary to press the key TWICE.

       Thus  the ESCAPE key itself would be a terrible choice for
       XXCCAAPPEE, because it is used so often by other  programs:  if
       you were logged into a remote system and running, say, vvii,
       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 xxcc scripts.

       Command	Function      Description

       XXCCAAPPEE //	Help	  Display the table of bound keys
       XXCCAAPPEE ??	Help	  Display the table of bound keys

       XXCCAAPPEE bb	_BREAK	 Send a MODEM BREAK signal (a sustained null).

       XXCCAAPPEE dd	_Directory     Display the phone directory.

       XXCCAAPPEE ff	_File	  Send a file through the modem (ASCII transfer).

       XXCCAAPPEE ss	_Script	XXcc will request the name of a script to execute.




								7





XC(L)							XC(L)



       XXCCAAPPEE hh	_Hangup	Tell the modem to go on-hook.

       XXCCAAPPEE oo	Graphics _Off  Clear  vt102  graphics  mode.   If line noise or
			      some other phenomenon puts you in graphics  mode
			      (weird  characters  being	displayed  instead of
			      plain text), use this command to toggle back  to
			      normal  text mode. Note that previously diplayed
			      text is unaffected. Only subsequent text will be
			      affected.

       XXCCAAPPEE yy	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.

       XXCCAAPPEE nn	Capture _No    Close the capture file. If  it  wasn't  open,  a
			      message of regret is printed.

       XXCCAAPPEE xx	e_Xit	  Exit terminal mode back to _<_X_C_> command mode.

       XXCCAAPPEE qq	_Quit	  Quit xxcc altogether.

   _P_h_o_n_e_l_i_s_t
       XXcc  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 com-
       mand, 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 charac-
		   ters 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



								8





XC(L)							XC(L)


		   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 xxcc 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 aawwkk(C) program does for those experienced in the
       C language: an aawwkk script LOOKS	like  C,  but  it  isn't,
       really;	and  in	the  same way, an xxcc 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 xxcc script language, but  only
       as an analogy.

       An  xxcc  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	semicolon  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 command terminator (in
       other words, a quoted string cannot contain a newline).

       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	xxcc  script  language  keywords, which are
	  listed below, with appropriate explanations.




								9





XC(L)							XC(L)


       *  A number, meaning a sequence consisting only of digits,
	  with an optional leading minus sign to indicate a nega-
	  tive 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 back-
	  slash ('\"'); when the string is interpreted, the back-
	  slash	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 xxcc 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 characters long, or else it will be truncated to its
	  first 80 characters.	Similarly,  such  an  environment
	  variable should not contain a newline.

       *  An expression surrounded by back-quotation marks ('`').
	  This sort  of	expression  operates  similarly  to  the
	  Bourne shell's command-substitution mechanism: the con-
	  tents of the	back-quotes  are  passed  to  the  Bourne
	  shell,  and the standard output of the back-quoted com-
	  mand 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 charac-
	  ters 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	identifying  the
	  bound	key as "65" or as "97" will always bind _b_o_t_h "a"



							       10





XC(L)							XC(L)


	  and "A" to the same command.

       Quoted literal strings (and the two other mechanisms  that
       act  like  quoted literal strings, shell environment vari-
       ables 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 characters, is considered to be a
       syntax error.

       User variables are created with the 'assign'  script  key-
       word,  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 variable. The
       value  of  any  user  variable can be changed with another
       'assign' command, and numeric variables can be changed  to
       string  variables  and vice-versa. Shell environment vari-
       ables cannot be changed within an xxcc script, but the value
       of  a shell environment variable can be assigned to a user
       variable, and the value of the user  variable  can  there-
       after be changed.

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

       With all this said, the following list of xxcc  script  lan-
       guage   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  evaluating	conditional  expressions.
	   The	string	must  be  terminated by a newline or car-
	   riage-return.




							       11





XC(L)							XC(L)


	   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 variable; 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 vari-
	   ables  is  unlikely.	All  variables are global across
	   scripts that run at the same time via the 'call'  key-
	   word,  and  all variables vanish when a script, called
	   directly from xxcc 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.  Successive
	   'assigns' are permissible, and the type of  the  vari-
	   able	changes  according to the type of the value fol-
	   lowing "eq". A user variable	is  destroyed	with  the
	   'unassign' keyword.

	   If  a  variable is assigned the value of a script com-
	   mand, 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



							       12





XC(L)							XC(L)


	       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 xxcc 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	interac-
	   tively)
	       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 func-
	   tion 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



							       13





XC(L)							XC(L)


	   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 XXCCAAPPEE ^^RR will ask for some file name(s),  and
	   start an sszz command on the remote system, and an rrzz 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 XXCCAAPPEE ^^SS will ask for some file name(s),  and
	   then	launch sszz on the current system.  SSzz will itself
	   start an rrzz 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 examined 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  xxcc  script language



							       14





XC(L)							XC(L)


	   'break' does not take a numeric argument.  Don't  con-
	   fuse	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 script-
	   name must be a quoted literal string. There is  no  xxcc
	   analogue  of the Bourne shell "exec" command; all sub-
	   scripts in xxcc are treated as sub-routines.  All  vari-
	   ables  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 cannot be changed  by  any
	   xxcc 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 "XXCCAAPPEE YY" 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  'con-
	   tinue'  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 xxcc	will  make  many
	   parenthetical  comments about what it's doing while it
	   runs the script. These comments can sometimes be help-
	   ful	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 excite-
	   ment-level of  any  colleagues  collected  circa  your
	   screen.



							       15





XC(L)							XC(L)


       _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 termi-
	   nal. The number of arguments is optional, except  that
	   the	total  result may not exceed 80 characters. Vari-
	   ables 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 terminate a script prema-
	   turely.

       _f_a_l_s_e
	   Syntax: false

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

	   Example:

	       if waitfor "CONNECT" 30 eq false



							       16





XC(L)							XC(L)


	       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, pro-
	   vided 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>; other-
	   wise,  if <list3> is specified, performs <list3>; then
	   resumes execution immediately  following  'endif'.  To
	   accommodate	those  whose  minds  wander while writing



							       17





XC(L)							XC(L)


	   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 regard-
	   less of the value of any of its component commands.

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

	   For	conditional  evaluation	in 'if' and 'while' con-
	   structions, 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  <var-
	   name1>  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 evalu-
	   ates to FALSE. Because environment variables and back-
	   quoted  shell  commands  are	treated as if their out-
	   put/value were quoted  literal  strings,  this  allows
	   direct testing 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  <var-
	   name1>  is  not equal to that of a specified string or
	   numeric constant or of  a  specified	second	variable



							       18





XC(L)							XC(L)


	   name.  Comparing  a string variable to a numeric vari-
	   able, 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  <var-
	   name1>  is  less  than  that	of a specified string or
	   numeric constant or of  a  specified	second	variable
	   name.  String variables are compared lexically accord-
	   ing 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 variable '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



							       19





XC(L)							XC(L)


	   if  the current script has been invoked from the dial-
	   ing 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  SEC-
	   ONDS. Identical to Unix "sleep."

       _p_i_p_e
	   Syntax: pipe "<shell-command>"

	   The	standard  input and standard output of the speci-
	   fied shell command 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 sys-
	   tem.


       _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 differ-
	   ent 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



							       20





XC(L)							XC(L)


       _q_u_i_t
	   Syntax: quit

	   Exits the script and terminates xxcc entirely. Any  LCK-
	   file will be removed if possible and the user's termi-
	   nal will be restored to the state it was  in	when  xxcc
	   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 variable 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 'waitfor' pro-
	   cessing. If no <number> is  specified,  then	all  the
	   characters  received	during the most recent 'waitfor'
	   command are examined, up to a  maximum  of  2048.  The
	   'seen' buffer is reset at the beginning of each 'wait-
	   for' 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 <xxcc-set-option> <value>

	   This	command is the same as the command-mode xxcc '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.



							       21





XC(L)							XC(L)


	   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 xxcc 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 nega-
	   tive, nothing happens.

	   Expiration of the specified timeout	causes	the  most
	   deeply nested script to exit, not to terminate xxcc.  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'



							       22





XC(L)							XC(L)


	   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 preceded 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 xxcc terminal-mode "send ASCII file"
	   escape.





							       23





XC(L)							XC(L)


       _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 vari-
	   able	names	are  considered to be xxcc 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 quota-
	   tion marks. The scanning continues for  the	specified
	   <number>  of	SECONDS or until the specified 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  <num-
	   ber>	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 corre-
	   sponding 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"



							       24





XC(L)							XC(L)


	   within  a current script, and if during 'waitfor' pro-
	   cessing a CIS B-Plus protocol file transfer request is
	   received,  then  the	B-Plus protocol transfer is per-
	   formed, 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 executed	repeatedly  so	long  as  <list1>
	   evaluates as TRUE. All the conditional 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
       XXcc provides several internal file transfer  protocols  and
       supports	external  protocols  such  as ZMODEM. This Linux
       version of xxcc  can  automatically  recognize  the  trigger
       string  for  a ZMODEM download and invoke rz to handle the
       transfer. You must use the 'set' command to have this fea-
       ture  enabled  (either use 'set' at the command line or in
       your xc.init). By default these	are  pre-set  at  compile
       time.

	      set zmcmd rz -y
	      set autozm on

       There  are  several  options for the rz command. The above
       '-y' tells rz to	overwrite  existing  files.  Familiarize
       yourself	with the other options by invoking rz or sz with
       the '-h' flag. To send files via ZMODEM you must	use  the
       xxcc  command  line.  From terminal mode, ^A x will bring up
       the xxcc command prompt. From there you can enter you ZMODEM
       command:

	       $ sz foobar.tar.Z

       Note  the '$'. This tells xxcc to attach 'sz' to the current
       modem port in use by xxcc..	Some  more  recent  versions  of
       rz/sz  have  this  feature crippled. The versions of rz/sz
       provided with this package work properly. The versions  of
       rz/sz  which  open the port directly should be avoided. By
       the way, rz can be invoked from the command line in  simi-
       lar  fashion,  but  DON'T specify the file name because it
       will be in the header provided by the sender on the  other



							       25





XC(L)							XC(L)


       end. Here are some examples:

	     $ rz      /* simple invocation */
	     $ rz -y   /* overwrite existing file */
	     $ rz -v   /* verbose */
	     $ rz -yv  /* verbose and overwrite existing file */

       When  transferring  files  using	the XMODEM protocol, the
       file mode is specified in the upload/download command. The
       main  modes for the XMODEM transfers are 1K packets or 128
       byte packets deternined by the commands "ro" and "so"  for
       the  former,  and "rx" and "sx" for the latter. In actual-
       lity, as implemented here, "rx" and "ro" are identical  as
       the packet size is automatically determined by the sender.
       XMODEM will automatically receive the packet  size  speci-
       fied by the sender, whereas the receiver always determines
       whether CRC or CHECKSUM	error  detection  is  used.  When
       available, xxcc will always negotiate a CRC transfer.

       Use  of the send "so" and "sx" send commands require a bit
       more attention.	The "so" command will try to negotiate an
       'old'  YMODEM transfer of 1K byte packets. If the receiver
       is unable to receive 1K packets xxcc attempts to recover  by
       falling	back  to  128 byte packets. If the negotiation is
       successful, xxcc will transfer 1K byte packets.  If  at  the
       end  of	the transfer there are less that 896 bytes in the
       final packet, xxcc will automatically  switch  to	128  byte
       size  so	as avoid padding the file with extraneous bytes.
       The "sx" command will only send 128 byte packets as speci-
       fied  in	the  original XMODEM specifiacation. As with the
       receive commands,  CRC  or  CHECKSUM  error  detection  is
       determined  automatically and will always revert to CRC if
       available. Note that  for  speed	of  transfer,	1-K  byte
       packet size is better.

       When  transferring files using CompuServe B-Plus protocol,
       the format of the file is specified by the host. An  ASCII
       mode  will  force  xxcc  to perform 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,
       xxcc 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
       checksum of the bytes that you already have  in	the  file
       matches	CompuServe's  checksum	on  the	the same initial



							       26





XC(L)							XC(L)


       bytes in its version of the file, file transfer will  pro-
       ceed 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	xxcc  script  lan-
       guage,  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 direc-
       tory, 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 pro-
       ceed. 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,  cciissddoowwnnllooaadd provided with the distribu-
       tion, can automatically retrieve a single file from a Com-
       puServe library.

       For  XMODEM,  YMODEM,  and  ZMODEM  transfers via scripts,
       there's no mechanism built into the xxcc script language  to
       use  the built-in, 128-byte-packet XMODEM in xxcc.	Instead,
       we strongly recommend that  you	obtain	Chuck  Forsberg's
       excellent, shareware utility called "RZSZ", which can han-
       dle XMODEM, XMODEM-1K, YMODEM, and  ZMODEM  transfers  and
       which  can be used from within xxcc with the 'pipe' command,
       or from command mode with the '$' command,  or  using  the
       examples under the _b_i_n_d___s_c_r_i_p_t command above.



							       27





XC(L)							XC(L)


EExxiitt CCooddeess
       00  Successful, uneventful completion.

       11  Error in command-line arguments.

       22  Failure in forking to execute a command or run a shell.

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

       44  Inability to create a LCK..file for the specified port.

       55  Inability to open the specified port.

       66  No environment variable TERM has been set.

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

       88  Problem caused by the 'ungetty' program.

CCccppyyrriigghhtt
       XXcc and its source files and sample scripts and manual page
       are Copyright 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 xxccoommmm, the xxcc 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.

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

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














							       28


