XCUT - High Resolution "Frame" Save Documentation - Version 1.0
(c) Paul Bradshaw 72177,2032  July 15th, '87

  XCUT is a program that allows you to save blocks of graphics (known as
"frames") from the graphics screen, and store them in one of your extra memory
banks.  In order to use XCUT, you must have used XINIT to install the high-res
graphics module into memory, and you must have specified a Frame Buffer with
XINIT's "BUFFER=" parameter.  Here is the syntax for XCUT (items in brackets
are optional):

XCUT frmname x1,y1-x2,y2 [(parms)]

  "frmname" is the frame name, an indentifier that you assign to the block of
graphics.  It must be 1 to 8 characters long, and must start with a letter.

   "x1,y1-x2,y2" are the coordinates of the block of graphics you wish to store
(the "frame coordinates").  X1,Y1 is the Upper-Left corner of the block, and
X2,Y2 is the lower right.  Each coordinate must be separated by a comma, and
the pair of coordinates must be separated by either a dash (as shown) or a
comma.  Spaces are illegal, and will give a "syntax error in coordinates" error
message.

  The "parms" are:

    IMAGE   - Specified to CUT from the IMAGE bank.  Not currently supported.

    TEXT    - Displays the text screen during the CUT operation.  The screen
            will be restored to the "default" established by XINIT after the
            cut is complete.  If not specified, the screen is not altered.

    GRON    - Displays the graphics screen during the CUT operation.  The
            screen will be restored to the "default" after the cut is complete.
            If not specified, the screen is not altered.

    SLOW    - Turns video waits on during the CUT operation.  The waits will
            be restored to the "default" established by XINIT after the cut
            is complete (RS board only -- see XINIT).  Wait status is unchanged
            if not specified.  Use SLOW=N to turn video waits off.

    NO      - Supresses all Display Output, so that programs that call XCUT
            (i.e. From BASICG via SYSTEM"XCUT...") will not have their display
            messed up.  Note that this suppresses all error messages except
            "Parameter Error", so be careful!

  You may XCUT any region from the graphics memory and store it in the BUFFER
bank.  X may be any number from 0 to 1023, and Y any number from 0 to
255.  Here is an example:

  XCUT TEST1 0,0-100,80 (NO)

  This command will store the graphics frame from (0,0) to (100,80) in the
Buffer Bank, and catalog it there under the name "TEST1".   If an error occurs
(such as "no more room in buffer"), then no error message will display (because
of the "NO" parameter).  If the "NO" parameter had NOT been specified, and no
error occurs, XCUT would THEN have displayed a message stating the amount of
memory left available for storing frames (in bytes).

  Please note that all parameters may be abreviated to their first character.
Also note that the graphics screen is not altered in any way by XCUTing.  Use
XPASTE to get the frames stored in the Buffer bank back to the screen.  


Error Messages
==============

This is a listing of the possible error messages reported by XCUT, along with
their meanings, and possible solutions for "fixing" the error.  The error
number listed is the code returned in the "_ERRRNT" field of the XHRG high
memory module.  An error code of zero indicates successful completion of the
XCUT  (see Technical Notes for more information). 

'Parameter Error!' (error #1)
 -- You mis-spelled one of the parameters, forgot to enclose the parameters in
parentheses, or use a parameter other than IMAGE, GRON, TEXT, SLOW, and NO.

'XINIT must be Installed before using XCUT' (error #2)
 -- You didn't use XINIT to install the required High Memory Module.  Type
"XINIT" from LS-DOS (or TRSDOS) Ready.

'Illegal, Missing, or Duplicate Frame Name' (error #4)
 -- You forgot to specify a frame name, your frame name didn't start with a
letter (A-Z), your frame name had a character in it other than a letter or
number, or a Frame with that exact name already exists in the Buffer Bank.
Try another name.

'Illegal Frame Coordinates' (error #8)
 -- Your "x1,y1-x2,y2" coordinates specified a point outside the range of
Graphics Memory.  "x1" and "x2" must both be between 0 and 1023 (inclusive),
and "y1" and "y2" must both be between 0 and 255.

'No Room in Buffer for Specified Frame!' (error #16)
 -- You have specified too many frames for the Frame Buffer to hold.  Either
try a smaller frame, or start over by clearing the Frame Buffer (this is done
with XINIT, by saying "XINIT (CLEAR)".

'Syntax Error in Coordinates' (error #32)
 -- You didn't separate your coordinates with commas, or you typed a space
or other illegal character within the coordinates.

'Frame Name too Long!' (error #64)
 -- The name of your Frame must be 8 characters or less.

'There is no Frame Buffer assigned!' (error #128)
 -- You must use the "BUFFER" parameter of XINIT to assign a bank for use as a
frame buffer.  Use "XINIT (B=n)", where 'n' is the number of the bank you wish
to use.


==========


  This software is Copyright 1987 by Paul Bradshaw, and is distributed as
"ShareWare".  You are free to copy and/or give away this software to anyone, or
post it on any other bulletin boards for private use PROVIDING that the program
and documentation (including this statement) are kept intact, unaltered, and
bundled together, and that no charge shall be made for such distribution of any
kind without the written permission of the author.  A $5 contribution may be
made to:

Paul Bradshaw
1372 West Second Ave
Columbus OH  43212

  For this $5, you will be registered as an owner of this software, and
immediately notified of any fixes, updates, and/or further additions and
enhancements.  This $5 covers this program, the XINIT program, and the XPASTE
program only.  If you do not register yourself as a user, please erase this
program and documentation from your disks.  Thank you, and I hope you like this
program.  Please forward any suggestions and/or comments to the above address,
or directly to me via CompuServe EasyPlex [72177,2032].  Enjoy!
