


        ͻ
                                                                     
                                                                     
                              Image::Runner(tm)                      
                             -------------------                     
                                                                     
            developers' pcx display utility for DOS applications     
                                                                     
                                                                     
                                                                     
                                                                     
                         a product of RCCO Research                  
                                                                     
                                                                     
        ͼ


Capabilities
-------------
Image::Runner(tm) is basically a simple utility that allows DOS executable
applications to display a developer- or enduser-designed VGA .pcx file from
anywhere within the application.  It is provided in form of a small,
efficient, fast .exe meant to be called with the system command processor
in the host application.  Image::Runner will display 640x480x16 VGA pcx
images that may contain static graphs, artwork, or other graphic objects
needed in an application.

While it has always been possible to execute other programs from within an
application that will display such images, Image::Runner provides advantages
for the commercial developer in that, upon payment of a very nominal
registration fee, it may included and distributed with multiple applications
legally and without further license, restriction, or payment of runtime
royalties.

Image::Runner may be called multiple times from within an application and
adds little overhead to the executable sequence.  The called pcx image
displays until the end-user presses a key, then returns quickly and
efficiently to the calling program.  An alternate version (included)
displays the image for about six seconds, also waiting for a keypress from
which to return; if such a keypress is not made during the delay interval,
it then returns automatically.

Image::Runner may be used with most traditional MS-DOS language executables,
including those created with CA-Clipper, Borland Turbo Pascal, QuickBASIC,
PowerBasic, Visual Basic(tm) for DOS, dBase, Clarion, C/C++, etc.   It is
very small, very efficient, and executes cleanly and quickly from within any
DOS program; its small file size (about 29k, not compressed) provides for
minimal space usage on distribution disks and is non-obtrusive and very
discrete to the end-user as to its purpose.  (An attempt by an end-user to
execute '_i_.exe' without knowledge of the proper command line parameter
will yield nothing other than an exit back to the DOS prompt.)

Image::Runner image displays will run under both DOS and Windows.  The chief
advantages, aside from the displays themselves, are both low cost and method
of acquisition.  The copy included herewith is a fully-functional evaluation
copy available easily and universally through the user-supported software
marketplace.
 



IRDemo.exe and the sample files
--------------------------------
To run the demonstration files included in this package (IRDEMO.EXE and 2
sample pcx files), copy all pertinent files (including _I_.EXE) to a
directory on the hard disk (or a ram drive), and simply execute

                           IRDEMO <enter>

from the DOS prompt.  IRDEMO is a C language program that will call the
Image::Runner utility (ie, _i_.exe) twice using the system() function;
other languages will call a similar instruction (see below).

For tolerable viewing results, do not run the demo from a floppy drive.




Preparation of images
----------------------
Image::Runner is particularly effective for software developers preparing
static graphs, artwork, or other images for their applications, in that they
can easily capture usable materials with programs like Hijaak(tm) for Windows
and modify or create them in editing programs such as Windows(tm) Paintbrush.
Image names may also be selected by the end-user via a menu selection and
passed to to the calling sequence with the appropriate string.
 
The only requirement is that images must be finally saved in 640x480 16-
color VGA .pcx file format.  If you are doing image preparation in Windows,
you will have to load a 16-color video driver for 640x480 VGA in order to
prepare proper images.  This format is used since it is the most universal
that will allow presentations to be viewed on as many DOS and/or Windows
VGA systems as possible.  Do not build your images with 256 or more colors
as they will not display with Image::Runner.  The end-user should then
be able to properly display using any VGA card and driver with 16 or more
colors; it is only during the preparation and saving of .pcx images that you
must use a 640x480x16 driver.
 
We have observed excellent, consistent results with using a program such as
Hijaak(tm) for Windows to capture entire DOS or Windows screens, or selected
areas of screens, or a particular window on a full Windows screen.  The pre-
parer then does final editing, adding text, drawing lines or other objects,
in a drawing program.  For example, the two sample pcx images provided with
this package were done entirely in the program that comes free with Win-
dows(tm) 3.1:  Paintbrush.  The inset picture in _ADMIN1.PCX was captured
from a black and white line drawing with a hand scanner and edited in Paint-
brush.
 
Other graphics programs are likely to provide compatible material, but they
must be tried on a test basis with Image::Runner.  The two programs mentioned
above work well for most users, are widely available, and do not require
great technical or artistic ability.  Scanned images will be effective in
Image::Runner if they are saved in the proper format.  If one format you are
using seems not workable, try saving that image in another program, such as
Windows Paintbrush; we have often found that certain images work better when
converted or simply saved in another program's format even though they may
use the same .pcx extension.
 
When attempting to use monochrome pcx files, resave them as 16-color
640x480 VGA pcx files.  Even though the appearance may remain the same,
they will be saved in a format usable by Image::Runner.
 
Once you find the right combination of steps to produce pcx file formats
consistently usable by Image::Runner, you will save a great deal of time
and effort by always using that combination in future applications.
 



Running Image::Runner from within your application
---------------------------------------------------
The basic requirement is that the image files and the related executables
be placed in the same directory on a hard drive.   Alternatively, the
Image::Runnner executable may be in the path, and the .pcx files may be
local in any directory from which you wish the images to display.  You
should advise end-users against running your application from a floppy
disk, due to the slowness of building the on-screen image when reading
from a diskette.
 
Your end-users will certainly need VGA graphics capabilities to view your
images.  If a user attempts execution on a non-VGA-capable system, a simple
screen will display the message
 



                   ͻ
                                                           
                     Image display requires VGA graphics.  
                                 (640x480x16)              
                                                           
                   ͼ

 



and return to the calling program after a 2-second delay.


The calling sequence for all languages will consist of the traditional
instruction for utilizing the command processor from within the program
plus an indication of the command line parameters:

                           _i_ x.pcx

where '_i_' indicates the _I_.EXE Image::Runner utility, and 'x.pcx'
is the full filename (including extension) of the 640x480x16 pcx image
you wish to display.  The image will not display without specifying the
.pcx extension.

You need not specify a clearscreen before or after the image display; a
clearscreen is automatic with an Image::Runner call.  Therefore, it may be
desirable to save and restore (or recreate) the screen existing at the time
of the call.  Also, if the non-VGA text screen is displayed (see above),
please note that the text cursor is momentarily turned off and then turned
on again as the screen exits; if, by chance, your program was originally
executing with the text cursor turned off, you may need to turn it off
again upon reentry.






Specific languages example calls
---------------------------------
The following examples provide typical calls to display a 640x480x16 pcx
image from within a program.


QuickBASIC, PowerBasic, Visual Basic for DOS
---------------------------------------------

   SHELL "_I_ X.PCX"




dBase and Clipper S '87
------------------------

   RUN _I_ X.PCX





CA-Clipper
-----------

   run _i_ x.pcx

   // may also be overlayed with Blinker's

   //       SwpRunCmd("_i_ x.pcx")

   // although this may be overkill for a simple
   // utility such as Image::Runner.





Clarion
--------

   OPEN(SCREEN)
   RUN('_I_ X.PCX')
   CLOSE(SCREEN)
   RETURN




Turbo Pascal
-------------
This is one suggestion for Turbo Pascal use; most Pascal developers will
have their own preferred method of executing a DOS program from within an
application.


{$M $8192,0,0 }  { stacks spec, used by drun procedure }
uses crt, dos;

procedure drun(what : string);
   begin
      swapvectors;
      exec(getenv('COMSPEC'), '/C ' + what);
      swapvectors;
      if DosError <> 0 then
         WriteLn('Could not execute COMMAND.COM');
      WriteLn;
   end;


{ call the image display within the program: }

   drun('_I_ X.PCX');




C programs
-----------
Although there are several excellent ways to call DOS processes,
including the many variants of SPAWN and EXEC, we provide herewith
the simple and direct use of the system() function.


   #include <process.h>   /*  or stdlib.h  */

   ...

   system("_I_ X.PCX");


(The sample demo program included in this package uses the system()
function.)



Other development environments will have equivalent methods for executing
a DOS executable program via the command processor; consult the appropriate
reference manual for specific procedures.



Batch files
------------

   @echo off
   _i_ x.pcx




From the DOS system prompt
---------------------------

   C:\DIR\_i_ x.pcx <enter>





In all instances, the calling of '_i_.exe' and the resulting image display
do not require a great deal of memory and therefore generally may be used
in a typical 640k DOS memory environment.




The alternate version, _i2_.exe
--------------------------------
The present package also contains an alternate version of the Image::Runner
executable, _i2_.exe.  While the main version of the program, _i_.exe,
requires a keypress from the enduser before returning to the calling program,
the alternate program _i2_.exe displays the image for about six (6) seconds,
waiting for a keypress from which to return; if such a keypress is not made
during the delay interval, _i2_.exe returns automatically to the calling
program.  Although not utilized by the included demonstration (irdemo.exe),
the usage of _i2_.exe is exactly the same as that of _i_.exe.  It offers an
additional choice for method of execution by the developer.

During the six-second image display, the enduser may press the <pause> key
on an enhanced keyboard to hold an image in view for a longer period; when
ready, the user may then press <spacebar> or any other regular key to
continue.
 
At initial glance, you may feel this alternate form of execution is always
more desirable for use than the main version (_i_.exe), but do realize that
certain images which contain a sizeable portion of text or other complex
content may simply leave the user's view too soon with the six-second display
without providing enough time for adequate perusal.  In ordinary use, a six-
second delay was found to be about the maximum amount to utilize without the
viewer feeling that images stayed on the screen for an agonizingly long
period of time.




Troubleshooting
----------------
The only caveat we might offer with this program is that if you find that
your images do not display, or do not display properly, it is probably
because they have been created or saved in a format that may only be
slightly incompatible with that which Image::Runner requires.  Before
you decide that the Image::Runner program is not usable in such instances,
try the suggestion given before for re-saving your .pcx files in another
graphics program.  Most image-editing programs will read files in several
formats, and often allow conversions, or perhaps will save them in a later
.pcx format that will work with applications such as Image::Runner.
 
Also, make certain that images are saved in 640x480 by 16-color format by
using the proper software and/or video drivers to handle the format.
 
 
 
 
 
 
Program Requirements
---------------------
The requirements for running Image::Runner include a DOS-compatible PC
with 512k memory, VGA graphics capability, and a hard drive.  DOS 3.1 (or
later) or Windows 3.x (or later) should be utilized.




The Unregistered Evaluation Copy
---------------------------------
The unregistered version of this program is intended for use in evaluation
situations.  It may be used for ninety (90) days within your own organ-
ization by persons that have knowledge and understanding of the fact that
this is an unregistered evaluation copy.

The payment of the $24.95 purchase price for a registered copy of this
program will allow license for a single user to make use of the program for
purposes that are traditionally accepted for software utilities of this
type.  Additional site license fees of $10.00 per user may be paid at the
time of registration, or any time in the future after initial registration
at the then current license fee in effect.  There are no runtime royalties
involved in the distribution of your materials utilizing a duly registered
copy of Image::Runner.
 
The license and authorized registration shall not be construed as being
in effect until direct payment has been received by RCCO Research and an
authorized, registered copy has been sent in the registered user's/users'
name(s).
 


 
The Registered Version of Image::Runner
--------------------------------------------
The registered copy performs the same execution as the evaluation copy, only
without the unregistered copy delay at the close of the VGA display.

Documentation for the registered version is an on-disk text file, similar to
the present format.





Licensing Information
----------------------
This program is licensed and supplied as is, without any warranty.  To the 
extent permitted under applicable law, RCCO Research Associates disclaims 
all warranties, either expressed or implied, with respect to this software 
program, its quality, performance, merchantability, or fitness for any 
particular purpose.
 
In particular, this software program is not guaranteed to prevent or detect
damage to your data or programs.  In no event shall RCCO Research Associates
be liable for any claims for lost profits or any damage, including, but not
limited to, special, incidental, consequential or other damage (including, 
without limitation, damages for loss of business profits, business interrup-
tion, loss of business information, or other pecuniary loss) arising out of
the use of or inability to use this RCCO Research Associates product, even
if RCCO Research Associates has been advised of the possibility of such
damages.  Some states do not allow the exclusion or limitation of incidental
or consequential damages, so the above limitation or exclusion may not apply
to you.  In no case shall RCCO Research Associates's liability exceed the
license fees paid for the right to use the licensed version of the software. 
 
The license agreement and warranty shall be construed, interpreted and
governed by the laws of the state of Tennessee.
 
This software program is protected under the Copyright Laws of the United 
States of America and all applicable International Copyright Conventions.  
Makers and/or users of illegal or unauthorized copies of the registered 
version are subject to prosecution under these laws.
 
The name  Image::Runner(tm)  is a trademark of RCCO Research Associates.
Windows(tm) is a trademark of Microsoft Corporation.  Other trade names
referenced herein are either trademarks or registered trademarks of their
respective companies.
 
 
 
 
 
Registration Notes
-------------------
Registration will obtain a copy of the most recent authorized version and
provide legal authorization for continued use of the program after the
ninety-day (90-day) evaluation period.
 
To obtain a registered copy, you may mail an advance-payment registration
fee of U.S. $24.95 + $2.55 shipping/handling ($7.05 non-U.S. shipping/
handling, $4.05 for Canada) directly to RCCO Research.  Additional users
are $10.00 per user.  Payment is to be made by check or money order only,
please.  We require payment with order so that prices and fees may be kept
as reasonable as possible; this policy has worked well for us in recent
years, as we observe increased registration on products that are reasonably
priced.  For telephone and credit card orders, see Additional Ordering
Options note below.
 
An invoice will be included with your order, showing the registered serial
number(s) applicable to the purchase.  We can provide a pro forma invoice
to those corporations or institutions that require same before payment can
be issued; shipment will be made promptly upon receipt of payment.  Prices
and/or registration and/or license fees are subject to change.

Tennessee clients please include the required 8.5% sales tax on both the
product amount and shipping/handling as mandated by the state.
 
International clients must pay by check or money order in U.S. dollars, drawn
on a U.S. bank or the U.S. branch of an international bank.  Please realize
that international postal money orders are considerably delayed through the
postal systems and may not be the most expedient way of relaying payment.  An
often-used form of payment consists of obtaining a dollar-denominated money
order from the local American Express office which you may then airmail to
us along with your order.  International orders are dispatched promptly
when using a credit card order as outlined below, under Additional Ordering
Options.

Please indicate program name and current version number on your order; you
may use the Order.frm file provided in this package, or simply send a note
or letter with your name, organization name, address, program name and
version, number of users being licensed, and remittance.  Your comments on
our programs are welcomed.

 
 

     Additional Ordering Options:
     ----------------------------------------------------------------------
     CREDIT CARD ORDERS ONLY -
     You may order a registered copy of this RCCO Research program
     with MasterCard, Visa, Amex, or Discover from PsL, Public (software)
     Library of Houston, Texas by calling 800-242-4775 or 713-524-6394,
     or by FAX to 713-524-6398, or by CompuServe E-mail to 71355,470;
     Internet address:  71355.470@compuserve.com.  PsL's office hours are
     7:00am to 6:00pm CST Monday-Thursday and 7:00am to 12:30pm CST on 
     Fridays.  You may also mail credit card orders to PsL at P.O. Box 
     35705, Houston, TX 77235-5705 (U.S.A).  Please include the cardholder
     name exactly as it appears on the credit card plus the billing 
     address for the card.

     PsL's item/product number for Image::Runner is #11623.

     THE ABOVE NUMBERS ARE FOR ORDERS ONLY.
     Any questions about the status of the shipment of the order,
     registration options, product details, technical support, volume
     discounts, dealer pricing, site licenses, etc. must be directed in
     writing to RCCO Research, P.O. Box 196, Gatlinburg, TN 37738.  To
     ensure that you get the fastest possible delivery of your registered
     copy, PsL will notify us the day of your order and we will promptly
     ship the materials directly to you.  There are no additional fees
     for ordering by credit card.

     Your credit card number is *not* transmitted to RCCO Research, but
     rather is processed by PsL as part of their software registration
     service.

     The above service is made available as a convenience to client
     individuals who wish the security and expediency of ordering by 
     telephone and/or with a credit card.  Established concerns may 
     prefer to order directly from RCCO Research with the company's 
     own business check.

     The PsL staff cannot answer non-order inquiries.
     ----------------------------------------------------------------------
 
 


 
Additional Information
-----------------------
If you have any comments or questions regarding this program after (or with)
registration, please send them to:
 
                              RCCO Research Associates
                              P. O. Box 196
                              Gatlinburg, TN 37738-0196
                              (U.S.A.)
 
Please include your phone (day & evening) and fax (if any) numbers as well
as your mailing address (and CompuServe number / Internet address, if any)
on ALL written communications.  Please indicate the serial number from your
registered copy of the program as well as your CustID number.  Our E-mail
addresses are provided to registered users along with the invoice.
 
 
RCCO Research is the publisher of Visible::Setup(tm) (a developers'
installation utility for DOS applications used widely in many parts of the
world), as well as several other popular development tools.  Please consult
your favorite user-supported software source for the availability of these
and other RCCO Research DOS and Windows programs.
 
 
 
 


Image::Runner(tm)
------------------
developers' pcx display utility for DOS applications
 

 
(C) Copyright 1994-95 RCCO Research Associates
All Rights Reserved under International Conventions
Product of U.S.A.
 


RCCO Research Associates
Post Office Box 196
Gatlinburg, Tennessee 37738-0196
(U.S.A.)
 



                     Ŀ
                          RCCO Research Associates    
                      Technical Publishers, Est. 1965 
                     


