DP Tool Club 19/CD_ASCQ_19_010295.iso/dos/prg/bas/hanlin3/aabas20/aabas.doc

Text File | 1994-11-03 | 35KB | 1,194 lines

         The Affordable Alternative Library for BASIC
         =------------------------------------------=
                         Version 2.0

     AABas  Copyright (c) 1992-1994  Thomas G. Hanlin III



This is a library for QuickBASIC 4.0 - 4.5.  It provides easy
access to BIOS and DOS calls, covering display and keyboard,
mouse, joystick, disk, printer, equipment information, XMS
memory, and more.

AABas is copyrighted and may be distributed only according to
the following simple rules:

   All AABas files must be distributed together as a unit.
   No files may be left out, added, or altered.

You use this library at your own risk.  It has been tested by
me on my own computer, but I will not assume any responsibility
for any problems which AABas may cause you.  If you do
encounter a problem, please let me know about it, and I will do
my best to verify and repair the error.

                         Using AABas



The .QLB that comes with AABas was created with QuickBASIC 4.5.
If you have one of the QuickBASIC 4.0 releases, you can still
use AABas, but you must create a new .QLB file.  The following
will do the trick:

   LINK AABAS.LIB/Q,AABAS.QLB,NUL,BQLB40

For some later releases of QB 4.0, you will need to specify
BQLB41 instead of BQLB40.  Check your QB files to see whether
you have BQLB40.LIB or BQLB41.LIB.

To use AABas routines, you must include the AABAS.BI file in
your program.  You can do this directly with a text editor, if
you like.  A simpler approach would be to place this line at
the start of your program:

   REM $INCLUDE: 'AABAS.BI'

If you compile from the command line, using BC, you must
specify AABas as a library when you LINK the program.  You can
let LINK prompt you for what it wants or type in the entire set
of parameters at once, like this:

   LINK program/EX,,NUL,AABAS

If you compile using the QuickBASIC environment, you must
specify AABas as a library when you load QB:

   QB program /L AABAS

In this case, the program name is optional.  Once in the QB
environment, you can load an existing program or create a new
one.  The /L AABAS switch allows you to use AABas routines.

                        Assorted Notes



These routines are broken into two rough categories: BIOS and
DOS.  I've included a few sets of routines in the BIOS category
which perhaps don't entirely belong there: mouse and XMS memory
routines.  Still, close enough.

The routines in the BIOS category will work on just about any
machine, with the exception of a few of the odder and older
machines.  How old is older?  Say, before mid-1984.  In other
words, compatibility is not much of a problem.

The DOS routines will work on any machine that runs DOS 2.11 or
later releases.  Compatibility is no problem at all there.

The source code for AABas is entirely in MASM-compatible
assembly language.  They require negligible space in your
program, and may even reduce the size of your program if their
use allows BASIC to remove some of its own support code from
the program.

The AABas library is based directly on BIOS and DOS routines,
with no attempt to provide anything more fancy.  The library is
intended to be small, convenient, and inexpensive-- just the
thing for folks learning about libraries for the first time or
on a budget.  You will find AABas quite powerful within these
limitations.  If you find you need something a little more
comprehensive, you may wish to examine my BasWiz and PBClone
libraries.  See the CATALOG.TXT file for more information.

Please note that the AABas disk and file routines do not
provide critical error handling.  If you expect to use them
with drives which are prone to critical errors (drive door
open, disk not formatted, etc-- the kind of errors which tend
to happen on drives with removable media), you should provide
your own ON ERROR handler.  Otherwise, depending on what the
user answers to the "A>bort, R>etry, I>gnore, F>ail?" message,
your program could be abruptly terminated by a critical error.
If you have an ON ERROR handler, you can take care of such
things in your program, rather than letting DOS handle it.

                        Reference List



BiosAlt%        return whether an ALT key is pressed
BiosBaseMem%    return amount of base memory installed
BiosCaps%       return whether CapsLock is on
BiosCheckKey$   get key from keyboard buffer, if any
BiosChkPrt%     check a printer
BiosComPorts%   return the number of com (serial) ports
BiosCtrl%       return whether a CTRL key is pressed
BiosELAlt%      return whether Left ALT is pressed
BiosELCtrl%     return whether Left CTRL is pressed
BiosERAlt%      return whether Right ALT is pressed
BiosERCtrl%     return whether Right CTRL is pressed
BiosESysRq%     return whether SysRq is pressed
BiosFloppies%   return the number of floppy drives
BiosGetKeyW$    get a key from the keyboard (wait if need be)
BiosGetVideo    get the screen width, mode, and active page
BiosInitPrt%    initialize a printer
BiosIns%        return whether Insert is on
BiosJoyPosn     get joystick positions
BiosJoyPress    get joystick buttons
BiosKeyIn%      stuff a key into the keyboard buffer
BiosKeyRep      change the key repeat rate
BiosLShift%     return whether Left SHIFT is pressed
BiosMHide       hide the mouse cursor
BiosMInit%      initialize the mouse, return # of buttons
BiosMLButton%   return whether left mouse button is pressed
BiosMLClick     return left clicks & position at last click
BiosMLocate     set the mouse cursor position
BiosMLRelease   return left releases & pos'n at last release
BiosMMButton%   return whether middle mouse button is pressed
BiosMMClick     return middle clicks & pos'n at last click
BiosMMRelease   return middle releases & pos'n at last release
BiosMRButton%   return whether right mouse button is pressed
BiosMRClick     return right clicks & position at last click
BiosMRRelease   return right releases & pos'n at last release
BiosMShow       make the mouse cursor visible
BiosMWhereX%    return the X coordinate of the mouse cursor
BiosMWhereY%    return the Y coordinate of the mouse cursor
BiosMWindow     set the allowed range for the mouse cursor
BiosNum%        return whether NumLock is on
BiosPrintCh%    print a character (to a printer)
BiosPrtPorts%   return the number of printer (parallel) ports
BiosPrtSc       print the screen on the default printer
BiosRShift%     return whether Right SHIFT is pressed
BiosScroll%     return whether ScrollLock is on
BiosScrollDn    scroll an area of the screen down
BiosScrollUp    scroll an area of the screen up

                        Reference List



BiosXClose      close an area of XMS
BiosXExists%    see if XMS memory is available
BiosXLFree&     return the largest block of XMS memory
BiosXOpen       open an area of XMS for use
BiosXRead       get information from XMS memory
BiosXResize     resize an area of XMS memory
BiosXTFree&     return the amount of available XMS memory
BiosXVer%       get the XMS driver version
BiosXWrite      put information into XMS memory

DosBreak%       return Break level
DosBreakOff     minimize Break checking
DosBreakOn      maximize Break checking
DosDelDir%      delete a directory
DosDelFile%     delete a file
DosDiskInfo     get space & capacity info about a disk drive
DosGetDay$      get the current day name
DosGetDir$      get a default disk directory
DosGetDisk$     get the default disk drive
DosGetFAttr%    get the attributes of a file
DosGetKey$      get a key from standard input
DosGetKeyW$     get a key from standard input (wait if needed)
DosGetVersion%  get the DOS version
DosMakeDir%     create a directory
DosRenFile%     rename a file and/or move it to a new directory
DosSetDir%      set default directory
DosSetDisk%     set the default disk drive
DosSetFAttr%    set the attributes of a file
DosVerify%      return disk write verification status
DosVerifyOff    turn off disk write verification
DosVerifyOn     turn on disk write verification
DosWriteSt      write a string to standard output

BiosAlt%

This function tells you whether an Alt key is pressed.

   Alt% = BiosAlt%



BiosBaseMem%

This function returns the amount of base memory installed, in
kilobytes.  These days, it will typically be 640.

   Kbytes% = BiosBaseMem%



BiosCaps%

This function tells you whether the CapsLock toggle is on.

   CapsLock% = BiosCaps%



BiosChkEKey$

This function reads a character from the keyboard.  It works
like INKEY$, but doesn't take the key from the keyboard
buffer.  This is useful for handling control characters
(Ctrl-S, Ctrl-Q, Ctrl-C, etc)-- you can have your program
recognize them if pressed, without disturbing the keyboard
buffer if someone is using type-ahead.

Actually, it doesn't work quite like INKEY$ in another fashion
which is to its advantage.  It always returns a zero or
two-character string, where the first character is the ASCII
code (CHR$(0) for extended keys, like function keys and arrow
keys) and the second character is the scan code.  For normal
keys, the scan code is always the same regardless of the shift
state of the key. That is, the scan code for "A" is the scan
code for "a" is the scan code for Ctrl-A is the scan code for
Alt-A.  Rose is a rose is a rose, eh?  This is an occasionally
useful property.

Note that this keyboard service is for "enhanced" keyboards
only.  Use BiosChkKey$ for older keyboards.

   Ky$ = BiosChkEKey$

BiosChkKey$

This function reads a character from the keyboard.  It works
like INKEY$, but doesn't take the key from the keyboard
buffer.  This is useful for handling control characters
(Ctrl-S, Ctrl-Q, Ctrl-C, etc)-- you can have your program
recognize them if pressed, without disturbing the keyboard
buffer if someone is using type-ahead.

Actually, it doesn't work quite like INKEY$ in another fashion
which is to its advantage.  It always returns a zero or
two-character string, where the first character is the ASCII
code (CHR$(0) for extended keys, like function keys and arrow
keys) and the second character is the scan code.  For normal
keys, the scan code is always the same regardless of the shift
state of the key. That is, the scan code for "A" is the scan
code for "a" is the scan code for Ctrl-A is the scan code for
Alt-A.  Rose is a rose is a rose, eh?  This is an occasionally
useful property.

Note that this keyboard service, for reasons known only to IBM,
is designed to ignore the new key codes for "enhanced"
keyboards.  This means it won't detect F11 or F12, for
instance.  Use BiosChkEKey$ for enhanced keyboards.

   Ky$ = BiosChkKey$



BiosChkPrt%

This function returns the status of the selected printer.
Status information is encoded at the bit level, as follows:

   7   not busy
   6   acknowledge
   5   out of paper
   4   selected
   3   I/O error
   2   unused
   1   unused
   0   timeout

   Status% = BiosChkPrt%(Port%)



BiosComPorts%

This function returns the number of serial (com) ports
installed.

   Ports% = BiosComPorts%

BiosCtrl%

This function tells you whether a Ctrl key is pressed.

   Ctrl% = BiosCtrl%



BiosELAlt%

This function tells you whether the left Alt key is pressed.
It works only with "enhanced" keyboards.

   LAlt% = BiosELAlt%



BiosELCtrl%

This function tells you whether the left Ctrl key is pressed.
It works only with "enhanced" keyboards.

   LCtrl% = BiosELCtrl%



BiosERAlt%

This function tells you whether the right Alt key is pressed.
It works only with "enhanced" keyboards.

   RAlt% = BiosERAlt%



BiosERCtrl%

This function tells you whether the right Ctrl key is pressed.
It works only with "enhanced" keyboards.

   RCtrl% = BiosERCtrl%



BiosESysRq%

This function tells you whether the SysRq key is pressed.  It
works only with "enhanced" keyboards.

   SysRq% = BiosESysRq%

BiosFloppies%

This function returns the number of floppy drives installed.

   Floppies% = BiosFloppies%



BiosGetEKeyW$

This function reads a character from the keyboard.  It works
like INKEY$, but waits until a key is pressed before returning.

Actually, it doesn't work quite like INKEY$, which is to its
advantage.  It always returns a two-character string, where the
first character is the ASCII code (CHR$(0) for extended keys,
like function keys and arrow keys) and the second character is
the scan code.  For normal keys, the scan code is always the
same regardless of the shift state of the key.  That is, the
scan code for "A" is the scan code for "a" is the scan code for
Ctrl-A is the scan code for Alt-A.  Rose is a rose is a rose,
eh?  This is an occasionally useful property.

Note that this keyboard service is for use with "enhanced"
keyboards only. Use BiosGetKeyW$ for older keyboards.

   Ky$ = BiosGetEKeyW$



BiosGetKeyW$

This function reads a character from the keyboard.  It works
like INKEY$, but waits until a key is pressed before returning.

Actually, it doesn't work quite like INKEY$, which is to its
advantage.  It always returns a two-character string, where the
first character is the ASCII code (CHR$(0) for extended keys,
like function keys and arrow keys) and the second character is
the scan code.  For normal keys, the scan code is always the
same regardless of the shift state of the key.  That is, the
scan code for "A" is the scan code for "a" is the scan code for
Ctrl-A is the scan code for Alt-A.  Rose is a rose is a rose,
eh?  This is an occasionally useful property.

Note that this keyboard service, for reasons known only to IBM,
is designed to ignore the new key codes for "enhanced"
keyboards.  This means it won't detect F11 or F12, for
instance.  Use BiosGetEKeyW$ for enhanced keyboards.

   Ky$ = BiosGetKeyW$

BiosGetVideo

This routine returns information about the current video mode:
the width of the screen (text columns), the screen mode, and
the active display page.

The screen mode uses a different numbering system than BASIC
(or, more properly, vice versa).  Standard BIOS screen modes
are as follows:

  Mode    Type       Resolut.  Colr  Displ.      Adapter
  ----  ---------    --------  ----  ------    -----------
    0   text mode     40x25     16    mono     CGA/EGA/VGA
    1   text mode     40x25     16    color    CGA/EGA/VGA
    2   text mode     80x25     16    mono     CGA/EGA/VGA
    3   text mode     80x25     16    color    CGA/EGA/VGA
    4   graphics     320x200     4    color    CGA/EGA/VGA
    5   graphics     320x200     4    mono     CGA/EGA/VGA
    6   graphics     640x200     2    color    CGA/EGA/VGA
    7   text mode     80x25     ..    mono     MDA/Herc
   13   graphics     320x200    16    color    EGA/VGA
   14   graphics     640x200    16    color    EGA/VGA
   15   graphics     640x350     2    mono     EGA/VGA
   16   graphics     640x350    16    color    EGA/VGA
   17   graphics     640x480     4    mono     VGA
   18   graphics     640x480    16    color    VGA
   19   graphics     320x200   256    color    VGA

   BiosGetVideo Columns%, ScreenMode%, ActivePage%



BiosInitPrt%

This function initializes the selected printer.  It also
returns the status of the printer. Status information is
encoded at the bit level, as follows:

   7   not busy
   6   acknowledge
   5   out of paper
   4   selected
   3   I/O error
   2   unused
   1   unused
   0   timeout

   Status% = BiosInitPrt%(Port%)

BiosIns%

This function tells you whether the Insert toggle is on.

   Ins% = BiosIns%



BiosJoyPosn

This routine returns the current joystick coordinates.  If only
one joystick is installed, the second set of coordinates is
meaningless, unless a FlightStick is in use.  The FlightStick
has a "throttle" dial, the value for which is returned as the Y
position of an imaginary second joystick.

Coordinates typically range from 0-400 or so.  It is a good
idea to include a joystick calibration routine in your program
since the numbers are likely to vary significantly.

   BiosJoyPosn Stick1X%, Stick1Y%, Stick2X%, Stick2Y%



BiosJoyPress

This routine tells you which joystick buttons are being
pressed.  If only one joystick is installed, the second set of
coordinates is meaningless.

   BiosJoyPress Stick1A%, Stick1B%, Stick2A%, Stick2B%



BiosKeyIn%

This function stuffs a key into the keyboard buffer.  It is for
AT-type computers only.  You may stuff up to 15 keys into the
normal buffer, depending on whether there are already any keys
pending.  A -1 will be returned if the keyboard buffer was full
and the key couldn't be stuffed.

The key specification must be as a two-character string.  The
first character is the ASCII code and the second, the scan
code.  In a pinch, you can usually get away with using CHR$(0)
for the scan code, but it is better to include the scan code
(use the BiosGetKeyW$ routine to find out the appropriate
code).

   ErrCode% = BiosKeyIn%(Ky$)

BiosKeyRep

This routine allows you to change the key repeat rate on
AT-type computers.  You must specify the delay before repeat:
0-3, for 250mS to 1 second.  You must also specify the repeat
rate: 0-31, for 30/second to 2/second (12 is the default).

   BiosKeyRep RepDelay%, RepRate%



BiosLShift%

This function tells you whether the left Shift key is pressed.

   LShift% = BiosLShift%



BiosMHide

This routine hides the mouse cursor, making it invisible.

   BiosMHide



BiosMInit%

This function tells you whether a mouse is available.  If so,
it returns the number of buttons the mouse has.  If not, it
returns a zero.

This function should be used at the start of any program which
expects to use a mouse.  You must not use any other mouse
routine unless a mouse is available.  Besides that, BiosMInit%
initializes the mouse driver to a proper starting state.

   Buttons% = BiosMInit%



BiosMLButton%

This function tells you whether the left mouse button is being
pressed.

   Pressed% = BiosMLButton%

BiosMLClick

This routine tells you how many times the left mouse button has
been pressed since the last time you checked.  It also returns
the position of the mouse cursor as of the last left button
press.

See BiosWhereX% and BiosWhereY% for information on the unusual
handling of coordinates in text and CGA SCREEN 1 modes.

   BiosMLClick Clicks%, X%, Y%



BiosMLocate

This routine sets the position of the mouse cursor.  Note that
coordinate handling is peculiar for text mode and SCREEN 1, for
which a virtual screen of 640x200 is assumed.  This means that
you will have to double your X coordinate when in SCREEN 1
mode.  For text mode, first subtract one from each coordinate,
then multiply the coordinate by eight.  Also keep in mind that
for text mode the coordinates are normally Row, Column, but are
here handled as if in graphics mode, so you need to use X, Y
(or Column, Row) order instead.

This is another fine mess Microsoft's gotten us into!

   BiosMLocate X%, Y%



BiosMLRelease

This routine tells you how many times the left mouse button has
been released since the last time you checked.  It also returns
the position of the mouse cursor as of the last left button
release.

See BiosWhereX% and BiosWhereY% for information on the unusual
handling of coordinates in text and CGA SCREEN 1 modes.

   BiosMLRelease Releases%, X%, Y%



BiosMMButton%

This function tells you whether the middle mouse button is
being pressed.  The results will not be meaningful on a
two-button mouse.

   Pressed% = BiosMMButton%

BiosMMClick

This routine tells you how many times the middle mouse button
has been pressed since the last time you checked.  It also
returns the position of the mouse cursor as of the last middle
button press.  The results will not be meaningful on a
two-button mouse.

See BiosWhereX% and BiosWhereY% for information on the unusual
handling of coordinates in text and CGA SCREEN 1 modes.

   BiosMMClick Clicks%, X%, Y%



BiosMMRelease

This routine tells you how many times the middle mouse button
has been released since the last time you checked.  It also
returns the position of the mouse cursor as of the last middle
button release.  The results will not be meaningful on a
two-button mouse.

See BiosWhereX% and BiosWhereY% for information on the unusual
handling of coordinates in text and CGA SCREEN 1 modes.

   BiosMMRelease Releases%, X%, Y%



BiosMRButton%

This function tells you whether the right mouse button is being
pressed.

   Pressed% = BiosMRButton%



BiosMRClick

This routine tells you how many times the right mouse button
has been pressed since the last time you checked.  It also
returns the position of the mouse cursor as of the last right
button press.

See BiosWhereX% and BiosWhereY% for information on the unusual
handling of coordinates in text and CGA SCREEN 1 modes.

   BiosMRClick Clicks%, X%, Y%

BiosMRRelease

This routine tells you how many times the right mouse button
has been released since the last time you checked.  It also
returns the position of the mouse cursor as of the last right
button release.

See BiosWhereX% and BiosWhereY% for information on the unusual
handling of coordinates in text and CGA SCREEN 1 modes.

   BiosMRRelease Releases%, X%, Y%



BiosMShow

This routine tries to make the mouse cursor visible.  However,
the mouse driver maintains a visibility count, so if multiple
calls were made to BiosMHide, it will take just as many calls to
BiosMShow to really make the cursor visible.

   BiosMShow



BiosMWhereX%

This function tells you the X coordinate of the mouse cursor.
This is expressed in graphics coordinates even when text mode
is in use.  For normal text modes and both CGA modes, a virtual
screen of 640x200 is assumed.  So, for 320x200 CGA mode, divide
the coordinate by two.  For 80x25 text mode, divide it by
eight.

   X% = BiosMWhereX%



BiosMWhereY%

This function tells you the Y coordinate of the mouse cursor.
This is expressed in graphics coordinates even when text mode
is in use.  For normal text modes and both CGA modes, a virtual
screen of 640x200 is assumed.  So, for 80x25 text mode, divide
it by eight.

   Y% = BiosMWhereY%



BiosMWindow

This routine restricts the mouse cursor to a specified area of
the screen.  See BiosMLocate for a description of the unusual
cursor handling in text modes and SCREEN 1 graphics mode.

   BiosMWindow X1%, Y1%, X2%, Y2%

BiosNum%

This function tells you whether the NumLock toggle is on.

   NumLock% = BiosNum%



BiosPrintCh%

This function sends a character to the selected printer.  It
also returns the status of the printer. Status information is
encoded at the bit level, as follows:

   7   not busy
   6   acknowledge
   5   out of paper
   4   selected
   3   I/O error
   2   unused
   1   unused
   0   timeout

   Status% = BiosPrintCh%(Port%, Ch$)



BiosPrtPorts%

This function returns the number of parallel (printer) ports
installed.

   Ports% = BiosPrtPorts%



BiosPrtSc

This routine sends the screen to the printer.  It works just
like pressing PrtSc (PrintScreen) on your keyboard.

If you want to print a graphics screen, you need to load the
GRAPHICS.COM TSR that came with DOS.  All versions of GRAPHICS
support CGA graphics modes.  Not all of them support EGA or VGA.

   BiosPrtSc



BiosRShift%

This function tells you whether the right Shift key is pressed.

   RShift% = BiosRShift%

BiosScroll%

This function tells you whether the ScrollLock toggle is on.

   ScrollLock% = BiosScroll%



BiosScrollDn

This routine scrolls any part of the screen down.  You may
specify the number of times to scroll.  If you specify 0, the
area will be cleared instead of scrolled.  You must specify the
colors to use on the new line(s) that was created by the
scrolling action.

   BiosScrollDn TopRow%, LfCol%, BotRow%, RtCol%, Times%,
      Fore%, Back%



BiosScrollUp

This routine scrolls any part of the screen up.  You may
specify the number of times to scroll.  If you specify 0, the
area will be cleared instead of scrolled.  You must specify the
colors to use on the new line(s) that was created by the
scrolling action.

   BiosScrollUp TopRow%, LfCol%, BotRow%, RtCol%, Times%,
      Fore%, Back%



BiosXClose

This routine closes an area of XMS associated with a specified
handle.  This must be done when you are finished using that
area of XMS, so other routines and programs will be able to use
it again later.

   BiosXClose Handle%



BiosXExists%

This function tells you whether an XMS driver is installed.

   XMS% = BiosXExists%

BiosXLFree&

This function tells you the size of the largest block of XMS
memory that is available, in kilobytes.  Compare with
BiosXTFree&.

   LargestFreeBlock& = BiosXLFree&



BiosXOpen

This routine opens an area of XMS memory for use.  The size is
specified in kilobytes.  If the specified amount of space can
be allocated, a handle is returned which you will use to access
that block in the future.  If there is an error allocating that
much memory, a non-zero error code will be returned.

Note that handles are a limited resource, so you should try to
use as few of them as possible.

The maximum size theoretically possible under the XMS spec is
65,535 kilobytes (64 megabytes).  I haven't tried this in
practice!

   BiosXOpen KBytes&, Handle%, ErrCode%



BiosXRead

This routine gets information from XMS memory.  You must
specify the memory handle, the starting offset within the
memory associated with that handle, and the number of bytes to
transfer.  The number of bytes must be an EVEN number, but is
not limited to 64k.  Finally, you must specify where to place
the information as a segment and offset in conventional memory.
For BASIC arrays and so forth, you can get this data using the
VARSEG and VARPTR functions.

Another common place to put the data might be the display.  For
text modes, this is a simple transfer.  Use an offset of 0 and
a segment of either &HB000 (MDA/Herc) or &B800 (CGA/EGA/VGA).

   BiosXRead Handle%, Posn&, Bytes&, DSeg%, DOfs%

BiosXResize

This routine allows you to change the size of a previously
allocated block of XMS memory.  You must specify the handle of
the area to resize and the desired size, in kilobytes.  If
unable to reallocate the block as specified, BiosXResize will
return a non-zero error code.

   BiosXResize Handle%, Bytes&, ErrCode%



BiosXTFree&

This function returns the total amount of available XMS memory
in kilobytes.  Compare with BiosXLFree&.

   TotalFree& = BiosXTFree&



BiosXVer%

This function returns the XMS driver version, multiplied by
100.  For instance, version 1.01 would be returned as 101.

   XMSver! = BiosXVer% / 100!



BiosXWrite

This routine puts information into XMS memory.  You must
specify the memory handle, the starting offset within the
memory associated with that handle, and the number of bytes to
transfer.  The number of bytes must be an EVEN number, but is
not limited to 64k.  Finally, you must specify where to get the
information as a segment and offset in conventional memory. For
BASIC arrays and so forth, you can get this data using the
VARSEG and VARPTR functions.

Another common place from which to get the data might be the
display.  For text modes, this is a simple transfer.  Use an
offset of 0 and a segment of either &HB000 (MDA/Herc) or &B800
(CGA/EGA/VGA).

   BiosXWrite Handle%, Posn&, Bytes&, DSeg%, DOfs%

DosBreak%

This function returns the current level of Break checking.  At
level 0, DOS checks for Ctrl-C/Break only during keyboard input
or screen output.  At level -1, DOS also checks during disk
access.

   ExtendedBreak% = DosBreak%



DosBreakOff

This routine disables extended Break checking, so DOS only
checks for Break during keyboard input or screen output.

   DosBreakOff



DosBreakOn

This routine enables extended Break checking, so DOS checks for
Break during disk access as well as during keyboard input or
screen output.

   DosBreakOn



DosDelDir%

This function deletes a directory.  The directory must be empty
and must not be the current or root directory.  Unlike RMDIR,
this function does not require an ON ERROR handler to cope with
normal errors, as it returns an error code directly (0 if no
error).  ON ERROR is only required if you need critical error
handling.

The path name must be in ASCIIZ form, that is, with a CHR$(0)
at the end.  This can be handled when the routine is called:

   ErrCode% = DosDelDir% (SubDir$ + CHR$(0))



DosDelFile%

This function deletes a file.  It takes up less space than the
corresponding BASIC statement, KILL.  Unlike KILL, it does not
require an ON ERROR handler to cope with normal errors, as it
returns an error code directly (0 if no error).  ON ERROR is
only required if you need critical error handling.

The filename must be in ASCIIZ form, that is, with a CHR$(0) at
the end.  This can be handled when the routine is called:

   ErrCode% = DosDelFile% (File$ + CHR$(0))



DosDiskInfo

This routine returns an assortment of information about a given
disk drive: sectors per cluster, free clusters, bytes per
sector, and total clusters.  From this, you can derive further
information such as how much disk space is available and the
total disk space.

You may specify a null drive to get the information from the
default drive.

If there was an error, SecsPerClus& will be -1.

   DosDiskInfo Drive$, SecsPerClus&, FreeClus&, BytesPerSec&,
      TotalClus&



DosGetDay$

This function returns the current day of the week as a
three-character string.  For instance, on Wednesday the result
would be "Wed".

   Today$ = DosGetDay$

DosGetDir$

This function returns the default directory on the specified
drive.  If there was an error, a null string ("") will be
returned.

You may specify a null drive to get the directory of the
default drive.

   Subdir$ = DosGetDir$(Drive$)



DosGetDisk$

This function returns the letter of the currently selected
disk drive.

   Drive$ = DosGetDisk$



DosGetFAttr%

This function returns the file attributes of a specified file.
The file must be terminated by CHR$(0).  If there was an error,
-1 will be returned.  Otherwise, the result will be any
combination of the following, added together:

    1   read-only
    2   hidden
    4   system
    8   volume label
   16   subdirectory
   32   archive

The results can be most conveniently decoded using the AND
function.  For instance:

   IF DosGetFAttr%(File$ + CHR$(0)) AND 16 THEN
      PRINT "Subdirectory"
   END IF



DosGetKey$

This function attempts to read a character from DOS standard
input (normally the keyboard).  It works like INKEY$.

Standard input can be redirected from the command line, so it
may get information from a file or device instead of the
keyboard.  That is one of the advantages of this function.

   Ky$ = DosGetKey$

DosGetKeyW$

This function reads a character from DOS standard input
(normally the keyboard).  It works like INKEY$, but waits until
a key is pressed before returning.

Standard input can be redirected from the command line, so it
may get information from a file or device instead of the
keyboard.  That is one of the advantages of this function.

   Ky$ = DosGetKeyW$



DosGetVersion%

This function returns the DOS version multiplied by 100.  For
instance, DOS 2.11 would be returned as 211.

   DOSver! = DosGetVersion% / 100!



DosMakeDir%

This function creates a directory.  Unlike MKDIR, it does not
require an ON ERROR handler to cope with normal errors, as it
returns an error code directly (0 if no error).  ON ERROR is
only required if you need critical error handling.

The path name must be in ASCIIZ form, that is, with a CHR$(0)
at the end.  This can be handled when the routine is called:

   ErrCode% = DosMakeDir% (SubDir$ + CHR$(0))



DosRenFile%

This function renames a file, and/or moves it to a new
directory on the same drive.  It can't move a file across
drives.  It takes less space than NAME, and does not require an
ON ERROR handler to cope with normal errors, as it returns an
error code directly (0 if no error).  ON ERROR is only needed
if you require critical error handling.

The path name must be in ASCIIZ form, that is, with a CHR$(0)
at the end.  This can be handled when the routine is called:

   ErrCode% = DosRenFile% (OldFile$+CHR$(0), NewFile$+CHR$(0))



DosSetDir%

This function sets the default directory.  Unlike CHDIR, it
does not require an ON ERROR handler to cope with normal
errors, as it returns an error code directly (0 if no error).
ON ERROR is only required if you need critical error handling.

The path name must be in ASCIIZ form, that is, with a CHR$(0)
at the end.  This can be handled when the routine is called:

   ErrCode% = DosSetDir% (SubDir$ + CHR$(0))



DosSetDisk%

This function sets the default disk drive.  It also returns the
number of logical drives in the system.

Note that a logical drive may be considered being like a drive
letter-- it may refer to part of a larger physical drive, to a
RAMdisk, to some other device, or to nothing at all.

   LogicalDrives% = DosSetDisk% (Drive$)



DosSetFAttr%

This function sets the file attributes of a specified file.
The file must be terminated by CHR$(0).  If there was an error,
-1 will be returned.  Otherwise, 0 will be returned.

You may set any combination of the following attributes, added
together:

    1   read-only
    2   hidden
    4   system
   32   archive

   ErrCode% = DosSetFAttr%(File$ + CHR$(0), FAttr%)

DosVerify%

This function tells you whether disk write verification is
turned on.

   Verify% = DosVerify%



DosVerifyOff

This routine disables disk write verification.  Verification
provides better file security but slows things down.  It is
normally off by default.

   DosVerifyOff



DosVerifyOn

This routine enables disk write verification.  Verification
provides better file security but slows things down.  It is
normally off by default.

   DosVerifyOn



DosWriteSt

This routine writes a string to the DOS standard output
(normally the display).

Standard output can be redirected from the command line, so it
may write information to a file or device instead of the
display.  It also supports device drivers such as ANSI.SYS.
That is one of the advantages of this routine.

   DosWriteSt St$