Black Box 4/BlackBox.cdr/progbas/pbclon18.arj/PBCLONE1.MAN

Text File | 1992-05-08 | 142KB | 4,151 lines

Name  : AddMatI              (Add Matrix Integer)
Class : Array management
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
DOfs%      offset of the first array element to add
Elements%  number of array elements to which to add
Value%     value to add to each array element
-------
ErrCode%   error code: 0 if no error

Name  : AddMatL              (Add Matrix Long integer)
Class : Array management
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
DOfs%      offset of the first array element to add
Elements%  number of array elements to which to add
Value&     value to add to each array element
-------
ErrCode%   error code: 0 if no error

Name  : AllExtMem&           (All Extended Memory)
Class : Equipment
Level : Clone (AT)

This routine returns the amount of extended memory installed in
the system, as reported by the power-on self-test (POST)
routine at boot time.  This does not tell you how much extended
memory is actually available, since extended memory may be
carved up by users of BIOS-level extended memory or XMS memory,
converted to expanded memory, etc.  It only tells you the
amount of physical extended memory that is installed.

Do not use this routine on PC/XT machines. It is only for
AT-class computers.

   TotalKb& = AllExtMem&

-------
TotalKb&      kilobytes of extended memory installed

Name  : AltKey               (Alt Key)
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.

   AltKey ASCIICode%, ScanCode%, Ky$

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

Name  : AndSt                (AND String)
Class : String
Level : Any

This routine ANDs each byte in one string with the
corresponding byte in a second string.  The strings must be the
same length.

   AndSt St1$, St2$

St1$      string to AND
St2$      string to AND with
-------
St1$      result

Name  : Any2Dec              (Any to Decimal)
Class : Numeric
Level : Any

This routine converts a number in any base to a normal (base
10) 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%   number base to convert from
-------
DecNr%    resulting integer
ErrCode%  error code: 0 if no error

Name  : AscI%                (ASC Integer)
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 char or -1 if null string

Name  : BarMenu              (Bar Menu)
Class : Input
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.

   BarMenu Pick$(), Row%, LCol%, RCol%, Attr%, HiAttr%, Prompt$

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

Name  : BarMenuM             (Bar Menu with Mouse)
Class : Input, Mouse
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.  Make
sure the mouse cursor is visible before calling this routine!

   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               (Bickel comparison)
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             (Big Print)
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  : BinSeekD             (Binary Seek Double precision)
Class : Array management
Level : Any

This routine uses binary search techniques to locate a specific
number in a sorted double-precision array.  Each number in the
array must be unique (no duplicates) for this to work.  This is
a very, very fast routine and is especially handy for look-up
tables.

The array is expected to begin at element 1.  You may specify
the maximum element to search, allowing use of only part of an
array.

A single number is returned in Posn%.  If Posn% is greater than
zero, the target number was found and Posn% is the position in
the array where it was found.  If Posn% is negative, the target
number was not found, but it could be inserted into the array
at the -Posn% element.  If the number is zero, the target
number was not found and there is no room in the array to add
any more values.

   BinSeekD Array#(), Elements%, Target#, Posn%

Array#()    array of sorted, unique values to search
Elements%   maximum array element to search
Target#     value to look for
-------
Posn%       whether and where the target was found (see above)

Name  : BinSeekI             (Binary Seek Integer)
Class : Array management
Level : Any

This routine uses binary search techniques to locate a specific
number in a sorted integer array.  Each number in the array
must be unique (no duplicates) for this to work.  This is a
very, very fast routine and is especially handy for look-up
tables.

The array is expected to begin at element 1.  You may specify
the maximum element to search, allowing use of only part of an
array.

A single number is returned in Posn%.  If Posn% is greater than
zero, the target number was found and Posn% is the position in
the array where it was found.  If Posn% is negative, the target
number was not found, but it could be inserted into the array
at the -Posn% element.  If the number is zero, the target
number was not found and there is no room in the array to add
any more values.

   BinSeekI Array%(), Elements%, Target%, Posn%

Array%()    array of sorted, unique values to search
Elements%   maximum array element to search
Target%     value to look for
-------
Posn%       whether and where the target was found (see above)

Name  : BinSeekL             (Binary Seek Long integer)
Class : Array management
Level : Any

This routine uses binary search techniques to locate a specific
number in a sorted long integer array.  Each number in the
array must be unique (no duplicates) for this to work.  This is
a very, very fast routine and is especially handy for look-up
tables.

The array is expected to begin at element 1.  You may specify
the maximum element to search, allowing use of only part of an
array.

A single number is returned in Posn%.  If Posn% is greater than
zero, the target number was found and Posn% is the position in
the array where it was found.  If Posn% is negative, the target
number was not found, but it could be inserted into the array
at the -Posn% element.  If the number is zero, the target
number was not found and there is no room in the array to add
any more values.

   BinSeekL Array&(), Elements%, Target&, Posn%

Array&()    array of sorted, unique values to search
Elements%   maximum array element to search
Target&     value to look for
-------
Posn%       whether and where the target was found (see above)

Name  : BinSeekS             (Binary Seek Single precision)
Class : Array management
Level : Any

This routine uses binary search techniques to locate a specific
number in a sorted single-precision array.  Each number in the
array must be unique (no duplicates) for this to work.  This is
a very, very fast routine and is especially handy for look-up
tables.

The array is expected to begin at element 1.  You may specify
the maximum element to search, allowing use of only part of an
array.

A single number is returned in Posn%.  If Posn% is greater than
zero, the target number was found and Posn% is the position in
the array where it was found.  If Posn% is negative, the target
number was not found, but it could be inserted into the array
at the -Posn% element.  If the number is zero, the target
number was not found and there is no room in the array to add
any more values.

   BinSeekS Array!(), Elements%, Target!, Posn%

Array!()    array of sorted, unique values to search
Elements%   maximum array element to search
Target!     value to look for
-------
Posn%       whether and where the target was found (see above)

Name  : BinSeekSt            (Binary Seek String)
Class : Array management
Level : Any

This routine uses binary search techniques to locate a specific
string in a sorted string array.  Each string in the array must
be unique (no duplicates) for this to work.  This is a very,
very fast routine and is especially handy for look-up tables.

The string array is expected to begin at element 1.  You may
specify the maximum element to search, allowing use of only
part of an array.  You must specify whether capitalization
matters-- set CapsCount% to 0 if it doesn't.

A single number is returned in Posn%.  If the number is greater
than zero, the target string was found, and the number is the
position in the array where it was found.  If the number is
negative, the target string was not found, but it could be
inserted into the array at the -Posn% element.  If the number
is zero, the target string was not found and there is no room
in the array to add any more values.

   BinSeekSt Array$(), Elements%, Target$, CapsCount%, Posn%

Array$()    array of sorted, unique values to search
Elements%   maximum array element to search
Target$     string to look for
CapsCount%  0 if capitalization doesn't matter
-------
Posn%       whether and where the target was found (see above)

Name  : BIOSInkey            (BIOS INKEY$)
Class : Input
Level : BIOS

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             (Backward Scroll)
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              (Backspace)
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                (Blink toggle)
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%    use blink (-1) or intense backgrounds (0)

Name  : BlockMove            (Block memory Move)
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&, Dirn%

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)
Dirn%       direction to copy (0 if forward, else backward)

Name  : BootDrive            (get Boot Drive)
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$          (get Boot Drive)
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  : BreakCheck%          (Break key Check)
Class : Input
Level : BIOS

This routine is for use after BreakOff.  It allows you to see
whether the Break key has been pressed since you last checked.
The Break status is cleared after the value is returned.

   Brk% = BreakCheck%
   IF Brk% THEN
      PRINT "** Break key pressed **"
      GOTO EndProgram
   END IF

-------
Brk%    whether Break was pressed (0 no, -1 yes)

Name  : BreakOff             (Break key Off)
Class : Input
Level : BIOS

This routine disables the Break key.  It is not effective in
the QB or QBX environments, as these use their own keyboard
handler.  It is also not effective if your program was compiled
with Debugging on (/D switch).

Note that BreakOff installs a routine to intercept some
interrupt vectors. You MUST use the BreakOffDone routine to
reverse this process before your program ends, or the computer
will be left in an indeterminate state and will probably crash
the next time Break is pressed!

   BreakOff

Name  : BreakOffDone         (Break key Off routine Done)
Class : Input
Level : BIOS

This routine is used after BreakOff to restore the original
interrupt vectors.  If you use BreakOff, you MUST call
BreakOffDone before your program ends!  Otherwise, the computer
will probably crash the next time someone presses Break.

   BreakOffDone

Name  : BSq                  (Blank Squeeze)
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.

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                 (Blank Unsqueeze)
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.

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              (Blank Unsqueeze Length)
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.

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             (Calculate Attribute)
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%           (Calculate Attribute)
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             (Calculate Date)
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 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%   return future result (0) or past (nonzero)
-------
NewDate$     resulting date
ErrCode%     whether the dates are valid (0 yes)

Name  : CalcSize             (Calculate array Size)
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         (Calculate VGA palette Color)
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              (detect 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 (1-4, though BASIC only handles 1-2)
-------
CarrierHigh%  zero if no carrier

Name  : CatchError           (Catch Error from SHELL)
Class : Miscellaneous
Level : Clone

NOTE: You should use the GetError2% function in preference to
this set of routines.

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                (check for CD-ROM)
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 first logical drive (init to >= 1 char)
Drives%       number of logical drives (0 if no CD-ROM)

Name  : CDROM2%              (check for CD-ROM)
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 (0 if no CD-ROM)

Name  : CeilD#               (Ceiling, Double-precision)
Class : String
Level : Any

This function returns the smallest integer greater than or
equal to the number you give it.  This is most often used for
rounding.

   Result# = CeilD#(Nr#)

Nr#          number to process
-------
Result#      result

Name  : CeilS!               (Ceiling, Single-precision)
Class : String
Level : Any

This function returns the smallest integer greater than or
equal to the number you give it.  This is most often used for
rounding.

   Result! = CeilS!(Nr!)

Nr!          number to process
-------
Result!      result

Name  : CheckDate            (Check Date validity)
Class : Time
Level : Any

This routine checks a date to see if it is valid.

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

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

Name  : CheckDisk            (Check Disk readiness)
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.

Results will normally be returned as one of the following,
although not all DOS versions report the exact cause of the
error, in which case the error number may not mean what you
expect.

   0   no error
   1   unformatted disk
   2   open drive door
   3   bad drive spec

   CheckDisk Drive$, ErrCode%

Drive$    letter of the drive to check
-------
ErrCode%  0 if no error, nonzero for error (see above)

Name  : CheckDsk%            (Check Disk readiness)
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             (Check for Key or mouse)
Class : Input, Mouse
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%, LButton%, RButton%

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)
LButton%      whether the left  mouse button was pressed
RButton%      whether the right mouse button was pressed

Name  : CheckKey3            (Check for Key or 3-button mouse)
Class : Input, Mouse
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%, LButton%,
      MButton%, RButton%

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)
LButton%      whether the left   mouse button was pressed
MButton%      whether the middle mouse button was pressed
RButton%      whether the right  mouse button was pressed

Name  : CheckShare           (Check for SHARE)
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%         (Check for SHARE)
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             (calculate 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 CRC1.

   Checksum St$, ChkSum%

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

Name  : Cipher               (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              (Cipher Printable)
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            (Clear a screen Area)
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.

   ClearArea TRow%, LCol%, BRow%, RCol%, Attr%, Fast%

TRow%       top row of area to clear
LCol%       left column of area to clear
BRow%       bottom row of area to clear
RCol%       right column of area to clear
Attr%       color/attribute to clear to
Fast%       whether to use fast displays (0 no)

Name  : Clock                (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             (Clock Settings)
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
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 (0 no)

Name  : CloseA               (Close Archive)
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              (Clear Columns)
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               (Clear to End Of Line)
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               (Clear to End Of Page)
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               (Clear to Start Of Line)
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               (Clear Keyboard buffer)
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               (Clear to Start Of Page)
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             (Copy a File)
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        (CGA Print Screen [SCREEN 1])
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        (CGA Print Screen [SCREEN 2])
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                  (calculate CRC)
Class : String / Serial
Level : Any

This routine has become obsolete; the CRC1 routine is much
faster.  However, CRC is still included for backwards
compatibility.

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  : CRC1                 (calculate 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.

Note that CRC1 does not work like the older CRC routine.  You
should not pad outgoing strings with a STRING$(2, 0) sequence.

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               (Crunch repeated characters)
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              (Control Key)
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 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.

   CtrlKey ASCIICode%, Ky$

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

Name  : CursorInfo           (Cursor Information)
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.  The minimum size will
always be zero, so it is not reported.

   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

Name  : CWindowManager       (CGA Window Manager)
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 delay given in milliseconds (15 works 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 TRow%, LCol%, BRow%, RCol%, Frame%,
      Fore%, Back%, Grow%, Shade%, TFore%, Title$, Fast%

TRow%       top row of window
LCol%       left column of window
BRow%       bottom row of window
RCol%       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 no)

Name  : DataSeg              (Data Segment)
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             (Date to Integer)
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 years)
-------
IntDate%     date compressed into an integer

Name  : DateA2R              (Date Actual to Relative)
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.

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

MonthNr%     month number (1-12)
DayNr%       day number (1-31)
YearNr%      year number (1900 on; years <100 assumed in 1900s)
-------
RelDate&     relative date

Name  : DateN2S              (Date Numbers to String)
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".

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 (see above).

Name  : DateR2A              (Date Relative to Actual)
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.

   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              (Date String to Numbers)
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                 (Direct-to-memory Calendar)
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.  If you supply a null date, the current
date will be used.

   DCal Scrn%(), CalDate$

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

Name  : DCalendar            (Direct-to-memory Calendar)
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.

If you supply a null date, the current date will be used.

   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 (0 no)

Name  : DClear               (Direct-to-memory Clear)
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             (Direct Clear for Specified Size)
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              (Decimal to Any base)
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 >= 16 chars)
NumberLen%  length of the result (-1 if string too short)

Name  : Delay                (Delay for seconds)
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            (Delay for 1/18th seconds)
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               (Delay based on Video timing)
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.

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               (Delete Character)
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              (Delete Line)
Class : Display
Level : BIOS

This routine deletes the specified row from the screen.

   DelLine Row%, Attr%

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

Name  : DelFile              (Delete File)
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               (Delete Subdirectory)
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               (Direct-to-memory File Read)
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%  # of bytes actually read from the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : DFWrite              (Direct-from-memory File Write)
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%  # of bytes actually written to the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : DGClear              (Direct-to-memory Graphics Clear)
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              (Direct-from-memory Get Record)
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 record length (see above).

Name  : DGetScreen           (Direct memory Get Screen image)
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%, TRow%, LCol%, BRow%, RCol%,
      Page%, Fast%

DSeg%      segment of the array in which to store the image
DOfs%      offset of the array in which to store the image
TRow%      top row of the desired screen area
LCol%      left column of the desired screen area
BRow%      bottom row of the desired screen area
RCol%      right column of the desired screen area
Page%      page from which to get the display area
Fast%      whether to use fast mode (0 no)

Name  : DGetSt               (Direct-from-memory Get String)
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 # of chars desired.

Name  : DGQPrint             (Direct Graphics Quick Print)
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            (Direct Graphics Extended Q Print)
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           (Direct Graphics Extended Q Print)
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  : DInput               (Dollar Input)
Class : Input
Level : Clone

This routine provides formatted input of a dollar amount.  You
specify the format and an initial value (may be zero).  You may
also specify whether to allow negation-- if so, the user may
press the "-" key to toggle the number between negative and
positive.  The numeric keypad will automatically be locked into
the numeric state.  Since the decimal point is implicit, the
"." key functions as a delete or backspace operation, for
convenient one-handed data entry and correction.

The dollar amount is kept in a long integer as a number of
pennies, to avoid the possibility of round-off errors which
might result from use of floating point math.  The results are
returned to you both as a long integer and as a formatted
number.

The format string works just like a PRINT USING format string.
Editing is not as flexible as for SInput, but is quite
adequate.  The SInputSet routines will work for DInput as well
as SInput.  The ExitCode% returned is the same as for SInput,
but left and right arrows may also be returned.

   DInput Format$, St&, St$, MinusOk%, Attr%, ExitCode%

Format$    numeric format (just like PRINT USING format)
St&        dollar amount (in pennies)
MinusOk%   whether negation is allowed (0 if no)
Attr%      color/attribute to use (see CalcAttr)
-------
St&        dollar amount (in pennies)
St$        formatted dollar amount
ExitCode%  key used to exit (ASCII code if +, scan code if -)

Name  : DiskStat             (Disk Statistics)
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.

   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, etc)

Name  : Dissolve             (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              (DOS Message Print)
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            (DOS Clear to End Of Line)
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

Name  : DOSCls               (DOS Clear Screen)
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

Name  : DOSColor             (DOS Color)
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.

   DOSColor Fore%, Back%

Fore%    foreground color
Back%    background color

Name  : DOSErrM$             (DOS Error Message)
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             (DOS INKEY$)
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$             (DOS INKEY$)
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 chars/key, like INKEY$)

Name  : DOSInt%              (DOS Interrupt)
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.).

Normally, the CarryFlag% will be set if there is an error, in
which case AX will return the error code.

   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 no error, else code in AX)

Name  : DOSLocate            (DOS Locate)
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.

   DOSLocate Row%, Column%

Row%      row
Column%   column

Name  : DPutRec              (Direct-to-memory Put Record)
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 record length (see above).

Name  : DPutScreen           (Direct-from-memory Put Screen)
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%, TRow%, LCol%, BRow%, RCol%,
      Page%, Fast%

DSeg%      segment of the array from which to restore the image
DOfs%      offset of the array from which to restore the image
TRow%      top row of the desired screen area
LCol%      left column of the desired screen area
BRow%      bottom row of the desired screen area
RCol%      right column of the desired screen area
Page%      page on which to restore the display
Fast%      whether to use fast mode (0 no)

Name  : DPutSt               (Direct-to-memory Put String)
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              (Direct-to-memory Record Deletion)
Class : Array management
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              (Direct-to-mem Record Insertion)
Class : Array management
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             (Direct-to-memory Recolor)
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         (Direct-to-memory Recolor Area)
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%, TRow%, LCol%, BRow%, RCol%, 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
TRow%       top row of area to recolor
LCol%       left column of area to recolor
BRow%       bottom row of area to recolor
RCol%       right column of area to recolor
Attr%       desired color

Name  : DriveSpace&          (Drive Space free)
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 error

Name  : DrvSpaceL            (Drive Space free as Long integer)
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 error

Name  : DrvType              (Drive Type)
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 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             (Direct-from-mem Screen Restore)
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 (0 no)

Name  : DScrSave             (Direct-from-memory Screen Save)
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 (0 no)

Name  : DTR                  (Data Terminal Ready signal)
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 (1-4, though BASIC only handles 1-2)
TurnOn%      whether to raise (turn on) the DTR (0 if no)

Name  : DWindowManager       (Direct-to-memory Window Manager)
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 delay given in milliseconds (15 works 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%, TRow%, LCol%, BRow%, RCol%,
      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
TRow%       top row of window
LCol%       left column of window
BRow%       bottom row of window
RCol%       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          (Direct-to-memory Window Manager)
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%, TRow%, LCol%, BRow%, RCol%,
      Frame%, FSt$, Fore%, Back%, Grow%, Shade%, TFore%, Title$

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
TRow%       top row of window
LCol%       left column of window
BRow%       bottom row of window
RCol%       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          (Direct-to-memory Window Manager)
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          (Direct-to-memory Window Manager)
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%, TRow%, LCol%, BRow%, RCol%,
      Frame%, Attr%

DSeg%       segment of "screen" memory
DOfs%       offset of "screen" memory
TRow%       top row of window
LCol%       left column of window
BRow%       bottom row of window
RCol%       right column of window
Frame%      frame type (see above)
Attr%       frame color/attribute (use CalcAttr)

Name  : DXQPrint             (Direct Extended Quick Print)
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             (EGA Restore for SCREEN 7)
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             (EGA Restore for SCREEN 8)
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             (EGA Restore for SCREEN 9)
Class : Display
Level : Clone

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

   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             (EGA Save for SCREEN 7)
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             (EGA Save for SCREEN 8)
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             (EGA Save for SCREEN 9)
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).

   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              (Elapsed time)
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$         (Elapsed time)
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            (EMS Buffer size)
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             (EMS Close)
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               (EMS Get)
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           result (must be correct type for array)

Name  : EMSOpen              (EMS Open)
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               (EMS Put)
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 store (must be correct type for array)

Name  : EMSRest              (EMS Restore state)
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              (EMS Save state)
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               (Enhanced Keyboard)
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.

   EnhKbd Enable%

Enable%     turn on enhanced keyboard support (0 disable)

Name  : EuropeDate           (European Date format)
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.

   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            (Equipment information)
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      (EGA Window Manager w Char coords)
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 delay given 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 TRow%, LCol%, BRow%, RCol%, Frame%,
      Fore%, Back%, Grow%, Shade%, S1%, S2%, TFore%, Title$

TRow%       top row of window
LCol%       left column of window
BRow%       bottom row of window
RCol%       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                (file Existence)
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%              (file Existence)
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  : ExplainFAttr$        (Explain File Attribute)
Class : Disk
Level : Any

This function returns a string explaining what a file attribute
means, using a specified level of abbreviation.  A single space
is used between each word, e.g. a hidden subdirectory at
abbreviation level 2 would be "Hid Dir".

Abbreviation Levels:
        1           2              3
   ---------------------------------------
 1      R          R-O         Read-Only
 2      H          Hid         Hidden
 4      S          Sys         System
 8      V          Vol         Volume
16      D          Dir         Directory
32      A          Arc         Archive

This function is convenient in conjunction with any of the
routines which return a file attribute: GetAttrF, GetAttrFx,
GetFAttr, LoadDirAll.

   Info$ = ExplainFAttr$(FilAttr%, AbbrevLevel%)

We use FilAttr% instead of FileAttr%, since BASIC has a
built-in FILEATTR function.

FilAttr%      file attribute
-------
AbbrevLevel%  how much to abbreviate the result (1-3)

Name  : EXQPrintC            (EGA Extended Quick Print, Char)
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          (Extend File Specification)
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 ExtendFSpec routine mimics DOS filename handling exactly,
to the best of my knowledge.

   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               (Extended memory Get)
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 to place data from extended memory
DOfs%       offset of array to place data from extended memory
Posn&       location of data in extended memory (starting at 1)
Words%      # of words to transfer (1 int = 1 word = 2 byte)
-------
ErrCode%    error code (0 if no error)

Name  : ExtMem               (Extended Memory)
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               (Extended memory Put)
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
Words%      # of words to transfer (1 int = 1 word = 2 bytes)
-------
ErrCode%    error code (0 if no error)

Name  : Extract              (Extract delimited substring)
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$ = "Tom Hanlin=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".

Delimiters of more than one character are fine.  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 substring within the string
SLen%       length of the substring (0 if none)

Name  : FadeOut              (Fade Out)
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%             (Far memory Peek)
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%)

Related routines include FarPeekI%, FarPeekL&, DGetSt, DGetRec.

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  : FarPeekI%            (Far memory Peek Integer)
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.  Unlike PEEK, this routine returns a word
(integer) rather than a byte.

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

Related routines include FarPeek%, FarPeekL&, DGetSt, DGetRec.

DSeg%    segment of the location to look at
DOfs%    offset of the location to look at
-------
Value%   value at the specified memory location (word)

Name  : FarPeekL&            (Far memory Peek Long integer)
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.  Unlike PEEK, this routine returns a dword
(long integer) rather than a byte.

   Value& = FarPeekL&(DSeg%, DOfs%)

Related routines include FarPeek%, FarPeekI%, DGetSt, DGetRec.

DSeg%    segment of the location to look at
DOfs%    offset of the location to look at
-------
Value&   value at the specified memory location (dword)

Name  : FarPoke              (Far memory Poke)
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%

Related routines include FarPokeI, FarPokeL, DPutSt, DPutRec.

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

Name  : FarPokeI             (Far memory Poke Integer)
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.  Unlike POKE, this routine stores a word
or integer.

   FarPokeI DSeg%, DOfs%, Value%

Related routines include FarPoke, FarPokeL, DPutSt, DPutRec.

DSeg%    segment of the location to look at
DOfs%    offset of the location to look at
Value%   value to store in the given memory posn (word)

Name  : FarPokeL             (Far memory Poke Long integer)
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.  Unlike POKE, this routine stores a dword
or long integer.

   FarPokeL DSeg%, DOfs%, Value&

Related routines include FarPoke, FarPokeI, DPutSt, DPutRec.

DSeg%    segment of the location to look at
DOfs%    offset of the location to look at
Value&   value to store in the given memory posn (dword)

Name  : FClose               (File Close)
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 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              (File Create)
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 no error)
ErrCode%   error code: 0 if no error, else DOS Error

Name  : FGetLoc              (File Get Location)
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&            (File Get Location)
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             (File Copy)
Class : Disk
Level : DOS

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

FileCopy works exactly like the DOS COPY command, except it
won't append files.  You may use wildcards in both source and
destination file specifications.  In the event of an error,
normal DOS error codes are returned, with two exceptions:

  -2  attempt to copy files over themselves
  -1  attempt to copy multiple sources to a single dest file

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

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

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

Name  : FileCount            (File Count)
Class : Disk
Level : DOS

This routine returns the number of files which match a given
file specification and attribute.  You need to use this routine
before LoadDir or LoadDirAll in order to DIM the array to the
appropriate size.

The attribute can be any of the usual file attributes:
   1   Read-Only
   2   Hidden
   4   System
  16   Directory

You can combine attributes by adding their values.  For
instance, to search for hidden directories, you'd use an
attribute of 18.  By default, DOS returns normal files as well
as files which have the specified attributes, so an attribute
of 18 would get you normal files, hidden files, directories,
and hidden directories.  However, FileCount can be made to
screen out unwanted files-- just negate the attribute to force
only files of that attribute to be counted.  For example, an
attribute of -18 would return only hidden subdirectories.

   FileCount FileSpec$, FilAttr%, Count%, ErrCode%

We use FilAttr% instead of FileAttr%, since BASIC has a
built-in FILEATTR function.

FileSpec$   search filename (may contain wildcards)
FilAttr%    search file attribute
-------
Count%      number of matching files found
ErrCode%    error code (0 if no error)

Name  : FileCRC              (File CRC)
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           (Find First file in an Archive)
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, ARJ, LZH, PAK,
ZIP and ZOO 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.

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           (Find First File)
Class : Disk
Level : DOS

This is part of a set of routines included for compatibility
with ADVBAS and ProBas.  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          (Find First File, Extended)
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.

   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            (Find Next file in an Archive)
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            (Find Next File)
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           (Find Next File, Extended)
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&

   FindNextFx Buffer$, ErrCode%

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

Name  : FindPatch            (Find Patch location)
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,
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.

Routines in this set include FindPatch, SetPatch, PatchDone.

   FindPatch FileName$, SearchSt$, ErrCode%

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

Name  : FloorD#              (Floor, Double-precision)
Class : String
Level : Any

This function returns the largest integer less than or equal to
the number you give it.  This is most often used for rounding.

   Result# = FloorD#(Nr#)

Nr#          number to process
-------
Result#      result

Name  : FloorS!              (Floor, Single-precision)
Class : String
Level : Any

This function returns the largest integer less than or equal to
the number you give it.  This is most often used for rounding.

   Result! = FloorS!(Nr!)

Nr!          number to process
-------
Result!      result

Name  : Floppies             (Floppies installed)
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%           (Floppies installed)
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  : FloppyType           (Floppy drive Type)
Class : Equipment / Disk
Level : Clone (AT)

This routine tells you what kinds of floppy drives are
installed, if any.  A code is returned for each drive, as
follows:

   0    no drive
   1    5 1/4"    360K
   2    5 1/4"    1.2M
   3    3 1/2"    720K
   4    3 1/2"    1.44M

Result codes of 5-7 are available, but not yet defined.  One
might guess that the 2.88M drive supported by DOS 5.0 will be
drive type 5.

Note that this routine supports a maximum of only two drives.
It is possible for a machine to have up to four drives, but
there is not currently any good way to find out about them.

FloppyType should only be used on AT-class machines.  It will
not work on PC/XT computers and may cause unusual results if
used on such machines.  It will also not work on some of the
earliest AT machines, which didn't adhere to the standard CMOS
format.

   FloppyType DriveA%, DriveB%

-------
DriveA%    drive type of first floppy drive
DriveB%    drive type of second floppy drive

Name  : FlushToDisk          (Flush file buffers To Disk)
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                (File Open)
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
   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 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 you want input, output, or both (see above)
Sharing%    file sharing mode (see above)
-------
Handle%    handle by which to access the file (if no error)
ErrCode%   error code: 0 if no error, else DOS Error

Name  : ForceMatch$          (Force Match of file to wildcard)
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.

   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           (Format Date)
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 BASIC VAL
function.

   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              (File Set to End)
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              (File Set Location to byte)
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              (File Set location by Offset)
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              (File Set location to Record)
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             (File Set Size)
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                (File get Size)
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&              (File get Size)
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