ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/UTILITY/BATCH/INT11.ZIP/INT.DOC

Text File | 1992-03-24 | 14.3 KB | 310 lines

               Documentation for INT.COM version 1.1

        INT.COM is Copyright (C) by David Abbott,  August 1990.

     This documentation,  with the exception of the disclaimer and
  licence agreement,  is also Copyright (C) by David Abbott 1990-1992
                          All Rights Reserved.


CONTENTS:

    * Warning
    * Disclaimer
    * Introduction
    * Usage
    * Examples
    * Beginner's guide
    * History
    * Bugs
    * Licence agreement


WARNING:

    This software has the ability to call DOS and BIOS routines
    which,   if used incorrectly,  may cause unintentional data
    loss. Be sure you understand exactly what a command will do
    before executing it. The potential to format your hard disk
    with one command is contained herin!


DISCLAIMER:

    The author makes no warranty, either implied or expressed,
    including, without limitation, any warranties with respect
    to the software documented here, its quality, performance,
    or fitness for any particular purpose.   In no event shall
    the author be liable for damage, whether direct, indirect,
    special, incidental, or consequential, that arise from the
    use of or any defect in the software.   The entire risk as
    to the quality and performance of the software is with the
    user.  By using this program, you acknowledge:
    (1) to have read and understood all parts of this
        disclaimer, the warning above,  and of the licence
        agreement appearing at the end of this document, and
    (2) to have agreed with and accepted all of their
        provisions.



INTRODUCTION:

    Have you ever wanted to check for a key press in a batch file, without
having the batch file wait for input?  If you have an EGA/VGA colour system,
wouldn't it be nice to be able to have full control over the colours a program
uses,  even if the program does not normally allow this?  Well now, thanks to
INT.COM,  virtually anyone can have this power!  INT.COM is a small but very
powerful utility,  which enables the easy execution of software interrupts
from the DOS command line.  Those users not experienced with software
interrupts or who don't know what a CPU register is may like to read now the
BEGINNER'S GUIDE to INT.COM which appears later in this document.  The rest of
you can continue on here.


USAGE:

              int R N [ah al bh bl ch cl dh dl si di] [;STRING]
        or:   int R N [ax bx cx dx si di] [;STRING]

    where R is one of A,a,B,b,C,c,D,or d indicating which general
    purpose register is to be returned as a DOS errorlevel: lower case
    indicating the lower byte, uppercase the high byte (e.g. D returns
    dh, d returns dl).

    N is the interrupt number to be called (in hexadecimal)

    The first group of optional arguments are 1,2,3, or 4 digit hex
    numbers specifying the contents of 8 or 16-bit registers in the
    order indicated. Thus the following command lines are equivalent:
        int a 12 34 56 07 89
        int a 12 3456 0789
        int a 12 34 56 789
    It is only necessary to supply values up to the last register you
    need to specify.  The remaining registers will be set to zero.
    NOTE: The segment registers cs,ds,es, and ss all point to the
    Program Segment Prefix (PSP).  This can be useful when supplying
    additional data on the command line (see below).

    ;STRING is used to supply additional data for some interrupts.  All
    characters appearing after the semi-colon are ignored by INT.COM,
    but are accessible to the interrupt called.  To use this feature,
    all one has to know is that the offset from the start of the PSP to
    the first character of the command tail is 81h.  Thus it is a simple
    matter to count up to the semi-colon and find the offset of the
    extra data. For example,  the following line uses int 21h, function
    9 to write the string "Hello World!" to the screen:
        int a 21 09 00 0000 0000 009c;Hello World!$
    (with the first space after int at offset 81h, Hello World must
    start at offset 9ch,  to which dx is set).

NOTE: INT.COM does very little checking of command line syntax.  As long as
the first argument is legal,  and no illegal characters appear before the
semi-colon,  INT.COM will be satisfied.  It is therefore most important that
you check the command line before execution,  or some nasty results may
follow!


EXAMPLES:

    The following examples illustrate the power and convenience of
    INT.COM,  especially when used in batch files.  To get the most
    out of INT.COM,  however,  you will need a reference listing the
    DOS and ROM BIOS interrupts.  There are many books available
    containing this information,  as well as some useful public domain
    and shareware databases.


* Check to see if ESC key has been pressed,  without waiting.  The first int
  command checks for the presence of a keypress,  the second reads it:
echo off
int a 21 0b
if not errorlevel 1 goto :nokey
int a 21 08
if not errorlevel 28 if errorlevel 27 goto :esc_pressed
rem: The above line tests errorlevel (to which register al was returned) for
rem: the value decimal 27 (ASCII code for ESC).
goto :key_not_esc


* single line batch file to set new video mode (I call this vmode.bat):
int a 10 00 %1
  This accepts the video mode number in hexadecimal.  Thus to set video mode
  on a CGA to 40x25 16 colour text, use "vmode 6".  For 640x200 16 colour
  graphics on a VGA/EGA, use "vmode E".  Consult your video card's
  documentation to see if there are other useful modes available.  For
  example, a Paradise compatible VGA card can be switched to 132 column text
  with "vmode 55".


* set VGA/EGA displayable colour 0Eh (yellow) to a different shade of yellow
  from the available palette:
int a 10 1000 37 e


* set VGA palette colour 0 (black) to very dark blue by specifying RGB values:
int a 10 1010  0000   0 11 0
             col.reg. G B  R  (remember they are in hexadecimal)
  To use this for other colours,  it is helpful to know which palette colour
  registers actually correspond to which displayable colours in the default
  palette selection.  They are as follows:
    displayable colour:  0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
    colour from palette: 00,01,02,03,04,05,14,07,38,39,3a,3b,3c,3d,3e,3f
  So to specify the RGB values for yellow, you would need to change register 3e.


* disable default colour palette/register loading on VGA mode set:
int a 10 12 01 0031
  to re-enable, use:
int a 10 12 00 0031
  This can be very useful after setting precisely the colours you want to use
  in a particular application,  to prevent these colours being reset by the
  application program itself if it resets the video mode.  In this way, you
  can use VGA colours in programs that don't support the VGA (but note that
  some programs which switch video modes during execution rely on default
  loading being enabled,  in which case you could be left with weird colours
  if you use this trick)!



BEGINNER'S GUIDE:

        Hidden inside every PC are many small programs which perform tasks
such as reading the keyboard,  setting different colours, changing video
modes,  or writing text to the screen.  These programs are contained in two
places:  the ROM BIOS (Read Only Memory Basic Input Output System) and DOS
(Disk Operating System).  Normally,  one has to write programs in assembly
language or a higher level language to access these operating system routines.
That's because they're called by what are known as software interrupts.  When
a particular interrupt is called, the computer executes the corresponding BIOS
or DOS routine,  and then passes control back to the calling program.  What's
needed, therefore, is a small program which will call the interrupt for us,
and this is exactly what INT.COM does.

        INT.COM is a small program which allows software interrupts to be
called directly from the command line,  or from within batch files. Those of
you familiar with the available DOS and BIOS interrupts will know just how
powerful a tool this makes INT.COM.  If you are not a DOS programmer,  don't
worry; included in this document are several examples of INT.COM in use.  In
addition, there are many books which list all of the DOS and BIOS routines,
and with INT.COM,  most are instantly available to anyone can write a simple
batch file (though if you can't write a simple batch file,  you should
probably just stick to copying the example batch files listed elsewhere in
this document).

        You probably would not want to call most of the DOS & BIOS routines
available, since many perform tasks such as reading or writing to particular
blocks on a disk,  disk formatting and so on.  There are a few routines which
are particularly useful though, and I'll talk about some of these shortly.
Let's now look at how to use INT.COM.  As a simple example, we'll use it to
write the letter 'Z' to the screen. To do this,  one must first know which
interrupt to call. As mentioned above,  to get the most out of INT.COM,  you
will need a book which lists all the available interrupts,  and their calling
parameters. One such book is "Advanced MS DOS Programming" 2nd ed. by Ray
Duncan (Microsoft Press),  but there are many others. Looking through the list
of interrupts,  one finds that the DOS interrupt 21h function 02h will do the
job.  The h after the number means the number is in hexadecimal (base 16).
All numbers will be quoted in hexadecimal, since INT.COM expects its arguments
to be in hexadecimal and most books list the interrupts in hexadecimal anyway.
Most interrupts are able to do several different things, and so there are
different function numbers, and sometimes sub-function numbers,  for the one
interrupt. You may well be wondering how you tell the interrupt which function
you want it to execute.  The answer is the same way you pass it other
parameters: through temporary storage locations called registers in the CPU
(Central Processing Unit).  All you need to know about the registers is how to
set them to the values specified in the description of the interrupt. This too
is done via INT.COM,  and it is now that it will be necessary to reveal the
command line syntax.  If you are not a programmer,  don't be frightened!  It
all looks more complicated than it actually is.  The formal syntax for INT.COM
is as follows:

           INT R N [ah al bh bl ch cl dh dl si di] [;STRING]

        The first argument indicates which register is to be returned, but we
don't need to worry about that here;  for now we will just set it to the
letter 'a'. N is the interrupt number in hexadecimal,  which we want to be
21h.  The first set of optional arguments are register values. Only those
registers up to the last one required need to be given a value.  Looking at
the description of interrupt 21h,  function 02h, one finds ah must be set to
02h (the function number), and dl the ASCII code of the character we want to
write (the ASCII code for 'Z' is 5Ah).  STRING is not required in this
example. We thus have all we need to write the letter 'z' to the screen. The
command to use is simply:

                    INT a 21 02 00 00 00 00 00 00 5A

Notice that registers before dl which we did not use are just set to zero;
they could be set to anything. Since no registers after dl are used,  they
don't have to be included. If you type this command exactly as printed and hit
return,  the letter 'Z' will magically appear!  Of course this example is not
of much practical use,  but some useful examples are listed elsewhere in this
document.  One word of warning though:  INT.COM does very little checking of
command line syntax.  As long as the first argument is legal,  and no illegal
characters appear before the optional semi-colon,  INT.COM will be satisfied.
It's therefore most important that you check the command line before
execution,  or some nasty results may follow!



HISTORY:
    v1.0 - May 1990
    v1.1 - August 1990: Code improved. Support added for 3-digit arguments.
           March 1992:  Expanded documentation,  added licence agreement and
                        released INT.COM for wider public distribution.


BUGS:
    Bugs?  In my program?  Hey,  don't expect me to admit to that!  This
    program has been tested on systems running PC-DOS v3.1, MS-DOS v3.x, and
    MS-DOS v5.0.  No problems have been reported.  Well,  no problems
    with INT.COM anyway,  but the example VMODE.BAT was used to diagnose
    a fault in early Trident VGA cards (some of which didn't work well
    at 640x400 and 640x480, 256 colour modes with fixed frequency
    monitors; the cards' scan rate was incorrect).  That was back in
    1990,  so hopefully things are better with the Trident cards now!


LICENCE AGREEMENT:

    INT.COM is supplied free for personal, private non-profit use at
    home or within a university or educational institution or non-profit
    organisation. For use anywhere else,  a separate licence must be
    obtained from the author. Feel free to distribute INT.COM given the
    following restrictions:

    * The program must be supplied in its original,  unmodified form,
      which includes this documentation

    * No fee may be charged

    * Commercial use under this license is prohibited

    * The program may not be included -  or bundled - with  other goods
      or services for which a fee is charged,  with the single exception
      of strictly non-profit PC clubs who may charge a fee no more than
      reasonably required to cover the cost of distribution.  Clubs so
      doing are requested to notify the author.

   *  With the exception of this licence agreement and the disclaimer,
      no part of this document may be published elsewhere without the
      prior written permission of the author.



      If you find INT.COM useful, your gift in any amount would be
      appreciated. Please direct your inquiries, complaints,
      suggestions, etc., to:

                 Internet:  [e-mail]
                       or:  [e-mail]
                 or
                              David Abbott
                              24 Yuille St.
                              Brighton,  3186
                              Victoria, Australia.


               Last documentation change: March 24, 1992.