ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/BASIC/PBCLON16.ZIP/PBCLONE1.MAN

Text File | 1991-10-06 | 121.3 KB | 3,473 lines

Name  : AddMatI
Class : Numeric
Level : Any

This routine adds an integer to as many elements of an integer array as you
like, starting at a specified place in the array.  It can also be used to
subtract (just specify a negative value).  If there was a numeric overflow at
any point in the operation, an error code will be returned.

   AddMatI DSeg%, DOfs%, Elements%, Value%, ErrCode%

DSeg%      segment of the first array element to add, obtained by VARSEG
DOfs%      offset of the first array element to add, obtained by VARPTR
Elements%  number of array elements to which to add
Value%     value to add to each array element
-------
ErrCode%   error code: 0 if no error, else there was an overflow

Name  : AddMatL
Class : Numeric
Level : Any

This routine adds a long integer to as many elements of an long integer array
as you like, starting at a specified place in the array.  It can also be used
to subtract (just specify a negative value).  If there was a numeric overflow
at any point in the operation, an error code will be returned.

   AddMatL DSeg%, DOfs%, Elements%, Value&, ErrCode%

DSeg%      segment of the first array element to add, obtained by VARSEG
DOfs%      offset of the first array element to add, obtained by VARPTR
Elements%  number of array elements to which to add
Value&     value to add to each array element
-------
ErrCode%   error code: 0 if no error, else there was an overflow

Name  : AltKey
Class : Input
Level : Any

This routine works in conjunction with a key input routine, such as INKEY$ or
the CheckKey and GetKey routines.  Given the ASCII code and scan code of a
key, AltKey returns the associated key letter, if any.  For instance, it
returns "A" if you pass it ASCII code 0 and scan code 30, because those codes
represent Alt-A.

This routine works the same as one in the ProBas ToolKit.

   AltKey ASCIICode%, ScanCode%, Ky$

ASCIICode%   ASCII code of the key
ScanCode%    scan code of the key
-------
Ky$          associated key letter ("" if none)

Name  : Any2Dec
Class : Numeric
Level : Any

This routine converts a number in any base to a normal integer.  It works
like the &H and &O prefixes in BASIC, but rather than working only in
hexadecimal (base 16) and octal (base 8), it can be used for binary, octal,
or almost anything else.

If you specify base 10, you can use this routine to convert a signed integer
(0-65,535) to a normal integer.

   Any2Dec Number$, NrBase%, DecNr%, ErrCode%

Number$   any-base number to convert to an integer
NrBase%   base of the number to convert from
-------
DecNr%    resulting integer
ErrCode%  error code: 0 if no error, else overflow, bad base, or invalid nr

Name  : AscI%
Class : String
Level : Any

This is a replacement for the ASC function provided by BASIC.  It is smaller
than ASC, however, and also somewhat faster.

Unlike BASIC or ProBas, the PBClone AscI function returns -1 as an error
condition if you try to use it on a null string.  This convention owes its
origin to the similar routine in Crescent's libraries.

   Value% = AscI%(St$)

St$        string for which to return ASCII code
-------
Value%     code of the first string character or -1 if null string

Name  : BarMenu
Class : Display
Level : Clone

This is a bar menu routine.  It allows the user to select one of a list of
items given on a single menu row or "bar".  The current item is highlighted
in your choice of colors; user selection can be done either by moving this
highlight and pressing return or by entering the letter associated with the
desired item.  Only text mode is supported.

The highlight may be moved with the left and right arrow keys, tab and
backtab, or space and backspace.  Selection is done with <CR>, the enter key.

The letter used to select an item is the first character of the item that is
not lowercase or a space.  If the item is all lowercase, the first character
of the item will be used.  For example, suppose you want the user to select
one of "list" or "log".  By passing the options to BarMenu as "List" and
"lOg", you allow the user to press "L" for "List" and "O" for "lOg".

The user's choice will be returned to you as a number, with the first choice
being numbered 1.  If <ESC> was pressed, 0 will be returned.

This routine differs from the ProBas ToolKit routine of the same name in that
it allows you to specify the letters used to select items, rather than always
using the first letter of each item.  It does not alter your left and right
column or prompt parameters.  It will accept an array of any dimensions,
rather than being restricted to at most ten elements beginning at 1.  It will
also work on any screen page and with any screen width.

   BarMenu PickList$(), Row%, LeftCol%, RightCol%, Attr%, HiAttr%, Prompt$

PickList$()   list of items to choose from
Row%          row on which to display the bar
LeftCol%      leftmost column of the bar
RightCol%     rightmost column of the bar (use -1 for auto-sizing)
Attr%         bar color/attribute (see CalcAttr)
HiAttr%       bar highlight color/attribute (see CalcAttr)
Prompt$       prompt text (displayed at the left side of the bar)
-------
Row%          number of the chosen item (1-items, or 0 if <ESC>)

Name  : BarMenuM
Class : Display
Level : Clone

This is a bar menu routine.  It functions just like BarMenu, but supports the
use of a mouse as well as the keyboard.

Besides the differences inherited from BarMenu, this version of BarMenuM
differs from the one in the ProBas ToolKit in several other respects.  The
mouse handling is visually different, with the mouse cursor allowed to roam
freely instead of emulating cursor keys.  Also, if you use a mouse, the mouse
cursor must be visible when BarMenuM is called.  The ShowCursor% parameter no
longer has any effect and is included merely for compatibility purposes.

   BarMenuM PickList$(), Row%, LeftCol%, RightCol%, Attr%, HiAttr%, Prompt$,
      Mouse%, ShowCursor%

PickList$()   list of items to choose from
Row%          row on which to display the bar
LeftCol%      leftmost column of the bar
RightCol%     rightmost column of the bar (use -1 for auto-sizing)
Attr%         bar color/attribute (see CalcAttr)
HiAttr%       bar highlight color/attribute (see CalcAttr)
Prompt$       prompt text (displayed at the left side of the bar)
Mouse%        whether a mouse is available (0 no)
ShowCursor%   not used
-------
Row%          number of the chosen item (1-items, or 0 if <ESC>)

Name  : Bickel
Class : String
Level : Any

A string comparison routine, Bickel allows you to see how closely two strings
match.  The better the match, the larger the returned value will be.  Since
there is no constant minimum or maximum value, this routine is best used for
applications involving dictionary searches.  You would scan the dictionary
and make a list of the best matches.  This is appropriate for a spelling
checker, for instance.

   Bickel St1$, St2$, Result%

St1$      first string to compare
St2$      second string to compare
-------
Result%   resulting "match magnitude" value

Name  : BigPrint
Class : Display
Level : BIOS

As the name suggests, this routine displays text in large characters.  How
large?  Eight times as high and as wide as normal!  Each "big character" will
be composed of many normal-sized characters.  You may choose the normal
character used to create the big characters (the default is a CHR$(219) solid
block character, if you pass a null string here).

You should avoid using CHR$(128) to CHR$(255) when in either of the CGA
graphics modes, as many CGAs are unable to display these characters when in
graphics mode.

   BigPrint St$, FormCh$, Row%, Column%, Attr%

St$       string to display in big characters
FormCh$   character used to compose the big characters
Row%      starting row
Column%   starting column
Attr%     color/attribute of big characters (see CalcAttr)

Name  : BIOSInkey
Class : Input
Level : BIOS

This is a new routine which does not exist in ProBas at all.  It seemed like
a good thing to have, however, so I added it.

BIOSInkey works like INKEY$, but it gets its key directly by asking the BIOS.
The primary advantage of this is that you get the "scan" code as well as the
ASCII code of the key.  The scan code is independent of the shift status--
for instance, the scan code for "A" is the same as the scan code for "a" or
Control-A or Alt-A.  This can be very handy.

If there is no key available, both the scan code and ASCII code will be zero.

   BIOSInkey AscCode%, ScanCode%

-------
AscCode%    ASCII code of the key, if any
ScanCode%   scan code of the key, if any

Name  : BkScroll
Class : Display
Level : BIOS

This routine scrolls any selected part of the display down-- it does a
backwards scroll.  You may scroll as many times as you like, or scroll "zero"
times to totally clear the selected part of the display.

Note that BIOS-level scrolling can cause the screen to flicker on some CGAs
due to a combination of unfortunate design factors.

   BkScroll TopRow%, LeftCol%, BottomRow%, RightCol%, Times%

TopRow%      top row of the area to scroll
LeftCol%     left column of the area to scroll
BottomRow%   top row of the area to scroll
RightCol%    left column of the area to scroll
Times%       number of times (or rows) to scroll

Name  : BkSpace
Class : Display
Level : BIOS

Although CHR$(8) is supposed to mean "backspace", it shows up as a graphics
character when BASIC prints it.  This routine does an actual backspace with
full wrap-- if it's at the beginning of the line, it will move back to the
previous line (if there is one).  It backspaces destructively (erasing the
previous character) from the current cursor position.  The new cursor is
returned to you, since QuickBASIC may ignore the new status.

   BkSpace Row%, Column%       ' do the backspace
   LOCATE Row%, Column%        ' inform QuickBASIC

-------
Row%      new row
Column%   new column

Name  : Blink
Class : Display
Level : BIOS / Clone (see text)

It is possible to make characters in text mode blink by giving them an
appropriate "color".  I wouldn't mention something so obvious but for another
possibility which is less widely known: blinking can be turned off, in which
case the characters that would have otherwise blinked will instead have a
bright background.  In other words, turn off blinking, and you double the
possible number of background colors.

This technique will always work with EGA and VGA displays.  It can also be
used with MDA/Hercules and CGA displays, on which it will almost always
work... unfortunately, on some less-than-perfect PC clones, it will cause the
computer to lock up instead.  So, be careful with this one!

   Blink SetBlink%

SetBlink%    whether to blink (-1) or use intense backgrounds (0)

Name  : BlockMove
Class : Memory
Level : Clone

This routine allows you to copy or "move" a block of data from one memory
location to another.  It isn't very bright, so if the memory areas overlap,
you will have to tell the routine to "move backwards" instead of forwards.
In that case, you will also have to change the offsets to point to the ends
of the memory areas instead of the beginnings.

Normally, you can use forward moves.  In that case, the offsets you specify
are those of the beginning of the memory areas.  If backward moves are
required, the offsets specified are those of the end of the memory areas.

If you are familiar with assembly language, you may recognize this as a
straightforward implementation of the "REP MOVSB" instruction.

You may move up to 65,520 bytes at a time, provided that the addresses are in
normalized form (if you don't know what this means, you probably don't need
to worry about it).

This routine can be used to copy information to an array from any area of
memory (the BIOS data area, the screen, another array, etc), or vice versa.
It can also be used to do things like insert/delete elements from an array,
scroll the screen, fill the screen with a specified character, and so on.

   BlockMove FromSeg%, FromOfs%, ToSeg%, ToOfs%, Bytes&, Direction%

FromSeg%    segment of the area from which to copy
FromOfs%    offset of the area from which to copy
ToSeg%      segment of the area to which to copy
ToOfs%      offset of the area to which to copy
Bytes&      number of bytes to copy (0-65,520)
Direction%  direction to copy (0 if forward, else backward)

Name  : BootDrive
Class : Disk
Level : DOS 4.0+

This routine tells you which drive was used to boot the system.  See also
BootDrive2, a function version of this routine.

One use for BootDrive would be in installation programs, to determine the
most likely destination drive for your software.

   Drive$ = "x"
   BootDrive Drive$

-------
Drive$   boot drive-- set it to at least one char beforehand!

Name  : BootDrive2$
Class : Disk
Level : DOS 4.0+

This routine tells you which drive was used to boot the system.

One use for BootDrive2 would be in installation programs, to determine the
most likely destination drive for your software.

   Drive$ = BootDrive2$

-------
Drive$   boot drive (null if wrong DOS version)

Name  : BSq
Class : String
Level : Any

A simple compression routine, BSq "squeezes" the blank spaces in a string.
It is designed expressly for use with text data.  The text may not contain
more than 131 spaces in a row, or CHR$(128) through CHR$(255), which are used
in the compression.

Average text files are liable to be compressed by around 16%.  Files that
contain more spaces, such as structured programs, will benefit more.  The
compression algorithm is simple but extremely fast, adding no noticeable
overhead to string processing.

Note that the PBClone version of BSq produces results that are not directly
compatible with the ProBas version of BSq.

See also BUsq, BUsqLen.

   BSq St$, StLen%
   St$ = LEFT$(St$, StLen%)

St$     string to compress
-------
St$     compressed string
StLen%  length of the compressed string

Name  : BUsq
Class : String
Level : Any

This routine is used to uncompress strings that were processed by BSq.
Before uncompression, the BUsqLen routine must be used to find out how long
the resulting string will be.

Note that the PBClone version of BUsq is not directly compatible with the
ProBas version of BUsq.

See also BSq, BUsqLen.

   BUsqLen St$, StLen%
   IF StLen% < 0 THEN
      PRINT "Error in compressed string"
   ELSE
      Result$ = SPACE$(StLen%)
      BUsq St$, Result$
   END IF

St$      string to uncompress
-------
Result$  uncompressed string

Name  : BUsqLen
Class : String
Level : Any

This routine is used in coordination with BUsq to uncompress strings that
were processed by BSq.  It determines what the length of the uncompressed
string will be, which is necessary to initialize the string for BUsq.

Note that the PBClone version of BUsqLen is not directly compatible with the
ProBas version of BUsqLen.

See also BSq, BUsq.

   BUsqLen St$, StLen%
   IF StLen% < 0 THEN
      PRINT "Error in compressed string"
   ELSE
      Result$ = SPACE$(StLen%)
      BUsq St$, Result$
   END IF

St$      string to uncompress
-------
StLen%   length of the uncompressed string

Name  : CalcAttr
Class : Display
Level : Any

Many of the display routines in this library require an "attribute" rather
than foreground and background colors.  An attribute is a combination of the
foreground and background colors in a format which is used by all types of
displays when in text mode.

Foreground colors are usually specified as 0-31, with backgrounds as 0-7.  If
you turn blinking off (see Blink), it may be more convenient to express the
same thing as foreground 0-15, background 0-15.  The CalcAttr routine will
accept either way of expressing it.

Note, however, that UnCalcAttr will always return the former pair of results,
since it has no way of knowing whether Blink has been used (foreground 0-31,
background 0-15).  See UnCalcAttr for more details and a solution.

See also CalcAttr2, the FUNCTION version of this routine.

   CalcAttr Foreground%, Background%, Attr%

Foreground%  foreground color
Background%  background color
-------
Attr%        color "attribute"

Name  : CalcAttr2%
Class : Display
Level : Any

Many of the display routines in this library require an "attribute" rather
than foreground and background colors.  An attribute is a combination of the
foreground and background colors in a format which is used by all types of
displays when in text mode.

Foreground colors are usually specified as 0-31, with backgrounds as 0-7.  If
you turn blinking off (see Blink), it may be more convenient to express the
same thing as foreground 0-15, background 0-15.  The CalcAttr2 routine will
accept either way of expressing it.

Note, however, that UnCalcAttr will always return the former pair of results,
since it has no way of knowing whether Blink has been used (foreground 0-31,
background 0-15).  See UnCalcAttr for more details and a solution.

See also CalcAttr, the SUB version of this routine.

   Attr% = CalcAttr2%(Foreground%, Background%)

Foreground%  foreground color
Background%  background color
-------
Attr%        color "attribute"

Name  : CalcDate
Class : Time
Level : Any

This routine calculates what the date will be a given number of days from
now, either in the past or the future.  Actually, you may use any starting
date, not just the current date.  An error code is returned if the starting
date or resulting date are not valid.  Dates may not preceed January 1, 1900.

CalcDate differs from the ProBas ToolKit routine of the same name in that it
expects the "days" parameter to be a long integer rather than single
precision.  It does not consider zero days to be an error.  It also accepts
the date in any standard form ("01/30/91" or "01-30-1991", for example) and
returns its results in the same format.

   CalcDate StartDate$, Days&, Direction%, NewDate$, ErrCode%

StartDate$   starting date
Days&        number of days from the current date (0 or more)
Direction%   whether to return result in the future (0) or past (nonzero)
-------
NewDate$     resulting date
ErrCode%     whether the dates are valid (0 yes)

Name  : CalcSize
Class : Display
Level : Any

This routine calculates the necessary DIM size for an integer array, assuming
that you intend to store display data in the array.  This is most useful in
conjunction with DGetScreen and GetScreen.

   CalcSize TopRow%, LeftCol%, BottomRow%, RightCol%, Elements%
   DIM Array%(1 TO Elements%)

TopRow%      top row of the display area
LeftCol%     left column of the display area
BottomRow%   top row of the display area
RightCol%    left column of the display area
-------
Elements%    required size of the integer array

Name  : CalcVGAColor
Class : Display
Level : Any

The QuickBASIC manual gives a cumbersome formula for calculating VGA palette
colors.  This routine does it faster and with less fuss.  All you need to do
is pass it the appropriate intensity values (0-63) and you get back a long
integer, just the way BASIC wants it.

   CalcVGAColor Red%, Green%, Blue%, Colour&

Red%      red   intensity
Green%    green intensity
Blue%     blue  intensity
-------
Colour&   color value for use in the PALETTE statement

Name  : Carrier
Class : Serial
Level : Clone

If you write communications programs, particularly things like doors and
BBSes, you probably want to keep an eye on the carrier.  BASIC won't do it,
but we will!

   Carrier CommPort%, CarrierHigh%

CommPort%     serial port number (1-4, although BASIC only handles 1-2)
-------
CarrierHigh%  zero if no carrier

Name  : CatchError
Class : Miscellaneous
Level : Clone

The CatchError routine is used in conjunction with GetError.  It lets you get
the exit code (error level) returned by a program to which you have SHELLed.
Since CatchError hooks an interrupt to do its work, you must always make sure
to use GetError afterwards to "clean up".  See also GetError.

Note that differences in DOS mean that this routine will not always work.  In
some versions of DOS, you can only get the error level if a batch file was
executed; in others, you can't get the error level from a batch file at all.
Sorry about that.  I don't know of any way to work around it.

   CatchError
   SHELL ProgramName$
   GetError ExitCode%

Name  : CDROM
Class : Disk / Equipment
Level : DOS

This routine tells you whether the Microsoft CD-ROM Extensions are installed.
If so, it tells you what the letter of the first CD-ROM logical drive is and
how many logical drives exist.

Note: The CD-ROM installation check conflicts with the GRAPHICS.COM
installation check for DOS 4.0, due to some screw-up at IBM or Microsoft.
This may cause unexpected results.  I'm not yet sure whether DOS 5.0 is
similarly afflicted.

   FirstDrive$ = "x"
   CDROM FirstDrive$, Drives%

-------
FirstDrive$   letter of the first logical drive (init to at least one space!)
Drives%       number of logical drives available (0 if no CD-ROM is there)

Name  : CDROM2%
Class : Disk / Equipment
Level : DOS

This routine tells you whether the Microsoft CD-ROM Extensions are installed.
If so, it tells you how many logical drives exist.

Note: The CD-ROM installation check conflicts with the GRAPHICS.COM
installation check for DOS 4.0, due to some screw-up at IBM or Microsoft.
This may cause unexpected results.  I'm not yet sure whether DOS 5.0 is
similarly afflicted.

   Drives% = CDROM2%

-------
Drives%       number of logical drives available (0 if no CD-ROM is there)

Name  : CheckDate
Class : Time
Level : Any

This routine checks a date to see if it is valid.  Note that the year is not
checked to see if it is too large, so you must do that yourself if you have a
specific range of years in mind.

This routine works like one of the same name in the ProBas ToolKit.

   CheckDate MonthNr%, DayNr%, YearNr%, ErrCode%

MonthNr%     month number (1-12)
DayNr%       day number (1-31)
YearNr%      year number (1900 on; years <100 will be assumed 20th century)
-------
ErrCode%     whether the date is valid (0 yes)

Name  : CheckDisk
Class : Disk
Level : DOS

The CheckDisk routine determines whether a disk is ready.  About the only
thing it won't tell you is if a disk is write-protected or out of space.
Since the PBClone disk routines all contain critical error handling, which
reports back an appropriate error code for all such problems, this routine
isn't really needed any more.  It's included for compatibility with older
ProBas programs.

Note that DOS versions before 3.0 do not return as useful error codes as
later versions.  Under such circumstances, both "unformatted disk" and "open
drive door" will be returned as "open drive door".

   CheckDisk Drive$, ErrCode%

Drive$    letter of the drive to check
-------
ErrCode%  0: no error; 1: unformatted disk; 2: open drive door; 3: bad drive

Name  : CheckDsk%
Class : Disk
Level : DOS

The CheckDsk% function determines whether a disk is ready.  About the only
thing it won't tell you is if a disk is write-protected or out of space.
Since the PBClone disk routines all contain critical error handling, which
reports back an appropriate error code for all such problems, this routine
isn't really needed any more.  It's included for compatibility with older
ProBas programs.

Note that DOS versions before 3.0 do not return as useful error codes as
later versions.  Under such circumstances, both "unformatted disk" and "open
drive door" will be returned as "open drive door".

   ErrCode% = CheckDsk%(Drive$)

Drive$    letter of the drive to check

Name  : CheckKey
Class : Input
Level : BIOS

This routine is kind of an extended version of INKEY$.  It checks the
keyboard to see if any key is available and gets the key if it is.  At your
option, it can also check the mouse to see if a button has been pressed.

   CheckKey Mouse%, ASCIIcode%, ScanCode%, LeftButton%, RightButton%

Mouse%        whether to check the mouse (0: no)
-------
ASCIIcode%    ASCII code of the key pressed
ScanCode%     scan code of the key pressed (0 if none)
LeftButton%   whether the left  mouse button was pressed
RightButton%  whether the right mouse button was pressed

Name  : CheckKey3
Class : Input
Level : BIOS

This routine is kind of an extended version of INKEY$.  It checks the
keyboard to see if any key is available and gets the key if it is.  At your
option, it can also check the mouse to see if a button has been pressed.

   CheckKey3 Mouse%, ASCIIcode%, ScanCode%, LeftButton%, MidBttn%, RightButton%

Mouse%        whether to check the mouse (0: no)
-------
ASCIIcode%    ASCII code of the key pressed
ScanCode%     scan code of the key pressed (0 if none)
LeftButton%   whether the left   mouse button was pressed
MidBttn%      whether the middle mouse button was pressed
RightButton%  whether the right  mouse button was pressed

Name  : CheckShare
Class : Disk
Level : DOS

The CheckShare routine determines whether SHARE.EXE is active.  This is
particularly helpful before using the BASIC OPEN statement, which will fail
if you request file sharing when it's not available.  The PBClone file
routines handle such situations automatically, so CheckShare is not needed
for them.

   CheckShare ShareActive%

-------
ShareActive%   whether SHARE is active (0 if no)

Name  : CheckShare2%
Class : Disk
Level : DOS

The CheckShare2% function determines whether SHARE.EXE is active.  This is
particularly helpful before using the BASIC OPEN statement, which will fail
if you request file sharing when it's not available.  The PBClone file
routines handle such situations automatically, so CheckShare2% is not needed
for them.

   ShareActive% = CheckShare2%

-------
ShareActive%   whether SHARE is active (0 if no)

Name  : Checksum
Class : String / Serial
Level : Any

The Checksum routine calculates a checksum on a string.  The resulting number
is compatible with Xmodem and Ymodem checksum routines and will vary from
0-255.  This checksum provides a minimal, but fast, check of what characters
are contained in the string.  See also CRC.

   Checksum St$, ChkSum%

St$       string to process
-------
ChkSum%   checksum of the characters in the string

Name  : Cipher
Class : String
Level : Any

This is a very simple text encryption routine.  It isn't particularly hard to
crack, but will provide a basic level of security for undemanding
applications.  The same routine can be used either to encrypt or decrypt
text.  The original text may contain any character; likewise, the resulting
text.  This is not well suited for use with sequential files-- if such is
required, see CipherP.

I'd suggest using a long password composed of an unlikely string of
characters, e.g. "#*@@!A^%x{.'".

   Cipher St$, Password$

St$        string to encrypt or decrypt
Password$  password
-------
St$        encrypted or decrypted string

Name  : CipherP
Class : String
Level : Any

This is a very simple text encryption routine.  It isn't particularly hard to
crack, but will provide a basic level of security for undemanding
applications.  The same routine can be used either to encrypt or decrypt
text.  The original text may contain any character below CHR$(128), as may
the password.  The resulting text will be printable, if bizarre (all
characters will be above CHR$(127)), and may be used with sequential files.

This routine is potentially less secure than the Cipher routine (see).

I'd suggest using a long password composed of an unlikely string of
characters, e.g. "#*@@!A^%x{.'".

   CipherP St$, Password$

St$        string to encrypt or decrypt
Password$  password
-------
St$        encrypted or decrypted string

Name  : ClearArea
Class : Display
Level : Clone

This routine clears an area of the screen to a specified color.  The clearing
is done by removing random characters until the area is totally clear.

This routine does not exist in ProBas.

   ClearArea TopRow%, LeftCol%, BottomRow%, RightCol%, Attr%, Fast%

TopRow%     top row of area to clear
LeftCol%    left column of area to clear
BottomRow%  bottom row of area to clear
RightCol%   right column of area to clear
Attr%       color/attribute to clear to
Fast%       whether to use fast displays (may cause snow on CGAs) (0 no)

Name  : Clock
Class : Display / Time
Level : Clone

This routine allows you to turn a visible time display on or off.  When on,
the time will be continuously displayed at a selected location while your
program continues processing.  The clock is managed as a background process,
in effect doing some simple multitasking.

You should turn the clock off before you terminate your program, including
any time you execute another program with RUN.  The clock can be safely kept
on when you SHELL to another program, however, as long as you can be sure
that control will return to your program when the other is done.

The clock must also be turned off if you change any of its parameters with
the ClockSet routine (see).

The clock will only be visible when the display is in text mode.  The use of
PLAY or SOUND statements may shut off the clock, depending on your version of
the BASIC compiler.

   Clock DisplayOn%

DisplayOn%   whether to display the clock (0 if no)

Name  : ClockSet
Class : Display / Time
Level : Clone

The ClockSet routine is used in conjunction with Clock (see).  It should only
be used when the clock is turned off.

This routine allows you to set 12-hour or 24-hour time, whether to display
the seconds or not, how often to update the clock display (in 1/18th seconds;
9 is usually the best choice), where to display the clock and in what color,
and whether to use flicker-free displays (needed for cheap CGAs only).  The
defaults are 12-hour time, display seconds, put the time (in white on black)
in the upper right corner, and display quickly (may flicker on some CGAs).

   ClockSet Hours24%, Seconds%, Updates%, Row%, Column%, Attr%, Fast%

Hours24%   whether to display 24-hour time (0 if no)
Seconds%   whether to display seconds (0 if no)
Updates%   display update frequency in 1/18th seconds (9 is usually best)
Row%       row on which to display the clock
Col%       column at which to display the clock
Attr%      color/attribute to use (see CalcAttr)
Fast%      whether to use fast mode (nonzero if so; may cause snow on CGAs)

Name  : CloseA
Class : Disk / Time
Level : DOS

This routine closes an archive opened by FindFirstA or FindNextA.  It must be
used when you are done searching the archive.

Routines in this series include:
   FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA,
   GetSizeAL, GetStoreA

   CloseA

Name  : ClrCols
Class : Display
Level : BIOS

This routine clears the current row between the specified columns, inclusive.
It does not affect the cursor position.

   ClrCols StartCol%, EndCol%

StartCol%  starting column
EndCol%    ending column

Name  : ClrEOL
Class : Display
Level : BIOS

This routine clears from the cursor to the end of the line, inclusive.  It
does not affect the current cursor position.

   ClrEOL

Name  : ClrEOP
Class : Display
Level : BIOS

This routine clears from the cursor to the end of the display, inclusive.  It
does not affect the current cursor position.

   ClrEOP

Name  : ClrSOL
Class : Display
Level : BIOS

This routine clears from the start of the line to the cursor, inclusive.  It
does not affect the current cursor position.

   ClrSOL

Name  : ClrKbd
Class : Input
Level : DOS

ClrKbd clears the keyboard buffer, discarding any keys that may be waiting.
This is a good idea for situations where an unexpected input is made and you
don't want to chance it being answered accidentally by keys that were typed
beforehand-- for instance, in the event of an error or other condition where
it is important that the user see a message or take an action before pressing
a key.

   ClrKbd

Name  : ClrSOP
Class : Display
Level : BIOS

This routine clears from the start of the display to the cursor, inclusive.
It does not affect the current cursor position.

   ClrSOP

Name  : CopyFile
Class : Disk
Level : DOS

This works like the DOS COPY command, although it does not allow wildcards.
One file is copied to another, retaining the same date and time.  Full path
specifications are supported, including drive and subdirectory specs.

See also FileCopy, which supports wildcards.

   CopyFile FromFile$, ToFile$, ErrCode%

FromFile$   name of file to copy
ToFile$     name of new file to create
-------
ErrCode%    0 if no error, else DOS Error

Name  : CPrintScreen1
Class : Display / Printer
Level : Clone

This routine dumps a SCREEN 1 display (CGA 320x200) to the printer.  It uses
the stdprn device (normally PRN or LPT1) by default, although this can be
altered with the PrtSwap routine.

   CPrintScreen1

Name  : CPrintScreen2
Class : Display / Printer
Level : Clone

This routine dumps a SCREEN 2 display (CGA 640x200) to the printer.  It uses
the stdprn device (normally PRN or LPT1) by default, although this can be
altered with the PrtSwap routine.

   CPrintScreen2

Name  : CRC
Class : String / Serial
Level : Any

This routine calculates a complex 16-bit checksum, called a Cyclical
Redundancy Check (or CRC) on a string.  The results are compatible with
Xmodem and Ymodem CRC routines.  The CRC provides a fairly reliable check of
what characters are contained in the string.  See also Checksum.

If you are using this routine for Xmodem or Ymodem, note that the string
should be padded with two null characters before calculating a "send" CRC:
St$ = St$ + STRING$(2, 0).  On receive, you should calculate the CRC on the
entire data block, plus the received CRC; if the block was received
correctly, the calculated CRC will be zero in both lsb and msb.

Although Intel notation uses "lsb, msb" order, the Xmodem/Ymodem CRC uses the
opposite format, which is why the parameters are ordered in this fashion.

   CRC St$, CRCmsb%, CRClsb%

St$       string to process
-------
CRCmsb%   most significant byte of CRC
CRClsb%   least significant byte of CRC

Name  : Crunch
Class : String
Level : Any

It was hard to decide on a name for this routine, and I don't know if I've
done the best job.  What Crunch does is to eliminate repeated sequences of
the same character.  For instance, if you gave it "This    is a   test" and
asked it to crunch spaces, it would return "This is a test".  I use this to
filter information from the COMMAND$ function, but it's a good general
purpose input filter.

   Crunch St$, Ch$, StLen%
   St$ = LEFT$(St$, StLen%)

St$       string to be processed
Ch$       character to crunch out of the string
-------
St$       crunched string
StLen%    length of the crunched string

Name  : CtrlKey
Class : Input
Level : Any

This routine works in conjunction with a key input routine, such as INKEY$ or
the CheckKey and GetKey routines.  Given the ASCII code and scan code of a
key, CtrlKey returns the associated key letter, if any.  For instance, it
returns "A" if you pass it ASCII code 1, because that code represents Ctrl-A.

The scan code is ignored, as it's irrelevant.  The parameter exists only for
compatibility with the ProBas ToolKit.

   CtrlKey ASCIICode%, ScanCode%, Ky$

ASCIICode%   ASCII code of the key
ScanCode%    scan code of the key (ignored)
-------
Ky$          associated key letter ("" if none)

Name  : CursorInfo
Class : Input
Level : Clone

While BASIC allows you to set the size and shape of the cursor with LOCATE,
it's fairly hazardous to do so.  There is no way to find out the maximum size
of the cursor, so your cursor may end up a peculiar shape on some adapters.
If you change the cursor size or visibility in a subprogram, you may be
screwing up the main program.

CursorInfo offers a solution to these problems.  It returns the current
cursor visibility and size, plus the maximum size possible with the current
video adapter.

This routine does not exist in ProBas.

   CursorInfo Visible%, StartLine%, EndLine%, MaxLine%

-------
Visible%      whether the cursor is visible (0 no, 1 yes)
StartLine%    starting scan line of cursor
EndLine%      ending scan line of cursor
MaxLine%      maximum possible scan line for cursor (minimum is always zero)

Name  : CWindowManager
Class : Display
Level : Clone

CWindowManager displays a pop-up window on a CGA graphics screen.  It is
intended for SCREEN 1, although it can be used on SCREEN 2 as well (it will
still have 40 columns and will display shades rather than colors).  The
window may have any of a variety of frames, a title, or a shadow, and it may
appear instantly or "grow" onto the screen.

These are the available frame types:
    0   no frame
    1   single lines
    2   double lines
    3   single horizontal, double vertical lines
    4   double horizontal, single vertical lines
    5   block graphic lines

Options for growing windows are as follows:
   -1   grow as fast as possible
    0   pop onto the screen
   1+   grow with a specified delay in milliseconds (15 works well for me)

Note that this routine is different from its ProBas equivalent in a number of
respects.  The grow delay time is different.  Growing is done more smoothly.
The shadow and title parameters are not changed by this routine.  A new frame
type (5) was added.  If a title is too long, it is truncated instead of being
ignored completely.  Using a -1 as the title foreground color will not turn
off the title; instead, use a null title string.

   CWindowManager TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%,
      Fore%, Back%, Grow%, Shade%, TFore%, Title$, Fast%

TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
Fore%       frame foreground color
Back%       frame background color
Grow%       window growing option (see above)
Shade%      window shadow option (0 for none)
TFore%      title foreground color
Title$      window title ("" if none)
Fast%       whether to use fast mode (0 if no, to avoid snow on CGAs)

Name  : DataSeg
Class : Memory
Level : Any

It's rare that you need to know the data segment used by BASIC, but it does
happen.  DataSeg tells you that value.  This is the segment used by (near)
strings, static arrays (except in the QuickBASIC environment), some COMMON
data, BASIC internal variables and so forth.  It is also the area specified
by a plain "DEF SEG", though not (usually) by "DEF SEG=xxxx".

   DataSeg DSeg%

-------
DSeg%     data segment for BASIC

Name  : Date2Int
Class : Time
Level : Any

This routine compresses a date into a single integer.  Note that this integer
is not in a format that lends itself to simple computation-- you cannot
subtract one from another to find out the length of time between them.
However, as long as the year is in the range 1980-2042, you can compare the
two integers to see if one date is before or after another.

You may express the year as either a two-digit or four-digit number.

The ProBas and PBClone versions of this routine do not work the same way in
regards to the year.  ProBas assumed that any two-digit year was in the
1900s.  In contrast, PBClone assumes that years 80-99 should be converted to
1980-1999 and that 0-79 should be converted to 2000-2079.  I consider the
PBClone method more appropriate, with the turn of the century moving closer.
The date format used does not allow dates before 1980 anyway, so nothing is
being lost by this change.

   Date2Int MonthNr%, Day%, Year%, IntDate%

MonthNr%     month number (1-12)
Day%         day (1-31)
Year%        year (1980-2079; see above for two-digit year handling)
-------
IntDate%     date compressed into an integer

Name  : DateA2R
Class : Time
Level : Any

This routine converts an actual date to a relative date, expressed as a
number of days.  This allows you to compare dates, find out what the date
will be in a given number of days (or what it was a given number of days
ago), see how many days passed between two dates, and so forth.

I've frequently seen routines of this nature called "Julian date" routines.
I'm not sure where that nomenclature originated, as it has nothing to do with
the Julian calendar.  Most of these routines rely on approximations through
floating point math, and may or may not handle leap years and centuries
appropriately.  The DateA2R routine takes no such shortcuts and may be relied
upon to return accurate results.

The DateA2R routine differs from the routine by the same name in the ProBas
ToolKit in that it uses long integers rather than single precision to express
the relative date.  This is both faster and more appropriate.

   DateA2R MonthNr%, DayNr%, YearNr%, RelDate&

MonthNr%     month number (1-12)
DayNr%       day number (1-31)
YearNr%      year number (1900 on; years <100 will be assumed 20th century)
-------
RelDate&     relative date

Name  : DateN2S
Class : Time
Level : Any / DOS

Many of the PBClone routines return the date as a set of numbers.  This
routine provides an easy way to convert those numbers into string form.  The
date format used (year length and delimiter) will be based on the string
which you pass to the routine.  For instance, "xx-xx-xxxx" will return a date
like "11-26-1990", whereas "xx.xx.xxxx" would return "11.26.1990", and
"xx/xx/xx" would return "11/26/90".

This routine differs from the ProBas routine by the same name, which assumed
that the date delimiter should always be "/".  Also unlike ProBas, if you
pass zeroes for the MonthNr%, Day%, and Year% values, the current date will
be returned in the format that you specified.

The ProBas and PBClone versions of this routine do not work the same way in
regards to the year.  ProBas assumed that any two-digit year was in the
1900s.  In contrast, PBClone assumes that years 80-99 should be converted to
1980-1999 and that 0-79 should be converted to 2000-2079.

   DateSt$ = "xx-xx-xxxx"
   DateN2S MonthNr%, Day%, Year%, DateSt$

MonthNr%  month
Day%      day
Year%     year
-------
DateSt$   date string.  Init to 8 or 10 chars including delimiters (see above).

Name  : DateR2A
Class : Time
Level : Any

This is the opposite of the DateA2R routine-- it takes a "relative" date and
converts it back to the usual form.

The DateR2A routine differs from the routine by the same name in the ProBas
ToolKit in that it uses long integers rather than single precision to express
the relative date.  This is both faster and more appropriate.

   DateR2A MonthNr%, DayNr%, YearNr%, RelDate&

RelDate&     relative date
-------
MonthNr%     month number (1-12)
DayNr%       day number (1-31)
YearNr%      year number (1900 on)

Name  : DateS2N
Class : Time
Level : Any

Many of the PBClone routines need to be passed the date as a set of numbers.
This routine provides an easy way to convert a date from string form into
numbers.  You may use either "xx/xx/xx" or "xx-xx-xxxx" form to specify the
date (the string length is important, but the delimiter and contents of the
string are ignored).

The ProBas and PBClone versions of this routine do not work the same way in
regards to the year.  ProBas assumed that any two-digit year was in the
1900s.  In contrast, PBClone assumes that years 80-99 should be converted to
1980-1999 and that 0-79 should be converted to 2000-2079.

   DateS2N MonthNr%, Day%, Year%, DateSt$

DateSt$   date string.  Init to 8 or 10 characters (see above).
-------
MonthNr%  month
Day%      day
Year%     year

Name  : DCal
Class : Time
Level : Any

This routine draws a calendar for a specific month and year.  The results are
placed in an array which can be displayed using ScrRest or the other PBClone
routines to restore a screen image.

You must supply an integer array large enough to hold the image generated by
DCal, which expects a 25x80 screen.  DIM Scrn%(1 TO 2000) will do it.

The "page" and "fast" parameters are ignored.  They are included only for
compatibility with the ProBas ToolKit (which didn't use them either, so I
have no idea why they exist).

   DCal Scrn%(), CalDate$, Page%, Fast%

Scrn%()      array to hold screen image
CalDate$     date for the calendar
Page%        ignored
Fast%        ignored

Name  : DCalendar
Class : Time
Level : Clone

This routine displays a calendar for a specific month and year.  It waits for
input and acts accordingly, allowing the user to move to different dates via
the arrow keys or by entering the date directly. The bottom row of the screen
gives a list of the available key commands.

Screen handling is largely done by writing to an array, then dumping the
entire array to the display with DScrRest.  This provides for very smooth
displays.  You must supply an integer array large enough to hold the image
generated by DCalendar, which expects a 25x80 screen.  DIM Scrn%(1 TO 2000)
will do it.  Only text mode is supported by this routine.

DCalendar interprets the arrow keys in a different fashion than the ProBas
ToolKit routine of the same name.

   DCalendar Scrn%(), CalDate$, Page%, Fast%

Scrn%()      array to hold screen image
CalDate$     date for the calendar
Page%        page on which to display (normally zero)
Fast%        whether to use fast mode (nonzero if so; may cause snow on CGAs)

Name  : DClear
Class : Display
Level : Any

The DClear routine allows you to clear a text-mode display.

This routine does not necessarily work on the display itself.  Instead, it
allows you to specify the memory location (segment and offset) of the
"screen", which may be an actual screen, a saved screen in an array, a
multitasker's virtual screen, etc.  Among other things, this makes it easy to
work with two displays at once: use a segment of &HB000 for the mono display
and &HB800 for the color display (the offset in each case is zero).

   DClear DSeg%, DOfs%, Attr%

DSeg%    segment of "screen" memory
DOfs%    offset of "screen" memory
Attr%    color/attribute to use (see CalcAttr)

Name  : DClearSS
Class : Display
Level : Any

Like the CLS statement, this routine allows you to clear a text display.
However, rather than clearing the actual screen, DClearSS clears a screen
that is stored in an array.  This allows you to design a screen in memory,
then flash it onto the display using PutScreen or a similar routine.

This routine is designed for a text screen of any specified size.

   DClearSS DSeg%, DOfs%, Attr%, Rows%, Columns%

DSeg%     segment of the array that holds the screen
DOfs%     offset of the array that holds the screen
Attr%     color/attribute to use (see CalcAttr)
Rows%     length of the screen
Columns%  width of the screen

Name  : Dec2Any
Class : Numeric
Level : Any

This routine converts a normal integer to a number in any base.  It works
like the HEX$ function in BASIC, but rather than working only in hexadecimal
(base 16), it can be used for binary, octal, or almost anything else.

The result will be right-justified in the string you provide.  If you use
zeroes, this allows you to ignore the NumberLen% spec and just trim the
string to the desired length, leaving nothing worse than possible leading
zeroes.

The length needed by the return string will vary according to the number,
with a maximum length depending on the number base chosen.  For integers,
this will be at most 16 characters (worst case: base 2 or binary).

   Number$ = STRING$(16, "0")
   Dec2Any DecimalNr%, NrBase%, Number$, NumberLen%
   Number$ = RIGHT$(Number$, NumberLen%)

DecimalNr   integer to convert to another base
NrBase%     desired number base (2-31)
-------
Number$     resulting number in desired base (init to at least 16 chars)
NumberLen%  length of the result (-1 if insufficient space in string)

Name  : Delay
Class : Time
Level : Clone

This routine delays for a given number of seconds.  The timing will be the
same from an 8088 PC through an 80486 AT-- it's entirely independent of the
processor.  See also Delay18th.

   Delay Seconds%

Seconds%   number of seconds for which to delay

Name  : Delay18th
Class : Time
Level : Clone

This routine delays for a given number of 18ths of seconds.  The timing will
be the same from an 8088 PC through an 80486 AT-- it's entirely independent
of the processor.  See also Delay.

   Delay WaitTime%

WaitTime%  number of 18ths of seconds for which to delay

Name  : DelayV
Class : Time
Level : Clone

This routine delays for a given number of milliseconds.  The timing is based
on a signal from the video adapter and may vary somewhat depending on the
adapter.  The delay is largely independent of the cpu type and speed, however.

Note that this routine differs from the one in ProBas, which is based on an
arbitrary number of fractions of milliseconds.  The ProBas documentation on
DelayV incorrectly asserts that the delay is measured in microseconds, and
tidies up with an example that claims 1,100 microseconds is equal to half a
second.  Since the ProBas documentation on the matter is so confused, I
thought I might as well clean up the delay time when I rewrote the routine.

For anyone unfamiliar with the metric system: there are 1000 milliseconds in
one second.  Depending on the specific display adapter, this routine may well
be fairly inaccurate; it is intended for providing small delays for animation
and similar purposes, not as a reliable timer.

   DelayV MilliSeconds%

MilliSeconds%   number of milliseconds for which to delay

Name  : DelChr
Class : Display
Level : Clone

The DelChr routine deletes the character at the specified screen location.

   DelChr Row%, Column%

Row%      row of character
Column%   column of character

Name  : DelLine
Class : Display
Level : BIOS

This routine deletes the specified row from the screen.

   DelLine Row%, Attr%

Row%      row to delete
Attr%     color/attribute to use on new bottom row (see CalcAttr)

Name  : DelFile
Class : Disk
Level : DOS

This works like the DOS DEL (or ERASE) command, although it does not allow
wildcards.  The specified file is deleted.  Full path specifications are
supported, including drive and subdirectory specs.

   DelFile FileName$, ErrCode%

FileName$   name of the file to delete
-------
ErrCode%    0 if no error, else DOS Error

Name  : DelSub
Class : Disk
Level : DOS

This works like the DOS RD (or RMDIR) command.  It does not allow wildcards.
The specified subdirectory is deleted.  Note that you may not delete a
subdirectory that you're located in, or a subdirectory which contains files,
or the root directory.

   DelSub SubDir$, ErrCode%

SubDir$     name of the subdirectory to delete
-------
ErrCode%    0 if no error, else DOS Error

Name  : DFRead
Class : Disk
Level : DOS

This routine reads data into an array from a file that was opened by FOpen or
FCreate.  If it wasn't possible to read it all from the file, an error code
will be returned and the BytesRead% value will tell you how many bytes were
actually read.

   DFRead Handle%, DSeg%, DOfs%, Bytes%, BytesRead%, ErrCode%

Handle%     handle of the file from which to read
DSeg%       segment of the array into which to read the file
DOfs%       offset of the array into which to read the file
Bytes%      number of bytes to read
-------
BytesWrit%  number of bytes actually read from the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : DFWrite
Class : Disk
Level : DOS

This routine writes data from an array to a file that was opened by FOpen or
FCreate.  If it wasn't possible to write it all to the file, an error code
will be returned and the BytesWrit% value will tell you how many bytes were
actually written.

   DFWrite Handle%, DSeg%, DOfs%, Bytes%, BytesWrit%, ErrCode%

Handle%     handle of the file to which to write
DSeg%       segment of the data to write to the file
DOfs%       offset of the data to write to the file
Bytes%      number of bytes to write
-------
BytesWrit%  number of bytes actually written to the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : DGClear
Class : Display
Level : Any

This routine works like the CLS statement, clearing a CGA graphics display.
However, rather than clearing the actual screen, DClearSS clears a screen
that is stored in an array.  This allows you to design a screen in memory,
then flash it onto the display using GrafRest.

This routine is designed for use with SCREEN 1 or SCREEN 2 (CGA graphics).

   DGClear DSeg%, DOfs%, Colour%

DSeg%     segment of the array that holds the screen
DOfs%     offset of the array that holds the screen
Colour%   color to use

Name  : DGetRec
Class : String
Level : Clone

The DGetRec routine allows you to get a string from a specified area of
memory (numeric array, BIOS data area, display memory, or whatever).  The
string should be initialized to the desired record length in advance.

This works somewhat like an array of fixed length strings or a random file,
treating memory as a contiguous series of records of a specified length.

   DGetRec DSeg%, DOfs%, RecNr%, St$

DSeg%      segment of the array to read from
DOfs%      offset of the array to read from
RecNr%     record number (starting at 1)
-------
St$        returned string.  Init to the record length (see above).

Name  : DGetScreen
Class : Display
Level : Clone

This routine saves any portion of the display to an array.  Only text modes
are supported.  If your program uses multiple display pages, you can get an
image from any of those pages.  A special "slow" mode is supported for the
CGA, to prevent flickering (a problem only with some CGAs).

The size of the integer array needed to store a specific area of the screen
can be calculated using the CalcSize routine (see).

The GetScreen routine works the same way as this, but has a simpler calling
convention.  Also, if you wish to save the entire screen, you may find
ScrSave easier.

   DGetScreen DSeg%, DOfs%, TopRow%, LeftCol%, BotRow%, RightCol%, Page%, Fast%

DSeg%      segment of the array in which to store the image
DOfs%      offset of the array in which to store the image
TopRow%    top row of the desired screen area
LeftCol%   left column of the desired screen area
BotRow%    bottom row of the desired screen area
RightCol%  right column of the desired screen area
Page%      page from which to get the display area
Fast%      whether to use fast mode (nonzero if so; else slow, for some CGAs)

Name  : DGetSt
Class : String
Level : Clone

The DGetSt routine allows you to get a string from a specified area of memory
(numeric array, BIOS data area, display memory, or whatever).  The string
should be initialized to the desired length in advance.

You may specify an additional offset from the initial location, which itself
is specified as a segment and an offset.  The second offset begins with
position 1.  The combined total of the two offsets must be under 65,536 at
the moment.  I'll remove that restriction at a later time.  With normalized
segment and offset specifications, which is usually the case, this allows you
to specify a number from 1-65,521 for the second offset.

   DGetSt DSeg%, DOfs%, Posn&, St$

DSeg%      segment of the array to read from
DOfs%      offset of the array to read from
Posn&      location relative to the start of the array
-------
St$        returned string.  Init to the number of chars desired (see above).

Name  : DGQPrint
Class : Display
Level : Any

This is a simple high-speed replacement for the PRINT statement which works
on a CGA virtual graphics screen (SCREEN 2).  It does not interpret control
codes or support graphics characters (ASCII 128-255).

DGQPrint allows you to display to a CGA even if it isn't the active display
(use a segment of &HB800 and offset of 0).  Its intended use, however, is to
display to a virtual screen kept in an array or other memory area.  The
results can then be displayed using GrafRest.

   DGQPrint DSeg%, DOfs%, St$, Row%, Column%

DSeg%    segment of CGA virtual screen
DOfs%    offset of CGA virtual screen
St$      string to display
Row%     row (1-25)
Column%  column (1-80)

Name  : DGXQPrint
Class : Display
Level : Any

This is a simple high-speed replacement for the PRINT statement which works
on a CGA virtual graphics screen (SCREEN 1).  It does not interpret control
codes or support graphics characters (ASCII 128-255).

This routine can also be used on a SCREEN 2 display, where it will display
the string in shades instead of in color (using 40 columns/row).

DGXQPrint allows you to display to a CGA even if it isn't the active display
(use a segment of &HB800 and offset of 0).  Its intended use, however, is to
display to a virtual screen kept in an array or other memory area.  The
results can then be displayed using GrafRest.

   DGXQPrint DSeg%, DOfs%, St$, Row%, Column%, Fore%

DSeg%    segment of CGA virtual screen
DOfs%    offset of CGA virtual screen
St$      string to display
Row%     row (1-25)
Column%  column (1-40)
Fore%    foreground color (0-3)

Name  : DGXQPrint1
Class : Display
Level : Any

This is a high-speed replacement for the PRINT statement which works on a CGA
virtual graphics screen (SCREEN 1). It does not interpret control codes.

This routine can also be used on a SCREEN 2 display, where it will display
the string in shades instead of in color (using 40 columns/row).

DGXQPrint1 allows you to display to a CGA even if it isn't the active display
(use a segment of &HB800 and offset of 0).  Its intended use, however, is to
display to a virtual screen kept in an array or other memory area.  The
results can then be displayed using GrafRest.

   DGXQPrint1 DSeg%, DOfs%, St$, Row%, Column%, Fore%, Back%

DSeg%    segment of CGA virtual screen
DOfs%    offset of CGA virtual screen
St$      string to display
Row%     row (1-25)
Column%  column (1-40)
Fore%    foreground color (0-3)
Back%    background color (0-3)

Name  : DiskStat
Class : Disk
Level : DOS

DiskStat gives you statistics on the memory usage of a specified disk drive:
the total number of clusters, the number of available or free clusters, the
number of sectors per cluster, and the number of bytes per sector.

From this information, you can determine how much total disk space there is,
how much space is left and how much is used, the size of a cluster, et al.

A few formulas for you:

   ClusterSize% = BytesPerSec% * SecsPerClus%
   FreeSpace& = FreeClus& * ClusterSize%
   TotalSpace& = TotalClus& * ClusterSize%
   UsedSpace& = TotalSpace& - FreeSpace&

A "cluster" is the minimum amount of disk space that can be allocated at a
time.  A typical cluster size for a medium-sized hard drive is 2048 bytes,
which means that any file from 1-2048 bytes in length is actually taking up a
full 2048 bytes on the disk.  Large cluster sizes improve file access times
but can waste a lot of disk space.

NOTE that this routine is not directly compatible with its ProBas equivalent.
PBClone uses LONG integers to return free clusters and total clusters,
whereas ProBas uses ordinary integers.  The use of long integers is needed to
return the proper information for large hard drives.

   DiskStat Drive$, FreeClus&, TotalClus&, BytesPerSec%, SecsPerClus%

Drive$        letter of the drive to examine
-------
FreeClus&     number of free or available clusters
TotalClus&    total number of clusters
BytesPerSec%  bytes per sector
SecsPerClus%  sectors per cluster (-1 if bad drive, open drive door, etc)

Name  : Dissolve
Class : Display
Level : Clone

Like CLS, but a bit more fancy, this routine provides an interesting way to
clear the screen.  See also FadeOut.

This routine may cause heavy flickering on some CGA displays.

   Dissolve Attr%

Attr%   color/attribute to which to clear (see CalcAttr)

Name  : DMPrint
Class : Display
Level : DOS

This routine is similar to PRINT, but goes through DOS output services, which
allows your program to support output redirection, filters, CTTY and other
handy things.  See DOSInkey for a DOS input service.

Note that the use of DMPrint means that you should avoid using BASIC display
handling (CLS, INPUT, LINE INPUT, PRINT, LOCATE, CSRLIN, POS, etc).  Instead,
you should use ANSI escape sequences to control the display.  This requires
that an ANSI driver (like ANSI.SYS, DVANSI.SYS, NANSI.SYS, or ZANSI.SYS) be
installed on your system.  See your DOS manual for details on ANSI sequences,
or grab the documentation on ANSI from one of your friendly local BBSes.

It is -possible- to use BASIC display handling in conjunction with DMPrint,
but that tends to defeat the purpose of using DMPrint in the first place.

Note that the DMPrint routine does not add a carriage return/linefeed to the
end of a string.  If you want that, add CHR$(13) + CHR$(10) to the end of the
string.

   DMPrint St$

St$    string to display

Name  : DOSClrEol
Class : Display
Level : DOS

This routine clears from the cursor position to the end of the row using DOS
output functions.  It requires that ANSI.SYS or another ANSI driver be
installed.

DOSClrEol does not exist in ProBas.

   DOSClrEol

Name  : DOSCls
Class : Display
Level : DOS

This routine clears the screen using DOS output functions.  It requires that
ANSI.SYS or another ANSI driver be installed.

DOSCls works like the routine of the same name in the ProBas ToolKit.

   DOSCls

Name  : DOSColor
Class : Display
Level : DOS

This routine sets the screen colors using DOS output functions.  It requires
that ANSI.SYS or another ANSI driver be installed.

This routine works like the one of the same name in the ProBas ToolKit.

   DOSColor Fore%, Back%

Fore%    foreground color
Back%    background color

Name  : DOSErrM$
Class : Miscellaneous
Level : DOS

Of the many PBClone routines that return error codes, most simply pass the
code back from DOS without any processing.  You can see what the codes mean
by checking the chart in PBCLONE.DOC, or it may be more convenient to use
DOSErrM$ instead.  This routine returns a short text description of the error
in question.

   ErrMsg$ = DOSErrM$(ErrCode%)

ErrCode%     error code to translate
-------
ErrMsg$      brief explanation of the error

Name  : DOSInkey
Class : Input
Level : DOS

This routine is similar to INKEY$, but goes through DOS input services, which
allows your program to support input redirection, filters, CTTY and other
handy things.  See DMPrint for a DOS output service.  See also DOSInky$.

   DOSInkey CharCode%, CharType%

-------
CharType%    0 if no key, 1 if normal key, 2 if extended key
CharCode%    ASCII code if normal key, scan code if extended key

Name  : DOSInky$
Class : Input
Level : DOS

This routine works just like INKEY$, but goes through DOS input services,
which allows your program to support input redirection, filters, CTTY and
other handy things.  See DMPrint for a DOS output service.  See also DOSInkey.

   ky$ = DOSInky$

-------
ky$      key, if any was waiting (0-2 characters per key, like INKEY$)

Name  : DOSInt%
Class : Miscellaneous
Level : DOS

This routine provides you with easy access to DOS functions via INT 21H, the
major DOS interrupt.  It works like the CALL INTERRUPT routines provided with
QuickBASIC but is easier to use, at the expense of some flexibility.

CAUTION: This routine works directly with DOS, bypassing most of BASIC's
safety precautions.  Possible chaos may result if you don't know what you're
doing!  A few specific caveats:

   1) Do Not use this routine to exit your program or execute another.  BASIC
      needs to clean up after itself before these tasks, and bypassing its
      handling is liable to make the system unstable at best.

   2) If you expect to use a string or array as a buffer, make sure it is
      long enough to handle the maximum amount of information anticipated.
      Strings and arrays can move about in memory, so be sure to get their
      addresses Just Before using DOSInt%.

If you wish to specify BASIC's data segment for DS, you can find out what
that is using the DataSeg routine (q.v.).

   CarryFlag% = DOSInt%(AX%, BX%, CX%, DX%, DS%)

AX%         desired setting of the AX register
BX%         desired setting of the BX register
CX%         desired setting of the CX register
DX%         desired setting of the DX register
DS%         desired setting of the DS and ES registers
-------
AX%         returned setting of the AX register
BX%         returned setting of the BX register
CX%         returned setting of the CX register
DX%         returned setting of the DX register
DS%         returned setting of the DS and ES registers
CarryFlag%  returned carry flag (0 if no error, else AX is error code)

Name  : DOSLocate
Class : Display
Level : DOS

This routine sets the cursor position using DOS output functions.  It
requires that ANSI.SYS or another ANSI driver be installed.

Note that many ANSI drivers do not fully support EGA or VGA modes in that
they are limited to a maximum of 25 rows.

This routine works like the one by the same name in the ProBas ToolKit.

   DOSLocate Row%, Column%

Row%      row
Column%   column

Name  : DPutRec
Class : String
Level : Clone

The DPutRec routine allows you to put a string into a specified area of
memory (numeric array, BIOS data area, display memory, or whatever).  The
string should be initialized to the desired record length in advance.

This works somewhat like an array of fixed length strings or a random file,
treating memory as a contiguous series of records of a specified length.

   DPutRec DSeg%, DOfs%, RecNr%, St$

DSeg%      segment of the array to write into
DOfs%      offset of the array to write into
RecNr%     record number (starting at 1)
St$        string to write.  Init to the record length (see above).

Name  : DPutScreen
Class : Display
Level : Clone

This routine restores a portion of the display (which was saved to an array
by DGetScreen or GetScreen) to the screen.  Only text modes are supported.
If your program uses multiple display pages, you can put the image onto any
of those pages.  A special "slow" mode is supported for the CGA, to prevent
flickering (a problem only with some CGAs).

The PutScreen routine works the same way as this, but has a simpler calling
convention.  Also, if you wish to restore the entire screen, you may find
ScrRest easier (see).

   DPutScreen DSeg%, DOfs%, TopRow%, LeftCol%, BotRow%, RightCol%, Page%, Fast%

DSeg%      segment of the array from which to restore the image
DOfs%      offset of the array from which to restore the image
TopRow%    top row of the desired screen area
LeftCol%   left column of the desired screen area
BotRow%    bottom row of the desired screen area
RightCol%  right column of the desired screen area
Page%      page on which to restore the display
Fast%      whether to use fast mode (nonzero if so; else slow, for some CGAs)

Name  : DPutSt
Class : String
Level : Clone

The DPutSt routine allows you to put a string into a specified area of memory
(numeric array, BIOS data area, display memory, or whatever).

You may specify an additional offset from the initial location, which itself
is specified as a segment and an offset.  The second offset begins with
position 1.  The combined total of the two offsets must be under 65,536 at
the moment.  I'll remove that restriction at a later time.  With normalized
segment and offset specifications, which is usually the case, this allows you
to specify a number from 1-65,521 for the second offset.

   DPutSt DSeg%, DOfs%, Posn&, St$

DSeg%      segment of the array to write to
DOfs%      offset of the array to write to
Posn&      location relative to the start of the array
St$        string to write into memory

Name  : DRecDel
Class : Miscellaneous
Level : Any

This routine allows you to delete an item from an array.  The item may
consist of one or more array elements.  The size of the array isn't actually
changed, but the array elements are moved as if a deletion took place.

   DRecDel DSeg%, DOfs%, RecNr%, RecLen%, Records%

DSeg%      segment of the array
DOfs%      offset of the array
RecNr%     record/element number (starting at 1)
RecLen%    record/element length in bytes
Records%   total number of records/elements in the array

Name  : DRecIns
Class : Miscellaneous
Level : Any

This routine allows you to insert an item into an array.  The item may
consist of one or more array elements.  The size of the array isn't actually
changed, but the array elements are moved as if an insertion took place.  You
must of course make sure that the array is DIMed large enough to handle this.

   DRecIns DSeg%, DOfs%, RecNr%, RecLen%, Records%

DSeg%      segment of the array
DOfs%      offset of the array
RecNr%     record/element number (starting at 1)
RecLen%    record/element length in bytes
Records%   total number of records/elements in the array

Name  : DReColor
Class : Display
Level : Any

The DReColor routine changes all text in one color to another color.  It
works only in text modes.  The colors are specified as attributes (see
CalcAttr).

This routine does not necessarily work on the display itself.  Instead, it
allows you to specify the memory location (segment and offset) of the
"screen", which may be an actual screen, a saved screen in an array, a
multitasker's virtual screen, etc.  Among other things, this makes it easy to
work with two displays at once: use a segment of &HB000 for the mono display
and &HB800 for the color display (the offset in each case is zero).

   DReColor DSeg%, DOfs%, OldAttr%, NewAttr%

DSeg%      segment of "screen" memory
DOfs%      offset of "screen" memory
OldAttr%   color to be changed
NewAttr%   color to which to change

Name  : DReColorArea
Class : Display
Level : Clone

The DReColorArea routine changes a specified area of the screen to a
specified color.  It works only in text modes.  The color is specified as an
attribute (see CalcAttr).

One of the more common applications for this routine is marking an area of
the screen, e.g. menu highlight bars.

   DReColorArea DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%, Attr%

This routine does not necessarily work on the display itself.  Instead, it
allows you to specify the memory location (segment and offset) of the
"screen", which may be an actual screen, a saved screen in an array, a
multitasker's virtual screen, etc.  Among other things, this makes it easy to
work with two displays at once: use a segment of &HB000 for the mono display
and &HB800 for the color display (the offset in each case is zero).

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
TopRow%     top row of area to recolor
LeftCol%    left column of area to recolor
BottomRow%  bottom row of area to recolor
RightCol%   right column of area to recolor
Attr%       desired color

Name  : DriveSpace&
Class : Disk
Level : DOS

This routine tells you how many bytes are free on a specified disk drive.

   BytesFree& = DriveSpace&(Drive$)

Drive$      letter of the drive to examine
-------
BytesFree&  free bytes on the specified drive, or -1 if bad drive or disk error

Name  : DrvSpace
Class : Disk
Level : DOS

This is an obsolescent version of the DrvSpaceL routine.  It is included
solely for ProBas compatibility.

See DrvSpaceL.

Name  : DrvSpaceL
Class : Disk
Level : DOS

This routine tells you how many bytes are free on a specified disk drive.
See also DriveSpace, a function-type version of this routine.

   DrvSpaceL Drive$, BytesFree&

Drive$      letter of the drive to examine
-------
BytesFree&  free bytes on the specified drive, or -1 if bad drive or disk error

Name  : DrvType
Class : Disk
Level : DOS 3.1+

The DrvType routine tells you whether a specified drive is fixed or
removeable, and whether it is local or remote (network drive).

   DrvType Drive$, Removeable%, Remote%, ErrCode%

Drive$       letter of the drive to examine
-------
Removeable%  whether the disk in the drive can be removed (0 if no)
Remote%      whether this is a remote drive (0 if no)
ErrCode%     error code: 0 if none, else bad DOS version

Name  : DScrRest
Class : Display
Level : Clone

The DScrRest routine restores a display that was saved using ScrSave or a
similar routine.  It only works in text modes.  See also ScrRest.

   DScrRest DSeg%, DOfs%, Page%, Fast%

DSeg%      segment of info to restore to the screen
DOfs%      offset of info to restore to the screen
Page%      page on which to restore the display
Fast%      whether to use fast mode (nonzero if so; may cause snow on CGAs)

Name  : DScrSave
Class : Display
Level : Clone

The DScrSave routine saves the display to an array or other storage area.
Only text modes are supported.  For an 80x25 display, the array must hold
4,000 bytes (4,000 string characters or 2,000 integers).  See also ScrSave.

   DScrSave DSeg%, DOfs%, Page%, Fast%

DSeg%      segment of place to store the display
DOfs%      offset of place to store the display
Page%      page from which to get the display
Fast%      whether to use fast mode (nonzero if so; may cause snow on CGAs)

Name  : DTR
Class : Serial
Level : Clone

Just as IBM provided the standard for personal computers, Hayes provided
the standard for modem commands.  Unfortunately, the command method of
dropping carrier (hanging up the phone) was badly designed, and all
Hayes-compatible modems have a hard time recognizing that command under
certain line conditions.

Fortunately, there's a more reliable way of hanging up: the DTR serial
signal.  Turning this signal off will cause the modem to hang up very
quickly.  Most Hayes-compatible modems are factory-set to pay attention to
the DTR; those that aren't can be made to do so either by flipping a hardware
switch or with a special initialization command.  See your modem manual for
details.

BASIC will drop the DTR when you CLOSE the comm port, but this isn't always a
convenient way to do it.  As a matter of fact, this can be a decided
nuisance, so many people have patched their version of BASIC to avoid it.  If
you would like to do so, check your local BBS for the method!  With the
PBClone DTR routine, you can get full control over the DTR without having to
CLOSE the comm port.

Note: it may be wise to include a brief delay after dropping the DTR, to give
the modem a chance to react.  Try Delay18th (see) with a wait of around 4.

   DTR CommPort%, TurnOn%

CommPort%    serial port number (1-4, although BASIC only handles 1-2)
TurnOn%      whether to raise (turn on) the DTR (0 if no)

Name  : DWindowManager
Class : Display
Level : Any

DWindowManager displays a pop-up window according to your specifications.
The window may have any of a variety of frames, a title, or a shadow, and it
may appear instantly or "grow" onto the screen.

These are the available frame types:
    0   no frame
    1   single lines
    2   double lines
    3   single horizontal, double vertical lines
    4   double horizontal, single vertical lines
    5   block graphic lines

These are the available shadows:
   -3   transparent shadow on the right
   -2   transparent shadow on the left
   -1   solid black shadow on the left
    0   no shadow
   1+   shadow attribute (use CalcAttr) for a colored shadow

Options for growing windows are as follows:
   -1   grow as fast as possible
    0   pop onto the screen
   1+   grow with a specified delay in milliseconds (15 works well for me)

Note that this routine is different from its ProBas equivalent in a number of
respects.  The grow delay time is different.  Growing is done more smoothly.
The shadow and title parameters are not changed by this routine.  A new frame
type (5) was added.  If a title is too long, it is truncated instead of being
ignored completely.  Using a -1 as the title foreground color will not turn
off the title; instead, use a null title string.

   DWindowManager DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%,
      Frame%, Fore%, Back%, Grow%, Shade%, TFore%, Title$

This routine does not necessarily work on the display itself.  Instead, it
allows you to specify the memory location (segment and offset) of the
"screen", which may be an actual screen, a saved screen in an array, a
multitasker's virtual screen, etc.  Among other things, this makes it easy to
work with two displays at once: use a segment of &HB000 for the mono display
and &HB800 for the color display (the offset in each case is zero).

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
Fore%       frame foreground color
Back%       frame background color
Grow%       window growing option (see above)
Shade%      window shadow option (see above)
TFore%      title foreground color
Title$      window title ("" if none)

Name  : DWindowMan2
Class : Display
Level : Any

This routine is identical to DWindowManager but for the fact that it allows
you to design your own custom window frames.  Please see the description of
DWindowManager for general information.

These are the additional frame types:
    6   custom frame composed of a single character
    7   custom frame composed of the specified 7-character list:
        top left corner, top middle, top right corner,
        left middle, right middle,
        bottom left corner, bottom middle, bottom right corner

 /------------------------------------------------------------\
 | A custom frame like this would be defined as frame type 7, |
 | with a frame string of "/-\||\-/", for instance.           |
 \------------------------------------------------------------/

 *************************************************
 * On the other hand, a frame like this would be *
 * frame type 6, with a frame string of "*".     *
 *************************************************

Note that this routine differs from the ProBas equivalent in that it supports
full frame definitions through frame type 7 (ProBas only supports type 6).
The other differences mentioned under WindowManager are also relevant.

   DWindowMan2 DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%,
      Frame%, FSt$, Fore%, Back%, Grow%, Shade%, TFore%, Title$

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
FSt$        frame definition string (see above)
Fore%       frame foreground color
Back%       frame background color
Grow%       window growing option (see above)
Shade%      window shadow option (see above)
TFore%      title foreground color
Title$      window title ("" if none)

Name  : DWindowMan3
Class : Display
Level : Any

This routine is identical in function to DWindowManager.  The parameters are
mostly passed as an array, however, instead of one by one.  Please see the
description of DWindowManager for general information.

   DWindowMan3 Parm%(), Title$

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
Parm%(1)    top row of window
Parm%(2)    left column of window
Parm%(3)    bottom row of window
Parm%(4)    right column of window
Parm%(5)    frame type (see above)
Parm%(6)    frame foreground color
Parm%(7)    frame background color
Parm%(8)    window growing option (see above)
Parm%(9)    window shadow option (see above)
Parm%(10)   title foreground color
Title$      window title ("" if none)

Name  : DWindowMan4
Class : Display
Level : Any

This is an extremely cut-down version of DWindowManager, providing no more
than a simple frame generator.

These are the available frame types:
    0   no frame
    1   single lines
    2   double lines
    3   single horizontal, double vertical lines
    4   double horizontal, single vertical lines
    5   block graphic lines

Note that this routine is different from its ProBas equivalent in that a new
frame type (5) is available.

   DWindowMan4 DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%,
      Frame%, Attr%

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
Attr%       frame color/attribute (use CalcAttr)

Name  : DXQPrint
Class : Display
Level : Any

This routine provides a rather crude, but very fast, display capability.  It
works like the PRINT statement in BASIC, except that it doesn't move the
cursor or process control codes.  It works only in text modes.

This routine does not necessarily work on the display itself.  Instead, it
allows you to specify the memory location (segment and offset) of the
"screen", which may be an actual screen, a saved screen in an array, a
multitasker's virtual screen, etc.  Among other things, this makes it easy to
work with two displays at once: use a segment of &HB000 for the mono display
and &HB800 for the color display (the offset in each case is zero).

   DXQPrint DSeg%, DOfs%, St$, Row%, Column%, Attr%

DSeg%     segment of "screen" memory
DOfs%     offset of "screen" memory
St$       string to display
Row%      starting row
Column%   starting column
Attr%     color/attribute (see CalcAttr)

Name  : EGARest7
Class : Display
Level : Clone

This routine allows you to restore a SCREEN 7 (EGA, 320x200, 16 color)
display that was saved using EGASave7 (see).

   EGARest7 DSeg%, DOfs%

DSeg%        segment of storage array, returned by VARSEG
DOfs%        offset  of storage array, returned by VARPTR

Name  : EGARest8
Class : Display
Level : Clone

This routine allows you to restore a SCREEN 8 (EGA, 640x200, 16 color)
display that was saved using EGASave8 (see).

   EGARest8 DSeg%, DOfs%

DSeg%        segment of storage array, returned by VARSEG
DOfs%        offset  of storage array, returned by VARPTR

Name  : EGARest9
Class : Display
Level : Clone

This routine allows you to restore a SCREEN 9 (EGA, 640x350, 16 color)
display that was saved using EGASave9 (see).

Note that this routine is not compatible with the ProBas routine by the same
name.  See EGASave9 for further information.

   EGARest9 DSeg1%, DOfs1%, DSeg2%, DOfs2%

DSeg1%       segment of storage array #1, returned by VARSEG
DOfs1%       offset  of storage array #1, returned by VARPTR
DSeg2%       segment of storage array #2, returned by VARSEG
DOfs2%       offset  of storage array #2, returned by VARPTR

Name  : EGASave7
Class : Display
Level : Clone

This routine allows you to save a SCREEN 7 (EGA, 320x200, 16 color) display
that can be restored using EGARest7 (see).

The array used to hold the screen must contain 32,000 bytes.  For an integer
array, this means that you must create the array by DIM Array%(1 TO 16000).

   EGASave7 DSeg%, DOfs%

DSeg%        segment of storage array, returned by VARSEG
DOfs%        offset  of storage array, returned by VARPTR

Name  : EGASave8
Class : Display
Level : Clone

This routine allows you to save a SCREEN 8 (EGA, 640x200, 16 color) display
that can be restored using EGARest8 (see).

The array used to hold the screen must contain 64,000 bytes.  For an integer
array, this means that you must create the array by DIM Array%(1 TO 32000).

   EGASave8 DSeg%, DOfs%

DSeg%        segment of storage array, returned by VARSEG
DOfs%        offset  of storage array, returned by VARPTR

Name  : EGASave9
Class : Display
Level : Clone

This routine allows you to save a SCREEN 9 (EGA, 640x350, 16 color) display
that can be restored using EGARest9 (see).

Two arrays must be used to hold the screen, for a total of 112,000 bytes.  If
you use integer arrays, each array must be created by DIM Array%(1 TO 28000).

Note that this routine is not compatible with the ProBas routine by the same
name.  The ProBas routine, for no apparent reason, expects to use 128,000
bytes instead of 112,000.  Thus, its image format is different.

   EGASave9 DSeg%, DOfs%

DSeg1%       segment of storage array #1, returned by VARSEG
DOfs1%       offset  of storage array #1, returned by VARPTR
DSeg2%       segment of storage array #2, returned by VARSEG
DOfs2%       offset  of storage array #2, returned by VARPTR

Name  : Elapsed
Class : Time
Level : Any

This routine tells you the amount of time elapsed between a given starting
time and ending time.  The difference between the times must be less than 24
hours for the results to be meaningful.

See also ElapsedTime, the FUNCTION version of this routine.

   Elapsed TimeStart$, TimeStop$, TimeDiff$

TimeStart$   starting time
TimeStop$    ending time
-------
TimeDiff$    elapsed time

Name  : ElapsedTime$
Class : Time
Level : Any

This routine tells you the amount of time elapsed between a given starting
time and ending time.  The difference between the times must be less than 24
hours for the results to be meaningful.

See also Elapsed, the SUB version of this routine.

   TimeDiff$ = ElapsedTime$(TimeStart$, TimeStop$)

TimeStart$   starting time
TimeStop$    ending time
-------
TimeDiff$    elapsed time

Name  : EMSBuffer
Class : Memory
Level : BIOS

EMSBuffer tells you how many bytes are needed to save the state of the EMS
array routines.  Used in conjunction with EMSSave and EMSRest, it allows you
to preserve EMS arrays across a CHAIN to another part of your program.

   EMSBuffer Bytes%
   EMSState$ = SPACE$(Bytes%)
   EMSSave EMSState$

-------
Bytes%       bytes needed to save EMS array state

Name  : EMSClose
Class : Memory
Level : BIOS

The EMSClose routine is used when you are finished with an EMS array.  It
frees the array handle and EMS memory for other uses.  If you don't close all
EMS arrays before your program ends, the memory will be lost until the system
is rebooted, so it is important to remember EMSClose.

   EMSClose ArrayHandle%

ArrayHandle%    handle of an EMS array

Name  : EMSGet
Class : Memory
Level : BIOS

This routine gets an element from an EMS array created by EMSOpen.  Element
numbers start at 0.  Be sure to use the right numeric type for the array--
for instance, if you opened the array for SINGLE precision, use "Value!".

   EMSGet ArrayHandle%, ElementNr&, Value

ArrayHandle%    handle of an EMS array
ElementNr&      element number to get
-------
Value           value to get element into (must be correct type for array)

Name  : EMSOpen
Class : Memory
Level : BIOS

This routine allows you to open a block of EMS (expanded) memory which can
then be accessed like a numeric array.  The array size is limited only by
available EMS memory (use GetLIMM to find out how much is available).  You
may specify any numeric type:

    1   INTEGER
    2   LONG or SINGLE
    3   DOUBLE

When the array is opened, you are returned an "array handle" which is used to
access that array.  Access to the array is done via EMSGet and EMSPut.  When
you are finished with the array, you must close it with EMSClose.

As many as 25 EMS arrays can be in use at one time, subject to limitations
which may be imposed by your EMS driver (each array requires one EMS handle).

   EMSOpen Elements&, ElementType%, ArrayHandle%, ErrCode%

Elements&       number of elements in array (like DIM size)
ElementType%    numeric type of array (see above)
-------
ArrayHandle%    handle of an EMS array
ErrCode%        whether an error occurred (0 no)

Name  : EMSPut
Class : Memory
Level : BIOS

This routine puts an element into an EMS array created by EMSOpen.  Element
numbers start at 0.  Be sure to use the right numeric type for the array--
for instance, if you opened the array for SINGLE precision, use "Value!".

   EMSPut ArrayHandle%, ElementNr&, Value

ArrayHandle%    handle of an EMS array
ElementNr&      element number to set
Value           value to set element to (must be correct type for array)

Name  : EMSRest
Class : Memory
Level : BIOS

This routine allows you to restore the state of the EMS array handler.  Used
in conjunction with EMSBuffer and EMSSave, it allows you to preserve EMS
arrays across a CHAIN to another part of your program.

   EMSRest EMSState$

EMSState$    saved EMS array state

Name  : EMSSave
Class : Memory
Level : BIOS

This routine allows you to save the state of the EMS array handler.  Used in
conjunction with EMSBuffer and EMSRest, it allows you to preserve EMS arrays
across a CHAIN to another part of your program.

   EMSBuffer Bytes%
   EMSState$ = SPACE$(Bytes%)
   EMSSave EMSState$

-------
EMSState$    saved EMS array state

Name  : EnhKbd
Class : Input
Level : BIOS

By default, the PBClone routines assume an old-style keyboard is in use, for
greatest compatibility.  EnhKbd allows you to turn on enhanced keyboard
handling for the current generation of (usually) 101-key keyboards.  This
allows access to the F11 and F12 function keys as well as codes for key
combinations that used to be ignored, among other things.

The KbdType or KbdType2% routine can be used to determine if an enhanced
keyboard is available (recommended).

Note that EnhKbd works by intercepting the BIOS keyboard handler.  All calls
to the BIOS keyboard interrupt are converted from the old keyboard functions
to the new ones.  YOU MUST DISABLE EnhKbd BEFORE YOUR PROGRAM ENDS, so it can
restore the old setup.  Otherwise, the computer will most probably crash.

A list of the new key codes is given in PBCLONE.DOC.

This routine does not exist in ProBas, which instead assumes that you want to
use new keyboard handling if an enhanced keyboard is detected.

   EnhKbd Enable%

Enable%     turn on enhanced keyboard support (0 disable, else enable)

Name  : EuropeDate
Class : Time
Level : Any

This routine takes a date in one of the American formats ("MM/DD/YY" or
"MM-DD-YYYY") and converts it to the European convention ("DD.MM.YY" or
"DD.MM.YYYY").  The date is formatted according to a format string which
provides the desired delimiter and year length, e.g. "##-##-##" specifies a
delimiter of "-" and a year length of two digits.

An error code is returned if the date is not valid.

This routine works like the one of the same name in the ProBas ToolKit.

   EuropeDate DateSt$, Format$, Result$, ErrCode%

DateSt$     date to format (month, day, year order)
Format$     format for the date
-------
Result$     resulting date (day, month, year order)
ErrCode     whether the date is valid (0 ok)

Name  : Equipment
Class : Equipment
Level : BIOS

This routine gives you some information about the basic equipment in your
computer.  Note that the "game port" information is not reliable, due to
changes in the meaning of this particular area of the BIOS over many years.

   Equipment Memory%, Parallel%, Serial%, Game%

-------
Memory%    kilobytes of conventional memory installed (16 - 640)
Parallel%  parallel (printer) ports installed (0-4)
Serial%    serial (communications) ports installed (0-4)
Game%      game (joystick) ports installed (0-1).  See remarks, above.

Name  : EWindowManagerC
Class : Display
Level : Clone

EWindowManagerC displays a pop-up window according to your specifications.
The window may have any of a variety of frames, a title, or a shadow, and it
may appear instantly or "grow" onto the screen.  EGA and VGA graphics modes
(SCREEN 7 through SCREEN 12) are supported.

These are the available frame types:
    0   no frame
    1   single lines
    2   double lines
    3   single horizontal, double vertical lines
    4   double horizontal, single vertical lines
    5   block graphic lines

These are the available shadows:
    0   no shadow
   1+   shadow attribute (use CalcAttr) for a colored shadow

Options for growing windows are as follows:
   -1   grow as fast as possible
    0   pop onto the screen
   1+   grow with a specified delay in milliseconds (not recommended)

The differences between this routine and its ProBas equivalent are the same
as mentioned in the description for WindowManager.  In addition, growing
windows are supported, but are not recommended (too slow).  Colored shadows
work as in WindowManager.  "True" shadows are not yet supported.

   EWindowManagerC TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%,
      Fore%, Back%, Grow%, Shade%, S1%, S2%, TFore%, Title$

TopRow%     top row of window
LeftCol%    left column of window
BottomRow%  bottom row of window
RightCol%   right column of window
Frame%      frame type (see above)
Fore%       frame foreground color
Back%       frame background color
Grow%       window growing option (see above)
Shade%      window shadow option (see above)
S1%         unused
S2%         unused
TFore%      title foreground color
Title$      window title ("" if none)

Name  : Exist
Class : Disk
Level : DOS

Most versions of BASIC give you no way of seeing if a file exists before you
try to OPEN it, so you end up taking your chances.  The Exist routine allows
you to test to see if the file exists beforehand.  It isn't really necessary
for the PBClone file routines, which will return an appropriate error code,
but it's an important safeguard when using the BASIC OPEN statement.

The Exist routine does not support wildcards.  If you need that feature, try
the FindFirstFx and FindNextFx routines instead.

See also Exist2, the FUNCTION version of this routine.

   Exist FileName$, Found%

FileName$   name of the file to look for
-------
Found%      whether the file was found (0 if no)

Name  : Exist2%
Class : Disk
Level : DOS

Most versions of BASIC give you no way of seeing if a file exists before you
try to OPEN it, so you end up taking your chances.  The Exist2% function
allows you to test to see if the file exists beforehand.  It isn't really
necessary for the PBClone file routines, which will return an appropriate
error code, but it's an important safeguard when using the OPEN statement.

The Exist2% routine does not support wildcards.  If you need that feature,
try the FindFirstFx and FindNextFx routines instead.

See also Exist, the SUB version of this routine.

   Found% = Exist2%(FileName$)

FileName$   name of the file to look for
-------
Found%      whether the file was found (0 if no)

Name  : EXQPrintC
Class : Display
Level : Clone

This routine provides a rather crude, but very fast, display capability.  It
works like the PRINT statement in BASIC, except that it doesn't move the
cursor or process control codes.  It works in EGA and VGA graphics modes
(SCREEN 7 through SCREEN 12).

   EXQPrintC St$, Row%, Column%, Fore%, Back%

St$       string to display
Row%      starting row
Column%   starting column
Fore%     foreground color
Back%     background color

Name  : ExtendFSpec
Class : Disk
Level : DOS

The ExtendFSpec routine combines a number of handy services together.  It is
intended for processing user-entered file specifications.  It does the
following:

   1) Makes sure the filespec is valid
   2) Formats the filespec to normal DOS standards
   3) Tells you whether the drive and subdirectories specified exist
   4) Fills out any drive or subdirectory information that was left out
      (optionally includes adding an extension to files which lack one)

The error codes returned are as follows:
   -1    Invalid file specification
    0    No error
    1    Specified drive does not exist (warning only)
    2    Specified subdirectory does not exist (warning only)

The PBClone version of ExtendFSpec mimics DOS file handling exactly.  The
same is not true of the ProBas version of this routine.

   ExtendFSpec File$, Ext$, FullFile$, ErrCode%

File$      file specification to process
Ext$       extension to add to files that don't have extensions
-------
FullFile$  processed file specification
ErrCode%   error code

Name  : ExtGet
Class : Memory
Level : BIOS (AT)

This routine allows you to get information from extended memory.  It should
only be used on AT-class computers, since older PCs do not support extended
memory.

You may get up to 32,766 words (just under 64 kilobytes) at a time from a
specified location in extended memory.  The location is specified as the
distance from the start of extended memory, starting at 1 for the first
location.  One word is equivalent to one integer.

See ExtMem for information on extended memory constraints.

   ExtGet DSeg%, DOfs%, Posn&, Words%, ErrCode%

DSeg%       segment of array in which to place data from extended memory
DOfs%       offset of array in which to place data from extended memory
Posn&       location of data in extended memory (starting at 1)
Words%      number of words to transfer (1 integer = 1 word = 2 bytes)
-------
ErrCode%    error code (0 if no error)

Name  : ExtMem
Class : Memory / Equipment
Level : BIOS (AT)

This routine allows you to find out how much extended memory is available.
It should only be used on AT-class computers, since older PCs do not support
extended memory.

The amount of memory returned may be either the total amount of extended
memory installed or just the amount available at this time, depending on how
previously-installed programs (if any) make use of extended memory.
Unfortunately, there is no standard which defines how a program should use
extended memory as there is with EMS (expanded memory), so there is no way
for a program to determine whether or how another program is using extended
memory.  Microsoft is trying to clear up this situation with its HIMEM driver
(available at your local BBS, or [last I looked] free from Microsoft), but
this approach hasn't really become standard yet.

   ExtMem KBytes%

-------
KBytes%     the number of kilobytes of extended memory

Name  : ExtPut
Class : Memory
Level : BIOS (AT)

This routine allows you to put information into extended memory.  It should
only be used on AT-class computers, since older PCs do not support extended
memory.

You may put up to 32,766 words (just under 64 kilobytes) at a time into a
specified location in extended memory.  The location is specified as the
distance from the start of extended memory, starting at 1 for the first
location.  One word is equivalent to one integer.

Note that you can't rely on extended memory being available just because it
exists.  There is no automatic way to determine if another program is also
trying to use the same extended memory.  If in doubt, allow a user-installed
option to enable/disable the use of extended memory by your program.

   ExtPut DSeg%, DOfs%, Posn&, Words%, ErrCode%

DSeg%       segment of data to store in extended memory
DOfs%       offset of data to store in extended memory
Posn&       location to place data in extended memory (starting at 1)
Words%      number of words to transfer (1 integer = 1 word = 2 bytes)
-------
ErrCode%    error code (0 if no error)

Name  : Extract
Class : String
Level : Any

Extract allows you to remove any one of a list of delimited substrings in a
string.  It's useful for input parsing and database work.  You pass it the
string, delimiter, and the number of the desired substring (numbers start at
one).  It returns the starting position of the substring within the string
and the length of the substring (0 if not found).

Just for example, let's assume we have a string as follows:
   St$ = "Thomas G. Hanlin III=3544 E. Southern Ave #104=Mesa, AZ 85204"

If we selected a delimiter of "=" and substring number three, the results
would be "Mesa, AZ 85204".

Note that, unlike ProBas, the PBClone version of this routine will work with
a delimiter of more than one character.  This can be handy for locating
carriage return/linefeed pairs, among other things.

   Extract St$, Delimiter$, SubStrNr%, StartPosn%, SLen%
   SubSt$ = MID$(St$, StartPosn%, SLen%)

St$         string from which to extract
Delimiter$  delimiter between substrings
SubStrNr%   number of the desired substring
-------
StartPosn%  starting position of the substring within the string
SLen%       length of the substring (0 if none)

Name  : FadeOut
Class : Display
Level : Clone

Like CLS, but a bit more fancy, this routine provides an interesting way to
clear the screen.  See also Dissolve.

   FadeOut Attr%

Attr%   color/attribute to which to clear (see CalcAttr)

Name  : FarPeek%
Class : Memory
Level : Clone

This is like the BASIC PEEK function, but expects both a segment and an
offset, thus doing away with the need for DEF SEG.  This is especially handy
for use in subprograms which might otherwise inadvertently change the DEF SEG
value expected by the main program.

   Value% = FarPeek%(DSeg%, DOfs%)

DSeg%    segment of the location to look at
DOfs%    offset of the location to look at
-------
Value%   value at the specified memory location (byte: 0-255)

Name  : FarPoke
Class : Memory
Level : Clone

This is like the BASIC POKE statement, but expects both a segment and an
offset, thus doing away with the need for DEF SEG.  This is especially handy
for use in subprograms which might otherwise inadvertently change the DEF SEG
value expected by the main program.

   FarPoke DSeg%, DOfs%, Value%

DSeg%    segment of the location to look at
DOfs%    offset of the location to look at
Value%   value to store in the specified memory location (byte: 0-255)

Name  : FClose
Class : Disk
Level : DOS

This routine closes a file that was opened by FOpen or FCreate.  It can also
be used to close any of the predefined device handles.

These are the predefined device handles that are always available:

   0    CON     stdin     standard input, normally the keyboard
   1    CON     stdout    standard output, normally the display
   2    CON     stderr    standard error, almost always the display
   3    AUX     stdaux    auxiliary device, generally COM1
   4    PRN     stdprn    standard printer, generally LPT1

If you are running short of handles, you can always close stdaux to free up a
handle.  The stdprn device can also be closed as long as you don't use the
printer or if you only access the printer through LPRINT.  It is not a good
idea to close stdin, stdout, or stderr under normal circumstances.

   FClose Handle%

Handle%    handle of the file to close

Name  : FCreate
Class : Disk
Level : DOS

This routine creates a file and opens it for use by the PBClone file handling
routines.  If the file already existed, it will be wiped out, so you may want
to check beforehand if this is a problem.  Try the Exist routine.

The file is opened in read/write mode, allowing both input and output.

You may create the file using any of the following attributes:

   Normal          0      (nothing special)
   Read Only       1      file can be read, but not written to
   Hidden          2      file is "invisible"
   System          4      special DOS system file

The attributes can be combined by adding them together.  Don't use the System
attribute unless you know what you're doing!

Note that this routine does not support file sharing.  If that is a problem,
close the file just after it is created and reopen it using FOpen.

   FCreate FileName$, Attr%, Handle%, ErrCode%

FileName$  name of the file to create
Attr%      attribute(s) of the file
-------
Handle%    handle by which to access the file (if there was no error)
ErrCode%   error code: 0 if no error, else DOS Error

Name  : FGetLoc
Class : Disk
Level : DOS

This routine tells you the position of the file pointer of a file that was
opened using FOpen or FCreate.  This pointer is used to specify where the
next item should be read from or written to the file.  The first location of
the file is numbered 1.

See also FGetLoc2, the FUNCTION version of this routine.

   FGetLoc Handle%, Posn&

Handle%    handle of the file
-------
Posn&      location of the file pointer

Name  : FGetLoc2&
Class : Disk
Level : DOS

This routine tells you the position of the file pointer of a file that was
opened using FOpen or FCreate.  This pointer is used to specify where the
next item should be read from or written to the file.  The first location of
the file is numbered 1.

See also FGetLoc, the SUB version of this routine.

   Posn& = FGetLoc2&(Handle%)

Handle%    handle of the file
-------
Posn&      location of the file pointer

Name  : FileCopy
Class : Disk
Level : DOS

This routine copies one or more files, just like the DOS command "COPY".

FileCopy differs from the ProBas routine of the same name in that it works
exactly like the DOS COPY command, except it won't append files.  You may use
wildcards in both source and destination file specifications.  Also, rather
than the peculiar error codes returned by the ProBas version, normal DOS
error codes are returned, with two exceptions:
  -2  attempt to copy files over themselves
  -1  attempt to copy multiple source files to a single destination file

See also CopyFile, a simpler routine which doesn't support wildcards.

   FileCopy SrcFile$, DestFile$, FileCount%, ByteCount&, ErrCode%

SrcFile$    source file name(s)
DestFile$   destination file name(s)
-------
FileCount%  number of files copied
ByteCount&  number of bytes copied
ErrCode%    error code (0 if no error)

Name  : FileCRC
Class : Disk
Level : DOS

This routine calculates a 32-bit CRC for a file.  This CRC is derived by a
formula which takes each character of the file into consideration.  It
provides a powerful (although not 100% foolproof) way to verify that a file
hasn't changed since you last checked.

   FileCRC FileName$, Result&, ErrCode%

FileName$   source file name(s)
-------
Result&     32-bit CRC of the file
ErrCode%    error code (0 if no error)

Name  : FindFirstA
Class : Disk
Level : DOS

The FindFirstA routine is used to find the first file that matches search
parameters which you specify.  Various information about the file that
matches (if any) can be retrieved by other routines.

Rather than working on a directory, this routine works on files in an
archive.  Supported archives include ARC, LZH, PAK, and ZIP formats.  If no
extension is given, a search will be made through each valid archive
extension, and the first matching archive will be used for the file search.

Archive names may contain drive and subdirectory specifications, but not
wildcards.  File names may contain wildcards, but not drive/subdir specs.

When you are done searching, be sure to use CloseA to terminate the search.

This routine differs from its ProBas equivalent in that it supports LZH.  It
also will search for any archive if the archive extension is left off, which
ProBas claims to do but doesn't.

Routines in this series include:
   FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA,
   GetSizeAL, GetStoreA

   FindFirstA ArcName$, FileName$, ErrCode%

ArcName$    name of archive to search through
FileName$   name of file(s) for which to search
-------
ErrCode%    error code (0 if no error, else no matching files)

Name  : FindFirstF
Class : Disk
Level : DOS

This is part of a set of routines included for ProBas compatibility.  A
better solution may be found in FindFirstFx.

The FindFirstF routine is used to find the first file that matches search
parameters which you specify.  Various information about the file that
matches (if any) can be retrieved by other routines.  See also FindNextF.

The file name specified may contain a drive and subdirectory specification.
Wildcards are also allowed.

Possible search attributes are as follows:

   Normal          0      (nothing special)
   Hidden          2      file is "invisible"
   System          4      special DOS system file
   Subdirectory   16      subdirectory

You can combine the attributes by adding them together.  All searches will
match if any of the specified attributes are found, so if you're looking only
for a specific attribute, you will need to test the results using GetAttrF.

Routines in this series include:
   FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL

   FindFirstF FileName$, Attr%, ErrCode%

FileName$   name of file(s) for which to search
Attr%       file attribute(s) to seek
-------
ErrCode%    error code (0 if no error, else no matching files)

Name  : FindFirstFx
Class : Disk
Level : DOS

The FindFirstFx routine is used to find the first file that matches search
parameters which you specify.  Various information about the file that
matches (if any) can be retrieved by other routines.

The file name specified may contain a drive and subdirectory specification.
Wildcards are also allowed.

Possible search attributes are as follows:

   Normal          0      (nothing special)
   Read Only       1      file can be read, but not written to
   Hidden          2      file is "invisible"
   System          4      special DOS system file
   Subdirectory   16      subdirectory

You can combine the attributes by adding them together.  All searches will
match if any of the specified attributes are found, so if you're looking only
for a specific attribute, you will need to test the results using GetAttrFx.

Routines in this series include:
   FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$,
   GetSizeFx&

These routines differ from the older FindFirstF-based series in two major
respects.  They include a Buffer$ parameter, which allows you to have more
than one search going on at a time.  This makes it safe to use these routines
in subprograms without conflict with the main program.  It also allows you to
search entire subdirectory trees recursively.  The other major difference is
that many of these routines are coded as functions for greater convenience.
The FindFirstFx series does not exist in the ProBas library.

   Buffer$ = SPACE$(64)
   FindFirstFx Buffer$, FileName$, Attr%, ErrCode%

FileName$   name of file(s) for which to search
Attr%       file attribute(s) to seek
-------
Buffer$     buffer used in search (init to 64 characters)
ErrCode%    error code (0 if no error, else no matching files)

Name  : FindNextA
Class : Disk
Level : DOS

This routine is for use after FindFirstA, to find any additional archived
files which may match your search specifications.

Routines in this series include:
   FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA,
   GetSizeAL, GetStoreA

   FindNextA ErrCode%

-------
ErrCode%    error code (0 if no error, else no matching files)

Name  : FindNextF
Class : Disk
Level : DOS

This routine is for use after FindFirstF, to find any additional files which
may match your search specifications.

Routines in this series include:
   FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL

   FindNextF ErrCode%

-------
ErrCode%    error code (0 if no error, else no matching files)

Name  : FindNextFx
Class : Disk
Level : DOS

This routine is for use after FindFirstFx, to find any additional files which
may match your search specifications.

Routines in this series include:
   FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$,
   GetSizeFx&

This routine does not exist in ProBas.  See FindFirstFx for details.

   FindNextFx Buffer$, ErrCode%

Buffer$     buffer used in search
-------
Buffer$     updated buffer
ErrCode%    error code (0 if no error, else no matching files)

Name  : FindPatch
Class : Disk
Level : DOS

This is one of a set of routines that allow you to write self-modifying code.
Your program can patch DATA statements in itself or in another program,
allowing you to save configuration information (for example) without having
to create additional data files.

In order for this routine to work, you must have a series of DATA statements
containing quoted strings of the maximum desired length.  The first DATA
statement must contain a unique string, as FindPatch will use it to locate
the data block.  Note that if your program is patching itself, you must READ
the unique string rather than assigning it directly, to make sure it's
unique.  The string must exist at only one place in the program.

See the PDEMO.BAS file if you would like clarification.  This little demo
program, when compiled, will patch itself with whatever you enter on the
command line.  For instance, if you type PDEMO Banana, it will store "Banana"
in its DATA statement.  PDEMO will not work in the QuickBASIC environment, of
course.  You must compile it to an .EXE file.

A precompiled version of PDEMO has been included.  It was compiled with
Crescent's PDQ library in addition to PBCLONE and PTCLONE, which makes the
.EXE file much smaller.  It also doesn't capitalize COMMAND$.  You can
recompile PDEMO using the PCREATE.BAT program (PDQ is not required).

You may compile the program using any switches.  You may not use the /EXEPACK
switch for LINK, though, as this may alter the program DATA area.  Likewise,
you must not use compression utilities such as PKLite on the program.

This routine differs from the ProBas ToolKit routine of the same name in that
it does not use the MoveBack% parameter for anything.  It's also much faster
and is not restricted to files smaller than 64K.

Routines in this set include FindPatch, SetPatch, and PatchDone.

   FindPatch FileName$, SearchSt$, MoveBack%, ErrCode%

FileName$     name of the file to patch
SearchSt$     value of the first DATA statement
MoveBack%     not used
-------
ErrCode%      whether the search was successful (0 yes, <0 no, >0 Disk Error)

Name  : Floppies
Class : Equipment / Disk
Level : BIOS

The Floppies routine tells you how many floppy drives are installed (0-4).
See also Floppies2, a function version of this routine.

   Floppies Drives%

-------
Drives%  number of floppy disk drives installed

Name  : Floppies2%
Class : Equipment / Disk
Level : BIOS

The Floppies2 routine tells you how many floppy drives are installed (0-4).

   Drives% = Floppies2%

-------
Drives%  number of floppy disk drives installed

Name  : FlushToDisk
Class : Disk
Level : DOS

This is a "file safety" routine for use with files opened by FOpen or
FCreate.  Files are normally buffered by DOS, which makes file handling
faster but creates the danger of losing the file if there is a crash or power
outage.  By flushing the file to disk, you insure that it is updated to the
current moment.

Note: this routine will need to temporarily create a new file handle if DOS
versions before 4.0 are used.

   FlushToDisk Handle%, ErrCode%

Handle%    handle of the file to flush
-------
ErrCode%   error code: 0 if none, else DOS Error

Name  : FOpen
Class : Disk
Level : DOS

This routine opens an existing file for use with the PBClone file handling
routines.  If you need to create a file that doesn't already exist, use the
FCreate routine instead.

The file may be opened for reading, writing, or both:

   0   Read
   1   Write
   2   Read/Write

You may specify a file sharing mode for use with networks and multitaskers.
This will only take effect if the DOS version is 3.0 or later and if the DOS
SHARE utility has been executed.  Otherwise, it will be ignored.

   0   Normal       compatibility mode: no file sharing permitted
   1   Exclusive    no one else may access the file
   2   Deny Write   no one else may write to the file
   3   Deny Read    no one else may read from the file
   4   Deny None    anyone else may read from or write to the file

Most of the time, "Deny Write" will be appropriate.  This allows others to
read the file, but not to modify the file on you unexpectedly.

See the discussion of predefined device handles at FClose.

   FOpen FileName$, ReadWrite%, Sharing%, Handle%, ErrCode%

FileName$   name of the file to open
ReadWrite%  whether to want to do input, output, or both (see above)
Sharing%    file sharing mode (see above)
-------
Handle%    handle by which to access the file (if there was no error)
ErrCode%   error code: 0 if no error, else DOS Error

Name  : ForceMatch$
Class : Disk
Level : Any

The ForceMatch$ function allows you to mimic DOS commands that operate on
source file(s) and destination file(s).  It forces a source file name to
match a specified pattern (which may contain wildcards), producing an
appropriate destination file name.

For example, if the source is "TESTNAME.BAS" and the pattern is "?RUE*.*",
the result would be "TRUENAME.BAS".

Consider the DOS command "COPY *.BAS A:*.BAK".  The "*.BAK" part is the
desired pattern.  The "*.BAS" part specifies which files to copy to the new
pattern.  Each filename that matches "*.BAS" is translated through the
"*.BAK" pattern to give the destination filename.  The ForceMatch$ function
is designed to do this sort of translation for you.

This routine does not exist in ProBas.

   DestFile$ = ForceMatch$(Pattern$, SrcFile$)

Pattern$   pattern of desired file name (may contain wildcards)
SrcFile$   file name to force through the pattern
-------
DestFile$  resulting file name

Name  : FormatDate
Class : Time
Level : Any

This is a highly flexible date formatting routine.  It accepts a date in one
of the usual American formats ("03-22-1990", "03/22/90", or even "3/22/90")
and converts it according to a format string.  This format string allows you
to normalize the date, select a new delimiter, choose between two-digit and
four-digit years, and even change the order from month/day/year to anything
else.  An error code will be returned if the date is not valid.

The format string can be as simple as "##/##/##", which specifies that the
usual month/day/year order be used, with a delimiter of "/" and a two-digit
year.  If you want to change the date order, you would need a format like
"DD.MM.YYYY" instead.  For sorting or storage, you might want to convert the
date to a plain number, using a format string like "YYYYMMDD".  The result
could then be converted to a LONG with the VAL function provided by BASIC.

The ability to specify the date order, to return undelimited results, and to
accept dates with single-digit month and day values is new to PBClone.  The
ProBas ToolKit does not provide these capabilities.

   FormatDate DateSt$, Format$, Result$, ErrCode%

DateSt$     date to format (month, day, year order)
Format$     format for the date
-------
Result$     resulting date
ErrCode     whether the date is valid (0 ok)

Name  : FSetEnd
Class : Disk
Level : DOS

This moves the file pointer to the end of the file.  It is for use with files
opened by FOpen or FCreate.  The usual purpose for this is to append
information to an existing file.

Note that some text files may have a Control-Z or CHR$(26) on the end.  For
historical reasons, this character is sometimes used as an "end of file"
marker.  When dealing with text files, you may want to examine the last
character of the file to make sure it isn't a Control-Z.

QuickBASIC is among the programs which, unfortunately, put a Control-Z at the
end of a file (if you OPEN for OUTPUT).  This is a bad habit at best.

   FSetEnd Handle%

Handle%    handle of the file

Name  : FSetLoc
Class : Disk
Level : DOS

This moves the file pointer to a specified position in the file.  It is for
use with files opened by FOpen or FCreate.  File positions are considered to
start at 1.

   FSetLoc Handle%, Posn&

Handle%    handle of the file
Posn&      location to which to move

Name  : FSetOfs
Class : Disk
Level : DOS

This moves the file pointer backwards or forwards in the file.  It is for
use with files opened by FOpen or FCreate.

   FSetOfs Handle%, Offset&

Handle%    handle of the file
Offset&    number of bytes by which to move

Name  : FSetRec
Class : Disk
Level : DOS

This sets the file pointer to a specific record in the file.  It is for use
with files opened by FOpen or FCreate.

This routine provides the same function as FSetLoc, but is a bit more
convenient for dealing with files composed of fixed-length records.

   FSetRec Handle%, RecSize%, RecNr%

Handle%    handle of the file
RecSize%   number of bytes per record
RecNr%     number of record (starting at 1)

Name  : FSetSize
Class : Disk
Level : DOS

Many people have asked how to delete information from a file.  Well, there's
no straightforward way to do it most of the time, but if the record is at the
end of the file, you can chop it right off.

This routine can also be used to make a file larger, perhaps pre-allocating
space that will be used later (for better speed).

The file in question must have been opened by FCreate or FOpen.

   FSetSize Handle%, Bytes&

Handle%    handle of the file
Bytes&     desired file size, in bytes

Name  : FSize
Class : Disk
Level : DOS

This routine allows you to get the size of a file that was opened by FOpen or
FCreate.

See also FSize2, the FUNCTION version of this routine.

   FSize Handle%, Bytes&

Handle%    handle of the file
-------
Bytes&     file size, in bytes

Name  : FSize2&
Class : Disk
Level : DOS

This routine allows you to get the size of a file that was opened by FOpen or
FCreate.

See also FSize, the Sub version of this routine.

   Bytes& = FSize2&(Handle%)

Handle%    handle of the file
-------
Bytes&     file size, in bytes