home *** CD-ROM | disk | FTP | other *** search
/ Enigma Amiga Life 106 / EnigmaAmiga106CD.iso / www / amosfactory / ext / lha / dump.lha / dump_extension / dump_readme next >
Encoding:
Text File  |  1998-03-20  |  8.8 KB  |  251 lines
  1. *************************************************
  2. *                        *
  3. * Dump.Readme - documentation for        *
  4. *        the AMOS dump extension v1.0    *
  5. *        by Alex J. Grant / 26-2-91    *
  6. *        Modified by A.Fothergill 2/3/93 *
  7. *        The Official Version !       *
  8. *************************************************
  9.  
  10. As you may by now know, AMOS does not include a screen harcopy facility.
  11. It does however include the ability to add commands via loaded extensions.
  12. Dump is such an extension which adds several powerful commands to the AMOS
  13. language.  If you need to make hardcopies of screens, this is for you.
  14.  
  15.  
  16. Summary of operation:
  17. ~~~~~~~~~~~~~~~~~~~~~
  18. The Dump command is available in three formats (dicussed later) which 
  19. allow different effects to be achieved.  Each is invoked thus:
  20.  
  21. E=Dump(n,n,n,n,n.....)
  22.  
  23. Where the n's are various parameters.
  24.  
  25. The value returned (here assigned to E) is the error number.  This is the
  26. error returned by the printer on completion/abortion of the dump.
  27.  
  28. Also included is a special function =Dump Err$, which returns a string 
  29. describing the last error.
  30.  
  31.  
  32. All screen dumps are done via the printer driver selected using Prefences,
  33. on your workbench disk.  No responsibility is assumed for problems which
  34. may occur due to different drivers etc. (although this is very unlikely.)
  35.  
  36.  
  37. Installation:
  38. ~~~~~~~~~~~~~
  39.  
  40. The dump routines are contained in an AMOS extension.  This must be added 
  41. to the extension list as follows:
  42.  
  43. Make sure you are using a backup of your language disk!!!!!
  44.  
  45. 0. This extension only works with AMOS1.3 and over
  46. 1. Copy the Dump.Lib file into the AMOS_System Directory of your AMOS Disk
  47. 2. Load up the Config1_3.AMOS program, and run it.
  48. 3. Load in the Default Configuration (or whatever configuration you use.)
  49. 4. Select 'Loaded Extensions' from the 'Set' menu
  50. 5. Enter the following at position 10 (this is vital - no other number
  51.    will work!!!) :Amos_System/Dump.Lib
  52. 6. Save this configuration
  53. 7. If you have the AMOS Compiler
  54.    i) Select the Load Other Configuration menu option
  55.    ii) Load in the RAMOS1_3.Env file from your AMOS System Directory
  56.    iii) follow steps 4-6 as above
  57.  
  58. You should now reboot AMOS to start using the Dump extension.
  59. (Remember to wait until the disk is completely finished before
  60. re-booting !!!!!!!!!).
  61.  
  62. Command descriptions:
  63. ~~~~~~~~~~~~~~~~~~~~~
  64.  
  65. The three formats for the Dump command are as follows:
  66. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  67. =Dump
  68.  
  69. This simply dumps the current screen to the printer, using
  70. SPECIAL_FULLCOLS | SPECIAL_FULLROWS | SPECIAL_ASPECT
  71. (meaning that it utilises maximum paper space, and retains the
  72. aspect ration of the screen.)
  73.  
  74. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  75. Dump(x1,y1 to x2,y2)
  76.  
  77.     (x1,y1) - Top left corner
  78.     (x2,y2) - Bottom right corner
  79.  
  80. This command allows you to dump portions of the screen defined by (x1,y1)
  81. and (x2,y2).  It retains the aspect ratio, and also screen size - paper
  82. size ratio.  ie. If you dump only half of the screen, it will take up
  83. only half of the normal print size that Dump(n) would.
  84. For the technically minded, this is using 
  85. SPECIAL_FRACCOLS | SPECIAL_FRACROWS | SPECIAL_ASPECT.
  86.  
  87. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  88.  
  89. Dump(x1,y1 to x2,y2,px,py,s)
  90.  
  91.     (x1,y1) - Top left corner
  92.     (x2,y2) - Bottom right corner
  93.     (px,py) - Print width, height
  94.           s - Special command
  95.  
  96.  
  97. x1,y1,x2,y2 are the same as before - they define the 'source' dimensions.
  98.  
  99. px,py define, in printer pixels, how wide,high to print the screen.  This is
  100. useful if you want to shrink or enlarge portions.
  101.  
  102. s is a special command parameter which tells the printer how to do the
  103.   dump.  Values for s are or'ed together from the following list:
  104.  
  105. Value        Name        Description
  106. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  107. $0001        MILCOLS        px is in 1/1000" (note 1)
  108. $0002        MILROWS        py is in 1/1000"
  109. $0004        FULLCOLS    use maximum print width (note 2)
  110. $0008        FULLROWS    use maximum print height
  111. $0010        FRACCOLS    px is a fraction of FULLCOLS (note 3)
  112. $0020        FRACROWS    py is a fraction of FULLROWS 
  113. $0040        CENTER        centre image on page
  114. $0080        ASPECT        retain correct aspect ratio
  115. $0100        DENSITY1    lowest resoltion (dpi) (note 4)
  116. $0200        DENSITY2    next resolution
  117. $0300        DENSITY3    next resolution
  118. $0400        DENSITY4    next resolution
  119. $0500        DENSITY5    next resolution
  120. $0600        DENSITY6    next resolution
  121. $0700        DENSITY7    highest resolution
  122. $0800        NOFORMFEED    don't eject paper
  123. $1000        TRUSTME        don't reset 
  124. $2000        NOPRINT        don't print. 
  125.  
  126. Note 1:     MILCOLS, MILROWS   - means that the corresponding dx or dy is in
  127.                   1/1000th of an inch.  Eg. if dx=10000, the
  128.                   dump will be 10 inches wide.
  129.  
  130. Note 2:  FULLCOLS, FULLROWS - uses the maximum available width/height on 
  131.                   the paper
  132.  
  133. Note 3:  FRACCOLS, FRACROWS - dx, dy is between $0000 and $ffff.
  134.                   the print width is calculated thus:
  135.  
  136.                      width = FULLCOLS * dx/$ffff
  137.  
  138.                    eg. If dx = $8000, print width will be $8000/$ffff
  139.                   = 1/2 of FULLCOLS ie. take up half the width
  140.                   of the paper.
  141.  
  142. eg. To dump a portion 100x100 on a full page, retaining correct aspect:
  143.  
  144. E=Dump(0,0 to 100,100,0,0,$80 or $8 or $4)
  145.  
  146. eg. To dump a lo-res screen to an 8" by 6" area:
  147.  
  148. E=Dump(0,0 to 320,200,8000,6000,$1 or $2)
  149.  
  150. eq. To dump a section to 1/3 the available width, but full length:
  151.  
  152. E=Dump(0,0 to 200,200,$5555,0,$8 or $10)
  153.  
  154. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  155.  
  156. The printer error commands are as follows:
  157. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  158. E$=Dump Err$
  159.  
  160. This return a string in E$ describing the last printer error that occured.
  161. It could be used like so:
  162.  
  163. E=Dump(0)
  164. If E<>0 Then Goto PE
  165.  .
  166.  .
  167.  .
  168.  
  169. PE:
  170.    Print "PRINTER ERROR!!! - ";Dump Err$
  171.  
  172. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  173. Avoiding "Lockout"
  174. ~~~~~~~~~~~~~~~~~~
  175.  If you have no printer connected, it is offline, busy or out of paper,
  176. the Amiga will respond in a very user friendly manner. It will lock out !
  177.  To avoid this, two commands were added to the AMOS Club/Shuffle extension
  178. (Available to AMOS Club Members and AMOS TOME users). These commands are:
  179.  
  180. =Busy Printer
  181.  This returns false if the printer is online and not busy
  182.  
  183. =No Paper
  184.  This returns false if there is paper ready in the printer
  185.  
  186. So by doing:
  187.  
  188. If No Paper=0 and Busy Printer=0
  189.   E=Dump
  190. Endif
  191.  
  192.  You can use the dump commands (as well as any other printer commands)
  193. without worrying about lockout !
  194.  
  195.  The AMOS Club extension is available from the Official AMOS Club to
  196. AMOS Club members, and as part of the AMOS TOME system.
  197.  To join the AMOS Club, send £12 U.K (£15 Overseas) to
  198. The AMOS Club,
  199.    1 Lower Moor,
  200.     Whiddon Valley,
  201.      Barnstaple,
  202.       N.Devon. EX32 8NW
  203.        (England)
  204. enclosing your name and address. Subscription to the AMOS Club is for
  205. six newsletters, gets you access to the AMOS Helpline, and discounts on
  206. AMOS Club developed software (Some of which is only available to AMOS
  207. Club members) and a 10% discount on P.D disks from the AMOS P.D Library.
  208.  
  209. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  210. Notes on Extensions
  211. ~~~~~~~~~~~~~~~~~~~
  212. The sourcecode for Dump.Lib is included on this disk. If you are writing
  213. your own AMOS extensions for release, work with extension number 24 while
  214. you are writing it, and contact the AMOS Club to make sure that the you
  215. are not using commands already in another AMOS extension or that duplicate
  216. commands already available. If your extension is a new one, and is ready
  217. for release, you will then be given an Official AMOS extension number to use.
  218. Remember that the AMOS Club keeps the only official list of AMOS Extensions, 
  219. and that using an extension number without checking first will mean that
  220. nobody can use your extension without it clashing with one or more of the 
  221. official extensions that they have installed.
  222.  
  223. More on the printer drivers
  224. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  225.  
  226. To have more information on the effect of all the flags and different
  227. variables, just read "The Amiga Rom Kernel Reference Manual", libraries
  228. and devices, published by Addison Wesley. This is the book every 
  229. Amiga programmer should have.
  230. The AMOS P.D Library (0792 588 156) has several disks of printer drivers,
  231. suitable for most printers on the Amiga. If you have an unusual printer,
  232. most of the printer manufacturers provide excellent support for their
  233. machines, so try contacting them to see if they have an Amiga printer
  234. driver.
  235.  
  236. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  237. Credits:
  238. ~~~~~~~~
  239.  
  240. This extension was programmed by Alex J. Grant in assembler
  241. and compiled using Aztec 68K v3.6a Assembler and linker.
  242. It was (a bit) improved, and converted into AMOS1.3 extension system
  243. by François Lionet using Genam2.
  244. Further mods and documentation correction by Aaron Fothergill.
  245.  
  246. Original idea from the AmigaBasic demo 'ScreenPrint' on the Extras disk.
  247.  
  248. Enjoy...
  249.  
  250. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  251.