************************************************* * * * Dump.Readme - documentation for * * the AMOS dump extension v1.0 * * by Alex J. Grant / 26-2-91 * * Modified by A.Fothergill 2/3/93 * * The Official Version ! * ************************************************* As you may by now know, AMOS does not include a screen harcopy facility. It does however include the ability to add commands via loaded extensions. Dump is such an extension which adds several powerful commands to the AMOS language. If you need to make hardcopies of screens, this is for you. Summary of operation: ~~~~~~~~~~~~~~~~~~~~~ The Dump command is available in three formats (dicussed later) which allow different effects to be achieved. Each is invoked thus: E=Dump(n,n,n,n,n.....) Where the n's are various parameters. The value returned (here assigned to E) is the error number. This is the error returned by the printer on completion/abortion of the dump. Also included is a special function =Dump Err$, which returns a string describing the last error. All screen dumps are done via the printer driver selected using Prefences, on your workbench disk. No responsibility is assumed for problems which may occur due to different drivers etc. (although this is very unlikely.) Installation: ~~~~~~~~~~~~~ The dump routines are contained in an AMOS extension. This must be added to the extension list as follows: Make sure you are using a backup of your language disk!!!!! 0. This extension only works with AMOS1.3 and over 1. Copy the Dump.Lib file into the AMOS_System Directory of your AMOS Disk 2. Load up the Config1_3.AMOS program, and run it. 3. Load in the Default Configuration (or whatever configuration you use.) 4. Select 'Loaded Extensions' from the 'Set' menu 5. Enter the following at position 10 (this is vital - no other number will work!!!) :Amos_System/Dump.Lib 6. Save this configuration 7. If you have the AMOS Compiler i) Select the Load Other Configuration menu option ii) Load in the RAMOS1_3.Env file from your AMOS System Directory iii) follow steps 4-6 as above You should now reboot AMOS to start using the Dump extension. (Remember to wait until the disk is completely finished before re-booting !!!!!!!!!). Command descriptions: ~~~~~~~~~~~~~~~~~~~~~ The three formats for the Dump command are as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =Dump This simply dumps the current screen to the printer, using SPECIAL_FULLCOLS | SPECIAL_FULLROWS | SPECIAL_ASPECT (meaning that it utilises maximum paper space, and retains the aspect ration of the screen.) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dump(x1,y1 to x2,y2) (x1,y1) - Top left corner (x2,y2) - Bottom right corner This command allows you to dump portions of the screen defined by (x1,y1) and (x2,y2). It retains the aspect ratio, and also screen size - paper size ratio. ie. If you dump only half of the screen, it will take up only half of the normal print size that Dump(n) would. For the technically minded, this is using SPECIAL_FRACCOLS | SPECIAL_FRACROWS | SPECIAL_ASPECT. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dump(x1,y1 to x2,y2,px,py,s) (x1,y1) - Top left corner (x2,y2) - Bottom right corner (px,py) - Print width, height s - Special command x1,y1,x2,y2 are the same as before - they define the 'source' dimensions. px,py define, in printer pixels, how wide,high to print the screen. This is useful if you want to shrink or enlarge portions. s is a special command parameter which tells the printer how to do the dump. Values for s are or'ed together from the following list: Value Name Description ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ $0001 MILCOLS px is in 1/1000" (note 1) $0002 MILROWS py is in 1/1000" $0004 FULLCOLS use maximum print width (note 2) $0008 FULLROWS use maximum print height $0010 FRACCOLS px is a fraction of FULLCOLS (note 3) $0020 FRACROWS py is a fraction of FULLROWS $0040 CENTER centre image on page $0080 ASPECT retain correct aspect ratio $0100 DENSITY1 lowest resoltion (dpi) (note 4) $0200 DENSITY2 next resolution $0300 DENSITY3 next resolution $0400 DENSITY4 next resolution $0500 DENSITY5 next resolution $0600 DENSITY6 next resolution $0700 DENSITY7 highest resolution $0800 NOFORMFEED don't eject paper $1000 TRUSTME don't reset $2000 NOPRINT don't print. Note 1: MILCOLS, MILROWS - means that the corresponding dx or dy is in 1/1000th of an inch. Eg. if dx=10000, the dump will be 10 inches wide. Note 2: FULLCOLS, FULLROWS - uses the maximum available width/height on the paper Note 3: FRACCOLS, FRACROWS - dx, dy is between $0000 and $ffff. the print width is calculated thus: width = FULLCOLS * dx/$ffff eg. If dx = $8000, print width will be $8000/$ffff = 1/2 of FULLCOLS ie. take up half the width of the paper. eg. To dump a portion 100x100 on a full page, retaining correct aspect: E=Dump(0,0 to 100,100,0,0,$80 or $8 or $4) eg. To dump a lo-res screen to an 8" by 6" area: E=Dump(0,0 to 320,200,8000,6000,$1 or $2) eq. To dump a section to 1/3 the available width, but full length: E=Dump(0,0 to 200,200,$5555,0,$8 or $10) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The printer error commands are as follows: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ E$=Dump Err$ This return a string in E$ describing the last printer error that occured. It could be used like so: E=Dump(0) If E<>0 Then Goto PE . . . PE: Print "PRINTER ERROR!!! - ";Dump Err$ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Avoiding "Lockout" ~~~~~~~~~~~~~~~~~~ If you have no printer connected, it is offline, busy or out of paper, the Amiga will respond in a very user friendly manner. It will lock out ! To avoid this, two commands were added to the AMOS Club/Shuffle extension (Available to AMOS Club Members and AMOS TOME users). These commands are: =Busy Printer This returns false if the printer is online and not busy =No Paper This returns false if there is paper ready in the printer So by doing: If No Paper=0 and Busy Printer=0 E=Dump Endif You can use the dump commands (as well as any other printer commands) without worrying about lockout ! The AMOS Club extension is available from the Official AMOS Club to AMOS Club members, and as part of the AMOS TOME system. To join the AMOS Club, send £12 U.K (£15 Overseas) to The AMOS Club, 1 Lower Moor, Whiddon Valley, Barnstaple, N.Devon. EX32 8NW (England) enclosing your name and address. Subscription to the AMOS Club is for six newsletters, gets you access to the AMOS Helpline, and discounts on AMOS Club developed software (Some of which is only available to AMOS Club members) and a 10% discount on P.D disks from the AMOS P.D Library. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Notes on Extensions ~~~~~~~~~~~~~~~~~~~ The sourcecode for Dump.Lib is included on this disk. If you are writing your own AMOS extensions for release, work with extension number 24 while you are writing it, and contact the AMOS Club to make sure that the you are not using commands already in another AMOS extension or that duplicate commands already available. If your extension is a new one, and is ready for release, you will then be given an Official AMOS extension number to use. Remember that the AMOS Club keeps the only official list of AMOS Extensions, and that using an extension number without checking first will mean that nobody can use your extension without it clashing with one or more of the official extensions that they have installed. More on the printer drivers ~~~~~~~~~~~~~~~~~~~~~~~~~~~ To have more information on the effect of all the flags and different variables, just read "The Amiga Rom Kernel Reference Manual", libraries and devices, published by Addison Wesley. This is the book every Amiga programmer should have. The AMOS P.D Library (0792 588 156) has several disks of printer drivers, suitable for most printers on the Amiga. If you have an unusual printer, most of the printer manufacturers provide excellent support for their machines, so try contacting them to see if they have an Amiga printer driver. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Credits: ~~~~~~~~ This extension was programmed by Alex J. Grant in assembler and compiled using Aztec 68K v3.6a Assembler and linker. It was (a bit) improved, and converted into AMOS1.3 extension system by François Lionet using Genam2. Further mods and documentation correction by Aaron Fothergill. Original idea from the AmigaBasic demo 'ScreenPrint' on the Extras disk. Enjoy... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~