home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / z / zlink / GUIDE next >
Encoding:
Text File  |  1997-06-01  |  14.4 KB  |  342 lines
  1.  
  2. ___________________
  3.  
  4. ZeriLink user guide
  5. ___________________
  6.  
  7.  
  8. User, please note
  9. =================
  10.  
  11. ZeriLink is Freeware, i.e. it is free software.
  12.  
  13. Copyright notice
  14. ================
  15.  
  16. The copyright (c) of this program belongs to John Kortink. All rights are
  17. reserved.
  18.  
  19. You may not change this program (except for documented configuration
  20. changes). You may not use any part of this program in any other program or
  21. product without my written approval. You may spread this program freely, but
  22. only in complete and unchanged form, and only against bare distribution costs
  23. (if any). This program is provided 'as is'. No fitness of this program for
  24. any particular purpose is implied. Using this program is entirely at your own
  25. risk.
  26.  
  27.  
  28. //
  29. //
  30. // Introduction
  31. //
  32. //
  33.  
  34. ZeriLink provides a robust and fast (up to 800kB/sec) file transfer link
  35. between two Acorn machines, two IBM compatible machines, or one Acorn and one
  36. IBM compatible machine. ZeriLink's only requirement is that both machines
  37. have a parallel port that supports either ECP or PS/2 mode. Most Acorn and
  38. IBM compatible machines support at least one of these parallel port modes.
  39.  
  40. ZeriLink has been developed on an Acorn RISC PC and a generic IBM compatible
  41. 'clone' PC. Both machines have a parallel port that supports both ECP and
  42. PS/2 modes. Apart from a successful link between a HP Vectra machine and my
  43. Acorn RISC PC, I currently don't know about other combinations that will
  44. work, so I cannot give definite guarantees that ZeriLink will work on your
  45. Acorn or IBM compatible machine(s). The Acorn RISC PC should work in either
  46. ECP or PS/2 mode. The Acorn A5000 and Acorn A4 will *probably* work in PS/2
  47. mode (but will not work in ECP mode). Once I get positive results from users
  48. I will compile a list of compatible machine types.
  49.  
  50. The hardware side of the link simply consists of a suitably wired parallel
  51. cable, which is plugged into both machines' parallel port. The ZeriLink
  52. software provides convenient commands to transfer files between the two
  53. machines, across this cable.
  54.  
  55. In the following, IBM compatible machines will mostly be referred to by 'IBM'
  56. and Acorn machines by 'Acorn'.
  57.  
  58.  
  59. //
  60. //
  61. // Hardware requirements
  62. //
  63. //
  64.  
  65. Acorn
  66. -----
  67. - A parallel port with ECP or PS/2 support.
  68.  
  69. IBM
  70. ---
  71. - A parallel port with ECP or PS/2 support.
  72. - An Intel 80386 or compatible processor.
  73. - An environment with DPMI memory management support.
  74.  
  75. Additional
  76. ----------
  77. - A parallel cable wired to specifications. See below.
  78.  
  79.  
  80. //
  81. //
  82. // Using ZeriLink
  83. //
  84. //
  85.  
  86. On an Acorn, the 'ZLink' module and its configuration file 'LinkConfig'
  87. should be installed, preferrably in the !Boot sequence. The 'ZLink' module
  88. provides the 'LinkT', 'LinkR' and 'LinkConfigure' *-commands. Acorn
  89. installation and use is discussed below.
  90.  
  91. On an IBM, a configuration file called 'Link.CNF' and two executable files
  92. called 'LinkT.EXE' and 'LinkR.EXE' should be installed in one of the
  93. directories pointed to by the PATH system variable. IBM compatible
  94. installation and use is discussed below.
  95.  
  96. It is important to note that the ZeriLink software is fully sufficient to
  97. link any one of three combinations of machine types (Acorn to IBM, Acorn to
  98. Acorn, or IBM to IBM). The 'receiver' software on a machine is capable of
  99. interpreting both 'native' files (which will be left untranslated) and
  100. 'foreign' files (which will be suitably translated to 'native' format). The
  101. 'transmitter' software simply sends its 'native' format only.
  102.  
  103. The parallel cable which connects both sides' parallel port consists of a
  104. 'male 25 pin D' plug on both sides, and a multi-wire *SHIELDED* cable. The
  105. cable should be wired as follows (pin numbers are marked on the plugs) :
  106.  
  107.   Pin 1 (nSTROBE)   <--->  Pin 10 (nACK)
  108.   Pin 2 (DATA 0)    <--->  Pin 2 (DATA 0)
  109.   Pin 3 (DATA 1)    <--->  Pin 3 (DATA 1)
  110.   Pin 4 (DATA 2)    <--->  Pin 4 (DATA 2)
  111.   Pin 5 (DATA 3)    <--->  Pin 5 (DATA 3)
  112.   Pin 6 (DATA 4)    <--->  Pin 6 (DATA 4)
  113.   Pin 7 (DATA 5)    <--->  Pin 7 (DATA 5)
  114.   Pin 8 (DATA 6)    <--->  Pin 8 (DATA 6)
  115.   Pin 9 (DATA 7)    <--->  Pin 9 (DATA 7)
  116.   Pin 10 (nACK)     <--->  Pin 1 (nSTROBE)
  117.   Pin 11 (BUSY)     <--->  Pin 14 (nAUTOFD)
  118.   Pin 12 (PE)       <--->  Pin 16 (nINIT)
  119.   Pin 13 (SLCT)     <--->  Pin 17 (nSLCTIN)
  120.   Pin 14 (nAUTOFD)  <--->  Pin 11 (BUSY)
  121.   Pin 16 (nINIT)    <--->  Pin 12 (PE)
  122.   Pin 17 (nSLCTIN)  <--->  Pin 13 (SLCT)
  123. * Pin 18 (0V)       <--->  Pin 18 (0V)
  124. * Pin 19 (0V)       <--->  Pin 19 (0V)
  125. * Pin 20 (0V)       <--->  Pin 20 (0V)
  126. * Pin 21 (0V)       <--->  Pin 21 (0V)
  127. * Pin 22 (0V)       <--->  Pin 22 (0V)
  128. * Pin 23 (0V)       <--->  Pin 23 (0V)
  129. * Pin 24 (0V)       <--->  Pin 24 (0V)
  130.   Pin 25 (0V)       <--->  Pin 25 (0V)
  131.  
  132. In addition, on each connector seperately, pin 13 (SLCT) should be connected
  133. to pin 15 (nERROR) by a short piece of wire.
  134.  
  135. Connections marked with a * are not required, but they are recommended. In
  136. addition to these connections, the shielding wire should be soldered to the
  137. plug's metal on both sides (i.e. to the plug itself, not one of its pins).
  138.  
  139. It is recommended to buy a prefabricated completely wired 'straight' parallel
  140. extension cable (i.e. pin 1 to pin 1, pin 2 to pin 2, ..., pin 25 to pin 25),
  141. and re-wire that to the specifications above. This saves a lot of soldering.
  142. Ensure that both sides of the prefabricated cable have 'male' plugs (i.e.
  143. plugs with pins, not holes), that the cable is shielded, and that the plugs
  144. can be opened for re-wiring (some cables have moulded plugs which cannot be
  145. opened).
  146.  
  147.  
  148. //
  149. //
  150. // The software on both sides
  151. //
  152. //
  153.  
  154. The general ZeriLink tranfer concept is as follows :
  155.  
  156. 1) The receiving side issues the 'LinkR' command.
  157.    This starts waiting for a transmission from the other side.
  158. 2) The transmitting side issues the 'LinkT <filespec>...' command.
  159.    This starts transmitting files, one after the other.
  160. 3) The transmitted files are received, interpreted and saved.
  161. 4) The transfer is terminated (LinkR exits, LinkT exits).
  162.  
  163. The receiving side needs to issue 'LinkR' because ZeriLink software uses
  164. 'polled I/O', to make the fastest transfer speeds possible. ZeriLink achieves
  165. transfer speeds of up to 800kB/sec (ECP mode) or 200kB/sec (PS/2 mode), for
  166. large-ish files.
  167.  
  168. When files are transmitted, all relevant information about the file is
  169. included and is retained (as well as possible) in the file on the other side.
  170. There are, however, restrictions, which will be discussed below. Also, file
  171. attributes are always ignored. This is because e.g. 'locked' or 'read only'
  172. files are usually a big pain to work with. If you really, really, really need
  173. to preserve file attributes, then archive the files at one end, transmit the
  174. archive, and unarchive the files at the other end.
  175.  
  176. The ZeriLink software can be configured in a very flexible way, by means of a
  177. configuration file ('LinkConfig' (Acorn) and 'Link.CNF' (IBM) are examples of
  178. generally usable configuration files). The configuration of the ZeriLink
  179. software is discussed below (which options are available depends on whether
  180. the software runs on an Acorn or on an IBM). In general, the configuration
  181. file simply consists of a number of lines. If a line starts with a letter, it
  182. is a definition line (i.e. it contains configuration information), else it is
  183. a comment line (i.e. it is ignored). A definition line starts with a keyword,
  184. and is followed by one or more values. The relevance of each keyword and its
  185. possible values is discussed below. The example configuration files include
  186. detailed explanations of the keywords.
  187.  
  188. The keyword 'Mode' is a general keyword. It selects either ECP (value 'ECP')
  189. or PS/2 (value 'BIDIR') mode. It is strongly recommended to first try the
  190. 'BIDIR' setting, and, when this works, the 'ECP' setting (if appropriate). If
  191. the 'BIDIR' setting does not work, the 'ECP' setting is also very unlikely to
  192. work. Conversely, if the 'ECP' setting works, the 'BIDIR' setting is very
  193. likely to work too.
  194.  
  195. File data integrity is ensured by a CRC32 algorithm (32-bit Cyclic Redundancy
  196. Check). If the received file data fails this check, it is corrupted, and the
  197. file will be deleted. If the received file data passes this check, it is
  198. extremely unlikely that it is corrupted.
  199.  
  200. Note that only leafnames of files are transmitted. Directory paths are
  201. discarded. All files on the receiving side are written to the current
  202. directory on that machine.
  203.  
  204.  
  205. //
  206. //
  207. // The software on the Acorn side
  208. //
  209. //
  210.  
  211. Installation of two files is required. The 'ZLink' file is a module which
  212. should be loaded in your machine's !Boot sequence. The 'LinkConfig' file is a
  213. configuration file for 'ZLink', and should also be loaded, by ZLink, in your
  214. machine's !Boot sequence (using '*LinkConfigure LinkConfig'). E.g., in a
  215. typical installation, you would copy the 'ZLink' and 'LinkConfig' files to
  216. your $.!Boot directory, and add the following lines at some suitable place in
  217. your !Boot sequence :
  218.  
  219. RMLoad <Boot$Dir>.ZLink
  220. LinkConfigure <Boot$Dir>.LinkConfig
  221.  
  222. Alternatively, if you have a RISC PC, follow Acorn's guidelines on how to add
  223. modules and commands to the standard boot sequence (as I find Acorn's !Boot
  224. system cumbersome, I use my own !Boot sequence, so I can't help you there).
  225.  
  226. The ZLink module provides three commands : *LinkR, *LinkT and *LinkConfigure.
  227. *LinkR needs no further explanation. '*LinkT <filespec>...' transmits all the
  228. files that match <filespec>. Wildcards may be used freely, and multiple
  229. filespecs may be given, seperated by spaces (e.g. '*LinkT $.A.B.C.* RAMFS:D*
  230. E*').
  231.  
  232. When receiving 'Acorn' files, translations are as follows :
  233.  
  234. - The leafname is scanned for characters that are illegal in Acorn
  235.   leafnames (see the 'MapChar' configuration keyword). If any are found, they
  236.   are replaced by the configured corresponding 'legal' leafname characters.
  237. - The leafname is then truncated, if needed, to a fixed number of characters
  238.   (see the 'LeafLength' configuration keyword).
  239. - The file's attributes are ignored (and set to 'WRwr' instead).
  240. - All other file information is retained.
  241.  
  242. The first two translations do not usually change the leafname, but are
  243. performed for safety and convenience reasons. In general, Acorn file
  244. information is fully retained, except for file attributes.
  245.  
  246. When receiving 'DOS' files, translations are as follows :
  247.  
  248. - The leafname is scanned for a known extension (see the 'ExtToType'
  249.   configuration keyword). If no match is found, the leafname remains
  250.   untouched and the Acorn filetype is set to a default (see the 'NoExtToType'
  251.   configuration keyword). If a match is found, the extension, including the
  252.   leading '.', is removed from the leafname, and the Acorn filetype is set to
  253.   the configured corresponding filetype.
  254. - The leafname is then scanned for characters that are illegal in Acorn
  255.   leafnames (see the 'MapChar' configuration keyword). If any are found, they
  256.   are replaced by the configured corresponding 'legal' leafname characters.
  257. - The leafname is then truncated, if needed, to a fixed number of characters
  258.   (see the 'LeafLength' configuration keyword).
  259. - The file's time stamp is translated to Acorn format, if possible.
  260. - The file's attributes are ignored (and set to 'WRwr' instead).
  261.  
  262. The configuration file 'LinkConfig' contains example configuration settings
  263. and is self-explanatory when you have read the above.
  264.  
  265.  
  266. //
  267. //
  268. // The software on the IBM side
  269. //
  270. //
  271.  
  272. Installation of three files is required. The 'LinkT.EXE' and 'LinkR.EXE'
  273. files are executable files and should reside in one of the directories
  274. specified in your PATH system variable, where they can be readily executed.
  275. The 'Link.CNF' configuration file should be put in the same directory. If you
  276. are running in an MSDOS environment that supports long filenames (e.g. an
  277. MSDOS box under Windows 95) you must set the system variable 'LFN' to 'Y'
  278. (e.g., add the line 'set LFN=Y' to your AUTOEXEC.BAT file). Failing to do
  279. this will give the usual troubles with long filenames being truncated to
  280. something like 'BLAHBL~1', etc..
  281.  
  282. Rather obviously, the 'LinkT.EXE' executable provides the 'LinkT' command,
  283. and the 'LinkR.EXE' executable provides the 'LinkR' command. 'LinkT
  284. <filespec>...' transmits all the files that match <filespec>. Wildcards may
  285. be used freely, and multiple filespecs may be given, seperated by spaces
  286. (e.g. 'LinkT C:\A\B\C\*.* D:\D*.* E*.*').
  287.  
  288. When receiving 'DOS' files, translations are as follows :
  289.  
  290. - The leafname is scanned for characters that are illegal in DOS leafnames
  291.   (see the 'MapChar' configuration keyword). If any are found, they are
  292.   replaced by the configured corresponding 'legal' leafname characters.
  293. - The leafname is then truncated, if needed, to a fixed number of characters
  294.   (see the 'LeafLength' configuration keyword).
  295. - The file's attributes are ignored (and set to 'A' instead).
  296. - All other file information is retained.
  297.  
  298. The first two translations do not usually change the leafname, but are
  299. performed for safety and convenience reasons. In general, DOS file
  300. information is fully retained, except for file attributes.
  301.  
  302. When receiving 'Acorn' files, translations are as follows :
  303.  
  304. - The leafname is scanned for characters that are illegal in DOS leafnames
  305.   (see the 'MapChar' configuration keyword). If any are found, they are
  306.   replaced by the configured corresponding 'legal' leafname characters.
  307. - Then the Acorn filetype, if present, is looked up (see the 'TypeToExt'
  308.   configuration keyword). If no match is found, the leafname remains
  309.   untouched. If a match is found, the configured corresponding extension is
  310.   appended to the leafname, including a leading '.'.
  311. - The leafname is then truncated, if needed, to a fixed number of characters
  312.   (see the 'LeafLength' configuration keyword).
  313. - The file's time stamp, if present, is translated to DOS format, if
  314.   possible.
  315. - The file's attributes are ignored (and set to 'A' instead).
  316.  
  317. The configuration file 'Link.CNF' contains example configuration settings and
  318. is self-explanatory when you have read the above.
  319.  
  320. The 'LinkPort' configuration keyword enables configuration of the parallel
  321. port to be used. The value needs to be the port number of the parallel port
  322. which is to be used by ZeriLink (either 278, 378 or 3BC). Consult your
  323. hardware documentation and BIOS settings to find out what port number to use,
  324. and ensure that the port has its ECP ('Extended Capabilities Port') and/or
  325. PS/2 ('bidirectional') support enabled. This is very important.
  326.  
  327.  
  328. //
  329. //
  330. // Epilogue
  331. //
  332. //
  333.  
  334. Updates of ZeriLink will be made available by (in order of preference) :
  335.  
  336. - World Wide Web, on www.inter.nl.net/users/J.Kortink.
  337. - Electronic mail, to kortink@inter.nl.net.
  338. - Snail mail, to : John Kortink, Nutterbrink 31, 7544 WJ Enschede, The
  339.   Netherlands. Include a DD or HD floppy, return envelope and one
  340.   International Reply Coupon (IRC).
  341.  
  342.