                Run Menu
                --------
                        
The "Run" menu allows you to define your own menu items to
run external programs.  This can be used for frame grabbers,
printers, paint programs, image processing, or any other 
MS-DOS application.

You define these menu items, and associated actions, by
placing commands in the PKTV.CFG file.  The general format is:

        RUN_MENU "menu item" keyboard action action ...

Details:

    RUN_MENU

        The line begins with this in either upper or lower case.
        The entire command must appear on a single line, which
        could get quite long.

    "menu item"

        This is what you want to appear in the menu.
        For example: "HiRes 32..."
        You can omit the quotation marks (") if the item does 
        not contain any blanks.

    keyboard

        A single character for the keyboard equivalent.  
        When no menu is visible, the menus are searched from 
        left to right so the Run menu is first.
        If you defined a Run menu item with the letter "P", 
        pressing the P key would select this item instead of 
        Print in the File menu.
        In this case, you would have to display the File menu 
        first (with Alt-F) then press P to select the Print 
        function from the keyboard.

    action

        Finally, you specify one or more "actions" to perform.
        These include:

            SELECT="prompt"     - Display the file selector.
            SAVE="file-name"    - Write the current image to 
                                  a file.
            RUN="command"       - Run a program or batch file.
            OPEN="file-name"    - Read an image file.
            DELETE="file-name"  - Delete a file.

        Again, the quotation characters (") may be omitted if 
        the item does not contain any spaces.  It is very 
        important to remember that there MUST NOT be any 
        spaces before after the equal sign (=).  This is valid:

                OPEN=XYZ.BMP

        But this is not valid:

                OPEN = XYZ.BMP


More details are contained in the examples below.  When 
adding your own it is easiest to start with an example 
closest to your needs and make minor adjustments.


Example: MS-DOS Prompt
----------------------

        RUN_MENU "DOS prompt..." ! RUN=

This is a special case of the RUN action item which gives you 
the MS-DOS command interpreter.

When you pick the "DOS prompt..." menu item, or press the "!" 
key, you will get the MS-DOS command prompt.  When you type 
"EXIT", control will return to Pasokon TV.


Example: Frame grabbers
-----------------------

For Ventek VIP 640C:

        RUN_MENU "VIP 640C..." V RUN="PKVIP DIG~TMP.TGA" 
                        OPEN=DIG~TMP.TGA DELETE=DIG~TMP.TGA

The PKVIP program grabs an image from the VIP 640C video 
digitizer and stores it into the specified file.   There is 
nothing special about the file name.  I just happened to put 
the ~ character in the middle to minimize the chance of 
overwriting some existing file.  

The OPEN action causes the specified file to be read. 

The DELETE action causes the specified file to be deleted.

PKVIP.EXE is described in the file PKVIP.TXT.

PKVIP was written by Ventek in response to all the people who 
wanted to use their product with Pasokon TV.  Please contact 
them if you need further assistance with this program.


For Digital Vision Computer Eyes RT:

        RUN_MENU "Eyes RT..." E RUN="HAMCAP TG=DIG~TMP" 
                        OPEN=DIG~TMP.TGA DELETE=DIG~TMP.TGA

Note that there is no file type specified in the TG= command
line argument.

Here is a slight variation:

        RUN_MENU "CE RT S-Video..." E RUN="HAMCAP SV=1 TG=DIG~TMP" 
                        OPEN=DIG~TMP.TGA DELETE=DIG~TMP.TGA

The only difference is the "SV=1" command line option which 
means use the S-video input rather than the NTSC composite input.

HAMCAP.EXE is based on the CECAP program and is described in
the files CECAP.TXT and HAMCAP.TXT.

HAMCAP was written by Digital Vision in response to all the 
people who wanted to use their product with Pasokon TV.  Please 
contact them if you need further assistance with this program.  
I borrowed one of these during development but don't have it 
any more.

Note: The File menu has a predefined item for running a video
digitizer program.  You can't change the menu item and keyboard
equivalent but the action items are the same as the Run menu.


Example: A non-supported printer
--------------------------------

        RUN_MENU "Acme Print" P SAVE=SSTV~TMP.BMP
                RUN="ACMEPRIN SSTV~TMP.BMP" DELETE=SSTV~TMP.BMP

Pasokon TV has built-in support for most popular types of
printers used with personal computers.  Other printer types
can be used with suitable external programs.

In this case, pressing the "P" key would save the current 
image in a temporary file called SSTV~TMP.BMP, run the 
hypothetical ACMEPRIN program to print the file, and finally
delete the file.


Example: Paint programs
-----------------------

        RUN_MENU "HiRes 32..." H SAVE=SSTV~TMP.TGA256 RUN=HIRES32 
                        OPEN=SSTV~TMP.TGA256 DELETE=SSTV~TMP.TGA

Note: This must appear on a single long line.  It was broken into
2 lines, above, to fit better in this document.

The SAVE action, causes the current image to be stored into a
file called SSTV~TMP.TGA.  The special file extension of ".TGA256"
means store it as a 256 x 240 image with only 32K colors for
compatibility with older versions of HiRes 32.

Next, the RUN item means run a program called HIRES32.  If you
don't specify a complete location with directory, the program 
must be in the current directory or it must be somewhere in
the directory search path.

The HiRes 32 program does not use a command line argument for
a file name.  Instead it looks for the specific name SSTV~TMP.TGA.
It reads this file automatically.  When you exit from the program
it saves the results in this file.

When Pasokon TV regains control, the OPEN action item tells it
to read the modified SSTV~TMP.TGA file.  The extra "256" on the
end of the file name extension is for compatibility with version
2 and has no effect.

Finally, the DELETE item gets rid of the temporary file.

Note: The actual sample implementation in the PKTV.CFG file is
a little different.


Example: Image creation program
-------------------------------

        RUN_MENU Flag Z RUN="FLAG FRANCE FRANCE.TGA" 
                        OPEN=FRANCE.TGA DELETE=FRANCE.TGA

This simple program generates flags for a several countries.

The type of flag can be changed by specifying a different
country on the command line.  Source code, FLAG.C, is provided
so those interested can see how it works and use it as a
starting point for their own applications.


Example: Read a GIF file
------------------------

        RUN_MENU "Open GIF..." SELECT="Pick GIF file for read:"
                RUN="GIF2TGA %1 TEMP1$$.TGA"  OPEN=TEMP1$$.TGA  
                DELETE=TEMP1$$.TGA

This version of Pasokon TV does not read GIF files.  The 
reason is that Unisys holds a patent for the compression 
technique used in GIF files.  Anyone using GIF files in a 
commercial or shareware product must obtain a license and pay 
royalties on every copy sold.  That's why GIF support is
disappearing from more and more programs.

This restriction does not apply to completely FREE (not
shareware) software.

You really wouldn't want to save your beautiful SSTV pictures
in GIF because it can handle a maximum of only 256 colors.
However, there might be cases where you'd want to read an 
existing GIF file.  Here is a work-around.

Define a menu item as shown above.  The SELECT action item
means display the file selector with the prompt shown.
In the RUN action item, the "%1" means the result of the 
first SELECT item.  An external program is used to convert
the specified GIF file to a TGA file.  This temp file is
read and deleted.

The GIF2TGA program is a free program.  It is being passed 
along as a free service because there is some space left 
over on the diskette.  It is not part of the purchase price.

Obviously, the same technique could be used with any other
image conversion program that is controlled by command line
arguments.


Example: Remote control of transceiver
--------------------------------------

Many modern ham transceivers have the ability to accept commands
from a serial port.  You might want to define menu items to
move to your favorite frequencies.  Suppose you had a program
called SETFREQ which would set the frequency of your transceiver.
You might define menu items resembling:

        RUN_MENU "14.230" 1 RUN="SETFREQ 14230 USB"
        RUN_MENU "14.233" 2 RUN="SETFREQ 14233 USB"
        RUN_MENU "3.857" 3 RUN="SETFREQ 3857 LSB"
        RUN_MENU "3.862" 4 RUN="SETFREQ 3862 LSB"

Just press 1, 2, 3, or 4 to jump between your favorite spots.

This example uses an imaginary program called SETFREQ.  If 
someone sends me examples of real programs I'll use them instead.


Example: An MS Windows program
------------------------------

It is possible to start a Microsoft Windows (3.1) application 
from the MS-DOS command line like this:

        win c:\windows\pbrush c:\src\pktv30\sstv~tmp.bmp

This means:
    1. Start Microsoft Windows.
    2. Automatically run the Paintbrush program.
    3. Pass a file name to the application, causing it to
        automatically read that file when it starts up.

You might be tempted to try something like this:

        RUN_MENU "Paintbrush..." P SAVE=SSTV~TMP.BMP 
                RUN="win c:\windows\pbrush c:\src\pktv30\sstv~tmp.bmp" 
                OPEN=SSTV~TMP.BMP DELETE=SSTV~TMP.BMP

I tried it and it gave me some error message about VDA.386 
whatever that is.

I suspect it is impossible, or at least difficult, to make this
work because Pasokon TV has already grabbed most of the memory
for itself.  There is not enough left over to start Windows.

