home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine 1996 / ARCHIVE_96.iso / discs / mag_discs / volume_8 / issue_07 / risc_pc / !7Plus / !Help < prev    next >
Text File  |  1993-04-03  |  16KB  |  396 lines
  1. 7Plus for the Archimedes : Version 1.00
  2. =======================================
  3.  
  4. Introduction
  5. ------------
  6.  
  7. Hip Hip Hooray!! Throw away that tired old PC emulator and install
  8. 7Plus for the Archimedes instead. Its been a long time coming but the
  9. Archimedes now has a native version of 7Plus, all be it in command
  10. line form.
  11.  
  12. For those of you who already use 7Plus under the PC Emulator this
  13. program should not be too much of a culture shock. For those who don't
  14. use the PC emulator or the command line I apologize for releasing this
  15. program with no nice'n'easy desktop front end, but once this
  16. conversion is proven in the field then I shall devote more time to the
  17. desktop version.
  18.  
  19. Theory behind the conversion
  20. ----------------------------
  21.  
  22. When I started porting 7Plus across to the Archimedes it soon became
  23. apparent that much of 7Plus' internal workings were dependant on the
  24. PC concept of file name extensions (similar to RISC OS file types).
  25. ie-:
  26.   
  27. EXAMPLE.DOC
  28.  
  29. Where 'EXAMPLE' is the filename and 'DOC' is the file name extension.
  30. In this case a DOCument for a word processor. This would be the
  31. equivalent to the Archimedes file type TEXT (&FFF) or similar.
  32.  
  33. So in order to keep as much of the original 7Plus source code untouched
  34. I have wrapped it in cotton wool by translating RISC OS file names and
  35. types into DOS format and back again.
  36.  
  37. The upshot of all this is that we only have a command line version of
  38. the program. This should be easy to keep up to date and in line with the
  39. PC version and it also has a command line syntax almost exactly the
  40. same. This also means WE understand what PC owners are going on about
  41. when they ask for a re-send of 'EXAMPLE.P06' for example.
  42.  
  43. If you have not read the 7Plus manual written by Axel DG1BBQ then it
  44. would be advisable to do so now. This is kept in the Archive '7+ 4 PC'
  45. and is called '7PLUS_E/DOC'. The manual covers the operation of all the
  46. versions of 7Plus across all the platforms except for RISC OS machines.
  47. The rest of this file gives a quick guide as to the structure of 7Plus
  48. under RISC OS and how to use it.
  49.  
  50. How 7Plus organises its work files.
  51. -----------------------------------
  52.  
  53. In order to keep the command line as close to the PC format as possible
  54. all 7Plus 'work' files are kept in one place. This is the '!7+_Work'
  55. directory with the open brief case icon. Double clicking on this will
  56. cause the directory to open revealing a couple of 7Plus files called
  57. '!Spock' and '!Spocky'. The directory structure of the '!7+_Work'
  58. directory is shown here.
  59.  
  60.  
  61.  
  62.  
  63. !7+_Work--------|
  64.                 |----!Sprites22
  65.                 |----!Sprites
  66.                 |----!Boot
  67.                 |----!Run
  68.                 |
  69.                 |----Work----|
  70.                              |-----!Spock  (7+ 'file')
  71.                              |-----!Spocky (7+ 'file')
  72.                              |-----Spock   (decoded sprite file)
  73.                              |-----JPEG----|
  74.                                            |-----Spocky (JPG decoded PC)
  75.                                                         (file stamped  )
  76.                                                         (with DOS type )
  77.  
  78.  
  79.  
  80.  
  81. Any successfully decoded Archimedes files are also put in this
  82. directory. If the file was originally from a PC or other machine the
  83. file is put in a newly created Sub-directory whose name is the files
  84. file extension. Sounds complicated but hopefully all will be made clear
  85. in the following examples.
  86.  
  87. Decoding Examples.
  88. ------------------
  89.  
  90. This is a small example to show you how to decode the 7Plus file
  91. '!Spock' into its normal Archimedes sprite form.
  92.  
  93. Press the 'F12' to get to the * command line prompt and then type the
  94. following
  95.  
  96. *7Plus Spock
  97.  
  98. and then press 'Return'
  99.  
  100. 7Plus will now display its banner and proceed to decode the '!Spock'
  101. 7Plus file. You may have noticed that to decode we did not type in
  102. '!Spock' but 'Spock'. When decoding you do not use the first '!' in
  103. the file name.
  104.  
  105. Once the decoding has finished press 'Return' to go back to the desktop.
  106. If you have opened the '!7+_Work' directory ( called the work directory
  107. from now on ) you will now find a successfully decoded sprite file
  108. called 'Spock'. The '!Spock' 7Plus file is now redundant and can be
  109. deleted.
  110.  
  111. You have now successfully decoded a 7Plus file that was created on the
  112. Archimedes. Now how about a file that was created on a PC.
  113.  
  114. Press 'F12' again and type
  115.  
  116. *7Plus Spocky
  117.  
  118. When it has finished press 'Return' to get back to the desktop. You
  119. will now find a new directory in the work directory called 'JPG'.
  120. Inside you will find a file called 'Spocky' with a file type of DOS.
  121. This file would have had the full name of 'SPOCKY.JPG' on a PC. I have
  122. implemented PC file names in this manner instead of the more usual
  123. 'SPOCKY/JPG' so that no truncation of the name occurs.
  124.  
  125. The '!Spocky' 7Plus file is now redundant and could be deleted.
  126.  
  127. To view 'Spocky' you will need the application !changeFSI (comes with
  128. RISC OS 3.1) or !Translator ( a shareware program ) and djpeg.
  129.  
  130. The nitty gritty of the !7Plus files
  131. ------------------------------------
  132.  
  133. Yep you've guessed it '!Spock' was not a file at all but another fancy
  134. 'file' directory as inspired by !Impression. The structure of '!Spock'
  135. is shown here.
  136.  
  137. !Spock---|
  138.          |---!Run
  139.          |---!Sprites
  140.          |---!Sprites22
  141.          |---!Help
  142.          |---7ix-----|
  143.          |           |---7ix (data type)
  144.          |
  145.          |---7mf-----|
  146.          |           |---7mf (data type)
  147.          |
  148.          |---cor-----|
  149.          |           |---cor (text type)
  150.          |           |---c01 (text type)
  151.          |           |--- ......
  152.          |             
  153.          |---err-----|---err (text type)
  154.          |           |---e01 (text type)
  155.          |           |--- ......
  156.          |            
  157.          |---p0_-----|---p01 (text type)
  158.          |           |---p02 (text type)
  159.          |           |---p03 (text type)
  160.          |           |--- ...... upto p0f
  161.          |                       
  162.          |---p1_-----|---p10
  163.          |           |--- ...... upto p1f
  164.          | 
  165.          |... upto pf_ 
  166.                 
  167.  
  168. Double clicking on '!Spock' will open the file to reveal a number of
  169. files and directories. The '!Run' and '!Sprites' are the normal run of
  170. the mill stuff and can be ignored. The !Help file is slightly special
  171. and to find out why just double click on it and read.
  172.  
  173. Why the complicated directory structure?.....
  174. ---------------------------------------------
  175.  
  176. 7Plus produces many different file name extensions on the PC which can
  177. cause problems when exceeding the 77 file limit on ADFS. The file
  178. extensions, to recap, are-:
  179.   
  180. 7PL     A file encoded into 7Plus format and has only one part
  181.         ( 1 of 1)
  182. P01     A file encoded into 7Plus format and is the first part of many
  183. ERR     A file generated while decoding a set of corrupted 7Plus files.
  184. COR     A file generated to correct the errors listed by the ERR file.
  185. 7MF     A file generated while decoding. This is a partly decoded file
  186.         and is kept to speed up the process of decoding when a COR
  187.         file is received.
  188. 7IX     A file that is related to the 7MF file.
  189.  
  190. When downloading 7Plus files from a BBS it is possible to download more
  191. than one 'COR' file. In this case the 'COR' files will be named 'COR'
  192. for the first file and then the sequence C01,C02..C4C will be used.
  193. (ie a maximum of 77 'COR' files).
  194.  
  195. The same also applies to the 'ERR' files. You will almost certainly
  196. receive more than one error file when you have encoded and distributed
  197. some 7Plus files.
  198.  
  199. All the above file name extensions are kept in sub-directories of the
  200. same name for each file that you are de/encoding. Have another look at
  201. the '!Spocky' directory structure.
  202.  
  203. The only exception to this rule is the parts files ('P01'..etc). These
  204. are kept in directories of names described as follows. The files 'P01'
  205. to 'P0F' are kept in the sub-directory 'P0_', similarly the files 'P30'
  206. to 'P3F' are kept in the sub-directory 'P3_' . This enables the
  207. Archimedes to support 255 parts for 7Plus files ( over the top I know )
  208. and still keep within the 77 file limit of the ADFS filing system.
  209. Remember if only one part of one is created it will have a file name of
  210. '7PL' and will be in a directory of that name.
  211.  
  212. Encoding files.
  213. ---------------
  214.  
  215. We are now going to re-encode the 'Spock' file so first you must delete
  216. the 7Plus 'file' called '!Spock'. This is necessary so there is no
  217. confusion as to what has been achieved.
  218.  
  219. Encoding is quite tricky because the file to be encoded has to be
  220. specified by a full path name. To make this easier move the file
  221. 'Spock' into the root directory of the floppy.
  222.  
  223. The simple format of the encode command is -:
  224.   
  225. *7Plus <full path name>
  226.  
  227. assuming 'Spock' is in the root directory of the floppy the command
  228. would be
  229.  
  230. *7Plus ADFS::0.$.Spock
  231.  
  232. Quite a mouthful. It can be made easier by using a Currently Selected
  233. Directory ( CSD ) setter written by many PD authors. (A good one is
  234. !Menon). This will allow the command to be simplified to just -:
  235.   
  236. *7plus Spock
  237.  
  238. Assuming you have now successfully encoded the file you will find
  239. '!Spock' the 7Plus file has returned. Double clicking on this will
  240. reveal the usual assortment of '!Run's etc and a directory called 'p0_'.
  241. Looking in this directory will reveal the parts files 'p01' and onwards.
  242. These are the files that you send out on the packet network.
  243.  
  244. All the other sub-directories such as 'COR','ERR','7MF' etc are created
  245. as and when necessary.
  246.  
  247. Decoding files in the real world.
  248. ---------------------------------
  249.  
  250. The decoding examples earlier were a piece of cake as the parts files
  251. had already been 'downloaded' for you. For the successful operation of
  252. 7Plus under RISC OS it is essential that all the parts files and 'COR's
  253. etc are in the right place. To aid this the following procedure is best
  254. followed.
  255.  
  256. Download all the 7plus files off the BBS into a spool file including
  257. any 'COR' files. Now we use the auto extract facility of 7Plus to sort
  258. and extract the 7Plus files from the spool file. The format of this
  259. command is -:
  260.   
  261. *7Plus <full spool file path name> -x
  262.  
  263. The spool file has to be named in full again unless the CSD is set
  264. correctly. The -x option makes 7Plus scan the spool file for 7Plus
  265. files and auto extract them and in the process create any necessary
  266. directories. This operation can be carried out as many times as
  267. necessary to get all the right files off the BBS.
  268.  
  269. Assuming you have just downloaded some files that make up an original
  270. file called 'EXAMPLE' you will find in the work directory a new 7Plus
  271. 'file' called '!EXAMPLE'. You are now able to decode the same way as
  272. shown earlier ie -:
  273.   
  274. *7Plus Example
  275.  
  276. 7Plus will inform you if any of the parts are missing. You will also
  277. be informed if errors exist in the downloaded parts. In this case an
  278. 'ERR' file will be created. Put the appropriate packet headers onto
  279. this file and send it back to the originator of the 'EXAMPLE' file.
  280. You will eventually receive back a 'COR' file. To correct the '7MF'(the
  281. partially decoded file ) created so far you use the command -:
  282.   
  283. *7Plus Example.cor
  284.  
  285. Hopefully you will now have a new file that you can play, run, view etc.
  286.  
  287. Coping with ERR files.
  288. ----------------------
  289.  
  290. When you send out a load of 7Plus files it is inevitable that you are
  291. going to receive some 'ERR' files. To this end it is probably worth
  292. joining most of the 'ERR' files ('err', 'e01' to 'e4c') together into
  293. a large 'ERR' and creating one 'COR' file to be sent out as a bulletin.
  294. The command to join all the 'ERR' files into one is -:
  295.   
  296. *7Plus <file name>.err -j
  297.  
  298. To create the 'COR' file we now call 7Plus with the following-:
  299.   
  300. *7Plus <file name>.err <full path name of original source file>
  301.  
  302. For example with 'Spock' earlier it would be
  303.  
  304. *7Plus Spock.err ADFS::0.$.Spock
  305.  
  306. The full pathname has to be given for the original 'Spock' file. This
  307. is slightly different from the PC version where a search path is given
  308. instead.
  309.  
  310. This short! file has given the very basics of 7Plus which is far more
  311. flexible and has more options than have been given here. If you still
  312. haven't read Axels 7Plus manual then I really do suggest that you do
  313. to get the best out of 7Plus.
  314.  
  315. Multitasking 7Plus
  316. ------------------
  317.  
  318. It is possible to multitask 7Plus by using the frontend module supplied
  319. by Acorn with the Desktop C and Assembler. A much cheaper way of
  320. getting this module is to send off to RISC developments for the disk
  321. for Risc User Volume 5 issue 10. The 7Plus application will then run
  322. and will sit on the icon bar. It is still command line based but will
  323. multitask.
  324.  
  325. Another method is to use the task window provided by Edit (or launched
  326. by the Task manager menu on Risc OS 3 ). There is the extra option -CR
  327. on 7Plus that you must use to force all printed output of 7Plus to have
  328. a carriage return. The screen looks a mess otherwise. eg -:
  329.    
  330. *7Plus Spock -CR
  331.  
  332. There is a slight problem I have noticed when running 7Plus under the
  333. front end module in that it sometimes fails to correct the '7MF'
  334. properly. This appears not to be fatal, just a case of the front end
  335. module forgetting what it was doing. If this occurs just run it from
  336. the command line like everybody else. This may also occur under the
  337. Task window although I have not noticed this myself.
  338.  
  339. What can 7Plus under Risc OS do?
  340. --------------------------------
  341.  
  342. 7Plus on the Archimedes supports all the features that are expected of
  343. V2.02 on the PC. That is to say-:
  344.   
  345. 1)      Will intelligently extract 7Plus files from a spool file
  346.         (essential to the correct operation of 7Plus under Risc OS )
  347. 2)      Supports file types and time stamps regardless of original
  348.         source operating system
  349. 3)      Supports multiple error and correction files of upto 77 each
  350. 4)      Supports splitting of files in upto 255 parts
  351.  
  352. What doesn't 7Plus do under Risc OS?
  353. ------------------------------------
  354.  
  355. 1)      It doesn't support the 'FLS' file for BBSs
  356. 2)      You can only use DOS characters in your filenames when encoding
  357. 3)      Doesn't support the use of the .x file extension
  358. 4)      Doesn't autokill redundant files ( -k option not supported )
  359. 5)      Does not support filename from DOSFS such as 'EXAMPLE/DOC'.
  360.         This is thrown out as it has a non-DOS compatible character
  361.         ( the '/' ). This is potentially useful so it may be
  362.         incorporated later.
  363. 6)      Is not able to encode the following filenames -:
  364.         '7ix' or '7IX'
  365.         '7pl' or '7PL'
  366.         'p01' or 'P01'
  367.         'err' or 'ERR'
  368.         'cor' or 'COR'
  369.         'c01' to 'cff' or 'C01' to 'CFF'
  370.  
  371.         although it will encode them if they are only part of a
  372.         filename ie.
  373.         
  374.         will encode '7ixexamp'
  375.         will encode '7plsource'
  376.         will encode 'correct'
  377.         etc etc......
  378.  
  379. Things to do in the future
  380. --------------------------
  381.  
  382. 1)      Tidy up the source code
  383. 2)      Speed 7Plus up. Due to the number of file name conversions
  384.         taking place within 7Plus the speed of an ARM2 machine is
  385.         about the same as that of a 386 25Mhz PC. In one of my earlier
  386.         versions of 7Plus when no name translation was taking place
  387.         the ARM2 was about 30% faster.
  388. 3)      Write a multitasking frontend for it. This will probably be in
  389.         the form of a filer type window. ie. dragging from the 7Plus
  390.         window to a normal filer window will decode the file and
  391.         dragging a file from a filer window to the 7Plus window
  392.         encodes it.
  393. 4)      Any suggestions?
  394. TTFN de John Ingram G1CWL @ GB7SUT.#29.GBR.EU
  395.  
  396.