                                 FOTO 1.02
                                 ---------

    FOTO is a utility to take a screen snapshot of an OS/2 character
    mode screen.  The snapshot can be recalled via a hotkey, and it can
    be stored in a disk file.  FOTO is not for PM or other graphical
    applications, or for sessions running in windows--it is only for
    fullscreen character mode sessions.

    This is a bit of a "quick & dirty" utility; some amenities are
    missing from the current version.  Most important of these is that
    the hotkeys are fixed and can't be changed by the user.  When time
    permits, we will release a version with user-definable hotkeys.


    Loading
    -------
    The basic syntax used to load FOTO is:

        [d:][path]FOTO [/Q] [FILE=[d:][path]name[.ext]]

    When loaded without any parameters, FOTO loads and remains resident
    (in background) awaiting a hotkey wakeup call; you are returned to
    the OS/2 command prompt.

    The /Q option specifies "quiet" operation; with this option, FOTO
    will not make any noise unless an error is encountered and FOTO is
    unable to display a message.

    The FILE option allows you to specify a filename for the snapshot
    file; if no name is specified, FOTO will use the name FOTOxx.TXT,
    where xx is the two-digit number that identifies the current
    session.  It will be located in the root directory of the drive that
    contains FOTO.EXE.

        NOTE: all FOTO keywords except ALL (i.e., FILE, SESSION,
        LIST, and KILL) can be truncated to as little as one
        character.  For example, any of "L", "LI", "LIS", and
        "LIST" will be accepted.

    An example of a complete load command:

        d:\os2util\foto /q f=c:\snap.txt

    This example loads FOTO, specifies quiet operation, and causes FOTO
    to use a file named C:\SNAP.TXT for snapshots written to disk.

    When FOTO loads, it will display a brief report indicating the
    current session number (in hex), the snapshot filename, and a
    reminder of the hotkey assignments.

    NOTE: while FOTO is loaded, its executable file (FOTO.EXE) is
    protected by the system and cannot be deleted or moved.


    Taking snapshots
    ----------------
    Once loaded, FOTO can be called up at any time by pressing Alt-P
    (think of Photo).  The screen must be in text mode, else FOTO will
    beep at you and refuse to pop up.

    FOTO pops up a window and displays a brief menu:

        FOTO option menu
        F - snapshot to file and memory
        M - snapshot to memory only
        U - unload FOTO
        Enter option (or ESC):

    Press 'F' to take a snapshot of the current screen, save it in
    memory, and copy it to the snapshot file; a brief tone sounds to let
    you know that the operation was successful.  A double-pitch tone
    sounds if there is a problem (disk full, bad filename, write
    protected, etc.)  If the snapshot file already exists, the new
    screen will be appended to it; a divider row of hyphens is placed
    below each screen photo.

    Press 'M' to take a snapshot of the current screen and save it in
    memory only; the snapshot is not appended to the snapshot file.  A
    brief tone sounds to let you know that the snapshot was successful.

    Press 'U' to unload FOTO from memory.

    Press ESC to return to the active session without taking any action.


    Quick memory snapshots
    ----------------------
    To take a memory snapshot at any time, press Shift-Alt-P.  This is
    equivalent to pressing Alt-P and selecting M from the menu.  A brief
    tone sounds to let you know that the snapshot has been taken.


    Viewing snapshots
    -----------------
    To view a previous snapshot (taken with Shift-Alt-P or 'M' from the
    menu), press Alt-V.  You must be in the same screen mode (text, same
    number of rows and columns) as when the snapshot was taken.

    Press any key to return to the live screen.


    Unloading FOTO
    --------------
    You can unload FOTO by selecting 'U' from the menu (as described
    above) or from the command line.  To unload from the command line:

        [d:][path]FOTO KILL


    Selecting a session
    -------------------
    FOTO is active only within a single session (sometimes called a
    "screen group").  Normally, this will be the session that was active
    when you loaded FOTO.  However, you can select a different session
    for both loading and unloading FOTO.

    To select a session into which FOTO will be loaded, add the SESSION
    option to your FOTO command:

        FOTO SESSION=n

    'n' is the 1- or 2-digit session number, in hex.  For example, to
    load FOTO in session 0B:

        FOTO SES=0B

    With this command line, FOTO is active only in session 0B, not in
    the current session (unless the current is session 0B!).  If there
    is no such active session, FOTO will load anyway; it will become
    active if and when a session with that number is created.

    To unload a copy of FOTO from another session, simply add the
    SESSION parameter to the KILL command:

        FOTO K S=0B

    You can load a copy of FOTO in each session; each copy is
    independent, i.e., it has its own snapshot file (unless you specify
    a common name) and its own memory snapshot buffer.


    "Orphan" FOTOs
    --------------
    If you load a copy of FOTO in a session and then close the session
    without unloading FOTO, you may leave "orphan" copies of FOTO in
    memory.  These have no ill effects, but they do use some memory.

    You can use the PLIST program (included) to locate active copies of
    FOTO if you think this has happened.  A report might look like this:

        PID   PPID   Session  Name
        -----  -----  -------  ----
        x0005  x0003    x20    PMEXEC
        x000f  x0003    x04    CMD
        x0003  x0000    x01    PMSHELL
        x0002  x0000    x00    (kernel)
        x0004  x0003    x00    HARDERR
        x0028  x0011    x04    CMD
        x0025  x0000    x05    FOTO
        x0029  x0028    x04    PLIST

    A copy of FOTO is present for session 05, which is now defunct.
    This can be easily removed:

        FOTO KILL S=5

    You should note that PLIST shows the number of the session that
    activated FOTO, not the session number in which FOTO is actually
    active.  These will be the same unless you explicitly specify a
    session number when loading:

        FOTO S=0C

    In this case, PLIST would show the number of the session from which
    the FOTO command was executed, not session 0C.

    When starting a progam in a separate session for which FOTO would be
    useful, we like to use a batch file:

        d:\os2util\foto
        ...run program
        d:\os2util\foto kill

    When this is run via START (e.g., START "name" /c /fs batname.cmd),
    the program runs nicely in its own session, and FOTO is loaded and
    unloaded automatically.


    Listing and unloading all copies of FOTO
    ----------------------------------------
    You can list the session numbers for all active copies of FOTO with
    the LIST option:

        FOTO LIST

    You can also kill all active copies by adding the ALL option with
    KILL:

        FOTO KILL ALL

    Remember that, unlike other FOTO keywords, "ALL" cannot be
    abbreviated.


    Version history
    ---------------
    1.02 9/3/91
        Corrected a problem when a screen contains data in the
        roghtmost column

    1.01
        Improved error messages (some displayed unwindowed)
        Miscellaneous internal cleanup

    1.00 03/22/91
        Initial release


    Copyright/License/Warranty
    --------------------------
    This document and the program file FOTO.EXE ("the software") are
    copyrighted by the author.  If you are an individual, you are
    licensed to:  use the software; make as many copies of the program
    and documentation as you wish; give such copies to anyone; and
    distribute the software and documentation via electronic means.
    There is no charge for any of the above.

    However, you are specifically prohibited from charging, or
    requesting donations, for any such copies, however made; and from
    distributing the software and/or documentation with commercial
    products without prior permission.  An exception is granted to
    not-for-profit user's groups, which are authorized to charge a small
    fee (not to exceed $7) for materials, handling, postage, and general
    overhead.  NO FOR-PROFIT ORGANIZATION IS AUTHORIZED TO CHARGE ANY
    AMOUNT FOR DISTRIBUTION OF COPIES OF THE SOFTWARE OR DOCUMENTATION,
    OR TO INCLUDE COPIES OF THE SOFTWARE OR DOCUMENTATION WITH SALES OF
    THEIR OWN PRODUCTS.

    THIS INCLUDES A SPECIFIC PROHIBITION AGAINST FOR-PROFIT
    ORGANIZATIONS DISTRIBUTING THE SOFTWARE, EITHER ALONE OR WITH OTHER
    SOFTWARE, AND CHARGING A "HANDLING" OR "MATERIALS" FEE OR ANY OTHER
    SUCH FEE FOR THE DISTRIBUTION.  NO FOR-PROFIT ORGANIZATION IS
    AUTHORIZED TO INCLUDE THE SOFTWARE ON ANY MEDIA FOR WHICH MONEY IS
    CHARGED.  PERIOD.

    Businesses, institutions, and governmental entities are prohibited
    from installing or using the software on their systems without
    specific permission from The Cove Software Group.

    No copy of the software may be distributed or given away without
    this document; and this notice must not be removed.

    There is no warranty of any kind, and the copyright owner is not
    liable for damages of any kind.  By using this free software, you
    agree to this.

    The software and documentation are:

                           Copyright (C) 1991 by
                          The Cove Software Group
                           Christopher J. Dunford
                               P.O. Box 1072
                          Columbia, Maryland 21044

                               (301) 992-9371
                       CompuServe 76703,2002 [IBMNET]
             Internet, Bitnet, etc.: 76703.2002@compuserve.com

              Software and documentation author: Chris Dunford
