home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / b / vmsmit.mss < prev    next >
Text File  |  2020-01-01  |  68KB  |  1,420 lines

  1. @part(VMSMIT,root="kuser")
  2. @string{-vmsversion="@q<3.3.126>"}
  3. @Chapter<VAX/VMS KERMIT>
  4. @label<-vmsk>
  5. @Index[VAX/VMS]
  6. @begin<description>
  7. @i(Authors:)@\Robert C. McQueen, Nick Bush, Stevens Institute of Technology;
  8. @\Jonathan Welch, University of Massachusetts;
  9. @\Burt Johnson, Diversified Computer Systems, Inc.
  10.  
  11. @i(Language:)@\Bliss-32
  12.  
  13. @i(Documentation:)@\C. Gianone, F. da Cruz, Columbia University
  14. @\with thanks to the program's authors
  15.  
  16. @i(Version:)@\@value(-vmsversion)
  17.  
  18. @i(Date:)@\July, 1990
  19. @end<description>
  20.  
  21. @subheading<VAX/VMS Kermit-32 Capabilities At a Glance:>
  22. @begin<format,leftmargin +2,above 1,below 1>
  23. @tabclear()@tabset(3.5inches,4.0inches)
  24. Local operation:@\Yes
  25. Remote operation:@\Yes
  26. Transfers text files:@\Yes
  27. Transfers binary files:@\Yes
  28. Wildcard send:@\Yes
  29. Long packets:@\Yes
  30. Sliding windows:@\No
  31. Attribute packets:@\No
  32. File transfer interruption:@\Yes
  33. Filename collision avoidance:@\Yes
  34. Timeouts:@\Yes 
  35. 8th-bit prefixing:@\Yes
  36. Repeat character compression:@\Yes
  37. Alternate block check types:@\Yes
  38. Communication settings:@\Yes
  39. Transmit BREAK:@\Yes
  40. IBM mainframe communication:@\Yes
  41. Transaction logging:@\Yes
  42. Session logging (raw capture):@\Yes
  43. Debug logging:@\Yes
  44. Raw transmit:@\Yes
  45. Act as server:@\Yes
  46. Talk to server:@\Yes
  47. Advanced commands for servers:@\Yes
  48. Local file management:@\Yes
  49. Initialization file:@\Yes (@q<VMSKERMIT.INI>)
  50. Command Macros:@\No
  51. Script programming language:@\No
  52. International Character Sets:@\No
  53. @end<format>
  54.  
  55. Kermit-32 is a program that implements the Kermit file transfer protocol for
  56. the Digital Equipment Corporation VAX series computers under the VAX/VMS
  57. operating system. It is written in BLISS-32 and MACRO-32, with sources for
  58. all BLISS modules also available as MACRO-32 sources.  Kermit-32 should run
  59. on any VAX/VMS system from version 4.0 on (Version 3@q<.>1 of Kermit-32
  60. is the last version that runs under pre-4.0 releases of VMS).
  61.  
  62. The first section of this chapter will describe the things you need to know
  63. about the VAX/VMS file system and how Kermit-32 uses it.  The second section
  64. describes the special features of Kermit-32.  The final section contains
  65. information of interest to those who need to install Kermit-32 on a system.
  66.  
  67. @Section<The VAX/VMS File System>
  68.  
  69. The two main items of interest of the VAX/VMS file system (for the Kermit user)
  70. are the format of file specifications and the types of files and file data.
  71.  
  72. @Subheading<VAX/VMS File Specifications>
  73.  
  74. VAX/VMS file specifications are of the form
  75. @example(NODE::DEVICE:[DIRECTORY]NAME.TYPE;VERSION)
  76. Under version 4.0 and later of VMS, NAME, TYPE and each item in DIRECTORY
  77. may be up to 39 characters long, and may contain alphanumeric characters plus
  78. underscore.  Under earlier versions, NAME and DIRECTORY could be at most 9
  79. characters each and TYPE could be at most 3.
  80.  
  81. VERSION is a decimal number indicating the version of the file (generation).
  82. DEVICE may be either a physical or logical device name.  If it is a logical
  83. name, it may be up to 63 characters long and may contain alphanumeric
  84. characters plus dollar signs and underscores.  NODE may be either a logical
  85. name which translates to a DECnet node name or a physical DECnet node name.
  86. In either case, access information can be included (see the DECnet-VMS User's
  87. guide for more information).  The node name is not normally present, since
  88. most files are accessed on the same node where the user's job is running.  The
  89. version number is not normally given (in fact, should not normally be given).
  90. When device and/or directory are not supplied, they default to the user's
  91. current default device and directory.  Therefore, @q<NAME.TYPE> is normally
  92. all that is needed to specify a file on the user's default device and
  93. directory.  This is also all that Kermit-32 will normally send as the name of
  94. a file being transferred.
  95.  
  96. The node field specifies the name (and access information) for the DECnet
  97. node where the file is located.  Kermit-32 does not transmit the node field
  98. to the target system, but will attempt to honor a node field in an incoming
  99. file name.
  100.  
  101. The device field specifies a physical or "logical" device upon which the file
  102. is resident.  The directory field indicates the area on the device, for
  103. instance the area belonging to the owner of the file.  Kermit-32 does not
  104. normally transmit the device or directory fields to the target system, but will
  105. attempt to honor device or directory fields that may appear in incoming file
  106. names. It will not create new directories, however, so any directory specified
  107. in an incoming filename must already exist.
  108.  
  109. The name is the primary identifier for the file.  The type, also called the
  110. "extension", is an indicator which, by convention, tells what kind of file we
  111. have.  For instance @q<FOO.FOR> is the source of a Fortran program named FOO;
  112. @q<FOO.OBJ> might be the relocatable object module produced by compiling
  113. @q<FOO.FOR>; @q<FOO.EXE> could an executable program produced by LINKing
  114. @q<FOO.OBJ>, and so forth.
  115.  
  116. @index<Wildcard>
  117. VAX/VMS allows a group of files to be specified in a single file
  118. specification by including the special "wildcard" characters, "@q<*>" and
  119. "@q<%>".  A "@q<*>" matches any string of characters, including no characters
  120. at all; a "@q<%>" matches any single character.  Here are some examples:
  121. @Begin(Description,spread 0.5,leftmargin +8, indent -8)
  122. @q<*.FOR>@\All files of type @q<FOR> (all Fortran source files) in the
  123. default directory.
  124.     
  125. @q<FOO.*>@\Files of all types with name @q<FOO>.
  126.     
  127. @q<F*.*>@\All files whose names start with F.
  128.  
  129. @q<F*X*.*>@\All files whose names start with F and contain at least one X.
  130.  
  131. @q<%.*>@\All files whose names are exactly one character long.
  132.  
  133. @q<*.%%*>@\All files whose types are at least two characters long.
  134. @End(Description)
  135. Wildcard notation is used on many computer systems in similar ways, and it is
  136. the mechanism most commonly used to instruct Kermit to send a group of files.
  137.  
  138. @heading<Text Files and Binary Files>
  139.  
  140. The file system used by VAX/VMS provides for a large number of attributes to
  141. be associated with each file.  These attributes provide some indication of
  142. whether the file is a text file, or is some other type of non-text data.
  143. The two major attributes that affect VMS Kermit are the record type and
  144. record attribute.  The record type describes how logical records are stored
  145. in the file.  Records may be of some fixed length (specified by another
  146. attribute), or variable length (specified within each record), or stream
  147. (implying that records -- if there are any -- are separated by control
  148. characters within the data).  The record attributes describe
  149. how the breaks between records are to be treated.  For example, a record
  150. attribute of implied carriage return means that any program reading the
  151. file with intentions of printing it should add a carriage return / linefeed
  152. sequence between each record.  Other record attributes include FORTRAN carriage
  153. control and print file format.
  154.  
  155. The most common method of storing text in a file under VAX/VMS is to store one
  156. line of text per record (variable length records), with a carriage return /
  157. linefeed sequence implied by the end of the record (implied carriage return).
  158. This is the method Kermit-32 uses to store files it receives when using FILE
  159. TYPE ASCII (text).  Other formats are also used to store
  160. text under VAX/VMS, but the one used by Kermit-32 is the only one that
  161. is handled correctly by all known utility programs under VAX/VMS.  Also, most
  162. programs which work with text files (the editor EDT, for example) place some
  163. limit on the length of the lines which can be handled.  Typically this is 255.
  164. Kermit-32 can write text files with up to 4095 characters on a line, which
  165. means a text file from another system may be transferred and stored correctly
  166. by Kermit-32, but may still be unusable by certain VAX/VMS programs.
  167.  
  168. Certain PC applications may create text files with lines even longer than
  169. Kermit-32's maximum.  Typical examples are the ASCII export procedures of
  170. database, spreadsheet, and CAD packages.  If you try to send such a file to
  171. Kermit-32, the transfer will fail with a message@index<Record too big>:
  172. @example<%KERMIT32-E-REC_TOO_BIG, Record too big for KERMIT's internal buffer>
  173. If this happens, you can SET FILE TYPE BINARY on the VAX before transferring
  174. the file to it.  You should still be able to use the file as a text file,
  175. with the above proviso about record length.
  176.  
  177. There is no standard format for storing binary files.  In general, any record
  178. format with no record attributes can be used for binary files.  Since programs
  179. which work with binary files under VAX/VMS expect to see some particular
  180. format, more information is needed for transfer of binary files than for text
  181. files.  The current version of Kermit-32 is not capable of transferring all
  182. types of binary files which were created on a VAX/VMS system to another system
  183. and retrieving them intact, nor is it capable of transferring all of types
  184. binary files created on a VAX/VMS system to another VAX/VMS, P/OS, or
  185. RSX-11M/M+ system intact.  However, certain formats of binary files can be
  186. transferred, and binary files from some other systems may be transferred to a
  187. VAX and recovered intact.  See the section on the SET FILE command for details.
  188.  
  189. Using two programs supplied with Kermit-32, it is possible to transfer almost
  190. any type of file between VAXes, or between a VAX and a P/OS or RSX-11M/M+
  191. system.  The VMSHEX program converts a binary file to text (using a variation
  192. on Intel hex format).  The resulting file can be transferred as an ordinary
  193. text file, and finally "dehexified" on another VMS system using the VMSDEH
  194. program to reproduce the original file with all the attributes intact.  Since
  195. these text files are about twice the size of the original binary files, the
  196. transfers take longer.  On the plus side, the text versions of the files can
  197. be transferred to any system with a Kermit and still retrieved intact.  They
  198. can also be transferred over 7-bit data paths without any problems.  The
  199. Kermit-32 installation procedure (described later) makes use of hexified
  200. versions of the Kermit-32 binary executable file and VMSDEH to restore it
  201. a binary @q<.EXE> file, or task image.
  202.  
  203. @heading<Using the VAX to Archive Microcomputer Files>
  204.  
  205. You can use Kermit to send textual files from a microcomputer or any 8-bit
  206. computer system to VAX/VMS with no special provisions, since Kermit-32 stores
  207. incoming files as text files (variable length records with implied carriage
  208. returns) unless it is explicitly told otherwise.  But Kermit-32 has no
  209. automatic way of distinguishing an incoming binary file from an incoming text
  210. file.  You must inform Kermit-32 that a file it is about to receive is to be
  211. stored as a binary file.  This is done using the SET FILE TYPE BINARY command.
  212. This instructs Kermit-32 to store the data it receives in the file without
  213. checking for carriage return, line feed sequences.  The file it creates will
  214. be variable record length, with no record attributes.  Each record will
  215. contain 510 bytes of data, except the last, which will contain whatever amount
  216. is left before the end of the file.  This allows Kermit-32 to correctly return
  217. exactly the data it was sent when the file is returned to the original system.
  218.  
  219. Note that because of the need to use a different file type for binary files,
  220. it is not possible to use a "wildcard send" command to send a mixture of text
  221. and binary files to a VAX system unless the text files are not intended for
  222. use on the VAX; rather, you must send all text files with Kermit-32's file
  223. type set to ASCII, and all binary files with the file type set to binary.
  224.  
  225. Once you get the foreign file into the VAX system, stored with the correct
  226. file type, you need take no special measures to send it back to its system of
  227. origin.  This is because Kermit-32 honors the record type and attributes of
  228. the file as it is stored on the VAX.  In fact, SET FILE TYPE BINARY, ASCII, or
  229. FIXED only affects how Kermit-32 receives files -- it does not affect how
  230. Kermit-32 transmits files.
  231.  
  232. @heading<Files Kermit-32 Cannot Handle>
  233.  
  234. The Kermit protocol can only accommodate transfer of @i<sequential> files,
  235. files which are a linear sequence of bytes (or words).
  236.  
  237. Some files on a VAX/VMS system are not sequential, and cannot be successfully
  238. sent or received by Kermit-32.  These are mainly indexed data files, but can
  239. also include other files which require more than just the data in the file to
  240. be completely reconstructed.  External control information and file attributes
  241. are not transmitted.  However, @i<any> VMS file can be transferred with Kermit
  242. if it has been "hexified" with VMSHEX.
  243.  
  244. @Section<Program Operation>
  245.  
  246. If a system-wide foreign command "kermit" is defined for Kermit-32 (see
  247. section on installation), then you can run the program by just typing its name:
  248. @example($ @ux[kermit])
  249. If you get a message like:
  250. @begin(example)
  251. %DCL-W-IVVERB, unrecognized command verb - check validity and spelling
  252. @end(example)
  253. then Kermit has not been installed properly on your VMS system.  If you know
  254. where the @q<KERMIT.EXE> file is stored (for example, in the @q<SYS$SYSTEM:>
  255. area) then you can define a "kermit" command for yourself by including a line
  256. like this in your @q<LOGIN.COM> file:
  257. @example<kermit :== $sys$system:kermit.exe>
  258.  
  259. When you invoke Kermit by name only, it will enter interactive prompting
  260. mode, and allow you to type repeated commands until you exit with the EXIT
  261. command.  Kermit-32's normal prompt is "@q(Kermit-32>)".
  262.  
  263. Kermit-32 will also accept a single command on the command line, like this:
  264. @begin[example]
  265. $ @ux[Kermit send foo.bar]
  266. @End(Example)
  267. In this case, the program will exit immediately after executing the single
  268. command.
  269.  
  270. In either case, Kermit reads and executes commands from its "initialization
  271. file", @q<VMSKERMIT.INI>, if any, in your login directory before it executes
  272. any other commands.
  273.  
  274. Kermit-32 will try to open the file @q<VMSKERMIT> with a default filetype
  275. of @q<.INI>.  If the logical name VMSKERMIT exists then an attepmt to
  276. open the file pointed to by the value of that logical name will be made
  277. instead.  (For example, some sites might wish to set site-wide default
  278. parameters in a system-wide Kermit-32 initialization file, and so they might
  279. define the system-wide logical name VMSKERMIT to point at such a file.  The
  280. last command in this file could be @q<TAKE SYS$LOGIN:VMSKERMIT.INI> to "chain"
  281. to the user's initialization file.
  282.  
  283. Command keywords may be abbreviated to their shortest prefix that sets them
  284. apart from any other keyword valid in that field.
  285.  
  286. @section<Conditioning Your Job for Kermit>
  287.  
  288. @index<Interference>
  289. @index<Message Interference>
  290. Kermit-32 does as much as it can to condition your line for file transfer.  It
  291. saves all your terminal settings, and restores them after use.  However, there
  292. are some sources of interference over which Kermit-32 has no control.  In
  293. particular, messages issued by other processes in your job could become
  294. mingled with Kermit packets and slow things down or stop them entirely.  This
  295. is a fairly rare occurence and can be easily avoided by not running any other
  296. process which wishes to perform I/O to your terminal while you are running
  297. Kermit-32.
  298.  
  299. Normally, when Kermit-32 is run, it assumes you wish to use it in remote mode
  300. and perform file transfers over the terminal line which controls your job.
  301. This can be overridden, however, by defining a logical name which equates to
  302. some other terminal line in the system.  The default terminal line to be used
  303. for file transfers is determined by the first of the following logical names
  304. which translates to a terminal line which is available for use by your
  305. process: KER$COMM, SYS$INPUT, SYS$OUTPUT, and SYS$COMMAND.  If none of these
  306. logical names translate to an available terminal line, there is no default
  307. terminal line and a SET LINE command must be used before any transfer command
  308. is performed.  Note that this is the typical case in a batch job.
  309.  
  310. Kermit-32 will also default the type of parity to be used on the communication
  311. line to that which is set on its default terminal line when it is started.
  312. This means that if all communication at a site is normally done using even
  313. parity (for example), Kermit-32 will also use even parity.  If you need to use
  314. another kind of parity, use the SET PARITY command to change it.
  315.  
  316. There are two things to keep in mind when using Kermit-32 in local mode (where
  317. the file transfers are done over a different terminal line from where commands
  318. are typed):
  319. @begin(itemize,spread 0.5)
  320. Under VAX/VMS, every terminal line has an owner UIC and protection code
  321. associated with it.  This UIC and protection is used to determine who can
  322. allocate (and therefore use) the terminal line when they are not logged in
  323. on that line.  Therefore, in order for Kermit-32 to be able to perform
  324. file transfers over a terminal line other than the one on which you are
  325. logged in, the field of the protection code for the terminal which applies
  326. to your job (based on your UIC and the owner UIC of the terminal) must allow
  327. your job access to the terminal.  You may need to request your system manager
  328. to change the protection for a terminal line to allow you to use it with
  329. Kermit-32 in local mode.  See the section on Installation for details.
  330.  
  331. Terminal lines which have been declared as modem control lines will have the
  332. phone "hung up" whenever the terminal line becomes free (deallocated).  This
  333. means that if you do not use the DCL ALLOCATE command to allocate the terminal
  334. line to your job before entering Kermit-32, exiting Kermit-32 will cause the
  335. terminal line to "hang up" the modem.  If you do wish to get to DCL after
  336. having used Kermit-32 to connect a modem control line which you do not have
  337. allocated, you can use the PUSH command to spawn a subprocess running DCL,
  338. so that Kermit will keep the connection active.
  339. @end<itemize>
  340.  
  341. @Section<Kermit-32 Commands>
  342.  
  343. Kermit-32 has the following commands:
  344. @Begin(Format,spread 0)
  345. @tabclear()@tabset(1.25inches)
  346. @>@q<@@>@\  synonym for "take".
  347. @>BYE@\  to remote server.
  348. @>CONNECT@\  as terminal to remote system.
  349. @>EXIT@\  from Kermit-32.
  350. @>FINISH@\  Shut down remote server.
  351. @>GET@\  remote files from server.
  352. @>HELP@\  with Kermit-32.
  353. @>LOCAL@\  prefix for local file management commands.
  354. @>LOG@\  remote terminal session.
  355. @>LOGOUT@\  remote server.
  356. @>PUSH@\  to DCL command level.
  357. @>QUIT@\  from Kermit-32.
  358. @>RECEIVE@\  files from remote Kermit.
  359. @>REMOTE@\  prefix for remote file management commands.
  360. @>SEND@\  files to remote Kermit.
  361. @>SERVER@\  mode of remote operation.
  362. @>SET@\  various parameters.
  363. @>SHOW@\  various parameters.
  364. @>STATUS@\  about most recent file transfer.
  365. @>TRANSMIT@\  Transmit (upload) a file with no error checking.
  366. @>TAKE@\  Kermit-32 commands from a file.
  367. @End(format)
  368.  
  369. @subsection<Commands for File Transfer>
  370.  
  371. Kermit-32 provides the standard SEND, RECEIVE, and GET commands for
  372. transferring files using the Kermit protocol.
  373.  
  374. @Heading<The SEND Command>
  375. @Index[Initial Filespec]@Index[SEND]
  376. Syntax:  @q<SEND @i{filespec}>
  377.  
  378. The SEND command causes a file or file group to be sent from the VAX to the
  379. other system.
  380. If @i{filespec} contains wildcard characters then all matching files will be
  381. sent, in alphabetical order (according to the ASCII collating sequence) by
  382. name.
  383. If @i{filespec} does not contain any wildcard characters, then the single file
  384. specified by @i{filespec} will be sent.
  385.  
  386. Only the most recent generation of a file is sent unless the file
  387. specification includes specific or wild generation numbers.
  388.  
  389. @Index<Normal Form for File Names>
  390. Files will be sent with at least their VAX/VMS file name and type
  391. (for instance @q<FOO.BAR>).  If a SET FILE NAMING FULL command has been given,
  392. Kermit-32 will also send the device name, directory name and version number
  393. (for instance @q<USER$DISK:[JOE]FOO.BAR;25>).  If a SET FILE NAMING
  394. UNTRANSLATED command has been given, Kermit-32 will send the file name, type
  395. and version number (for instance @q<FOO.BAR;25>).  If a SET FILE NAMING
  396. NORMAL_FORM command has been given (this is the initial default), Kermit-32
  397. will only send the file name and type.
  398.  
  399. Each file will be sent according to the record type and attributes recorded in
  400. its file descriptor.  Kermit-32 attempts to translate all text file record
  401. formats (including those with FORTRAN or print carriage control) to a format
  402. usable on any system.  Note that there is no need to set the FILE TYPE
  403. parameter for sending files, since Kermit-32 always uses the information from
  404. the file descriptor to determine how to send the file.
  405.  
  406. @Index<Parity>@Index<Eighth-Bit Prefix>@Index<Binary Files>
  407.  
  408. If communication line parity is being used (see SET PARITY), Kermit-32 will
  409. request that the other Kermit accept a special kind of prefix notation for
  410. files that contain 8-bit data.  This is an optional Kermit protocol feature,
  411. supported by most modern Kermit programs.  If the other Kermit does not agree
  412. to use this feature, binary files cannot be sent correctly.  This includes
  413. executable programs (like @q<.EXE> files, CP/M @q<.COM> files), relocatable
  414. object modules (@q<.OBJ> files), as well as any text file containing
  415. characters with the eighth bit on.
  416.  
  417. @Index<Repeated Character Compression>
  418. Kermit-32 will also ask the other Kermit whether it can handle a special prefix
  419. encoding for repeated characters.  If it can, then files with long strings of
  420. repeated characters will be transmitted very efficiently.  Columnar data,
  421. highly indented text, and binary files are the major beneficiaries of this
  422. technique.
  423.  
  424. If you're running Kermit-32 in local mode, for instance dialing out from a VAX
  425. to another system using an autodialer, you should have already run Kermit on
  426. the remote system and issued either a RECEIVE or a SERVER command.  Once you
  427. give Kermit-32 the SEND command, the name of each file will be displayed on
  428. your screen as the transfer begins.  If the file is successfully transferred,
  429. you will see "@q<[OK]>", otherwise there will be an error message.
  430.  
  431. During local operation, you can type Control-A@Index<Control-A> at any point
  432. during the transfer to get a brief status report.
  433. @index<Control-X>@index<Control-Z>@Index<Cancelling a File Transfer> You may
  434. also type Control-X or Control-Z to interrupt the current file or file group.
  435.  
  436. @Heading<The RECEIVE Command>
  437. @Index[RECEIVE]
  438. Syntax:  @q<RECEIVE [@i{filespec}]>
  439.  
  440. The RECEIVE command tells Kermit-32 to receive a file or file group from the
  441. other system.  If only one file is being received, you may include the
  442. optional @i{filespec} as the name to store the incoming file under; otherwise,
  443. the name is taken from the incoming file header.  If the name in the header is
  444. not a legal VAX/VMS file name, Kermit-32 will normally replace the illegal
  445. characters with "X" (see SET FILE NAMING NORMAL_FORM).
  446.  
  447. @index<DELETE>@index<UNDELETE>@index<Version>
  448. If an incoming file has the same name as an existing file, Kermit-32 just
  449. creates a new version of the same name and type, for instance @q<FOO.BAR;3,
  450. FOO.BAR;4>.
  451.  
  452. Incoming files are stored with the prevailing file type, ASCII by default,
  453. which is appropriate for text files.  @Index<Binary Files> If you are asking
  454. Kermit-32 to receive binary files from a microcomputer or other 8-bit system,
  455. you must first type SET FILE TYPE BINARY.  Otherwise, an error may occur when
  456. receiving the file, or carriage return / linefeed sequences will be added to
  457. the file, making it useless when sent back to the system of origin.
  458.  
  459. @Index<Parity>@Index<Eighth-Bit Prefix>
  460. If parity is being used on the communications line, then 8th-bit prefixing
  461. will be requested.  If the other side cannot do this, binary files cannot be
  462. transferred correctly.  If parity is being added externally to Kermit and VMS
  463. (for example by some kind of communication device, or a public data network
  464. like Telenet) then you must inform Kermit-32 about it using the SET PARITY
  465. command, or else Kermit-32 will not know that it has to do 8th-bit prefixing,
  466. and the file transfer will fail.
  467.  
  468. If an incoming file does not arrive in its entirety, Kermit-32 will normally
  469. discard it; it will not appear in your directory.  You may change this behavior
  470. @Index<Incomplete File Disposition>
  471. by using the command SET INCOMPLETE KEEP, which will cause as much of the file
  472. as arrived to be saved in your directory. 
  473.  
  474. If you are running Kermit-32 in local mode, you should already have issued a
  475. SEND command to the remote Kermit, and then escaped back to Kermit-32.  As
  476. files arrive, their names will be displayed on your screen.  You can type
  477. Control-A during the transfer for a brief status report.
  478.  
  479. @Index<Control-X>@Index<Control-Z>@Index<Cancelling a File Transfer>
  480. If a file arrives that you don't really want, you can attempt to cancel it
  481. by typing Control-X; this sends a cancellation request to the
  482. remote Kermit.  If the remote Kermit understands this request (not all
  483. implementations of Kermit support this feature), it will comply;
  484. otherwise it will continue to send.  If a file group is being sent, you can
  485. request the entire group be cancelled by typing Control-Z.
  486.  
  487. @Heading<The GET Command>
  488.  
  489. Syntax: @q<GET [@i{remote-filespec}]>
  490.  
  491. The GET command requests a remote Kermit server to send the file or file group
  492. specified by @i<remote-filespec>.  This command can be used only when
  493. Kermit-32 is in local mode, with a Kermit server on the other end of the line
  494. specified by SET LINE.  This means that you must have CONNECTed to the other
  495. system, logged in, run Kermit there, issued the SERVER command, and escaped
  496. back to the VAX.
  497.  
  498. The remote filespec is any string that can be a legal file specification for
  499. the remote system; it is not parsed or validated locally.  Any leading spaces
  500. before the remote filespec are stripped, and lower case characters are raised
  501. to upper case.
  502.  
  503. As files arrive, their names will be displayed on your screen.  As in the
  504. RECEIVE command, you may type Control-A to get a brief status report, Ctrl-X
  505. to request that the current incoming file be cancelled, Ctrl-Z to request that
  506. the entire incoming batch be cancelled.
  507.  
  508. If the remote Kermit is not capable of server functions, then you will probably
  509. get an error message back from it like "Illegal packet type".  In this case,
  510. you must connect to the other Kermit, give a SEND command, escape back, and
  511. give a RECEIVE command.
  512.  
  513. @Heading<The STATUS Command>
  514. Give statistics about the most recent file transfer.
  515.  
  516. @Heading<The PUSH Command>
  517.  
  518. Syntax: @q<PUSH>
  519.  
  520. Spawn a DCL subprocess, to which you may issue any DCL commands.  Type LOGOUT
  521. to return to Kermit-32.
  522.  
  523. @Heading<The TAKE Command>
  524.  
  525. Syntax: @q<TAKE @i(file-spec) [ /DISPLAY ]>
  526.  
  527. Where 'file-spec' is any normal VAX/VMS file specification.  If file-spec does
  528. not specify a file-type Kermit-32 will supply a default of @q<.COM>.  The
  529. /DISPLAY option causes the commands read from the file to be displayed on the
  530. user's terminal. 
  531.  
  532. The TAKE command tells Kermit-32 to execute commands from the specified file.
  533. You may also use the VMS notation "@q<@@>" instead of TAKE to specify a
  534. command file.
  535.  
  536. If it exists, the file @q<VMSKERMIT.INI> (or, if the logical name VMSKERMIT is
  537. defined, whatever file it points to) is automatically taken upon
  538. program startup. 
  539.  
  540. @subsection<Server Operation>
  541.  
  542. @Heading<The SERVER Command>
  543. @Index<Server>
  544.  
  545. The SERVER command puts a remote Kermit-32 in "server mode", so that it
  546. receives all further commands in packets from the local Kermit.  The Kermit-32
  547. server is capable (as of this writing) of executing the following remote server
  548. commands:  SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD,
  549. REMOTE SPACE, REMOTE DELETE, REMOTE TYPE, REMOTE HELP, REMOTE COPY,
  550. REMOTE RENAME, REMOTE SEND_MESSAGE, REMOTE WHO, and REMOTE HOST.
  551.  
  552. Any nonstandard parameters should be selected with SET commands before putting
  553. Kermit-32 into server mode, in particular the file type. The Kermit-32 server
  554. can send all files in the correct manner automatically.  However, if you need
  555. to ask Kermit-32 to receive binary files you must issue the SET FILE TYPE
  556. BINARY command before putting it into server mode, and then you must only send
  557. binary files.  You cannot send a mixture of text files and 8-bit binary files
  558. to a Kermit-32 server unless the files are not for use on the VAX.
  559.  
  560. @Heading<Commands for Servers>
  561.  
  562. When running in local mode, Kermit-32 allows you to give a wide range of
  563. commands to a remote Kermit server, with no guarantee the that the remote
  564. server can process them, since they are all optional features of the protocol.
  565. Commands for servers include the standard @q<SEND>, @q<GET>, @q<BYE>,
  566. @q<LOGOUT> and @q<FINISH> commands, as well as the @q<REMOTE> command.
  567.  
  568. Syntax: @q<REMOTE @i{command}>
  569.  
  570. Send the specified command to the remote server.  If the server does not
  571. understand the command (all of these commands are optional features of the
  572. Kermit protocol), it will reply with a message like "Unknown Kermit server
  573. command".  If does understand, it will send the results back, and they will be
  574. displayed on the screen.  The REMOTE commands are:
  575. @begin<description>
  576. COPY @i<filespec>@\Copy file.  The server is asked to make a copy of the
  577. specified file.  Kermit-32 will prompt for the new file name on a separate
  578. line.  Both filespecs must be in the correct format for the remote system.
  579. Kermit-32 does not parse or validate the file specifications.  Any leading
  580. spaces will be stripped and lower case characters converted to upper case.
  581. Note that this command simply provides for copying a file within the server's
  582. system - it does not cause a file to be transferred.
  583.  
  584. CWD [@i<directory>]@\Change Working Directory.  If no directory name is
  585. provided, the server will change to the default or home directory.  Otherwise,
  586. you will be prompted for a password, and the server will attempt to change to
  587. the specified directory.  The password is entered on a separate line, and does
  588. not echo as you type it.  If access is not granted, the server will provide a
  589. message to that effect.  Note that while not all server Kermits require
  590. (or accept) a password to change the working directory, Kermit-32 will always
  591. ask for one when a directory name is provided.
  592.  
  593. DELETE @i<filespec>@\Delete the specified file or files.  The names of the
  594. files that are deleted will appear on your screen.
  595.  
  596. DIRECTORY [@i<filespec>]@\The names of the files that match the given
  597. file specification will be displayed on your screen, perhaps along with size
  598. and date information for each file.  If no file specification
  599. is given, all files from the current directory will be listed.
  600.  
  601. DISK_USAGE [@i<directory>]@\Display information about disk usage in the
  602. given directory (or by the given user).  If no directory is provided,
  603. disk usage information is provided for the current working directory (or user).
  604. This is the same as the REMOTE SPACE command.
  605.  
  606. EXIT@\Requests the
  607. server to leave Kermit, allowing the terminal to be used for normal commands.
  608.  
  609. FINISH@\Requests the server to return to the Kermit prompt, allowing statistics
  610. to be obtained about the transfers.
  611.  
  612. HELP [@i<topic>]@\Provide information about the given topic.  If no topic is
  613. given, provide a list of the functions that are available from
  614. the server.  Some servers may ignore the topic and always display the same
  615. information.
  616.  
  617. HOST [@i<command>]@\Pass the given command to the server's host command
  618. processor, and display the resulting output on your screen.
  619.  
  620. LOGIN @i<user-id>@\Supply information to the server Kermit to indicate what
  621. user-id, account and password are to be used.  The server Kermit may use
  622. this to validate the user's access to the system as well as for billing
  623. purposes. It may also use this information to provide the user with access
  624. to files on its system.
  625.  
  626. LOGOUT@\Request the server to exit Kermit and logout its job (or process).
  627. This command is identical to the LOGOUT command.
  628.  
  629. RENAME @i<filespec>@\Change the name on the specified file (or files).
  630. Kermit-32 will prompt for the new file specification on the next line.
  631. Both file specifications must be valid for the server's system.
  632.  
  633. SEND_MESSAGE @i<destination-address>@\Request the server to send a single
  634. line message to the specified destination address (which might be a
  635. user-id, terminal designator, or some other item, depending upon the server
  636. Kermit).  Kermit-32 will prompt for the single line message on the next line.
  637.  
  638. SPACE [@i<directory>]@\Display information about disk usage in the
  639. given directory (or by the given user).  If no directory is provided,
  640. disk usage information is provided for the current working directory (or user).
  641. This is the same as the REMOTE DISK_USAGE command.
  642.  
  643. STATUS@\Display information about the status of the server.
  644.  
  645. TYPE @i<filespec>@\Display the contents of the specified file on your screen.
  646.  
  647. WHO [@i<user-id>]@\Display information about the given user.  If no user-id
  648. is given, display information about the currently active users.  Kermit-32
  649. will prompt for options for selecting what information to display and/or
  650. formatting parameters.  The format of both the user-id and the options
  651. are dependent upon the server Kermit.
  652. @end<description>
  653.  
  654. @Subsection<Commands for Local File Management>
  655.  
  656. Syntax: @q<LOCAL [@i{command}]>
  657.  
  658. Execute the specified command on the local system -- on the VAX/VMS system
  659. where Kermit-32 is running.  These commands provide some local file management
  660. capability without having to leave the Kermit-32 program.  These commands are
  661. very similar to the REMOTE commands in function and syntax.  They are all
  662. executed locally, and are available when Kermit-32 is either local or remote.
  663. The arguments to these commands are the same as the arguments expected from
  664. the user Kermit when Kermit-32 is processing a command in server mode.
  665. @begin<description>
  666. COPY @i<filespec>@\Make a copy of the given file (or files).  Kermit-32
  667. will prompt for the new file specification.  The command is actually
  668. performed by using the DCL COPY command (COPY/LOG @i<old-file> @i<new-file>),
  669. and any options which are valid on the DCL COPY command may be included.
  670.  
  671. CWD [@i<directory>]@\Change working directory, or, in VAX/VMS terminology,
  672. change the default device/directory.  This command takes the same arguments
  673. as the DCL SET DEFAULT command (i.e., a device and directory, only a
  674. directory, or only a device).  If no argument is given, the default
  675. device and directory are reset to that in effect when Kermit-32 was run.
  676. The new default device and directory will be typed out.
  677.  
  678. DELETE @i<filespec>@\Delete the specified file or files.  This command
  679. is performed by using the DCL DELETE command (DELETE/LOG @i<filespec>).
  680. Therefore, any options which are valid on the DCL DELETE command
  681. may be included.
  682.  
  683. DIRECTORY [@i<filespec>]@\Provide a directory listing of the specified files.
  684. This command is performed by using the DCL DIRECTORY command
  685. (DIRECTORY @i<filespec>), so any options valid for the DCL DIRECTORY command
  686. may be included.
  687.  
  688. DISK_USAGE [@i<uic>]@\Display disk usage information for the given UIC.  If
  689. no UIC is given, display disk usage information for the process UIC.
  690. This command is performed by using the DCL SHOW QUOTA command (SHOW QUOTA or
  691. SHOW QUOTA/USER=@i<uic>).
  692.  
  693. HELP@\Display the help message describing the server commands which are
  694. available.
  695.  
  696. HOST @i<DCL-command>@\Perform the given DCL command.  The command should
  697. not perform any action which will require more input.  Any output resulting
  698. from the command will be typed on the terminal.
  699.  
  700. RENAME @i<filespec>@\Change the name of the specified file.  Kermit-32
  701. will prompt for the new name on the next line.  This command is performed
  702. by using the DCL RENAME command (RENAME/LOG @i<old-file> @i<new-file>), so
  703. any options which are valid on the DCL RENAME command may be included.
  704.  
  705. SEND_MESSAGE @i<terminal-name>@\Send a single line message to the given
  706. terminal.  Kermit-32 will prompt for the message on the next line.  Since
  707. this command is performed using the DCL REPLY command
  708. @example(REPLY/TERMINAL=@i<terminal-name> "@i<message>")
  709. OPER privileges are needed to perform it.
  710.  
  711. TYPE @i<filespec>@\Display the contents of the specified file or
  712. files at your terminal.
  713. Each file will be preceded by its name in angle brackets.
  714. @end<description>
  715.  
  716. @Subsection<The CONNECT Command>
  717.  
  718. Syntax: @q<CONNECT [@i{terminal-name}]>
  719.  
  720. Establish a terminal connection to the system connected to the terminal line
  721. specified here or in the most recent SET LINE command, using the currently set
  722. communication parameters (local-echo, parity, etc).  Get back to Kermit-32 by
  723. typing the escape character followed by the letter C.  The escape character is
  724. Control-Rightbracket (@q<^]>) by default.  When you type the escape character,
  725. several single-@|character commands are possible:
  726.  
  727. @Begin(Description,leftmargin +6,indent -4, spread 0)
  728. @q<B>@\Send a BREAK signal.
  729.  
  730. @q<C>@\Close (but do not hang up) the connection and return to Kermit-32.
  731.  
  732. @q<Q>@\If a session log is active, temporarily Quit logging.
  733.  
  734. @q<R>@\Resume logging to the session log.
  735.  
  736. @q<S>@\Show status of the connection.
  737.  
  738. @q<0>@\Send a null character.
  739.  
  740. @q<?>@\List all the possible single-character arguments.
  741.  
  742. @q<^]> (or whatever you have set the escape character to be):@\Typing the
  743. escape character twice sends one copy of it to the connected host.
  744. @End(Description)
  745. You can use the SET ESCAPE command to define a different escape character, and
  746. SET PARITY, and SET LOCAL_ECHO to change those communication-@|line-@|oriented
  747. parameters.  Type the SHOW LINE command for information about your current
  748. communication settings.
  749.  
  750. Kermit-32 does not have any special autodialer interface.  It assumes that the
  751. connection has already been made and the line assigned.  If the line has an
  752. autodialer attached to it, then you can type commands to the autodialer after
  753. you CONNECT.
  754.  
  755. @Subsection<The SET and SHOW Commands>
  756.  
  757. @Heading<The SET Command>
  758.  
  759. Syntax: @q<SET @i{parameter} [@i{option} [@i{value}]]>
  760.  
  761. Establish or modify various parameters for file transfer or terminal
  762. connection.  You can examine their values with the SHOW command.  The following
  763. parameters may be SET:
  764. @Begin(Format,spread 0)
  765. @tabclear()@tabset(2.0inches)
  766. @>BLOCK_CHECK@\  Packet transmission error detection method
  767. @>DEBUGGING@\  Record or display state transitions or packets
  768. @>DELAY@\  How long to wait before starting to send
  769. @>ESCAPE@\  Character for terminal connection
  770. @>FILE@\  For setting file parameters like file type
  771. @>HANDSHAKE@\  For establishing half duplex line turnaround handshake
  772. @>IBM_MODE@\  For communicating with an IBM mainframe
  773. @>INCOMPLETE_FILE@\  What to do with an incomplete file
  774. @>LINE@\  Terminal line to use for file transfer or CONNECT
  775. @>LOCAL_ECHO@\  For terminal connection, ON or OFF
  776. @>MESSAGE@\  The type of typeout to be done during transfers
  777. @>PARITY@\  Character parity to use
  778. @>PROMPT@\  Change the program's command prompt
  779. @>RECEIVE@\  Various parameters for receiving files
  780. @>REPEAT_QUOTE@\ Character to use for repeat compression
  781. @>RETRY@\  How many times to retry a packet before giving up
  782. @>SEND@\  Various parameters for sending files
  783. @>TRANSMIT@\  Control TRANSMIT command echo and delay
  784. @end(Format)
  785.  
  786. @Subheading<SET DEBUGGING>
  787. @Index<Debugging>
  788. Syntax: @q<SET DEBUGGING @i{options}>
  789.  
  790. Record the packet traffic, either on your terminal or in a file.  Some reasons
  791. for doing this would be to debug a version of Kermit that you are working on,
  792. to record a transaction in which an error occurred for evidence when reporting
  793. bugs, or simply to vary the display you get when running Kermit-32 in local
  794. mode.  Options are:
  795. @Begin(Description)
  796. ON@\Display each incoming and outgoing packet (lengthy).
  797.  
  798. OFF@\Don't display or record debugging information (this is the normal mode).
  799. If debugging was in effect, turn it off.
  800. @End(Description)
  801. The debugging information is recorded in the file specified by the most recent
  802. LOG DEBUGGING command.
  803.  
  804. @Subheading<SET ESCAPE>
  805. @Index<Escape Character for CONNECT>
  806. @q<SET ESCAPE @i{octal-number}>
  807.  
  808. Specify the control character you want to use to "escape" from remote
  809. connections back to Kermit-32.  The default is 35 (Control-]).  The number is
  810. the octal value, 1 to 37 (or 177), of the ASCII control character you want to
  811. use, for instance 2 is Control-B.
  812.  
  813. @Subheading<SET FILE>
  814. Syntax: @q<SET FILE @i{parameter keyword}>
  815.  
  816. Establish file-related parameters:
  817. @Begin(Description,leftmargin +8,indent -8)
  818. BLOCKSIZE @i<number>@\Specify the @i<record size> for incoming files when the
  819. file type is set to BINARY, FIXED, or BLOCK.  Note that "blocksize" is a
  820. misnomer, but one which is commonly used in VMS.  All VMS disk files have a
  821. true blocksize of 512 bytes.  The Kermit "blocksize" (as well as the blocksize
  822. referred to in many VMS commands, like BACKUP, and help files) is really the
  823. record size.
  824.  
  825. TYPE @i<keyword>@\@Index<File Type>How Kermit-32 should treat and store the
  826. file that is being sent to it, i.e. that Kermit-32 is @i<receiving>, and (in
  827. the case of FILE TYPE BLOCK only) how it is to read a file it is @i<sending>
  828. from disk.  The choices are ASCII, BINARY, BLOCK, and FIXED.  The BINARY,
  829. BLOCK, and FIXED types use a default record size (described below) which may be
  830. overriden, for received files only, with the SET FILE BLOCKSIZE command.
  831. Because the VMS file system is so complex, and because files created by
  832. different applications can have different characteristics, you might have to
  833. experiment with different values for the SET FILE TYPE and SET FILE BLOCKSIZE
  834. commands before you find the one that works right for you.
  835. @Begin(Description,leftmargin +8,indent -8)
  836.  
  837. ASCII@\This is the default file type.  Incoming files are stored as standard
  838. VAX/VMS text files with variable length records and carriage return / line
  839. feed sequences implied between records (that is, with the CR carriage control
  840. record attribute).  This is the format preferred by most utility programs
  841. under VAX/VMS.  A fatal error occurs if any line is more than 4096 characters
  842. long.  Note that incoming lines are only terminated by carriage return, line
  843. feed sequences.  A carriage return that is not followed by a line feed or a
  844. line feed that is not preceded by a carriage return is not considered the end
  845. of a line, and is included within the body of a record.
  846.  
  847. BINARY@\Store received files with variable length records and no record
  848. attributes.  Records are written using the current "blocksize", The last
  849. record may be short, with its record size correctly indicated.  The default
  850. "blocksize" for binary files is 510, so that a record together with its
  851. two-byte length field exactly fill a 512-byte VMS disk block.  Any file which
  852. is just a stream of bytes can be stored as a BINARY file, and recovered intact
  853. later.  This is the preferred file type for use in archiving non-VMS files.
  854. The longest possible record is 32765 plus two bytes for the RMS length field.
  855.  
  856. BLOCK@\Store received files exactly as they come in, byte for byte, with no
  857. formatting or record length information.  When sending files, send the file
  858. data literally, including record attributes (if any), and ignoring all RMS
  859. attributes.  Using a file type of BLOCK has proven effective when transferring
  860. files between the same application on unlike systems, for example Lotus 1-2-3
  861. spreadsheets between VMS and MS-DOS.  When receiving a file in this mode, any
  862. unused portions of the last block are filled with zeros.
  863.  
  864. FIXED@\Store the file as a fixed-length-record binary file.  Any file received
  865. is stored as fixed length records with no record attributes, using the current
  866. "blocksize" (i.e. record length, 512 by default).  Fixed-length 512-byte
  867. records is the format used for binary files such as VAX/VMS "EXE" files and
  868. RSX-11M/M+ "TSK" files.  VMS BACKUP savesets are fixed-length-record files
  869. with a record-length ("blocksize") of 2048 or more.  Since even the last
  870. record of the file is written with the whole record length (even if it is not
  871. filled), this format does not necessarily maintain the correct length of a
  872. file.  It should normally only be used for fixed-length-record files coming
  873. from a VAX/VMS, PDP-11, or other system, when the fixed-length nature of the
  874. data must be preserved.
  875. @End(Description)
  876.  
  877. @Index<Normal Form for File Names>
  878. NAMING @i<keyword>@\Determine the form of names to be sent with outgoing
  879. files and determine the translation performed on incoming file names.
  880. The choices are FULL, NORMAL_FORM and UNTRANSLATED.
  881. @Begin(Description,leftmargin +8,indent -8)
  882. FULL@\Kermit-32 will send full file names (including device, directory,
  883. file name, file type and version number).  When receiving a file, Kermit-32
  884. will perform no translation of the file name (which must therefore be a
  885. legal VAX/VMS file specification).
  886.  
  887. NORMAL_FORM@\Kermit-32 will send only the file name and file type. When
  888. receiving a file, Kermit-32 will convert the file specification received to
  889. contain only uppercase letters, digits, and at most one period.  Any other
  890. characters will be translated to "@q<X>".  There will be at most 39 characters
  891. before the period (if any), and at most 39 characters afterwards.  This forces
  892. the file name to be a valid VAX/VMS file specification for VMS versions 4.0
  893. and later.  This is the default style of file naming.
  894.  
  895. UNTRANSLATED@\Kermit-32 will send only the file name and file type. When
  896. receiving a file, Kermit-32 will not perform any conversions on the
  897. file specification, which therefore must be a legal VAX/VMS file specification.
  898. If you want to receive files with long names, use this option.  To transfer
  899. files with VAX/VMS long names between two VMS 4.0-or-later systems, use this
  900. option on both sides.
  901. @End(Description)
  902. @End(Description)
  903.  
  904. @subheading<SET HANDSHAKE>
  905. @index<Handshake>
  906. Syntax: @q<SET HANDSHAKE @i(ooo)>
  907.  
  908. Sets the half duplex line turnaround handshake character to the ASCII
  909. character whose octal value is @i(ooo).  Normally required for communication
  910. with half duplex systems like IBM mainframes in linemode.
  911.  
  912. @subheading<SET IBM_MODE>
  913. @index<IBM>
  914. Syntax: @q<SET IBM_MODE ON @i(or) OFF>
  915.  
  916. For communicating with IBM mainframes over half-duplex linemode connections.
  917. When IBM_MODE is set to ON, Kermit-32 will override the parity and local echo
  918. settings and use odd parity, local echo on, and also enable a handshake
  919. character of XON (control-Q, ASCII 021 octal).  This feature allows Kermit-32
  920. to exchange packets over half duplex connection with systems that
  921. wait for an XON before sending data.
  922.  
  923. The various features selected by this command can be overridden subsequently
  924. by SET PARITY, SET LOCAL_ECHO, and SET HANDSHAKE commands.
  925.  
  926. @Subheading<SET LINE>
  927. Syntax: @q<SET LINE [@i(terminal-name)]>
  928.  
  929. Specify the terminal name to use for file transfer or CONNECT; the
  930. @i<terminal-name> can be up to 255 characters long.
  931. If you issue this command using other than your job's controlling terminal,
  932. you will be running Kermit-32 in @i<local mode>, and you
  933. must log in to the remote system and run Kermit on that side in order to
  934. transfer a file.  If you don't issue this command, Kermit-32 determines whether
  935. it is to run locally or @i<remotely> based on the default terminal line
  936. found when Kermit-32 is started.  Kermit-32 uses a list of logical names to
  937. determine which terminal should be the default terminal line.  The first of
  938. these names which translates to a terminal which is available (i.e., not
  939. allocated by some other process) is used.  The logical names Kermit-32 tries
  940. are KER$COMM, SYS$INPUT, SYS$$OUTPUT, and SYS$COMMAND.  If none of these
  941. translate to an available terminal, Kermit-32 is running @i<detached>, and
  942. a terminal must be specified by the SET LINE command before any actions
  943. can be performed.  If a terminal is found, Kermit-32 is running locally
  944. if this is a terminal other than the one controlling the job (i.e., different
  945. from SYS$COMMAND), otherwise Kermit-32 is running remotely.
  946. You can also select the line directly in the CONNECT command;
  947. the command:
  948. @example(CONNECT TTA0)
  949. is equivalent to:
  950. @begin<example>
  951. SET LINE TTA0
  952. CONNECT
  953. @end<example>
  954.  
  955. If you type SET LINE with no argument, you will deassign any previous
  956. assigned line and revert to remote mode on your job's controlling terminal.
  957.  
  958. @subheading<SET SERVER_TIMEOUT>
  959. Syntax: SET SERVER_TIMEOUT @i<number>
  960.  
  961. This specifies the number of seconds between timeouts during server command
  962. wait, 0 specifies that no timeouts should occur during server command wait.
  963. When a Kermit server times out, it sends a NAK packet.  Some systems cannot
  964. clear piled-@|up NAKs from their input buffers; if you're using such a system
  965. to communicate with a Kermit-32 server, and you expect to be leaving the
  966. server idle for long periods of time, you should use this command to turn off
  967. server command-@|wait timeouts.  This command is also useful when a server is
  968. connected to a modem that is waiting for a call to come in, in which case the
  969. server's NAKs could confuse the modem's autodialer.
  970.  
  971. @subheading<SET TRANSMIT>
  972. Syntax: SET TRANSMIT DELAY @i<integer>, SET TRANSMIT ECHO ON/OFF
  973.  
  974. It is possible to set a few parameters associated with the raw TRANSMIT 
  975. command that vary both what the user sees on the screen as well as the speed of
  976. the transmit.
  977. @begin<description>
  978. SET TRANSMIT DELAY@\
  979. @begin<multiple>
  980. This parameter is the amount of time to delay after each carriage return is
  981. transmitted.  Valid delay values range between 0 (the default) and 9 tenths of
  982. a second.  The format of the command is: SET TRANSMIT DELAY @i<d>
  983. Where @i<d> is a single decimal digit representing tenths of a second.
  984.  
  985. Some remote hosts may not be able to receive the characters as fast as
  986. Kermit-32 can send them.  The TRANSMIT DELAY can be used to slow up the
  987. transfer by adding a slight delay after each line is sent.
  988.  
  989. The transfer also runs slower if the transmit echo is on, and the remote system
  990. is echoing the characters as it receives them.  If the transmit delay is set to
  991. 9 tenths of a second, the remote system is echoing characters, the transmit
  992. echo is on, and the remote system still cannot keep up, then the connection
  993. should be made at a slower baud rate.
  994.  
  995. Conversely, the file transfer speed can be increased by: setting the delay to 
  996. 0 and the echo off, stopping the remote system from echoing the characters it 
  997. receives, and connecting at higher baud rates.
  998. @end<multiple>
  999.  
  1000. SET TRANSMIT ECHO@\
  1001. This command controls what the user sees on the screen during the file
  1002. transfer.  The format of the command is SET TRANSMIT ECHO ON or OFF.
  1003. By default, the transmit echo is left off and the user sees the number of each
  1004. line after it has been transmitted.  With transmit echo on, the user sees 
  1005. whatever the remote system would normally echo back to him while he is typing
  1006. in a file.  Note that turning the echo on typically slows the file transfer 
  1007. down.
  1008. @end<description>
  1009.  
  1010. @Heading<The SHOW Command>
  1011. @Index<SHOW>
  1012. Syntax: @q<SHOW> [@i<option>]
  1013.  
  1014. The SHOW command displays various information:
  1015. @Begin(Description,spread 0.5)
  1016. ALL@\All parameters.
  1017.  
  1018. BLOCK_CHECK_TYPE@\The block check type being requested.
  1019.  
  1020. COMMUNICATIONS@\Parameters affecting the terminal line being used for
  1021. communication.
  1022.  
  1023. DEBUGGING@\Debugging mode in effect, if any.
  1024.  
  1025. DELAY@\The number of seconds Kermit-32 will delay before starting a SEND or
  1026. RECEIVE command when in remote mode.
  1027.  
  1028. ESCAPE@\The current escape character for the CONNECT processing.
  1029.  
  1030. FILE_PARAMETERS@\File blocksize, type, file naming, and incomplete file
  1031. disposition.
  1032.  
  1033. INCOMPLETE_FILE_DISPOSITION@\The action to take when a transfer is aborted.
  1034.  
  1035. LINE@\Terminal line in use.
  1036.  
  1037. LOCAL_ECHO@\Whether characters should be echoed locally when CONNECTed.
  1038.  
  1039. PACKET@\For incoming and outbound packets.
  1040.  
  1041. PARITY@\The parity type in use.
  1042.  
  1043. RECEIVE@\For inbound packets.
  1044.  
  1045. RETRY@\The number of retries to be done on bad packets.
  1046.  
  1047. SEND@\For outbound packets.
  1048.  
  1049. TRANSMIT@\Parameters for TRANSMIT command.
  1050.  
  1051. VERSION@\The program version number of Kermit-32.
  1052. @End(Description)
  1053.  
  1054. @subsection<Program Management Commands>
  1055. @Heading<The HELP Command>
  1056.  
  1057. Syntax: @q<HELP [@i{topic} {@i<subtopic>}]> 
  1058.  
  1059. Typing HELP alone prints a brief summary of Kermit-32 and its commands.
  1060. You can also type
  1061. @Begin(Example)
  1062. HELP @i<command>
  1063. @End(Example)
  1064. for any Kermit-32 command, e.g. "help send" or "help set parity" to get more
  1065. detailed information about a specific command.  The HELP feature depends on
  1066. the Kermit-32 help file being correctly installed on your system.
  1067.  
  1068. @Heading<The EXIT and QUIT Commands>
  1069. @Index<EXIT>@Index<CONTINUE>@Index<Control-C>
  1070. Syntax: @q<EXIT>
  1071.  
  1072. Exit from Kermit-32.
  1073. You can also exit from the Kermit-32 when it is waiting for a command by
  1074. typing a control-Z.  When Kermit-32 is running remotely, two control-Y's
  1075. will abort the transfer, bringing Kermit-32 back to command mode.  The
  1076. two control-Y's must be typed together; if a timeout occurs between them
  1077. the first is ignored.  When Kermit-32 is running locally, two control-Y's
  1078. will stop Kermit-32 and return you to DCL.  You will be able to CONTINUE
  1079. if you do not perform any command which runs a program.  However, after
  1080. continuing, control-A, control-X and control-Z will no longer be accepted
  1081. as commands.
  1082.  
  1083. @Index<QUIT>
  1084. @q<QUIT> is a synonym for EXIT.
  1085.  
  1086. @Heading<The LOG Command>
  1087.  
  1088. Syntax: @q<LOG> [@i<option> [@i<filespec>]]
  1089.  
  1090. Log the specified option to the specified file:
  1091. @begin<description>
  1092. SESSION@\During CONNECT log all characters
  1093. that appear on the screen to the specified file.  During CONNECT, the session
  1094. log can be temporarily turned off during the remote session by typing the
  1095. escape character followed by Q (for Quit logging), and turned on again by
  1096. typing the escape character followed by R (for Resume logging).
  1097.  
  1098. TRANSACTIONS@\During file transfer, log the progress of each file.
  1099. Transaction logging is recommended for long or unattended file transfers, so
  1100. that you don't have to watch the screen.  The log may be inspected after the
  1101. transfer is complete to see what files were transferred and what errors may
  1102. have occurred.
  1103.  
  1104. DEBUGGING@\Log debugging info to the specified file.
  1105. If no SET DEBUGGING command was previously issued, the file will be opened
  1106. and no information written.  If DEBUGGING is turned on (either via the
  1107. SET DEBUGGING command or by typing control-D during a local transfer), the
  1108. packet debugging information will be written to the file.
  1109. Packet format is described in @i<Kermit, A File Transfer Protocol>, Frank da
  1110. Cruz, Digital Press (1987).
  1111. @end<description>
  1112. Any log files are closed when you EXIT or QUIT from Kermit.  You may
  1113. explicitly close a log file and terminate logging by using the LOG command
  1114. without a file specification.
  1115.  
  1116. @Heading<The STATUS Command>
  1117.  
  1118. Syntax: @q<STATUS>
  1119.  
  1120. The current status of Kermit-32 will be displayed.  This includes the number
  1121. of characters that have been sent and received from the remote Kermit. Also
  1122. included is an estimate of the effective baud rate of the transfer. This
  1123. number is not intended to be exact, but only an indication of what range of
  1124. throughput has been provided. 
  1125.  
  1126. @Section<Raw Upload and Download>
  1127.  
  1128. @heading<The TRANSMIT Command>
  1129.  
  1130. Syntax: @q(TRANSMIT @i<file-spec>)
  1131.  
  1132. The TRANSMIT command allows you to upload files "raw" to systems that
  1133. don't have a Kermit program available.  Note that there is no error checking or
  1134. packets involved in this method of file transfer.
  1135.  
  1136. This command does a raw transmit of an ASCII file, one character at a time,
  1137. with carriage returns (no line-feeds) at the end of each line.  It is used with
  1138. Kermit-32 in local mode.  The user must first prepare the remote host to
  1139. receive the file by starting an edit session in input mode.  Then the user can
  1140. escape back to Kermit-32 and issue the TRANSMIT command.  After the transmit is
  1141. finished, the user then CONNECTs back to the remote host again and ends the
  1142. edit session.
  1143.  
  1144. During a file transmit, the following control characters can be used to affect
  1145. the transfer in progress:
  1146. @begin<description>
  1147. CTRL-C@\Cancel the transmit
  1148.  
  1149. CTRL-X@\Cancel the file currently being transmitted
  1150.  
  1151. CTRL-Z@\Cancel the file group currently being transmitted
  1152. @end<description>
  1153.  
  1154. See SET TRANSMIT for information about controlling echo and delays.
  1155.  
  1156. @heading<The LOG SESSION Command>
  1157.  
  1158. Syntax: @q(LOG SESSION @i<file-spec>)
  1159.  
  1160. @index<Raw Download>
  1161. "Raw Download" is the term commonly used to describe the capture of a remote
  1162. file on the local system, without any kind of error detection or correction.
  1163. This allows you to obtain files from remote systems that do not have Kermit,
  1164. but with the risk of loss or corruption of data.
  1165.  
  1166. Kermit-32 provides raw downloading via the LOG SESSION command during CONNECT
  1167. to a remote system.  The session log is described above.  To use session
  1168. logging to capture a file:
  1169. @begin<enumerate>
  1170. Run Kermit on the VAX/VMS system.
  1171.  
  1172. SET LINE to the terminal line through which you will be connected to the remote
  1173. system.
  1174.  
  1175. Perform any required SET commands to condition Kermit for communication with
  1176. the remote system.
  1177.  
  1178. CONNECT to the remote system and log in.
  1179.  
  1180. Condition your job on the remote system not to pause at the end of a
  1181. screenful of text, and give whatever commands may be necessary to achieve a
  1182. "clean" terminal listing -- for instance, disable messages from the system or
  1183. other users.
  1184.  
  1185. Type the appropriate command to have the desired file displayed at the
  1186. terminal, @i<but do not type the terminating carriage return>.  On most
  1187. systems, the command would be "type", on Unix it's "cat".
  1188.  
  1189. Escape back to Kermit-32 and give the LOG SESSION command with the file
  1190. specification where you wish to store the data.
  1191.  
  1192. CONNECT back to the remote system and type a carriage return.  The file will be
  1193. displayed on your screen and recorded in the session log file.
  1194.  
  1195. Escape back to Kermit-32 and give the LOG SESSION command without a file
  1196. specification to close the session log file.
  1197. @end<enumerate>
  1198. The file you specified will contain everything that was typed on your screen.
  1199. You will probably find
  1200. that some editing necessary to remove extraneous prompts, messages, padding
  1201. characters, or terminal escape sequences, or to fill
  1202. in lost or garbled characters.
  1203.  
  1204. Use the TRANSMIT command for raw uploading.
  1205.  
  1206. @section<Installation of Kermit-32>
  1207.  
  1208. VMS Kermit-32 comes in 3 forms: Hex, Macro source, and Bliss source.  Each can
  1209. be used as the basis for installation.
  1210.  
  1211. Before beginning, make a special directory for VMS Kermit and read the files
  1212. @q<VMS*.*> from the Kermit distribution tape into this directory.  Columbia's
  1213. 9-track Kermit tapes are written with blocksize 8192, which is 4 times larger
  1214. than the default tape blocksize for VMS.  You should mount these tapes on the
  1215. VMS system with the following command:
  1216. @example<MOUNT/BLOCK=8192/DENSITY=1600 MTA0: KERMIT>
  1217. (or substitute some other tape drive name for @q<MTA0:>) Do not use the
  1218. @q</FOREIGN> switch.  Once the tape is mounted, you can use normal VMS COPY
  1219. commands to copy the files from the tape.  For instance, if you have defined
  1220. your Kermit directory to have logical name @q<KER:>, you can use the following
  1221. command to copy the VMS Kermit files into this directory:
  1222. @example<$ copy mta0:vms*.* ker:>
  1223. You might also have received Kermit on a TK50 tape cartridge that contains
  1224. a VMS BACKUP saveset, in which case do this to get the files off:
  1225. @begin<enumerate>
  1226. SET DEFAULT to the directory under which you want the various Kermit
  1227. subdirectories created.
  1228.  
  1229. Physically mount the TK50 cartridge, and type "MOUNT $TAPE1/FOREIGN".
  1230.  
  1231. Type "BACKUP/LOG $TAPE1/SAVE [.*]".
  1232. @end<enumerate>
  1233.  
  1234. @subheading<Installation Procedure>
  1235.  
  1236. If you are running a pre-4.0 version of VMS, ignore the following material
  1237. and skip ahead to the section @b<Kermit-32 for Old VMS Versions>.
  1238.  
  1239. At present, there is no VMSINSTAL "kit" for Kermit-32.  However, there is
  1240. a DCL procedure that will do most of the installation work for you.  It is
  1241. called @q<VMSINS.COM>.  To run it, type:
  1242. @example[$ @ux<@@vmsins>]
  1243. It will ask you the question "Rebuild from sources? (YES or NO)".  If you
  1244. reply NO, then the Kermit task image will be decoded from the the
  1245. @q<VMSMIT.HEX> file into @q<KERMIT.EXE>.  If you reply YES, you will be given
  1246. the choice of building the program from the Macro-32 sources (which are
  1247. generated by the Bliss compiler from the original Bliss source code) or from
  1248. the Bliss itself.  All sites can build from Macro, but only those sites with
  1249. Bliss compilers can build from the Bliss.
  1250.  
  1251. After building the @q<KERMIT.EXE> file, the VMSINS procedure copies it into
  1252. @q<SYS$SYSTEM>, and then builds and installs the Kermit-32 help file in the
  1253. system-wide help library (@q<SYS$HELP:HELPLIB.HLB>) so that users can get help
  1254. for Kermit by typing "help kermit" at the DCL prompt, and it will also build
  1255. and install @q<SYS$HELP:KERMIT.HLP> so that the HELP command will work from
  1256. within Kermit.
  1257.  
  1258. @subheading<HEX, Macro, or Bliss?>
  1259.  
  1260. The @q<VMSMIT.HEX> file is built from @q<KERMIT.EXE> under the oldest version
  1261. of VMS that the developers have access to (for example VMS 4.5).  If you are
  1262. running that version of VMS or later, then you should reply NO to the
  1263. "Rebuild from sources? (YES or NO)" question.
  1264.  
  1265. If you are running an older version of VMS than the one under which the Kermit
  1266. that forms the basis of the hex file was linked, then you will not be able to
  1267. run it on your VMS system, because of a runtime library conflict.  In that
  1268. case, you should reply YES to the question, and VMSINS will try to build the
  1269. program from the Macro-32 assembly language source code using your system's
  1270. MACRO command.  This should build a working version of Kermit-32 on all
  1271. VAX/VMS systems 4.0 or later.
  1272.  
  1273. The only reason for building from the Bliss source is if you have made changes
  1274. to Kermit-32.  It is recommended that you only work on the Bliss source, and
  1275. not the Macro source.  If you make changes to the macro source, there is no
  1276. way to carry them forward to the Bliss code, which is the true source code for
  1277. the program.  If you do intend to make changes to the Bliss code, be sure to 
  1278. contact Columbia University's Kermit Distribution Center first to make sure
  1279. you are working from the latest release and that nobody else has already done,
  1280. or is working on, the same thing.
  1281.  
  1282. @subheading<Kermit-32 for Old VMS Versions>
  1283.  
  1284. If you are running a pre-4.0 version of VAX/VMS, then you will have to install
  1285. a very old version (3.1) of Kermit-32, rather than the current version, until
  1286. you upgrade your VMS version.  To use
  1287. version 3.1 of VMS Kermit:
  1288. @begin<enumerate>
  1289. Rename @q<VMSMIT.HEX> to @q<VMSV33.HEX>
  1290.  
  1291. Rename @q<VMSV31.HEX> to @q<VMSMIT.HEX>
  1292.  
  1293. Run the VMSINS procedure and reply NO to the "Rebuild from source" question.
  1294. @end<enumerate>
  1295. Note that the help files which are installed apply to the current release,
  1296. @value<-vmsversion>, rather than to version 3.3.
  1297.  
  1298. @subheading<Defining a Kermit Command>
  1299.  
  1300. You should define a system-wide symbol for Kermit as a "foreign command",
  1301. for example in your @q<SYS$MANAGER:SYLOGIN.COM> (system-wide login command)
  1302. file, like this:
  1303. @example[KERMIT :== $SYS$SYSTEM:KERMIT.EXE]
  1304. so that users can run Kermit just by typing its name.
  1305.  
  1306. @subheading<Files>
  1307.  
  1308. Kermit-32 is built from a number of BLISS-32 sources and one  MACRO-32  source.
  1309. In  order  to  make  it  possible for sites without BLISS-32 to build, MACRO-32
  1310. sources generated by BLISS-32 are also included for all of the  BLISS  modules.
  1311. The following files are distributed as part of Kermit-32:
  1312. @begin<description>
  1313. @q<VMSTT.BLI>@\Common BLISS source for the terminal text output support.
  1314.  
  1315. @q<VMSGLB.BLI>@\Common BLISS source for the global storage for VMSMSG.BLI.
  1316.  
  1317. @q<VMSMSG.BLI>@\Common BLISS source for the protocol handling module.
  1318.  
  1319. @q<VMSCOM.REQ>@\Common BLISS require file which defines various common
  1320. parameters.  This is required by VMSMSG.BLI.  This file must be renamed to
  1321. KERCOM.REQ.
  1322.  
  1323. @q<VMSMIT.BWR>@\"Beware File" for Kermit-32 (read it!).
  1324.  
  1325. @q<VMSMIT.BLI>@\BLISS-32 source for the command parser, and some basic support
  1326. routines.
  1327.  
  1328. @q<VMSFIL.BLI>@\BLISS-32 source for the file I/O.
  1329.  
  1330. @q<VMSTRM.BLI>@\BLISS-32 source for the terminal processing.  This handles the
  1331. driving of the terminal line for the transfers and the connect command
  1332. processing.
  1333.  
  1334. @q<VMSSYS.BLI>@\System interface routines for the Kermit generic command
  1335. processing.
  1336.  
  1337. @q<VMSGEN.MAR>@\Macro-32 source file that contains the REMOTE command text
  1338. that is given to VMS.  Sites desiring to change what DCL commands are used to
  1339. process the various generic server commands can make those changes in this
  1340. source.  This also contains the text of the help message returned in response
  1341. to the server generic help command.
  1342.  
  1343. @q<VMSERR.MSG>@\MESSAGE source for error messages used by VAX/VMS Kermit.
  1344.  
  1345. @q<VMSERR.REQ>@\BLISS-32 require file which defines the error  codes.  This  is
  1346. REQUIREd by the BLISS-32 sources.
  1347.  
  1348. @q<VMSMIT.MSS>@\SCRIBE source file for VMSMIT.DOC (this document).
  1349.  
  1350. @q<VMSMIT.RNH>@\RUNOFF source for the help files for VAX/VMS Kermit.  When
  1351. this is run through RUNOFF with /VARIANT=SYSTEM, it produces a .HLP
  1352. (VMSSYS.HLP) file suitable for inserting into the system help library
  1353. (SYS$HELP:HELPLIB.HLB) to provide a KERMIT topic for the system HELP command.
  1354. When run through RUNOFF without the /VARIANT=SYSTEM, it produces a .HLP file
  1355. (VMSUSR.HLP) to be stored on SYS$HELP: for use by the Kermit HELP command.
  1356.  
  1357. @q<VMSSYS.HLP>@\RUNOFF output file for system wide Kermit HELP.
  1358.  
  1359. @q<VMSUSR.HLP>@\RUNOFF output file for Kermit's HELP command.
  1360.  
  1361. @q<VMSREN.COM>@\Command file to rename VMS*.* to KER*.*.
  1362.  
  1363. @q<VMSINS.COM>@\Command file to build and install VAX/VMS Kermit.
  1364.  
  1365. @q<VMSMIT.HEX>@\A hexified version of .EXE file for VMS Kermit.  This file can
  1366. be dehexified using the supplied program.  In the hexified form, the file
  1367. should be transferable over any medium which handles normal text.  This is the
  1368. most reliable copy of the executable version of VMS Kermit.
  1369.  
  1370. @q<VMSHEX.MAR>@\Source for the hexification program.  This is the program
  1371. which was used to produce VMSMIT.HEX.  It can also be used to produce hexified
  1372. version of any (or at least almost any) Files-11 file.  The dehexification
  1373. program should then be able to reproduce a copy of the original file with the
  1374. file parameters correctly set.  Note that the format used for the hexified
  1375. files is basically Intel hex format.  There are some additional records used
  1376. to store the record format, etc.  Also, the file name as typed to the prompt
  1377. from VMSHEX is stored in the hexified version of the file for use by the
  1378. dehexification program.  By doing this, it is possible to store more than one
  1379. binary file with a single hexified file.
  1380.  
  1381. @q<VMSDEH.MAR>@\Source for the dehexification program.
  1382.  
  1383. @q<VMSV31.*>@\Version VMS Kermit, the last version that will run under release
  1384. 3.x of VMS.  Versions 3.2 and later require VMS release 4.0 or later.
  1385.  
  1386. @q<VMSV3x.MEM>@\ocumentation on the changes between releases 3.1 and 3.1, and
  1387. 3.2 and 3.3 of Kermit-32, and additional installation information.
  1388. @end<description>
  1389.  
  1390. @subheading<OTHER INSTALLATION CONSIDERATIONS>
  1391.  
  1392. As distributed, Kermit-32 should work on any VAX/VMS system (version 4.0 and
  1393. later).  Customization is possible with or without a BLISS-32 compiler.
  1394. Default parameter values may be changed by changing the appropriate LITERALs
  1395. in the BLISS-32 source for VMSMSG, or the actual values which are stored in
  1396. the routine MSG_INIT in the MACRO-32 source for VMSMSG.
  1397.  
  1398. Sites can also easily change the commands which are used for processing the
  1399. generic server functions (REMOTE commands when running as a server).  The text
  1400. which makes up these commands is in the file VMSGEN.MAR, along with the text
  1401. of the REMOTE HELP message.  This allows a site to make use of local programs
  1402. for performing some of the commands (perhaps using FINGER to perform the WHO
  1403. command, etc.).
  1404.  
  1405. If you want to allow your users to assign external terminal lines for
  1406. connecting to remote systems from the VAX, e.g. by dialing out, you will have
  1407. to configure those lines to allow the desired access.  Otherwise, users will
  1408. get a message like "No privilege for attempted operation" when they do a SET
  1409. LINE command.  Sample commands for terminal TXA0: might include:
  1410. @example<$ SET PROTECTION=(W:R) TXA0:/DEVICE>
  1411. or 
  1412. @example<$ SET PROTECTION=(W:RWLP)/DEVICE/OWNER=[1,4] TXA0:>
  1413. or
  1414. @begin<example>
  1415. $ SET ACL/OBJECT=DEVICE/ACL=(IDENTIFIER=INTERACTIVE,OPTIONS=NONE,-
  1416.   ACCESS=READ+WRITE) TXA0:
  1417. @end<example>
  1418. Consult  your VAX/VMS system manager's manual for the ramifications (especially
  1419. on security) of each of these commands.
  1420.