home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / d / k6oaaa.hlp < prev    next >
Text File  |  2020-01-01  |  22KB  |  474 lines
  1. OS-9/68000 Kermit Installation Manual:
  2.  
  3. Program by:    Roberto Bagnara, University of Bologna, Italy
  4.                Steve Williams, University of Texas at Austin, USA
  5. Language:      68000 Assembler
  6. Documentation: Roberto Bagnara -- Kermit68K User's Manual
  7.                Steve Williams  -- Kermit68K/OS9 Installation Manual
  8. Version:       1.0.00
  9. Date:          July, 1987
  10.  
  11. Introduction:
  12.  
  13. OS-9/68000 Kermit (hereafter to be known as Kermit68K/OS9) is an implementation
  14. of Kermit68K for microcomputer systems using the OS-9/68000 operating system
  15. from Microware.  Kermit68K is patterned after UNIX C-Kermit, however it is
  16. written completely in Motorola 68000 assembly language to allow easy
  17. portability to 68000 based systems without C compilers.
  18.  
  19. Kermit68K/OS9 was written to fulfill a need for reliable file transfer between
  20. the OS-9 operating system running on an Atari 520ST and several other systems
  21. in a laboratory environment.  While there is a Kermit implementation currently
  22. available for OS-9 systems, it is lacking in functionality.  Also, since I do
  23. not have access to the Microware C compiler, I needed a version of Kermit
  24. written in the native assembly language of the 68000.
  25.  
  26. The bulk of the program was written between May 1986 and June 1987 by Roberto
  27. Bagnara of the Physics Department at the University of Bologna, Italy.  He is
  28. responsible for the overall user-interface routines, as well as the Kermit
  29. protocol routines.  Kermit68K is written in a modular fashion quite similar to
  30. the UNIX C-Kermit after which it is patterned, to ease portability to various
  31. operating systems running on 68000 based microcomputers.  The OS-9 system
  32. specific modifications were performed by Steve Williams of the Electrical and
  33. Computer Engineering Department at the University of Texas at Austin.
  34.  
  35. This document discusses only the differences between generic Kermit68K and
  36. Kermit68K/OS9, as well as installation procedure for Kermit68K/OS9. The
  37. complete users guide for Kermit68K (and Kermit68K/OS9) is available as
  38. K6GMAN.DOC.
  39.  
  40.  
  41. Kermit68K/OS9 Capabilities At A Glance:
  42.  
  43.   Local operation:                   Yes
  44.   Remote operation:                  Yes
  45.   Login scripts:                     No
  46.   Transfer text files:               Yes
  47.   Transfer binary files:             Yes
  48.   Wildcard send:                     Yes
  49.   File transfer interruption:        Yes
  50.   Filename collision avoidance:      Yes
  51.   Can time out:                      Yes
  52.   8th-bit prefixing:                 Yes
  53.   Repeat count prefixing:            Yes
  54.   Alternate block checks:            Yes
  55.   Terminal emulation:                None
  56.   Communication settings:            Yes
  57.   Transmit BREAK:                    Yes (depending on serial driver)
  58.   Support for dialout modems:        No
  59.   IBM mainframe communication:       No
  60.   Transaction logging:               No
  61.   Session logging:                   No
  62.   Debug logging:                     No
  63.   Packet logging:                    No
  64.   Act as server:                     No
  65.   Talk to server:                    Yes
  66.   Advanced server functions:         No
  67.   Local file management:             Yes
  68.   Command/Init files:                Yes
  69.   File attributes packets:           No
  70.   Command macros:                    Yes
  71.   Raw file transmit:                 No
  72.  
  73.  
  74. Installing Kermit68K on an OS-9/68000 system:
  75.  
  76. What follows is a discussion of how to get Kermit68K/OS9 installed on your
  77. system. In order to run Kermit, your OS-9 system will require the following:
  78.  
  79.   1.  A console device and driver (hereafter referred to as /term)
  80.   2.  A serial port and driver (hereafter referred to as /t1)
  81.   3.  Diskspace.  About 80K of free space to install Kermit.  However, if
  82.       you want to work with the source code, you will need at least 600K of
  83.       free space (and this is very tight)
  84.  
  85. The Kermit68K/OS9 executable file is approximately 20K, and the program needs
  86. about 8K of variable and stack space.  It is not an extremely memory hungry
  87. program, and if the standard input and output paths are redirected, it can be
  88. run in the background to transfer files while you do other work.
  89.  
  90. The Kermit68K/OS9 distribution contains the following files:
  91.  
  92. Kermit68K and Kermit68K/OS9 documentation files:
  93.  
  94.   File name         Contents
  95.   ---------         --------
  96.   k6aaaa.hlp        A general guide to the file naming conventions used.
  97.   k6aaaa.bwr        Report of known bugs and restriction in Kermit68K
  98.   k6gman.doc        The user's manual for Kermit68K
  99.   k6oaaa.hlp        This file
  100.   k6oaaa.bwr        A companion file describing known problems/limitations of
  101.                     Kermit68K/OS9.
  102.   k6oimg.sre        The Kermit68K/OS9 executable (BINEX format)
  103.                     (see the warning below)
  104.  
  105. Kermit68K/OS9 Source Code files:
  106.  
  107.   File name         Contents
  108.   ---------         --------
  109.   k6ocmd.asm        The interactive command line interpreter
  110.   k6ocm2.asm        SET commands module
  111.   k6ocm3.asm        REMOTE and SHOW commands
  112.   k6ocm4.asm        Command line options handler
  113.   k6octb.asm        The command tables
  114.   k6odef.asm        Variable definitions
  115.   k6oiof.asm        High-level I/O subroutines
  116.   k6omai.asm        The main program
  117.   k6omak.bld        The makefile (will be renamed 'makefile' by the renamer)
  118.   k6opro.asm        The Kermit protocol switcher
  119.   k6opsf.asm        Command parser subroutines
  120.   k6optf.asm        Protocol functions
  121.   k6opt2.asm        Low-level protocol functions
  122.   k6ostr.asm        Message strings
  123.   k6osys.asm        OS-9/68000 operating system interface routines.
  124.   k6outf.asm        Utility subroutines
  125.   k6oren.com        A shell script for renaming all of the source files to
  126.                     be compatible with the makefile.
  127.  
  128. 1.  Installing the Kermit68K/OS9 Executable file:
  129.  
  130. For ease of installation of Kermit, there is a BINEX format file containing the
  131. executable module available as k6oimg.sre.  The BINEX format is a straight text
  132. file which encodes each byte as two printable characters.  This is the only file
  133. that need be downloaded to the OS-9 system in order to install Kermit, after
  134. which Kermit itself can be used to download the rest of the files.
  135.  
  136.                     *** WARNING ***   *** WARNING ***
  137.  
  138. The k6oimg.sre file was built from sources not completely up to date, so
  139. if you use it remember that the address of the Kermit68K main author
  140. (Roberto Bagnara) reported by the command SHOW VERSION is NOT correct.
  141. The correct address is Bagnara@Iboinfn over Bitnet.
  142.  
  143.                     *** WARNING ***   *** WARNING ***
  144.  
  145. Anyone attempting to install Kermit will need to have some means of downloading
  146. a raw text file onto the OS-9 system.  The k9 utility provided with the
  147. Microware OS-9/68000 Port-Pack is one way to accomplish this.  Another
  148. possibility is to use another microcomputer as a terminal to your OS-9 system
  149. and use the BUILD utility of OS-9.  Here is a possible sequence of commands to
  150. download the kermit.os9 file to an OS-9 system from another system:
  151.  
  152.   os9> build k6oimg.sre </t1 >/t1
  153.   os9> exbin k6oimg.sre Kermit
  154.   os9> attr -peewr Kermit
  155.   os9> copy kermit /d0/cmds/Kermit
  156.  
  157. The first command will re-direct the input and output of the build utility to
  158. the external terminal line, which should be connected to the other system.  At
  159. this point, you should instruct the other (non OS-9) system to list the file to
  160. the serial port.  Many terminal emulation programs have this capability.
  161.  
  162. The EXBIN command converts the S-Record file to raw binary, and the ATTR command
  163. makes the program executable.  You should substitute the name of your execution
  164. directory for the '/d0/cmds'
  165.  
  166. If your system is like mine and your extra serial port is named '/t1', then the
  167. command 'kermit' will start up Kermit68K/OS9 in the interactive mode.  If your
  168. serial port has a different name, you will have to use the command 'kermit -l
  169. /device' where '/device' is the name of your serial port.  As an alternative,
  170. you can make a kermit.ini file which contains the command 'SET LINE /device'
  171. which will also accomplish the desired effect.  A third alternative is to
  172. download the source code and modify the default line name in the k68str module.
  173.  
  174. If you do not wish to work with the Kermit source code, you are finished.  See
  175. the k6gman.doc file for complete user instructions.
  176.  
  177.  
  178. 2.  Acquiring the OS-9/68000 Kermit source code.
  179.  
  180. All of the OS-9/68000 Kermit source code is compatible with the standard OS-9
  181. assembler, 'R68'.  The only software needed to build OS-9/68000 Kermit is the
  182. standard R68 assembler and L68 linker.  The MAKE utility provided by Microware
  183. is also helpful, and a makefile is included with the source code.  The Kermit
  184. source files will require approximately 500 K-bytes of disk space.  This means
  185. that single-sided disks are out, and double-sided disks are tight.  My system
  186. has double-sided 3.5" disks each holding 650 Kbytes.  The sources take up
  187. almost all of this space.
  188.  
  189. Create a subdirectory called 'Kermit' and change to it with the chd command.
  190. Also, make another subdirectory 'Kermit/Rels' to hold the assembler
  191. relocatables.  Then, using Kermit, download all the source files listed above
  192. into the Kermit directory.
  193.  
  194. The 'k6oren.com' file is a Shell script (for OS-9) that will rename all of the
  195. source files to make them compatible with the makefile.  You should only run
  196. this file once.  Once you have downloaded all of the source files listed above
  197. and renamed them, you should have the following in your kermit directory:
  198.  
  199.   Rels      k68cmd.a  k68cm2.a  k68cm3.a  k68cm4.a  k68ctb.a
  200.   k68def.a  k68iof.a  k68mai.a  k68pro.a  k68psf.a  k68ptf.a
  201.   k68pt2.a  k68str.a  k68sys.a  k68utf.a  makefile
  202.  
  203. To build Kermit from the sources, you need to edit the makefile to change the
  204. definitions of the macros SDIR, RDIR, and LFLAGS to reflect the
  205. configuration of your system.  The one supplied assumes that the system files
  206. are on floppy disk /d0.  SDIR is the directory in which to find the sources
  207. (usually '.').  RDIR is the directory in which to place the relocatable
  208. '.r' files (usually Rels).  LFLAGS locates the system link library.  The
  209. Kermit executable file will be left in your current execution directory.
  210.  
  211. Also, you need to make a DefsFile that looks like the following:
  212.  
  213.           ifp1
  214.           use       /d0/Defs/oskdefs.d
  215.           use       /d0/Defs/systype.d
  216.           endc
  217.  
  218. Again, supply the correct pathnames to these two files for your system.
  219. Once this is accomplished, just type 'MAKE' to build Kermit from the sources.
  220. On my system with two floppy disk drives, this takes about 15 minutes.
  221.  
  222. Please report all problems and suggestions for improvement of the OS9 version
  223. to Steve Williams.
  224. My addresses are:
  225.  
  226. Usenet, Arpanet:  {seismo|gatech|ihnp4}!ut-sally!stevew
  227.  
  228. U.S. Snail:       1071 Clayton Lane #106
  229.                   Austin, TX  78723
  230.  
  231. GEnie:            SPWilliams
  232.  
  233. Problems and suggestions concerning all the versions of Kermit68K should
  234. be addressed to Roberto Bagnara (Bagnara@Iboinfn over Bitnet).
  235.  
  236. (End of K6OAAA.HLP)
  237. 15-Jul-87 02:50:47-EDT,11268;000000000001
  238. Return-Path: <BAGNARA%IBOINFN.BITNET@CUVMA.COLUMBIA.EDU>
  239. Received: from CUVMA.COLUMBIA.EDU by CU20B.COLUMBIA.EDU with TCP; Wed 15 Jul 87 02:50:43-EDT
  240. Received: from IBOINFN.BITNET (BAGNARA) by CUVMA.COLUMBIA.EDU (Mailer X1.24)
  241.  with BSMTP id 3262; Wed, 15 Jul 87 02:49:51 EDT
  242. Date:     Wed, 15 Jul 87 08:47 N
  243. From:     <BAGNARA@IBOINFN.BITNET> (Roberto Bagnara)
  244. Subject:  Kermit68K release 1.0, file K6OAAA.HLP
  245. To:       sy.fdc@cu20b.columbia.edu
  246. X-Original-To:  FRANK
  247.  
  248. OS-9/68000 Kermit Installation Manual:
  249.  
  250. Program by:    Roberto Bagnara, University of Bologna, Italy
  251.                Steve Williams, University of Texas at Austin, USA
  252. Language:      68000 Assembler
  253. Documentation: Roberto Bagnara -- Kermit68K User's Manual
  254.                Steve Williams  -- Kermit68K/OS9 Installation Manual
  255. Version:       1.0.00
  256. Date:          July, 1987
  257.  
  258. Introduction:
  259.  
  260. OS-9/68000 Kermit (hereafter to be known as Kermit68K/OS9) is an implementation
  261. of Kermit68K for microcomputer systems using the OS-9/68000 operating system
  262. from Microware.  Kermit68K is patterned after UNIX C-Kermit, however it is
  263. written completely in Motorola 68000 assembly language to allow easy
  264. portability to 68000 based systems without C compilers.
  265.  
  266. Kermit68K/OS9 was written to fulfill a need for reliable file transfer between
  267. the OS-9 operating system running on an Atari 520ST and several other systems
  268. in a laboratory environment.  While there is a Kermit implementation currently
  269. available for OS-9 systems, it is lacking in functionality.  Also, since I do
  270. not have access to the Microware C compiler, I needed a version of Kermit
  271. written in the native assembly language of the 68000.
  272.  
  273. The bulk of the program was written between May 1986 and June 1987 by Roberto
  274. Bagnara of the Physics Department at the University of Bologna, Italy.  He is
  275. responsible for the overall user-interface routines, as well as the Kermit
  276. protocol routines.  Kermit68K is written in a modular fashion quite similar to
  277. the UNIX C-Kermit after which it is patterned, to ease portability to various
  278. operating systems running on 68000 based microcomputers.  The OS-9 system
  279. specific modifications were performed by Steve Williams of the Electrical and
  280. Computer Engineering Department at the University of Texas at Austin.
  281.  
  282. This document discusses only the differences between generic Kermit68K and
  283. Kermit68K/OS9, as well as installation procedure for Kermit68K/OS9. The
  284. complete users guide for Kermit68K (and Kermit68K/OS9) is available as
  285. K6GMAN.DOC.
  286.  
  287.  
  288. Kermit68K/OS9 Capabilities At A Glance:
  289.  
  290.   Local operation:                   Yes
  291.   Remote operation:                  Yes
  292.   Login scripts:                     No
  293.   Transfer text files:               Yes
  294.   Transfer binary files:             Yes
  295.   Wildcard send:                     Yes
  296.   File transfer interruption:        Yes
  297.   Filename collision avoidance:      Yes
  298.   Can time out:                      Yes
  299.   8th-bit prefixing:                 Yes
  300.   Repeat count prefixing:            Yes
  301.   Alternate block checks:            Yes
  302.   Terminal emulation:                None
  303.   Communication settings:            Yes
  304.   Transmit BREAK:                    Yes (depending on serial driver)
  305.   Support for dialout modems:        No
  306.   IBM mainframe communication:       No
  307.   Transaction logging:               No
  308.   Session logging:                   No
  309.   Debug logging:                     No
  310.   Packet logging:                    No
  311.   Act as server:                     No
  312.   Talk to server:                    Yes
  313.   Advanced server functions:         No
  314.   Local file management:             Yes
  315.   Command/Init files:                Yes
  316.   File attributes packets:           No
  317.   Command macros:                    Yes
  318.   Raw file transmit:                 No
  319.  
  320.  
  321. Installing Kermit68K on an OS-9/68000 system:
  322.  
  323. What follows is a discussion of how to get Kermit68K/OS9 installed on your
  324. system. In order to run Kermit, your OS-9 system will require the following:
  325.  
  326.   1.  A console device and driver (hereafter referred to as /term)
  327.   2.  A serial port and driver (hereafter referred to as /t1)
  328.   3.  Diskspace.  About 80K of free space to install Kermit.  However, if
  329.       you want to work with the source code, you will need at least 600K of
  330.       free space (and this is very tight)
  331.  
  332. The Kermit68K/OS9 executable file is approximately 20K, and the program needs
  333. about 8K of variable and stack space.  It is not an extremely memory hungry
  334. program, and if the standard input and output paths are redirected, it can be
  335. run in the background to transfer files while you do other work.
  336.  
  337. The Kermit68K/OS9 distribution contains the following files:
  338.  
  339. Kermit68K and Kermit68K/OS9 documentation files:
  340.  
  341.   File name         Contents
  342.   ---------         --------
  343.   k6aaaa.hlp        A general guide to the file naming conventions used.
  344.   k6aaaa.bwr        Report of known bugs and restriction in Kermit68K
  345.   k6gman.doc        The user's manual for Kermit68K
  346.   k6oaaa.hlp        This file
  347.   k6oaaa.bwr        A companion file describing known problems/limitations of
  348.                     Kermit68K/OS9.
  349.   k6oimg.sre        The Kermit68K/OS9 executable (BINEX format)
  350.  
  351. Kermit68K/OS9 Source Code files:
  352.  
  353.   File name         Contents
  354.   ---------         --------
  355.   k6ocmd.asm        The interactive command line interpreter
  356.   k6ocm2.asm        SET commands module
  357.   k6ocm3.asm        REMOTE and SHOW commands
  358.   k6ocm4.asm        Command line options handler
  359.   k6octb.asm        The command tables
  360.   k6odef.asm        Variable definitions
  361.   k6oiof.asm        High-level I/O subroutines
  362.   k6omai.asm        The main program
  363.   k6omak.bld        The makefile (will be renamed 'makefile' by the renamer)
  364.   k6opro.asm        The Kermit protocol switcher
  365.   k6opsf.asm        Command parser subroutines
  366.   k6optf.asm        Protocol functions
  367.   k6opt2.asm        Low-level protocol functions
  368.   k6ostr.asm        Message strings
  369.   k6osys.asm        OS-9/68000 operating system interface routines.
  370.   k6outf.asm        Utility subroutines
  371.   k6oren.com        A shell script for renaming all of the source files to
  372.                     be compatible with the makefile.
  373.  
  374. 1.  Installing the Kermit68K/OS9 Executable file:
  375.  
  376. For ease of installation of Kermit, there is a BINEX format file containing the
  377. executable module available as k6oimg.sre.  The BINEX format is a straight text
  378. file which encodes each byte as two printable characters.  This is the only file
  379. that need be downloaded to the OS-9 system in order to install Kermit, after
  380. which Kermit itself can be used to download the rest of the files.
  381.  
  382. Anyone attempting to install Kermit will need to have some means of downloading
  383. a raw text file onto the OS-9 system.  The k9 utility provided with the
  384. Microware OS-9/68000 Port-Pack is one way to accomplish this.  Another
  385. possibility is to use another microcomputer as a terminal to your OS-9 system
  386. and use the BUILD utility of OS-9.  Here is a possible sequence of commands to
  387. download the kermit.os9 file to an OS-9 system from another system:
  388.  
  389.   os9> build k6oimg.sre </t1 >/t1
  390.   os9> exbin k6oimg.sre Kermit
  391.   os9> attr -peewr Kermit
  392.   os9> copy kermit /d0/cmds/Kermit
  393.  
  394. The first command will re-direct the input and output of the build utility to
  395. the external terminal line, which should be connected to the other system.  At
  396. this point, you should instruct the other (non OS-9) system to list the file to
  397. the serial port.  Many terminal emulation programs have this capability.
  398.  
  399. The EXBIN command converts the S-Record file to raw binary, and the ATTR command
  400. makes the program executable.  You should substitute the name of your execution
  401. directory for the '/d0/cmds'
  402.  
  403. If your system is like mine and your extra serial port is named '/t1', then the
  404. command 'kermit' will start up Kermit68K/OS9 in the interactive mode.  If your
  405. serial port has a different name, you will have to use the command 'kermit -l
  406. /device' where '/device' is the name of your serial port.  As an alternative,
  407. you can make a kermit.ini file which contains the command 'SET LINE /device'
  408. which will also accomplish the desired effect.  A third alternative is to
  409. download the source code and modify the default line name in the k68str module.
  410.  
  411. If you do not wish to work with the Kermit source code, you are finished.  See
  412. the k6gman.doc file for complete user instructions.
  413.  
  414.  
  415. 2.  Acquiring the OS-9/68000 Kermit source code.
  416.  
  417. All of the OS-9/68000 Kermit source code is compatible with the standard OS-9
  418. assembler, 'R68'.  The only software needed to build OS-9/68000 Kermit is the
  419. standard R68 assembler and L68 linker.  The MAKE utility provided by Microware
  420. is also helpful, and a makefile is included with the source code.  The Kermit
  421. source files will require approximately 500 K-bytes of disk space.  This means
  422. that single-sided disks are out, and double-sided disks are tight.  My system
  423. has double-sided 3.5" disks each holding 650 Kbytes.  The sources take up
  424. almost all of this space.
  425.  
  426. Create a subdirectory called 'Kermit' and change to it with the chd command.
  427. Also, make another subdirectory 'Kermit/Rels' to hold the assembler
  428. relocatables.  Then, using Kermit, download all the source files listed above
  429. into the Kermit directory.
  430.  
  431. The 'k6oren.com' file is a Shell script (for OS-9) that will rename all of the
  432. source files to make them compatible with the makefile.  You should only run
  433. this file once.  Once you have downloaded all of the source files listed above
  434. and renamed them, you should have the following in your kermit directory:
  435.  
  436.   Rels      k68cmd.a  k68cm2.a  k68cm3.a  k68cm4.a  k68ctb.a
  437.   k68def.a  k68iof.a  k68mai.a  k68pro.a  k68psf.a  k68ptf.a
  438.   k68pt2.a  k68str.a  k68sys.a  k68utf.a  makefile
  439.  
  440. To build Kermit from the sources, you need to edit the makefile to change the
  441. definitions of the macros SDIR, RDIR, and LFLAGS to reflect the
  442. configuration of your system.  The one supplied assumes that the system files
  443. are on floppy disk /d0.  SDIR is the directory in which to find the sources
  444. (usually '.').  RDIR is the directory in which to place the relocatable
  445. '.r' files (usually Rels).  LFLAGS locates the system link library.  The
  446. Kermit executable file will be left in your current execution directory.
  447.  
  448. Also, you need to make a DefsFile that looks like the following:
  449.  
  450.           ifp1
  451.           use       /d0/Defs/oskdefs.d
  452.           use       /d0/Defs/systype.d
  453.           endc
  454.  
  455. Again, supply the correct pathnames to these two files for your system.
  456. Once this is accomplished, just type 'MAKE' to build Kermit from the sources.
  457. On my system with two floppy disk drives, this takes about 15 minutes.
  458.  
  459. Please report all problems and suggestions for improvement of the OS9 version
  460. to Steve Williams.
  461. My addresses are:
  462.  
  463. Usenet, Arpanet:  {seismo|gatech|ihnp4}!ut-sally!stevew
  464.  
  465. U.S. Snail:       1071 Clayton Lane #106
  466.                   Austin, TX  78723
  467.  
  468. GEnie:            SPWilliams
  469.  
  470. Problems and suggestions concerning all the versions of Kermit68K should
  471. be addressed to Roberto Bagnara (Bagnara@Iboinfn over Bitnet).
  472.  
  473. (End of K6OAAA.HLP)
  474.