home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / old / ckermit5a190 / ckvker.hlp < prev    next >
Text File  |  2020-01-01  |  44KB  |  978 lines
  1. 1 KERMIT
  2. Kermit - File transfer, management, and terminal connection
  3.  
  4. Written by:
  5.  
  6.   Frank da Cruz, Columbia University, with contributions from hundreds
  7.   of other volunteer programmers all over the world; (Open)VMS help topic
  8.   by Alan Robiette, Oxford University (UK); Jim Barbour, University of
  9.   Colorado (USA); Christine M. Gianone and Frank da Cruz, Columbia
  10.   University (USA).  All references to VMS apply to both VMS and OpenVMS.
  11.  
  12. Documentation:
  13.  
  14.   C-Kermit 5A is documented in the book "Using C-Kermit" by Frank da Cruz
  15.   and Christine M. Gianone, Digital Press, Burlington, MA, USA.  Digital
  16.   Press ISBN: 1-55558-108-0; Prentice-Hall ISBN: 0-13-037490-3.  Price: US
  17.   $34.95.  In USA, call DECdirect at 1-800-344-4825, refer to order number
  18.   EY-J896E-DP.  Available: January 1993.
  19.  
  20. Format:
  21.  
  22.   KERMIT  [ cmdfile ] [ option(s) ... ] [ file(s) ... ]
  23. 2 COMMANDS
  24. C-Kermit has a large vocabulary of commands; for a summary see the
  25. "COMMAND_LIST" subtopic.  All command can be used either interactively,
  26. i.e.  typed in response to the "C-Kermit>" prompt, or placed in command
  27. files to be executed under the control of Kermit's programming language.
  28.  
  29. The SET and SHOW commands are particularly useful in that they are used
  30. to set and display respectively the many parameters governing Kermit's
  31. communication and file transfer capabilities.
  32. 3 BACKSLASH_NOTATION
  33. Within a command, \ is a special character to help you enter special
  34. quantities, or ordinary characters that would otherwise be illegal
  35. or hard to type.  At the end of a line, \ (backslash) makes the next
  36. line a continuation of the current line.  In all other circumstances
  37. the character following the \ identifies what the special item is:
  38.  
  39.   %          a user-defined simple (scalar) variable
  40.   &          an array reference
  41.   $          an environment variable
  42.   v (or V)   a built-in variable
  43.   m (or M)   a user-defined "long" variable
  44.   f (or F)   a function
  45.   d (or D)   a decimal (base 10) number
  46.   o (or O)   an octal (base 8) number
  47.   x (or X)   a hexadecimal (base 16) number
  48.   \          the backslash character itself
  49.   \b (or \B) the BREAK signal (OUTPUT command only)
  50.   \l (or \L) a long BREAK signal (OUTPUT command only)
  51.   A decimal digit (a 1-3 digit decimal number): see below
  52.   Anything else: following character taken literally
  53.  
  54. Numbers (in decimal, octal or hexadecimal format) turn into the
  55. character with that ASCII code, so you can use \7 for a bell, or
  56. \13 (or, say, \x0D) for a carriage return.
  57. 3 COMMAND_LIST
  58. You can use upper or lower case for commands.  Also, you can
  59. abbreviate commands as long as the abbreviation matches only one
  60. possibility.  This section gives a summary of C-Kermit's commands.
  61. For more information on each, look in the user manual, or online in
  62. SYS$HELP:KERMIT.DOC, or type HELP and then the command name in
  63. response to the "C-Kermit>" prompt.
  64.  
  65. ;              Introduce a full-line or trailing comment (also #).
  66. !              Execute a system command or enter system command
  67.                interpreter (also @).
  68. :              Introduce a label (GOTO target).
  69. ASK            Prompt the user, store user's reply in a variable.
  70. ASKQ           Like ASK, but doesn't echo (useful for passwords).
  71. ASSIGN         Assign an evaluated string to a variable or macro.
  72. BUG            Display instructions for reporting bugs.
  73. BYE            Terminate and log out a remote Kermit server.
  74. CD             Change working directory (also CWD).
  75. CHECK          Check for availability of a given feature.
  76. CLEAR          Clear communication device input buffer.
  77. CLOSE          Close a log or other local file.
  78. COMMENT        Introduce a full-line comment.
  79. CONNECT        Establish a terminal connection to a remote computer.
  80. DECLARE        Declare an array.
  81. DECREMENT      Subtract one (or other number) from a variable.
  82. DEFINE         Define a variable or macro.
  83. DELETE         Delete a file or files.
  84. DIAL           Dial a telephone number.
  85. DIRECTORY      Display a directory listing.
  86. DISABLE        Disallow access to selected features during server
  87.                operation.
  88. DO             Execute a macro.
  89. E-PACKET       Send an Error packet to the other Kermit.
  90. ECHO           Display text on the screen.
  91. ENABLE         Allow access to selected features during server
  92.                operation.
  93. END            End a command file or macro.
  94. EXIT           Exit from the program, closing all open files and
  95.                devices.
  96. FINISH         Instruct a remote Kermit server to exit, but not
  97.                log out.
  98. FOR            Execute commands repeatedly in a counted loop.
  99. GET            Get files from a remote Kermit server.
  100. GETOK          Ask a "yes/no" question (in scripts).
  101. GOTO           Go to a labeled command in a command file or macro.
  102. HANGUP         Hang up the phone or network connection.
  103. HELP           Display a help message for a given command.
  104. IF             Conditionally execute the following command.
  105. INCREMENT      Add one (or other number) to a variable.
  106. INPUT          Match characters from another computer against
  107.                a given text string.
  108. INTRODUCTION   Print a brief introduction to C-Kermit.
  109. LOG            Open a log file - debugging, packet, session, or
  110.                transaction.
  111. MAIL           Send a file as electronic mail to a specified
  112.                address.
  113. MSEND          Send a list of files (multiple send).
  114. MSLEEP         Do nothing for given number of milliseconds.
  115. OPEN           Open a local file for reading or writing.
  116. OUTPUT         Send text to another computer.
  117. PAUSE          Do nothing for a given number of seconds.
  118. PING           Check if an IP host is reachable.
  119. PRINT          Print a file on a local printer.
  120. PUSH           Invoke host system interactive command interpreter.
  121. PWD            Display current working device/directory.
  122. QUIT           Same as EXIT.
  123. READ           Read a line from a local file.
  124. RECEIVE        Passively wait for files to arrive.
  125. REDIAL         Redial the most recently dialed number.
  126. REINPUT        Reexamine text previously received from another
  127.                computer by an INPUT command.
  128. REMOTE         Issue commands to a remote Kermit server.
  129. RENAME         Change the name of a file.
  130. RETURN         Return from a user-defined function.
  131. RUN            Run a program or system command.
  132. SCRIPT         Execute a UUCP-style login script.
  133. SEND           Send files.
  134. SERVER         Begin server operation.
  135. SET            Set various parameters.
  136. SHOW           Display values of SET parameters.
  137. SPACE          Display current disk space usage.
  138. STATISTICS     Display statistics about most recent transaction.
  139. STOP           Stop executing macro or command file and return
  140.                to the prompt.
  141. TAKE           Execute commands from a file.
  142. TELNET         Make a TELNET connection to a TCP/IP host.
  143. TRANSLATE      Translate a file's character set.
  144. TRANSMIT       Upload a file with no error checking.
  145. TYPE           Display a file on the screen.
  146. VERSION        Display the program version number on the screen.
  147. WAIT           Wait for the specified modem signals.
  148. WHILE          Execute commands repeatedly while a condition
  149.                is true.
  150. WHO            Display list of logged in users.
  151. WRITE          Write text to a local file.
  152. XIF            Extended IF command.
  153. 3 SET_Command
  154. Here are the parameters you can change with the SET command.  Note
  155. that some of these parameters require further specification.  E.g.
  156. there are several RECEIVE parameters, so commands using SET RECEIVE
  157. look like "SET RECEIVE PACKET-LENGTH 1000".  For parameters in this
  158. category, the possible options are listed below them.
  159.  
  160. ATTRIBUTES     Turn attribute packet processing on or off.
  161.      ALL, CHARACTER-SET, DATE, DISPOSITION, LENGTH, SYSTEM-ID, TYPE
  162. BLOCK-CHECK    Level of packet error detection.
  163. BUFFERS        Size of send and receive packet buffers.
  164. CARRIER        Treatment of carrier on terminal connections.
  165. CASE           Treatment of alphabetic case in string comparisons.
  166. COMMAND        Command terminal settings, such as BYTESIZE.
  167. COUNT          Initialization of IF COUNT loops.
  168. DEBUG          Log or display debugging information.
  169. DELAY          How long to wait before sending first packet.
  170. DIAL           Set parameters for modem dialing.
  171.      DIAL-COMMENT, DIRECTORY, DISPLAY, HANGUP, INIT-STRING, KERMIT-SPOOF, 
  172.      MNP-ENABLE, MODEM-HANGUP, PREFIX, SPEED-MATCHING, TIMEOUT
  173. DUPLEX         Specify which side echoes during CONNECT.
  174. ESCAPE         Prefix for "escape commands" during CONNECT.
  175. FILE           Set various file parameters.
  176.      BYTESIZE, CHARACTER-SET, COLLISION, DISPLAY, INCOMPLETE,
  177.      LABEL, NAMES, RECORD-LENGTH, TYPE
  178. FLOW-CONTROL   Communication line full-duplex flow control.
  179. HANDSHAKE      Communication line half-duplex turnaround character.
  180. HOST           Specify network host name.
  181. INPUT          Control behavior of INPUT command.
  182.      CASE, ECHO, TIMEOUT-ACTION
  183. KEY            Key mapping during terminal connection.
  184. LANGUAGE       Enable language-specific character-set translations.
  185. LINE           Communication line device name.
  186. MACRO          Control aspects of macro execution.
  187. MODEM-DIALER   Type of modem dialer, such as HAYES.
  188. PARITY         Communication line character parity.
  189. PROMPT         The C-Kermit program's interactive command prompt.
  190. RECEIVE        Parameters for inbound packets.
  191.      END-OF-PACKET, PACKET-LENGTH, PAD-CHARACTER, PADDING,
  192.      START-OF-PACKET, TIMEOUT
  193. RETRY          Packet retransmission limit.
  194. SEND           Parameters for outbound packets.
  195.                See RECEIVE for subparameters.  Normally you need set
  196.                only RECEIVE parameters.  SEND parameters are
  197.                automatically set by the Kermit on the other end.
  198. SERVER         Parameters for server operation.
  199.      DISPLAY, TIMEOUT
  200. SPEED          Communication line speed, e.g. 2400, 9600.
  201. TAKE           Control aspects of TAKE file execution.
  202.      ECHO, ERROR
  203. TELNET         TELNET protocol parameters.
  204. TERMINAL       Terminal parameters.
  205.      BYTESIZE, CHARACTER-SET, LOCKING-SHIFT, NEWLINE-MODE
  206. TRANSFER       File transfer parameters.
  207.      CHARACTER-SET, LOCKING-SHIFT
  208. TRANSMIT       Control aspects of TRANSMIT command execution.
  209.      ECHO, EOF, FILL, LINEFEED, LOCKING-SHIFT, PAUSE, PROMPT
  210. UNKNOWN-CHAR   Specify handling of unknown character sets.
  211. WINDOW-SIZE    File transfer window size.
  212. 3 SHOW_Command
  213. The SHOW command displays the current values of Kermit parameters,
  214. programming constructs etc.  The usage is
  215.  
  216.   SHOW  [ category ]
  217.  
  218. where "category" may be any of the keywords listed below.  SHOW
  219. without any argument gives a summary of the most important
  220. parameters affecting communication and file transfer.  The available
  221. categories are as follows:
  222.  
  223. ARGUMENTS          List of currently-defined macro arguments.
  224. ARRAYS             List of arrays defined.
  225. ATTRIBUTES         Settings (on or off) of individual attributes.
  226. CHARACTER-SETS     Current character-set selections.
  227. COMMUNICATIONS     Settings of line speed, parity etc.
  228. COUNT              Value of COUNT variable
  229. DEFAULT            Default device and directory.
  230. DIAL               Settings for DIAL command.
  231. ESCAPE             Setting of escape character.
  232. FEATURES           C-Kermit configuration features and options.
  233. FILE               Settings for file transfer parameters.
  234. FUNCTIONS          List of built-in functions.
  235. GLOBALS            List of global variables and their values.
  236. KEY                Value assigned to key subsequently pressed.
  237. LABELED-FILE-INFO  Settings of VMS attributes to be encapsulated.
  238. LANGUAGES          Languages available for SET LANGUAGE command.
  239. MACROS             Listings of currently-defined macros.
  240. MODEM              Modem type and modem signals on current LINE.
  241. NETWORK            Available network support and current connection.
  242. PROTOCOL           Packet sizes and other protocol-related data.
  243. SCRIPTS            Settings in force for script processing.
  244. SERVER             Server functions and whether enabled.
  245. STATUS             SUCCESS or FAILURE of last command.
  246. TERMINAL           Settings of terminal bytesize, character set etc.
  247. TRANSMIT           Settings in force for TRANSMIT command.
  248. VARIABLES          List built-in variables and their values.
  249. VERSIONS           Versions of source modules used in compilation.
  250. 2 GENERAL_SYNOPSIS
  251. Kermit is a family of file transfer, management, and telecommunication
  252. programs available on many different computer operating systems and
  253. architectures.  Kermit programs transfer both text and binary files
  254. completely and correctly, and most Kermit programs include dial-out and
  255. terminal connection capability.  This help topic describes version 5A of
  256. C-Kermit, the Kermit program written in C for UNIX, (Open)VMS, and several
  257. other computer systems.
  258.  
  259. Kermit is designed to help you communicate between two computers over
  260. dial-ups and other RS-232 lines, and in some cases also over networks.
  261. Once the connection is established, you can conduct a terminal session
  262. and you can transfer files.  To transfer files, you need to run Kermit
  263. on both computers.
  264.  
  265. Kermit is an "integrated" communications program.  It does the same
  266. thing as separate dial-out programs like CU, tip or VAXNET and file
  267. transfer programs such as Xmodem.  It also has a script language, which
  268. you can use to automate communications tasks.  PC implementations of
  269. Kermit normally have a terminal emulator built in.  The version of
  270. Kermit described in this help topic does not include a terminal emulator
  271. because most systems on which it is used don't need one.
  272.  
  273. Kermit has one major philosophical difference from most file transfer
  274. programs.  With programs such as Xmodem, in order to transfer a file you
  275. have to tell the program on the remote machine to send the file, then
  276. return to your local computer and tell it to receive the file.  For
  277. every file to be sent or received, you must give commands to both
  278. computers.  Kermit can operate in this way too, but an alternative mode
  279. of use allows you to control all operations from your local computer.
  280. In this mode the copy of Kermit on the remote machine acts as a
  281. "server".  Your local computer initiates all operations, sending the
  282. necessary commands to the remote Kermit.  In addition to transferring
  283. files, you can also tell Kermit to execute commands on the server, such
  284. as listing directories, deleting files, and even sending e-mail.
  285.  
  286. Normally you give Kermit commands interactively.  That is, to start
  287. Kermit, simply type the command "KERMIT" with no arguments.  Once Kermit
  288. has started up, it will prompt you for commands.  Kermit's command
  289. interpreter has good built-in help facilities.  If you use the same
  290. command sequences a lot, you can put them into files, and get Kermit to
  291. execute them automatically.  It is also possible to give Kermit commands
  292. by using options on the command line.  The options available are
  293. described in the "Parameters" section of this help topic.
  294.  
  295. Kermit's command language is too extensive to describe completely in a
  296. help topic, although other sections outline many of the facilities
  297. available.  See "Using C-Kermit" for complete documentation.
  298. 2 INITIALIZATION
  299. When C-Kermit starts, it executes commands from its initialization file.
  300. The search for the initialization file proceeds in the following order:
  301.  
  302.  1. If the "-Y" (uppercase) command-line option is given,
  303.     initialization-file processing is skipped.  Otherwise:
  304.  2. The file specified in the "-y" command-line option, if any.
  305.  3. The file CKERMIT_INI:CKERMIT.INI.
  306.  2. The file designated by the logical name CKERMIT_INIT.
  307.  3. The file SYS$LOGIN:CKERMIT.INI.
  308.  
  309. C-Kermit executes those commands before prompting you for interactive
  310. commands.  A typical initialization file might read as follows:
  311.  
  312.   SET RECEIVE PACKET 960
  313.   SET WINDOW 2
  314.   SET BLOCK 3
  315.  
  316. These commands set long packet sizes and a window size of 2 for
  317. receiving files, together with a strengthened checksum which is
  318. recommended for long packets.
  319. 2 KERMIT_HELP
  320. Kermit has extensive built-in help.  You can find out what commands
  321. exist by typing ? in response to the "C-Kermit>" prompt.  For commands
  322. that take multiple arguments, you can type ? wherever an argument is
  323. expected to see the possible choices; e.g. SET has many different
  324. things you can set, an example being SET RECEIVE PACKET-LENGTH 1000.
  325. You can type "SET ?", "SET RECEIVE ?", or "SET RECEIVE PACKET-LENGTH ?"
  326. to see the options available at each level.
  327.  
  328. You can type also HELP followed by the name of a command for fuller
  329. information on it; e.g. "HELP SET" gives information about the "SET"
  330. command in general, "HELP SET RECEIVE" tells about the SET RECEIVE
  331. command.
  332. 2 Command_Line_Options
  333. The full syntax of the KERMIT command is as follows:
  334.  
  335.   KERMIT  [cmdfile] [-x arg [-x arg]...[-yyy]...]] [= arg [arg ...]]
  336.  
  337. where:
  338.  
  339.   cmdfile is an optional command file to be executed after initialization,
  340.     -x  is an option requiring an argument,
  341.     -y  an option with no argument, and
  342.     arg is an argument word.
  343.   Words after the = sign are ignored by the program but made available
  344.   to the user in the array \&@[].
  345.  
  346. C-Kermit is often run without any command-line arguments or with just
  347. a command file, i.e. in one of the simpler variants:
  348.  
  349.   KERMIT
  350.  
  351. or:
  352.  
  353.   KERMIT cmdfile
  354.  
  355. Using this approach any Kermit parameters not set by the initialization
  356. file (see "INITIALIZATION" in this help topic), followed by those in
  357. "cmdfile" if present, may be set using interactive commands.
  358.  
  359. Command-line options provide a further way to set certain parameters
  360. and/or initiate certain actions for that particular invocation of
  361. Kermit.  This can be a useful short-cut in specific cases, e.g.
  362.  
  363.   KERMIT -s *.C
  364.  
  365. will start up Kermit, send all files with a filetype of .C in the
  366. current directory, and then exit.
  367.  
  368. From VMS, type the command "kermit -h" for a list of possible command-
  369. line options.  The principal ones are listed below.  The options are
  370. case-sensitive.  Upper-case options must be enclosed in doublequotes.
  371.  
  372. Settings:
  373.  
  374.   -l device    Communication line device
  375.   -j host      Network host name (if network support included)
  376.   -q           Be Quiet during file transfer
  377.   -i           Binary file transfer
  378.   -b rate      Line speed (baud rate), e.g. 1200, used with -l
  379.   -m name      Modem type, e.g. hayes
  380.   -p x         Parity, x = e, o, m, s, or n
  381.   -t           Half duplex, XON handshake
  382.   -e n         Receive packet length
  383.   -v n         Window size
  384.   -y name      Alternate initialization file name
  385.   -Y           Do not execute initialization file
  386.   -d           Log debug information to DEBUG.LOG
  387.  
  388. Actions:
  389.  
  390.   -s files     Send files
  391.   -s -         Send files from standard input (SYS$INPUT)
  392.   -r           Receive files
  393.   -k           Receive files to standard output (SYS$OUTPUT)
  394.   -x           Enter server mode
  395.   -f           Finish remote server
  396.   -g files     Get remote files from server
  397.   -a name      Alternate file name, used with -s, -r, -g
  398.   -c           Connect (before file transfer, used with -l and -b)
  399.   -n           Connect (after file transfer, used with -l and -b)
  400.   -S           Stay (do not exit after executing action commands)
  401.  
  402. If no action command is included, enter interactive dialog.
  403. 2 SCRIPT_PROGRAMMING
  404. C-Kermit contains a powerful programming language, permitting complex
  405. sequences of Kermit instructions to be executed under the control of a
  406. user-supplied program.  The language features include simple variables,
  407. arrays, control structures, macros, and numeric and algebraic
  408. manipulations of variables including a range of built-in functions.
  409.  
  410. Programmed sequences of commands are stored in regular VMS files.  Such
  411. a program is executed by feeding the file to Kermit's command
  412. interpreter using the TAKE command,
  413.  
  414.   TAKE  command-file
  415.  
  416. The TAKE command may be issued as an interactive command at the
  417. "C-Kermit>" prompt.  In addition, an implicit TAKE command reads the
  418. initialization file when Kermit is started, followed by a further one if
  419. a command file name has been included as a command-line option: thus
  420. either of these files may include program sequences.
  421.  
  422. Command files may themselves contain TAKE commands.  Command files may
  423. be nested in this way to any reasonable depth.
  424. 3 CONTROL_STRUCTURES
  425. Kermit's programming language provides several means for writing
  426. loops and for conditional branching or transfer of control.  The
  427. principal control structures are summarized here.
  428.  
  429. Simple loops are constructed using the FOR command.  FOR loops take
  430. the form
  431.  
  432.   FOR variable iv fv step { command, command, ... }
  433.     The FOR loop is controlled by a loop variable which is assigned
  434.     an initial value (iv), gets tested against a final value (fv),
  435.     and gets incremented by a step value.  If the step value is
  436.     positive, the loop exits when the loop variable is greater than
  437.     the final value.  If the step is negative, the loop exits when
  438.     the variable becomes less than the final value.
  439.  
  440. Conditional actions can be programmed using the IF, XIF ("extended
  441. if") or WHILE commands.  The syntax of these is as follows:
  442.  
  443.   IF [NOT] condition command1
  444.   [ELSE command2]
  445.  
  446.   XIF condition { command1, command2... } [ ELSE { command3, ... } ]
  447.  
  448.   WHILE condition { command1, command2... }
  449.  
  450. The simple IF can only execute one command if the condition is true;
  451. similarly the optional ELSE on the following line can only control
  452. one command.  XIF and its optional ELSE clause typically has
  453. multiple commands enclosed in the braces, as does the WHILE form of
  454. loop.  The XIF..[ELSE] and WHILE structures are each logically
  455. written all on one line, but may be spread over more than one actual
  456. line by use of the line continuation character - (hyphen).
  457.  
  458. The conditions for which it is possible to test, illustrated in the
  459. context of the IF command, are as follows:
  460.  
  461.   IF SUCCESS
  462.       The previous command succeeded.
  463.  
  464.   IF FAILURE
  465.       The previous command failed.
  466.  
  467.   IF DEFINED name
  468.       The named variable or macro is defined.
  469.  
  470.   IF COUNT
  471.       Subtract one from COUNT, execute the command if the result is
  472.       greater than zero (COUNT is a special variable used for simple
  473.       counted loops, initialized by SET COUNT).
  474.  
  475.   IF EXIST filename
  476.       The named file exists.
  477.  
  478.   IF NUMERIC variable
  479.       The variable's value is numeric.
  480.  
  481.   IF EQUAL s1 s2
  482.       s1 and s2 (character strings or string variables) are equal.
  483.  
  484.   IF LLT s1 s2
  485.       s1 is lexically (alphabetically) less than s2.  Use IF NOT LGT
  486.       for less-than-or-equal.
  487.  
  488.   IF LGT s1 s1
  489.       s1 is lexically (alphabetically) greater than s2.  Use IF NOT
  490.       LLT for greater-than-or-equal.
  491.  
  492.   IF = n1 n2
  493.       n1 and n2 (numbers or numeric variables) are equal.
  494.  
  495.   IF < n1 n2
  496.       n1 is arithmetically less than n2. Use IF NOT > for
  497.       less-than-or-equal.
  498.  
  499.   IF > n1 n2
  500.       n1 is arithmetically greater than n2\n.  Use IF NOT < for
  501.       greater-than-or-equal.
  502.  
  503. Various commands exist to transfer control to another part of the
  504. program.  These are often used in conjunction with a conditional of
  505. some nature.  Examples are
  506.  
  507.   GOTO label   Transfers control to the point in the program marked
  508.                by "label".  A label is a string preceded by a colon
  509.                (:) at the beginning of a line, thus
  510.  
  511.        IF < \x% 10 GOTO LESS
  512.           .
  513.           .
  514.        :LESS
  515.  
  516.   STOP         Stops execution of the program and returns control to
  517.                C-Kermit.
  518.  
  519.   END          Exits from a macro or command file, and returns to the 
  520.                point from which the macro or file was called (also 
  521.                RETURN, see documentation for details).
  522.  
  523.   BREAK        Exits unconditionally from closest enclosing FOR or
  524.                WHILE loop.
  525.  
  526.   CONTINUE     Forces jump to next iteration (if any) of closest
  527.                enclosing FOR or WHILE loop.
  528. 3 EXPRESSIONS
  529. The \Feval function allows the following operators in the
  530. expression to be evaluated.  The expression can use variables
  531. beginning with \%.  Syntax, precedences etc. are shown below:
  532.  
  533. Operator  Fix  Precedence   Operation         Example
  534.  
  535.  (   )             1        Group             (\%a + 3) * (\%1 - 5)
  536.    !      Post     2        Factorial         \%x! - (\%x - 2)!
  537.    ~      Pre      3        Logical NOT       ~\%n
  538.    -      Pre      3        Negative          -\%n
  539.    ^      In       4        Raise to power    2^\%p
  540.    *      In       5        Multiply          \%c * 5
  541.    /      In       5        Divide            \%c / 5
  542.    %      In       5        Modulus           \%c % 5
  543.    &      In       5        Logical AND       \%c & 5
  544.    +      In       6        Add               \%t + \%u
  545.    -      In       6        Subtract          127 - \%x
  546.    |      In       6        Logical OR        \%z | 4
  547.    #      In       6        Exclusive OR      \%z # 4
  548.    @      In       6        Greatest common   \%z @ 30
  549.                                divisor
  550. 3 FILE_HANDLING
  551. Kermit programs can read from and write to local files.  The
  552. relevant commands are OPEN, CLOSE, READ and WRITE.  The use of these
  553. is as follows:
  554.  
  555.   OPEN mode filename
  556.        "Mode" can be READ, WRITE or APPEND.  !READ and !WRITE are
  557.        also allowed; the meaning of these is to read from or write
  558.        to a VMS command rather than a physical file.  E.g. OPEN READ
  559.        KERMIT.DOC opens the (real) file KERMIT.DOC for reading,
  560.        while OPEN !READ DIR *.TXT requests the directory listing of
  561.        files with filetype .TXT as input.
  562.  
  563.   CLOSE mode
  564.        E.g. CLOSE READ, CLOSE WRITE etc.  Closes the file or
  565.        input/output stream defined by the mode name.
  566.  
  567.   READ variable-name
  568.        Reads a line of the file or command output, defined by the
  569.        OPEN READ or OPEN !READ statement, into the variable
  570.        specified.
  571.  
  572.   WRITE destination text-expression
  573.        Writes the information generated by "text-expression" to the
  574.        specified destination.  "Destination" may be FILE, which
  575.        writes to the file or output stream opened for writing by the
  576.        appropriate OPEN statement, but may also be any of the four
  577.        possible log files (DEBUG-LOG, PACKET-LOG, SESSION-LOG or
  578.        TRANSACTION-LOG).  "Text-expression" may contain text,
  579.        variable names, functions, expressions etc. and is evaluated
  580.        before writing.
  581. 3 FUNCTIONS
  582. A range of built-in functions is provided in C-Kermit.  These are
  583. invoked via the general syntax \Fname(args).  From within C-Kermit
  584. they can be listed via the command SHOW FUNCTIONS.
  585.  
  586.   \Fliteral(arg)     copy argument literally, no evaluation
  587.   \Fcharacter(arg)   return the character corresponding to
  588.                      number or numeric variable arg
  589.   \Fcode(arg)        return numeric code of character arg
  590.   \Fsubstr(a1,a2,a3) substring of a1, starting at a2, length a3
  591.   \Fright(a1,a2)     rightmost a2 characters of string a1
  592.   \Flower(arg)       convert to lower case
  593.   \Fupper(arg)       convert to upper case
  594.   \Freverse(arg)     reverse characters in string arg
  595.   \Frepeat(a1,a2)    repeat a1 a2 times
  596.   \Flpad(text,n,c)   left pad text to length n with char c
  597.   \Frpad(text,n,c)   right pad text to length n with char c
  598.   \Fexecute(m a)     execute macro named "m" with given
  599.                      parameters "a"
  600.   \Fcontents(v)      return current definition of variable
  601.   \Fdefinition(m)    return current definition of macro
  602.   \Flength(arg)      return the length of the string "arg"
  603.   \Findex(a1,a2,a3)  position of a2 in string a1, starting
  604.                      at position a3
  605.   \Ffiles(spec)      number of files matching file specification
  606.   \Fnextfile()       next file name from list in last \Ffiles
  607.   \Fmax(a1,a2)       maximum of two numbers
  608.   \Fmin(a1,a2)       minimum of two numbers
  609.   \Feval(expr)       evaluate arithmetic expression
  610. 3 MACROS
  611. C-Kermit allows macros.  A macro is a command that you define,
  612. composed of one or more other C-Kermit commands.  A typical macro is
  613. a list of Kermit commands, separated by commas.  For example:
  614.  
  615.   DEFINE SUN SET SPEED 9600, SET PARITY NONE, SET DUPLEX FULL,-
  616.   SET FLOW XON/XOFF
  617.  
  618. You call a macro by using its name, just like a normal command.  You
  619. can also call a macro using the DO command.  If you have given the
  620. DEFINE command above (or have it in your initialization file), then
  621. you can type SUN or DO SUN to execute all the commands in the
  622. definition.
  623.  
  624. Macros have normal names (i.e. not beginning with \).  You call them
  625. by using the name like a command.  If you put additional words on
  626. the same line as the macro invocation, these become arguments.
  627. Inside the macro, you can refer to the arguments as \%1, \%2, etc.
  628. For example:
  629.  
  630.   C-Kermit>DEFINE BSEND SET FILE TYPE BINARY, SEND \%1
  631.   C-Kermit>DEFINE TSEND SET FILE TYPE TEXT, SEND \%1
  632.   C-Kermit>BSEND KERMIT.EXE
  633.   C-Kermit>TSEND KERMIT.DOC
  634.  
  635. The number of arguments supplied can be referred to as \v(argc).  If
  636. you call another macro from a macro, the new one gets its own set of
  637. arguments, which do not interfere with the previous set.
  638. 3 TERMINAL_DIALOG
  639. The interactive command CONNECT and the escape sequence Ctrl-\ C,
  640. which normally switch the console terminal between the two
  641. computers, cannot be used in a scripted sequence.  Instead there are
  642. two commands, INPUT and OUTPUT, which control the dialog in the
  643. script context, supplemented by a few other commands.  Brief details
  644. are as follows:
  645.  
  646. OUTPUT text
  647.     Send the text to the other computer.
  648.  
  649. INPUT timeout text
  650.     Read responses from the other computer.  Wait up to "timeout"
  651.     seconds for the specified text to appear.  If the text appears
  652.     within the timeout interval, the command succeeds immediately.
  653.     Otherwise it fails.  Test with IF SUCCESS or IF FAILURE.
  654.  
  655. REINPUT timeout text
  656.     Searches previous responses from the computer for the given
  657.     text.  The timeout parameter is ignored.
  658.  
  659. ECHO [ text ]
  660.     Display the text on the local screen, followed by a newline.
  661.  
  662. CLEAR { INPUT, DEVICE, BOTH }
  663.     Clear any as-yet-unread characters from the communication
  664.     device's input buffer, the INPUT command buffer, or both.
  665.  
  666. PAUSE [ n ]
  667.     Do nothing for the indicated number of seconds, the default
  668.     being 1.
  669.  
  670. For further details of these and related commands, see the full
  671. documentation, "Using C-Kermit".  A special case of programmed terminal
  672. dialog, intended mainly for UUCP-style login sequences, is provided by
  673. the SCRIPT command.
  674. 4 SCRIPT_Command
  675. SCRIPT is a concise method for specifying a dialog between your system
  676. and another one.  There is also a more powerful general purpose script
  677. programming language, whose commands are described elsewhere in this
  678. help topic.  The SCRIPT command can be used for dialing, logging in,
  679. etc.  The syntax consists of strings separated by spaces.  The syntax is
  680.  
  681.   SCRIPT  expect send [expect send] . . .
  682.  
  683. Kermit waits until it sees the expect string, and then sends the send
  684. string.  If there are several pairs, it waits for each expect string,
  685. and then sends the send string.  (To specify a null expect string, i.e.
  686. to tell Kermit not to wait, use ~0 as the expect string.)  It normally
  687. waits up to 15 seconds for each expect string.  However ~w can be used
  688. to redefine this time.  If the expect string does not arrive, the script
  689. fails at that point.  If you want to be able to do something about
  690. failure, you can use conditional strings, of the form
  691.  
  692.   -send-expect[-send-expect[...]]
  693.  
  694. You can think of this as giving a list of things to try.  The first time
  695. one succeeds (i.e. an expected string arrives), the command terminates.
  696. At that point Kermit skips to the end of the dashed sequence.  If an
  697. expect fails, Kermit simply proceeds with the next send in the dashed
  698. sequence.
  699.  
  700. Within the strings, some special sequences can be used:
  701.  
  702.   ~b         backspace
  703.   ~s         space
  704.   ~q         `?' (trapped by Kermit's command interpreter)
  705.   ~n         linefeed
  706.   ~r         carriage return
  707.   ~t         tab
  708.   ~'         single quote
  709.   ~-         dash (hyphen)
  710.   ~~         tilde
  711.   ~"         double quote
  712.   ~x         XON (Control-Q)
  713.   ~c         don't append a carriage return
  714.   ~o[o[o]]   octal representation of an ASCII character code
  715.   ~d         delay approx 1/3 second during send
  716.   ~w[d[d]]   set wait for next expect to "dd" seconds
  717.   \\b        send a BREAK signal
  718.  
  719. Kermit sends a carriage return after each of the send strings
  720. unless the string has a ~c.
  721. 3 VARIABLES
  722. C-Kermit also lets you define variables.  Normal variables look like
  723. \%i, where i is a single letter.  The alphabetic case doesn't matter,
  724. i.e. \%a and \%A are the same variable.  Like macros, they are defined
  725. by DEFINE or ASSIGN.  All values are strings.  DEFINE gives a variable a
  726. fixed value.  ASSIGN computes a value and assigns it to the variable. To
  727. see the difference, look at
  728.  
  729.   DEFINE \%A Monday
  730.   DEFINE \%B Today is \%A
  731.   ASSIGN \%C Today is \%A
  732.   DEFINE \%A Tuesday
  733.   ECHO \%B
  734.   ECHO \%C
  735.  
  736. This will print "Today is Tuesday" then "Today is Monday".  The
  737. difference is that when defining \%C, the \%A is evaluated at the time
  738. of the definition, whereas when defining \%B, the variable name \%A
  739. itself is put in the definition.  It isn't evaluated until the command
  740. "ECHO \%B" is obeyed.
  741.  
  742. There are also arrays, which use \& instead of \%.  They are declared by
  743. DECLARE, e.g. DECLARE \&A[100].  Elements are referenced with
  744. subscripts, which may themselves be variables, and act like simple
  745. variables, e.g.
  746.  
  747.   DEFINE \&A[3] Tuesday
  748.  
  749. The first subscript of an array is [1].  You can destroy the array
  750. by making it zero size, e.g. DECLARE \&A[0].
  751. 4 PREDEFINED
  752. There are a number of built-in variables, which are referred to by
  753. \v(name).  They cannot be changed by the user.  To list these from
  754. within C-Kermit give the command SHOW VARIABLES.  Descriptions are given
  755. below.
  756.  
  757. \v(argc)       number of arguments passed to currently active macro.
  758. \v(args)       number of arguments passed to the program on the
  759.                command line.  The program argument vector is
  760.                assigned to the array \&@[].
  761. \v(cmdfile)    name of currently active command file, if any
  762. \v(cmdlevel)   current command level (command stack depth)
  763. \v(cmdsource)  source of current commands: prompt, macro, or file
  764. \v(count)      current value of COUNT (loop control via SET
  765.                COUNT, IF COUNT).
  766. \v(cpu)        CPU hardware type, if known, otherwise "unknown".
  767. \v(date)       current date in dd mmm yyyy format (e.g.  8 Feb 1992).
  768. \v(day)        current day of the week, e.g. Mon, Tue, Wed.
  769. \v(directory)  current device and/or directory.
  770. \v(exitstatus) current program exit status.
  771. \v(filespec)   file specification from most recent SEND, MSEND,
  772.                or GET command, or the name of the file most
  773.                recently received.
  774. \v(fsize)      size of last file transferred.
  775. \v(home)       user's home (login) directory name.
  776. \v(host)       local computer's hostname.
  777. \v(input)      current INPUT buffer contents.
  778. \v(line)       current communication device or network host name.
  779. \v(local)      1 if C-Kermit in local mode, 0 if in remote mode.
  780. \v(macro)      name of currently executing macro, if any.
  781. \v(ndate)      current date in numeric format, e.g. 19911225.
  782. \v(nday)       numeric day of the week: 0, 1, 2, ..., 6.
  783. \v(ntime)      current time in seconds since midnight, 0 through
  784.                86399.
  785. \v(platform)   name of specific machine or environment for which
  786.                C-Kermit was built.
  787. \v(program)    name of program (C-Kermit).
  788. \v(return)     value of most recent RETURN command.
  789. \v(speed)      transmission speed of current communication
  790.                device, if known.  (A spurious value of 38400
  791.                might be reported for pseudoterminals.)
  792. \v(status)     0 if the previous command succeeded, nonzero if
  793.                it failed.
  794. \v(system)     name of generic operating system for which
  795.                C-Kermit was built, such as UNIX or VMS.
  796. \v(tfsize)     total size of all files in the last group of
  797.                files that was transferred.
  798. \v(time)       current time in hh:mm:ss 24-hour clock format
  799.                (e.g. 13:45:23).
  800. \v(version)    numeric version number of C-Kermit.
  801. 2 TRANSFERRING_FILES
  802. To transfer files, Kermit must be run on both of the computers involved.
  803. Transfers may be carried out either by controlling both computers
  804. directly, or by putting one of them into "server" mode and controlling
  805. operations entirely from the other.
  806.  
  807. In the first method, one computer is given a SEND command, and the
  808. other with a corresponding RECEIVE command.  The user switches control
  809. from one computer to the other using:
  810.  
  811. (a) the CONNECT command - this switches control from the "local" system
  812.     (usually, but not necessarily, the microcomputer or workstation on
  813.     the user's desktop) to the "remote" system; and
  814.  
  815. (b) the "escape sequence" - this switches control from the remote system
  816.     back to the local system.  The escape sequence is normally Ctrl-\ C
  817.     (Control-backslash followed by "C") for C-Kermit, but Alt-X or
  818.     Ctrl-] C (Control-] followed by "C") for MS-DOS or OS/2 Kermit.
  819.  
  820. The second method using one of the Kermits as a server is described in
  821. the "SERVER_USAGE" sub-topic.
  822. 3 CHARACTER_SETS
  823. C-Kermit has the ability to send, receive and store files in a wide
  824. range of 7-bit and 8-bit character sets, including many which are
  825. designed for languages other than English.  Two character sets have to
  826. be distinguished: that which applies to the file as stored under VMS,
  827. and that used "on the wire" (i.e. the communications line or network
  828. connection) during file transfer.  These are set via the commands "SET
  829. FILE CHARACTER-SET" and "SET TRANSFER CHARACTER-SET" respectively.
  830.  
  831. The possible arguments for the SET FILE CHARACTER-SET command are:
  832.  
  833.  Name                   Bits   Script
  834.   ASCII                   7     Roman
  835.   BRITISH                 7     Roman
  836.   CANADIAN-FRENCH         7     Roman
  837.   CP437                   8     Roman, West European multinational
  838.   CP850                   8     Roman, West European multinational
  839.   CP852                   8     Roman, East European multinational
  840.   CP866-CYRILLIC          8     Cyrillic
  841.   CYRILLIC-ISO            8     Cyrillic
  842.   DANISH                  7     Roman
  843.   DEC-KANJI              16     Japanese
  844.   DEC-MULTINATIONAL       8     Roman, West European multinational
  845.   DG-INTERNATIONAL        8     Roman, West European multinational
  846.   DUTCH                   7     Roman
  847.   FINNISH                 7     Roman
  848.   FRENCH                  7     Roman
  849.   GERMAN                  7     Roman
  850.   HUNGARIAN               7     Roman
  851.   ITALIAN                 7     Roman
  852.   JAPANESE-EUC           16     Japanese
  853.   JIS7-KANJI             16     Japanese
  854.   KOI8-CYRILLIC           8     Cyrillic
  855.   LATIN1-ISO              8     Roman, West European multinational
  856.   LATIN2-ISO              8     Roman, East European multinational
  857.   MACINTOSH-LATIN         8     Roman, West European multinational
  858.   NEXT-MULTINATIONAL      8     Roman, West European multinational
  859.   NORWEGIAN               7     Roman
  860.   PORTUGUESE              7     Roman
  861.   SHIFT-JIS-KANJI        16     Japanese
  862.   SHORT-KOI               7     Cyrillic
  863.   SPANISH                 7     Roman
  864.   SWEDISH                 7     Roman
  865.   SWISS                   7     Roman
  866.  
  867. The possible arguments for the SET TRANSFER CHARACTER-SET command
  868. are:
  869.  
  870.  Name                   Bits   Script
  871.   ASCII                   7     Roman
  872.   CYRILLIC-ISO            8     Cyrllic
  873.   JAPANESE-EUC           16     Japanese
  874.   LATIN1-ISO              8     Roman, West European Multinational
  875.   LATIN2-ISO              8     Roman, East European Multinational
  876.   TRANSPARENT 
  877.  
  878. where TRANSPARENT (the default) implies that no translation is
  879. attempted.  For translation between character sets involving accented or
  880. other foreign language characters, it will normally be necessary to use
  881. an 8-bit transfer character set such as LATIN1-ISO or CYRILLIC-ISO.
  882. 3 SERVER_USAGE
  883. Here's one way to use Kermit to transfer files.  It makes use of the
  884. "server" capability of VMS C-Kermit.  The procedure is as follows:
  885.  
  886.   + Run Kermit on your local (desktop) computer.
  887.  
  888.   + Establish connection to the VMS computer.  If your local
  889.     computer is running C-Kermit, and you are dialing with a modem,
  890.     then use the sequence SET MODEM <modem-name>, SET SPEED <rate>,
  891.     DIAL <number>.  If you are using MS-DOS or other Kermit that
  892.     lacks a DIAL command, carry on to the next step.
  893.  
  894.   + Set any other necessary communication parameters, such as PARITY,
  895.     DUPLEX, and FLOW-CONTROL.
  896.  
  897.   + Give the CONNECT command.  If you have a modem, but have not yet
  898.     dialed the VMS computer, type the modem dialing commands now.
  899.  
  900.   + Log in to VMS.
  901.  
  902.   + Start C-Kermit on VMS, and give it any desired SET commands for
  903.     file, communication, or protocol-related parameters.  If you
  904.     will be transferring binary files, give the command SET FILE
  905.     TYPE BINARY to the remote Kermit.
  906.  
  907.   + Give C-Kermit the SERVER command.
  908.  
  909.   + Escape back to the Kermit program on your local (desktop)
  910.     computer.  If your local computer is running C-Kermit, type
  911.     Ctrl-\ C (Control-backslash followed by the letter "C").  If
  912.     using MS-DOS Kermit, use Alt-X or Ctrl-] C.  You should now see
  913.     your local Kermit program's prompt.
  914.  
  915.   + If you will be transferring binary files, give the command SET
  916.     FILE TYPE BINARY.
  917.  
  918.   + Use GET followed by the filename to get files from VMS to your
  919.     local computer.  Use SEND followed by the filename to put files
  920.     from your local computer to VMS.  You may use "wildcard"
  921.     characters such as * and ? in the filenames to specify groups of
  922.     files.
  923.  
  924.   + When you finish transferring files, and you need to continue your
  925.     work on VMS, type FINISH and then CONNECT.  You're now talking to
  926.     C-Kermit on VMS.
  927.  
  928.   + If you don't need to go back to the remote computer again, type
  929.     the BYE command to the local Kermit program.  This will shut
  930.     down the remote Kermit server and terminate (log you off) your
  931.     VMS session.
  932. 3 VMS_SPECIFICS
  933. The standard Kermit file types of BINARY and TEXT should cope with
  934. most circumstances when files are transferred to or from VMS
  935. systems.  When sending, VMS files whose record organization is
  936. "Fixed" or "Undefined" are assumed to be BINARY; all other file
  937. types are assumed to be TEXT.
  938.  
  939. The default record length for binary files is 512 bytes.  This can
  940. be changed by the command "SET FILE RECORD-LENGTH n".
  941.  
  942. SET FILE TYPE LABELED is an option specific to VMS C-Kermit.  If
  943. invoked when sending a file, this causes the majority of the VMS
  944. file attributes to be encoded and sent as part of the file to the
  945. other system.  This information cannot be utilized by other (non-
  946. VMS) systems, but it is useful (a) for transmitting VMS file
  947. attributes between two different VMS systems; (b) for storing a file
  948. on a non-VMS system, while still allowing its attributes to be
  949. recreated when it is imported back into VMS.
  950.  
  951. When sending or receiving a VMS file of type LABELED, set the file
  952. type on the other system to BINARY.  Labeled files inported from
  953. another system do not have their attributes recreated automatically:
  954. an external utility CKVCVT is provided to do this.  A further
  955. sub-topic describes the options available when running CKVCVT.
  956. 4 CKVCVT
  957. The CKVCVT utility regenerates VMS file attributes from a file
  958. which has earlier been exported from VMS using the SET FILE TYPE
  959. LABELED option.  Note that this is a completely separate program
  960. from Kermit.  If desired it can be run from within Kermit by
  961. giving a command of the form "! CKVCVT parameters".
  962.  
  963. Format
  964.  
  965.   CKVCVT  input-file [ options ]
  966.  
  967. The command-line options are as follows:
  968.  
  969.   -a        Preserve file ACL data (may require privileges)
  970.   -b        Preserve file backup date
  971.   -d        Print debugging information
  972.   -f fn     Name output file fn instead of default
  973.   -i        Inquire if a file is labeled
  974.   -o        Preserve file ownership (requires privileges)
  975.   -s        Strip one level of label information
  976.   -t        Don't trim paths from output file name
  977.   -?        Display this message
  978.