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

Text File | 1992-05-08 | 198KB | 6,258 lines

Name  : Get4DOSv             (Get 4DOS Version)
Class : Equipment
Level : DOS

The Get4DOSv routine returns the version of 4DOS being used.
It returns the results as two integers containing the major and
minor version numbers. For instance, 4DOS 4.0 would return a
major number of 4, minor 0.  If 4DOS is not installed, both
version numbers will be zero.

If you're not familiar with 4DOS, it's a terrific improved
replacement for COMMAND.COM.  For more information, write JP
Software Inc., P.O. Box 1470, Arlington MA 02174, or call your
local BBS.

   Get4DOSv MajorV%, MinorV%

-------
MajorV%   major part of the 4DOS version
MinorV%   minor part of the 4DOS version

Name  : GetAttrF             (Get Attribute of File)
Class : Disk
Level : DOS

The GetAttrF routine returns the attributes of a file matched
by FindFirstF or FindNextF.

   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
   Archive        32      (used by some backup utilities)

You can see if a certain value is set using the AND operator:

   IF Attr% AND 16 THEN PRINT "Subdirectory"

Since the values are all powers of two, the AND operator makes
for a convenient way of decoding the results.

See also the ExplainFAttr$ function, which decodes the meanings
of the attribute for you.

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

   GetAttrF Attr%

-------
Attr%   attributes that are set

Name  : GetAttrFx%           (Get Attribute of File, Extended)
Class : Disk
Level : DOS

The GetAttrFx% function returns the attributes of a file
matched by FindFirstFx or FindNextFx.

   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
   Archive        32      (used by some backup utilities)

You can see if a certain value is set using the AND operator:

   IF Attr% AND 16 THEN PRINT "Subdirectory"

Since the values are all powers of two, the AND operator makes
for a convenient way of decoding the results.

See also the ExplainFAttr$ function, which decodes the meanings
of the attribute for you.

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

   Attr% = GetAttrFx%(Buffer$)

Buffer$   buffer used in search
-------
Attr%     file attributes

Name  : GetColor             (Get Color)
Class : Display
Level : Clone

This routine tells you the current default foreground and
background colors being used by BASIC.  It should be used only
in text modes.

   GetColor Foreground%, Background%

-------
Foreground%   foreground color
Background%   background color

Name  : GetCommAddr          (Get Comm Address)
Class : Serial
Level : Clone

This routine allows you to determine the base port address of a
serial port. You tell it the COM port number (1-4) and it
returns the port address.  If there is no port installed, zero
will be returned.

Note that ports are "supposed" to be assigned sequentially-- in
other words, if you find a "zero" port address, there will be
no ports after that.  This is not necessarily the case,
however.  Some semi-standard machines may have a COM2 without a
COM1, for instance.  QuickBASIC gets confused in that case, but
it's no problem with my PBClone or BasWiz libraries.

Aside from purely informational purposes, this routine can be
useful in conjunction with SetCommAddr in manipulating the
serial ports.

   GetCommAddr PortNr%, PortAddr%

PortNr%     COM port number (1-4)
-------
PortAddr%   port address

Name  : GetCRCA              (Get CRC of Archive file)
Class : Disk / Time
Level : DOS

GetCRCA returns the 16-bit CRC of an archived file matched by
the FindFirstA or FindNextA routines.  Since some archives use
32-bit CRCs, you may wish to use the more generic version of
this routine, GetCRCAL.

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

   GetCRCA CRC16%

-------
CRC16%     16-bit CRC

Name  : GetCRCAL             (Get CRC of Archive file as Long)
Class : Disk / Time
Level : DOS

GetCRCAL returns the 32-bit CRC of an archived file matched by
the FindFirstA or FindNextA routines.  If the archive only has
a 16-bit CRC, the result is converted to 32 bits, so this
routine works with all archives.

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

   GetCRCAL CRC32%

-------
CRC32%     32-bit CRC

Name  : GetCRT               (Get CRT)
Class : Display / Equipment
Level : Clone

The GetCRT routine simply tells you whether the current display
is capable of handling colors or not.  An unsophisticated
routine, GetCRT assumes that if the display is an MDA/Hercules,
it can't do color, but otherwise it can.

See also GetEGA, GetHGA and GetVGA.

   GetCRT Colour%

-------
Colour%   whether the display is color (0 if no)

Name  : GetCRT2%             (Get CRT)
Class : Display / Equipment
Level : Clone

The GetCRT2 routine simply tells you whether the current
display is capable of handling colors or not.  An
unsophisticated routine, GetCRT2 assumes that if the display is
an MDA/Hercules, it can't do color, but otherwise it can.

See also GetEGA, GetHGA and GetVGA.

   Colour% = GetCRT%

-------
Colour%   whether the display is color (0 if no)

Name  : GetDateA             (Get Date of Archive file)
Class : Disk / Time
Level : DOS

GetDateA returns the date of a archived file matched by the
FindFirstA or FindNextA routines.

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

   GetDateA MonthNr%, Day%, Year%

-------
MonthNr%    month
Day%        day
Year%       year

Name  : GetDateAT            (Get Date from AT clock)
Class : Time
Level : BIOS (AT)

This routine gets the date from the hardware real-time clock in
AT-class computers.  Depending on the DOS version, this date
may be partially or completely independent of the date kept by
DOS in software.  DOS always reads the date from the hardware
clock when it starts up.  However, use of the DATE command in
DOS (and the DATE$ function in QuickBASIC) may relate only to
the software copy of the date, which is not always guaranteed
to be the same as the date in the hardware clock due to certain
discrepancies in DOS.

   GetDateAT MonthNr%, Day%, Year%, ErrCode%

-------
MonthNr%     month number (1-12)
Day%         day (1-31)
Year%        year (1980-2079)
ErrCode%     error code: 0 if no error, else clock has stopped

Name  : GetDateF             (Get Date of File)
Class : Disk / Time
Level : DOS

The GetDateF routine returns the date of a file matched by
FindFirstF or FindNextF.

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

   GetDateF MonthNr%, Day%, Year%

-------
MonthNr%    month
Day%        day
Year%       year

Name  : GetDateFx$           (Get Date of File, Extended)
Class : Disk / Time
Level : DOS

The GetDateFx$ function returns the date of a file matched by
FindFirstFx or FindNextFx.

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

   FileDate$ = GetDateFx$(Buffer$)

Buffer$     buffer used in search
-------
FileDate$   date of file (e.g., "02-28-1991")

Name  : GetDOSv              (Get DOS Version)
Class : Equipment
Level : DOS

The GetDOSv routine tells you what version of DOS you're
using.  It returns the results as two integers containing the
major and minor version numbers. For instance, MS-DOS 2.11
would return a major number of 2, minor 11.

The OS/2 compatibility box returns version numbers beginning at
10.00.  For instance, OS/2 v1.1 returns 10.10 and OS/2 v2.0
returns 20.00.

   GetDOSv MajorV%, MinorV%

-------
MajorV%   major part of the DOS version
MinorV%   minor part of the DOS version

Name  : GetDrive$            (Get default Drive)
Class : Disk
Level : DOS

This routine tells you the letter of the current default drive.

See also GetDrv, the SUB version of this routine.

   Drive$ = GetDrive$

-------
Drive$    default drive letter.

Name  : GetDrv               (Get default Drive)
Class : Disk
Level : DOS

This routine tells you the letter of the current default drive.

See also GetDrive, the FUNCTION version of this routine.

   Drive$ = "x"
   GetDrv Drive$

-------
Drive$    default drive letter.  Init to at least one character.

Name  : GetDView             (Get DESQview version)
Class : Miscellaneous
Level : DOS

The GetDView routine tells you what version of DESQview is
loaded.  It returns the results as two integers containing the
major and minor version numbers.  For instance, DESQview 2.0
would return a major number of 2 and a minor number of 0.  If
DESQview is not loaded, zeroes are returned.

See also GetTView, GetTVScreen, UpdTVScreen.

   GetDView MajorV%, MinorV%

-------
MajorV%   major part of the DESQview version (0 if no DESQview)
MinorV%   minor part of the DESQview version

Name  : GetEGA               (Get EGA information)
Class : Display / Equipment
Level : BIOS

This routine tells you whether an EGA (or VGA) is available,
and if so, what kind.  It tells you whether the attached
display is monochrome or color, and how many kilobytes of RAM
are installed in the adapter.

Many early EGAs had only 64K of RAM.  Current adapters have
256K or more. Since there are some limitations attached to
having only 64K, it's a good idea to see if this is the case--
most PBClone EGA routines won't work properly on 64k adapters.

See also GetCRT, GetHGA and GetVGA.

See also GetEGA2, the FUNCTION version of this routine.

   GetEGA Display%, KBytes%

-------
Display%  EGA display type: 0 no EGA, 1 EGA color, 2 EGA mono
KBytes%   kilobytes of display memory

Name  : GetEGA2%             (Get EGA information)
Class : Display / Equipment
Level : BIOS

This routine tells you whether an EGA (or VGA) is available.

See also GetCRT2, GetHGA and GetVGA2.

See also GetEGA, the SUB version of this routine.  It returns
additional information.

   IsEGA% = GetEGA2%

-------
IsEGA%    whether the display is an EGA (0 if no)

Name  : GetError             (Get Error code from DOS)
Class : Miscellaneous
Level : Clone

NOTE: The GetError2% function should be used in preference to
this routine.

The GetError routine is used in conjunction with CatchError.
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 CatchError.

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%

-------
ExitCode%   exit code returned by SHELLed-to program (0-255)

Name  : GetError2%           (Get Error code from DOS)
Class : Miscellaneous
Level : DOS

The GetError2% function gets the exit code (error level)
returned by a program to which you have SHELLed.  It should be
used as soon as possible after the SHELL, and its value will
only be meaningful on the first call after the SHELL.

This routine should be used in preference to CatchError and
GetError.

   SHELL ProgramName$
   ExitCode% = GetError2%

-------
ExitCode%   exit code returned by SHELLed-to program (0-255)

Name  : GetExecPath          (Get Execution Path of program)
Class : Disk
Level : DOS 3.0+

This routine returns the full path of your program, i.e., the
drive, subdirectory, and name of the program.  It does not rely
on the current drive and subdirectory settings or look at the
PATH setting-- DOS tells it directly.  This makes it an
excellent way to find the program's "home" directory, where
(hopefully) any data files associated with the program will
also be stored.

   SelfName$ = SPACE$(80)
   GetExecPath SelfName$, SelfLen%
   SelfName$ = LEFT$(SelfName$, SelfLen%)

-------
SelfName$   full path for current program.  Init to 80+ chars.
SelfLen%    length of the full path spec.

Name  : GetExtM              (Get 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.  Note that some of
the very early AT machines will return erroneous results.

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.

   GetExtM KBytes%

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

Name  : GetFAttr             (Get File Attribute)
Class : Disk
Level : DOS

This routine lets you read the attributes of a file or
subdirectory.  The attributes may contain a combination of any
of the following:

   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
   Archive        32      (used by some backup utilities)

You can see if a certain value is set by using the AND operator:

   IF Attr% AND 2 THEN PRINT "Hidden file"

Since the values are all powers of two, the AND operator makes
for a convenient way of decoding the results.

See also the ExplainFAttr$ function, which decodes the meanings
of the attribute for you.

   GetFAttr FileName$, Attr%

FileName$   name of the file (or subdirectory) to examine
-------
Attr%       attributes that are set

Name  : GetFDate             (Get File Date)
Class : Disk / Time
Level : DOS

This routine gets the date of a file.

   GetFDate FileName$, MonthNr%, Day%, Year%

FileName$   name of the file to examine
-------
MonthNr%    month
Day%        day
Year%       year

Name  : GetFSize             (Get File Size)
Class : Disk
Level : DOS

This function gets the size of a file.

   FileSize& = GetFSize&(FileName$)

FileName$   name of the file to examine
-------
FileSize&   size of the file, in bytes

Name  : GetFTime             (Get File Time)
Class : Disk / Time
Level : DOS

This routine gets the time of a file.

   GetFTime FileName$, Hour%, Minute%, Second%

FileName$   name of the file to examine
-------
Hour%       hour
Minute%     minute
Second%     second (always even, due to DOS storage techniques)

Name  : GetHGA%              (Get Hercules Adapter info)
Class : Display / Equipment
Level : Clone

This routine tells you whether a Hercules-compatible monochrome
graphics adapter is in use.

See also GetCRT2, GetEGA and GetVGA2.

   IsHGA% = GetHGA%

-------
IsHGA%    whether the display is Hercules mono graphics (0 no)

Name  : GetKbd               (Get Keyboard toggles)
Class : Input
Level : Clone

The GetKbd routine allows you to get the state of the four
keyboard toggles: Insert, Caps lock, Num lock, and Scroll Lock.

   GetKbd Insert%, Caps%, Num%, Scrl%

-------
Insert%    whether "insert" mode is on (0 if no)
Caps%      whether "caps lock" is on (0 if no)
Num%       whether "num lock" is on (0 if no)
Scrl%      whether "scroll lock" is on (0 if no)

Name  : GetKbd1              (Get Keyboard Shifts)
Class : Input
Level : Clone

The GetKbd1 routine allows you to get the state of the four
keyboard shift keys: Left shift, Right shift, Control and Alt.

   GetKbd1 LShift%, RShift%, Control%, Alt%

-------
LShift%    whether the left shift key is depressed (0 if no)
RShift%    whether the right shift key is depressed (0 if no)
Control%   whether a control key is depressed (0 if no)
Alt%       whether an alt key is depressed (0 if no)

Name  : GetKbd2              (Get Keyboard Shifts)
Class : Input
Level : AT BIOS

The GetKbd2 routine allows you to get the state of the six
keyboard shift keys on an "enhanced" keyboard: Left shift,
Right shift, Left Control, Right Control, Left Alt and Right
Alt.

Normally, the BIOS only lets you see one key at a time, which
can be a barrier when you need more input.  This is a
particular problem with action games and other real-time
applications which have complex input requirements. Due to the
special way the BIOS treats shift keys, GetKbd2 can tell if the
the various shift keys are pressed simultaneously, allowing
more flexibility.

   GetKbd2 LShift%, RShift%, LCtrl%, RCtrl%, LAlt%, RAlt%

-------
LShift%    whether the left shift key is depressed (0 if no)
RShift%    whether the right shift key is depressed (0 if no)
LCtrl%     whether the left control key is depressed (0 if no)
RCtrl%     whether the right control key is depressed (0 if no)
LAlt%      whether the left alt key is depressed (0 if no)
RAlt%      whether the right alt key is depressed (0 if no)

Name  : GetKey               (Get Key or mouse)
Class : Input, Mouse
Level : BIOS

This routine is kind of an extended version of INPUT$.  It
waits until a key is available at the keyboard and returns the
key pressed.  At your option, it can also return if a mouse
button is pressed.

   GetKey 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  : GetKey3              (Get Key or 3-button mouse)
Class : Input, Mouse
Level : BIOS

This routine is kind of an extended version of INPUT$.  It
waits until a key is available at the keyboard and returns the
key pressed.  At your option, it can also return if a mouse
button is pressed.

   GetKey3 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 is pressed
MButton%      whether the middle mouse button is pressed
RButton%      whether the right  mouse button is pressed

Name  : GetLabel             (Get disk volume Label)
Class : Disk
Level : DOS

This routine gets the volume label from a specified drive.  See
also GetLabel2$.

   Label$ = SPACE$(11)
   GetLabel Drive$, Label$, LabelLen%, ErrCode%
   Label$ = LEFT$(Label$, LabelLen%)

Drive$     letter of the drive to examine
-------
Label$     volume label of drive.  Init to >= 11 chars.
LabelLen%  length of the volume label
ErrCode%   error code: 0 if no error, else DOS Error

Name  : GetLabel2$           (Get disk volume Label)
Class : Disk
Level : DOS

This routine gets the volume label from a specified drive.  See
also GetLabel, a subprogram version of this routine.  The
GetLabel subprogram is preferable in that it returns an error
code, but you may find the function version more convenient if
error checking is not desired.

   Label$ = GetLabel2$(Drive$)

Drive$     letter of the drive to examine
-------
Label$     volume label of the specified drive.

Name  : GetLIMHandles        (Get L/I/M expanded mem Handles)
Class : Memory
Level : DOS

Early Lotus/Intel/Microsoft expanded memory revisions provided
a limited number of "handles" which could be used to access
expanded memory-- often as few as 15 or so.  If your program
uses expanded memory and the EMS driver is one of the older
versions, you may want to make sure that enough handles are
available.  This routine tells you how many handles are in use.

Note that this routine expects an EMS driver to be installed.
If you can't be sure of that, use GetLIMM first to avoid an
unpleasant surprise.

   GetLIMHandles Handles%

-------
Handles%  number of EMS handles in use

Name  : GetLIMM              (Get L/I/M expanded Memory)
Class : Memory / Equipment
Level : DOS

This routine tells you how much expanded memory is installed.
If there is none, or if the EMS driver hasn't been installed,
it returns zeroes.  You should use this routine before any
other of the PBClone routines that access expanded memory,
since the other routines expect EMS to be available.

The results are returned in terms of EMS pages.  Each page is
16 kilobytes.

   GetLIMM TotalPages%, FreePages%

-------
TotalPages%  number of EMS pages installed
FreePages%   number of EMS pages available for use

Name  : GetLIMV              (Get L/I/M expanded mem Version)
Class : Memory / Equipment
Level : DOS

The GetLIMV routine tells you the version of EMS driver that is
being used. The version number is separated into major and
minor parts.  For example, an EMS 3.1 driver would return a
major number of 3 and minor number of 1.

Note that this routine expects an EMS driver to be installed.
If you can't be sure of that, use GetLIMM first to avoid an
unpleasant surprise.

   GetLIMV MajorVer%, MinorVer%

-------
MajorVer%  major part of the EMS version number
MinorVer%  minor part of the EMS version number

Name  : GetLine              (Get Line of text)
Class : Display
Level : Any

This routine retrieves a row of text from a saved (or virtual)
screen.

You can use GetLine with a saved screen of any size.  The St$
parameter must be initialized to the width of the saved screen
(in columns).

   St$ = SPACE$(ScrWidth)
   GetLine DSeg%, DOfs%, Row%, St$, SLen%
   St$ = LEFT$(St$, SLen%)

DSeg%      segment of saved screen
DOfs%      offset of saved screen
Row%       row of saved screen (starting at 1)
-------
St$        text at given row (init to width of saved screen)
SLen       logical length of text

Name  : GetMouseLoc          (Get Mouse Location)
Class : Mouse
Level : BIOS

This routine allows you to get the current location of the
mouse cursor.  It doesn't matter if the cursor is visible or
invisible.  GetMouseLoc is only for use in text mode.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

See also MMGetLoc, which returns the coordinates for graphics
mode.

   GetMouseLoc Row%, Column%

-------
Row%       mouse cursor row
Column%    mouse cursor column

Name  : GetNameA             (Get Name of file in Archive)
Class : Disk
Level : DOS

GetNameA returns the name of an archived file matched by the
FindFirstA or FindNextA routines.  Since some archives may
include subdirectory specs along with the file name, it is
recommended that you initialize the return string to 80
characters (at least 12 are required).

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

   FileName$ = SPACE$(80)
   GetNameA FileName$, NameLen%
   FileName$ = LEFT$(FileName$, NameLen%)

-------
FileName$   file name (init to >= 12 characters, preferably 80)
NameLen%    length of file name

Name  : GetNameF             (Get Name of File)
Class : Disk
Level : DOS

The GetNameF routine returns the name of a file matched by
FindFirstF or FindNextF.  The name will not contain a drive or
subdirectory specification.

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

   FileName$ = SPACE$(12)
   GetNameF FileName$, NameLen%
   FileName$ = LEFT$(FileName$, NameLen%)

-------
FileName$   file name (init to at least 12 characters)
NameLen%    length of file name

Name  : GetNameFx$           (Get Name of File, Extended)
Class : Disk
Level : DOS

The GetNameFx$ function returns the name of a file matched by
FindFirstFx or FindNextFx.  The name will not contain a drive
or subdirectory specification.

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

   FileName$ = GetNameFx$(Buffer$)

Buffer$       buffer used in search
-------
FileName$     file name

Name  : GetPrtAddr           (Get Printer Address)
Class : Printer
Level : Clone

This routine allows you to determine the base port address of a
parallel port.  You tell it the LPT port number (1-4) and it
returns the port address. If there is no port installed, zero
will be returned.

Note that up to four printer ports are (theoretically)
supported on most machines.  On PS/2 computers, only three
ports are allowed, and the fourth port data area is used for
other purposes.  So, it would probably be a good idea to
restrict your program to ports 1-3.

Aside from purely informational purposes, this routine can be
useful in conjunction with SetPrtAddr in manipulating the
parallel ports.

   GetPrtAddr PortNr%, PortAddr%

PortNr%     LPT port number (1-4 or 1-3 [see above])
-------
PortAddr%   port address

Name  : GetRows              (Get Rows on screen)
Class : Display
Level : Clone

This routine tells you how many rows are on the display.  This
is normally 25, but it may be greater on an EGA or VGA.  Only
text modes are supported.

   GetRows Rows%

-------
Rows%    text rows on the display

Name  : GetRows2%            (Get Rows on screen)
Class : Display
Level : Clone

This routine tells you how many rows are on the display.  This
is normally 25, but it may be greater on an EGA or VGA.  Only
text modes are supported.

   Rows% = GetRows2%

-------
Rows%    text rows on the display

Name  : GetScreen            (Get Screen)
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).

If you wish to save the entire screen, you may find ScrSave
easier (see).

   GetScreen Array%(), TRow%, LCol%, BRow%, RCol%, Page%, Fast%

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)
-------
Array%()   stored image of the selected area of the screen

Name  : GetSerial$           (Get disk Serial number)
Class : Disk
Level : DOS 4.0+

The GetSerial function returns the serial number of the
specified disk.  If there is no serial number, it returns
"0000-0000".

   SerialNr$ = GetSerial$(Drive$)

Drive$       drive to get serial # from ("" for current drive)
-------
SerialNr$    serial number of the specified drive

Name  : GetSizeAL            (Get Size of file in Archive Long)
Class : Disk
Level : DOS

GetSizeAL returns the size of an archived file matched by the
FindFirstA or FindNextA routines.

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

   GetSizeAL OrigSize&, CurrSize&

-------
OrigSize&    original (uncompressed) file size
CurrSize&    current (compressed) file size

Name  : GetSizeFL            (Get Size of File as Long)
Class : Disk
Level : DOS

The GetSizeFL routine returns the size of a file matched by
FindFirstF or FindNextF.

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

   GetSizeFL FileSize&

-------
FileSize&   file size

Name  : GetSizeFx&           (Get Size of File, Extended)
Class : Disk
Level : DOS

The GetSizeFx& function returns the size of a file matched by
FindFirstFx or FindNextFx.

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

   FileSize& = GetSizeFx&(Buffer$)

Buffer$     buffer used in search
-------
FileSize&   file size

Name  : GetStoreA            (Get Storage of file in Archive)
Class : Disk / Time
Level : DOS

GetStoreA returns the method used to compress an archived file
matched by the FindFirstA or FindNextA routines.

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

   Storage$ = SPACE$(8)
   GetStoreA Storage$

-------
Storage$    storage method (init to 8 characters)

Name  : GetSub               (Get default Subdirectory)
Class : Disk
Level : DOS

The GetSub routine gets the current subdirectory on the default
drive.  It does not put a backslash at the start of the
subdirectory, so you should add this yourself.

See also GetSub1, which is a more advanced version of this
routine.

   SubDir$ = SPACE$(64)
   GetSub SubDir$, SubLen%
   SubDir$ = "\" + LEFT$(SubDir$, SubLen%)

-------
SubDir$    name of the current subdirectory. Init to 64+ chars
SubLen%    length of the subdirectory name

Name  : GetSub1              (Get default Subdirectory)
Class : Disk
Level : DOS

The GetSub1 routine gets the current subdirectory on a
specified drive. Unlike GetSub, it places a backslash at the
start of the name.  It also returns an error code, which allows
you to see if there was a disk error.

If you don't care about the error code, you may prefer GetSub2,
the FUNCTION version of this routine.

   SubDir$ = SPACE$(65)
   GetSub1 Drive$, SubDir$, SubLen%, ErrCode%
   SubDir$ = LEFT$(SubDir$, SubLen%)

Drive$     letter of the drive to check
-------
SubDir$    name of the current subdirectory. Init to 65+ chars
SubLen%    length of the subdirectory name
ErrCode%   error code: 0 if no error, else DOS Error

Name  : GetSub2$             (Get default Subdirectory)
Class : Disk
Level : DOS

The GetSub2 routine gets the current subdirectory on a
specified drive. Unlike GetSub, it places a backslash at the
start of the name.

See also GetSub1, the SUB version of this routine.  It returns
an error code.

If you just want the subdirectory of the current drive, you can
use a null string ("") as the drive letter.

   SubDir$ = GetSub2$(Drive$)

Drive$     letter of the drive to check
-------
SubDir$    name of the current subdirectory. Init to 65+ chars

Name  : GetSwitch            (Get Switch character)
Class : Miscellaneous
Level : DOS

An undocumented capability in many DOS versions allows you to
set the DOS "switch character", which is the delimiter used to
identify a switch on the DOS command line.  This is normally a
slash, as in "DIR /W".  However, many people prefer to change
it to a "-", which is the switch character used by Unix.

With the normal "/" delimiter, a backslash "\" is used in
subdirectory specifications.  DOS itself will recognize either
one as a subdirectory delimiter, but the command line won't
unless the switch char was changed.

The upshot of all this is, whereas you might normally use a
command like:
   DIR /W C:\GAMES

Someone with a different switch character might use something
like this:
   DIR -W C:/GAMES

This is exactly the sort of syntax that Unix commands use.

If you design your program to recognize the different
delimiters, you will make some people very happy!  The
GetSwitch routine will detect changed delimiters on those
versions of DOS which support it, and will return an ordinary
"/" on those versions of DOS which don't.

   Switch$ = "x"
   GetSwitch Switch$

-------
Switch$    the DOS switch character.  Init to one character.

Name  : GetSwitch2$          (Get Switch character)
Class : Miscellaneous
Level : DOS

This does exactly the same thing as the GetSwitch routine, but
it is a FUNCTION rather than a SUB.  For more information, see
GetSwitch.

   Switch$ = GetSwitch2$

-------
Switch$    the DOS switch character

Name  : GetTime              (Get Time)
Class : Time
Level : DOS

This routine tells you the time according to DOS.

The main difference between getting the time from BASIC and
getting it from DOS is the "hundredths of seconds" value.
However, this value is not available on some machines, in which
case it will be set to zero.  It is not accurate on most
machines, being calculated instead using a semi-random
approach; it is more of a novelty than a useful value.

   GetTime Hour%, Minute%, Second%, Hundredth%

-------
Hour%       hour (0-23)
Minute%     minute
Second%     second
Hundredth%  hundredth of a second.  See remarks, above.

Name  : GetTimeA             (Get Time of file in Archive)
Class : Disk / Time
Level : DOS

GetTimeA returns the time of an archived file matched by the
FindFirstA or FindNextA routines.

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

   GetTimeA Hour%, Minute%, Second%

-------
Hour%      hour
Minute%    minute
Second%    second

Name  : GetTimeAT            (Get Time from AT clock)
Class : Time
Level : BIOS (AT)

This routine gets the time from the hardware real-time clock in
AT-class computers.  Depending on the DOS version, this time
may be partially or completely independent of the time kept by
DOS in software.  DOS always reads the time from the hardware
clock when it starts up.  However, use of the TIME command in
DOS (and the TIME$ function in QuickBASIC) may relate only to
the software copy of the time, which is not always guaranteed
to be the same as the time in the hardware clock due to certain
discrepancies in DOS.

   GetTimeAT Hour%, Minute%, Second%, ErrCode%

-------
Hour%        hour (0-23)
Minute%      minute
Second%      second
ErrCode%     error code: 0 if no error, else clock has stopped

Name  : GetTimeF             (Get Time of File)
Class : Disk / Time
Level : DOS

The GetTimeF routine returns the time of a file matched by
FindFirstF or FindNextF.

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

   GetTimeF Hour%, Minute%, Second%

-------
Hour%      hour
Minute%    minute
Second%    second

Name  : GetTimeFx$           (Get Time of File, Extended)
Class : Disk / Time
Level : DOS

The GetTimeFx$ function returns the time of a file matched by
FindFirstFx or FindNextFx.

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

   FileTime$ = GetTimeFx$(Buffer$)

Buffer$      buffer used in search
-------
FileTime$    file time (e.g., "17:53:20")

Name  : GetTView             (Get TopView)
Class : Miscellaneous
Level : BIOS

This routine tells you whether TopView or a compatible
multitasker (such as TaskView or DESQview) is loaded.

See also GetDView, GetTVScreen, UpdTVScreen.

   GetTView Installed%

-------
Installed%   whether a TopView-type multitasker is loaded

Name  : GetTVScreen          (Get TopView Screen address)
Class : Display / Miscellaneous
Level : BIOS

GetTVScreen returns the address of the screen buffer used by a
TopView-type multitasker.  This allows you to use direct screen
access while remaining within the windows allocated to your
program by the multitasker.

You must tell the multitasker the address of the screen you
would be writing to if the multitasker was not installed.
Specify a segment of &HB000 if using an MDA or Hercules, or a
segment of &HB800 for CGA, EGA, MCGA or VGA. The offset should
always be 0.  This is for use in text modes.

The routine will return with the new segment and offset for you
to use. These values can be used with any PBClone screen
routine that accepts a segment and offset-- DQPrint and
DXQPrint, for example.

Note that not all TopView-compatible multitaskers will
automatically update the screen from the buffer.  The
UpdTVScreen routine allows you to force a screen update.

See also GetDView, GetTView, UpdTVScreen.

   GetTVScreen DSeg%, DOfs%

DSeg%       segment of desired screen
DOfs%       offset of desired screen
-------
DSeg%       segment of screen buffer
DOfs%       offset of screen buffer

Name  : GetValidKey          (Get Valid Key)
Class : Input
Level : DOS

This one is useful for getting one of a list of keys from the
keyboard.  You give it a list of keys (letters should be
uppercase) to accept.  It will wait until one of the listed
keys is pressed; for letters, it will accept either lowercase
or uppercase keys, but will convert the letter to uppercase
before it returns to you.  If you pass it a blank list, it will
accept any key.

This routine is handy for when you want to allow one of a list
of choices from a menu, for instance.

   GetValidKey GoodList$, Result$

GoodList$    list of acceptable keys.  See above for remarks.
-------
Result$      the key that was accepted (uppercase if letter)

Name  : GetVerify            (Get Verify setting)
Class : Disk
Level : DOS

The GetVerify routine tells you the state of the DOS VERIFY
flag.  When VERIFY is on, some checking is done to make sure
that writing to the disk works as requested.  The checks are
not very good, however, and VERIFY slows down disk handling, so
it is usually better to have VERIFY off.

You can change the state of VERIFY by using the DOS VERIFY
command or with the SetVerify routine in PBClone.

   GetVerify VerifyOn%

-------
VerifyOn%   whether VERIFY is on (0 if no)

Name  : GetVGA               (Get VGA information)
Class : Display / Equipment
Level : BIOS

This routine tells you whether a VGA is available.

See also GetCRT, GetEGA and GetHGA.

   GetVGA IsVGA%

-------
IsVGA%    whether a VGA is installed (0 if no)

Name  : GetVGA2%             (Get VGA information)
Class : Display / Equipment
Level : BIOS

This routine tells you whether a VGA is available.

See also GetCRT, GetEGA and GetHGA.

   IsVGA% = GetVGA2%

-------
IsVGA%    whether a VGA is installed (0 if no)

Name  : GetVGAPalette        (Get VGA Palette)
Class : Display
Level : BIOS

This routine allows you to get any number of the VGA palette
settings into a TYPEd array.  The TYPE for the array should be
defined like this:

   TYPE Palet
      IRed AS STRING * 1
      IBlue AS STRING * 1
      IGreen AS STRING * 1
   END TYPE

This type holds a CHR$-encoded representation of the intensity
of each component of the color.  The values range from 0-63.

   GetVGAPalette DSeg%, DOfs%, Start%, Colors%

DSeg%      segment of the palette array
DOfs%      offset of the palette array
Start%     color number to start with
Colors%    number of colors to get

Name  : GetVidMode           (Get Video Mode)
Class : Display
Level : BIOS

The GetVidMode routine tells you about the current display
status from the BIOS' point of view.  Note that the BIOS
display mode is not the same as the BASIC SCREEN mode (a direct
translation between the two is messy, because BASIC
conglomerates several BIOS modes into a single SCREEN mode in
several instances).

   GetVidMode BIOSMode%, ScreenWidth%, ActivePage%

-------
BIOSMode%     BIOS video mode
ScreenWidth%  number of columns per row
ActivePage%   active (visible) display page

Name  : GetXMSm              (Get XMS Memory)
Class : Memory / Equipment
Level : DOS

This routine tells you how much XMS memory is available.  If
there is none, or if the XMS driver hasn't been installed, it
returns zeroes.  Memory is returned kilobytes.

   GetXMSm LargestFree&, TotalFree&

-------
LargestFree&  largest free block of XMS memory
TotalFree&    total free XMS memory

Name  : GetXMSv              (Get XMS Version)
Class : Memory / Equipment
Level : BIOS

The GetXMSv routine tells you the version of XMS driver that is
being used. The version number is separated into major and
minor parts.  For example, an XMS 2.0 driver would return a
major number of 2 and minor number of 0.

   GetXMSv MajorVer%, MinorVer%

-------
MajorVer%  major part of the XMS version number
MinorVer%  minor part of the XMS version number

Name  : GLoad                (Graphics Load)
Class : Disk
Level : DOS

A replacement for the BASIC BLOAD statement, this routine loads
a binary memory image from a file into the area of memory it
formerly occupied.  This is most often used to restore a screen
display from a file, although PBClone offers more flexible
alternatives.

   GLoad FileName$

FileName$    name of the file to load into memory

Name  : GQPrint              (Graphics Quick Print)
Class : Display
Level : Clone

This is a simple high-speed replacement for the PRINT statement
which works in CGA graphics mode (SCREEN 2).  It does not
interpret control codes, support graphics characters (ASCII
128-255), or update the cursor position, in return for which it
is much faster than PRINT.

The Fast% parameter is ignored at the moment-- top speed is
always used, which may cause flickering on some CGAs.

   GQPrint St$, Row%, Column%, Fast%

St$      string to display
Row%     row (1-25)
Column%  column (1-80)
Fast%    not used

Name  : GrafPrint            (Graphics Print)
Class : Display
Level : Clone

This is a flexible replacement for the PRINT statement which
operates in graphics mode.  It allows you to display text at
graphics coordinates instead of text coordinates for better
alignment with graphs and so forth.  It also lets you specify
the size of the font-- you can stretch it in either vertical or
horizontal directions, or both, using a font multiplier value.

The disadvantages of this routine are that it is slower than an
ordinary PRINT, only does foreground printing (if you need a
background color, you need to fill that in yourself
beforehand), won't do automatic wrap or scroll, and won't
handle control codes or graphics characters (ASCII 0-31,
127-255). The font is based on the normal CGA graphics font,
which uses an 8x8 grid for each character.

GrafPrint will work in any graphics mode.

   GrafPrint St$, X%, Y%, High%, Wide%

St$      string to display
X%       graphics column to start at
Y%       graphics row to start at
High%    font height multiplier
Wide%    font width multiplier

Name  : GrafRest             (Graphics Restore)
Class : Display
Level : Clone

This routine allows you to restore a SCREEN 1 (CGA, 320x200, 4
color) or SCREEN 2 (CGA, 640x200, 2 color) display that was
saved using GrafSave (see).

   GrafRest DSeg%, DOfs%

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

Name  : GrafSave             (Graphics Save)
Class : Display
Level : Clone

This routine allows you to save a SCREEN 1 (CGA, 320x200, 4
color) or SCREEN 2 (CGA, 640x200, 2 color) display that can be
restored using GrafRest (see).

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

   GrafSave DSeg%, DOfs%

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

Name  : GXQPrint             (Graphics Extended Quick Print)
Class : Display
Level : Clone

This is a simple high-speed replacement for the PRINT statement
which works in CGA graphics mode (SCREEN 1).  It does not
interpret control codes, support graphics characters (ASCII
128-255), or update the cursor position, in return for which it
is much faster than PRINT.

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

The Fast% parameter is ignored at the moment-- top speed is
always used, which may cause flickering on some CGAs.

   GXQPrint St$, Row%, Column%, Fore%, Fast%

St$      string to display
Row%     row (1-25)
Column%  column (1-40)
Fore%    foreground color (0-3)
Fast%    not used

Name  : GXQPrint1            (Graphics Extended Quick Print)
Class : Display
Level : Clone

This is a high-speed replacement for the PRINT statement which
works in CGA graphics mode (SCREEN 1).  It does not interpret
control codes or update the cursor position, in return for
which it is much faster than PRINT.

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

The Fast% parameter is ignored at the moment-- top speed is
always used, which may cause flickering on some CGAs.

   GXQPrint1 St$, Row%, Column%, Fore%, Back%, Fast%

St$      string to display
Row%     row (1-25)
Column%  column (1-40)
Fore%    foreground color (0-3)
Back%    background color (0-3)
Fast%    not used

Name  : HandleInfo           (Handle Information)
Class : Miscellaneous
Level : DOS

HandleInfo tells you whether a file handle refers to a file or
to a device. If the handle does not exist, an error code will
be returned.

This is for file handles as returned by FOpen and FCreate.  It
can also be used with file numbers associated with OPEN, via a
BASIC function that was introduced with QuickBASIC 4.0:

   Handle% = FILEATTR(FileNumber%, 2)

See FClose for a list of predefined handles.

   HandleInfo Handle%, Device%, ErrCode%

Handle%    file handle
-------
Device%    whether the handle refers to a device (0 no)
ErrCode%   whether there was an error (0 no)

Name  : HCls                 (Hercules CLS)
Class : Display
Level : Clone

This routine clears a Hercules graphics screen to the specified
color.

Routines in this series are:
   HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel

   HCls Colour%

Colour%    color (0-1)

Name  : HLine                (Hercules LINE)
Class : Display
Level : Clone

This routine draws a line on a Hercules graphics screen.

Routines in this series are:
   HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel

   HLine X1%, Y1%, X2%, Y2%, Colour%

X1%        starting graphics column (0-719)
Y1%        starting graphics row (0-347)
X2%        ending graphics column (0-719)
Y2%        ending graphics row (0-347)
Colour%    color (0-1)

Name  : HMode                (Hercules Mode)
Class : Display
Level : Clone

This routine switches between text mode and Hercules graphics
mode.  Use HInit first to initialize the graphics mode
appropriately.

HMode will clear page 0 when graphics mode is entered.  Page 1,
if it exists, is not cleared.  PBClone does not support page 1
in any respect.

Routines in this series are:
   HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel

   HMode Graphics%

Graphics%    display mode to set (0 text, else graphics)

Name  : HPrint               (Hercules Print)
Class : Display
Level : Clone

This routine displays text in Hercules graphics mode.   It uses
the full resolution of the screen, so text is 90 columns by 43
rows.  This gives you more space than even the largest EGA text
mode, which is only 80x43.

Routines in this series are:
   HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel

   HPrint St$, Row%, Column%

St$        text to display
Row%       row (1-43)
Column%    column (1-90)

Name  : HSetPixel            (Hercules Set Pixel)
Class : Display
Level : Clone

This routine draws a dot on a Hercules graphics screen.

Routines in this series are:
   HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel

   HSetPixel X%, Y%, Colour%

X%         graphics column (0-719)
Y%         graphics row (0-347)
Colour%    color (0-1)

Name  : HTestPixel           (Hercules Test Pixel)
Class : Display
Level : Clone

This routine returns the color of a dot on a Hercules graphics
screen.

Routines in this series are:
   HCls, HLine, HMode, HPrint, HSetPixel, HTestPixel

   Colour% = HTestPixel%(X%, Y%)

X%         graphics column (0-719)
Y%         graphics row (0-347)
-------
Colour%    color (0-1)

Name  : IdentifyFile         (Identify File)
Class : Disk
Level : DOS

Given a file name, this routine attempts to identify what kind
of file it is. Most information is derived from the file
extension, but some files are processed more deeply.  For
instance, a file named "UNKNOWN.BAS" will be checked to see if
it is source code (tokenized GWBASIC format, tokenized
QuickBASIC format, or plain ASCII text) or a binary BSAVE/BLOAD
image (which is further categorized as to whether it is a
screen image, and if so, for what kind of display).

   Descript$ = SPACE$(80)
   IdentifyFile FileName$, Descript$, DescrLen%
   Descript$ = LEFT$(Descript$, DescrLen%)

FileName$    name of the file to identify
-------
Descript$    description of the file (init to at least 80 chars)
DescrLen%    length of the description

Name  : InitPtr              (Initialize Pointers)
Class : Array management
Level : Any

This routine initializes an array of pointers for use with the
pointer sort routines (PSortD, et al).  It may also be useful
for other purposes.  Each element of the array is set equal to
its index (the first element is set to 1, the second to 2, and
so forth).  Arrays are expected to begin at element 1.  You may
specify the last element to initialize, allowing you to use
only part of an array.

   InitPtr Ptr%(), Elements%

Ptr%()      array to initialize
Elements%   number of elements to initialize
-------
Ptr%()      initialized array

Name  : InsChr               (Insert Character)
Class : Display
Level : Clone

The InsChr routine inserts a space at the specified screen
location.

   InsChr Row%, Column%

Row%      row of character
Column%   column of character

Name  : InsLine              (Insert Line)
Class : Display
Level : BIOS

This routine inserts a blank line at the specified row of the
screen.

   InsLine Row%, Attr%

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

Name  : Int2Date             (Integer to Date)
Class : Time
Level : Any

This routine undoes the results of the Date2Int routine.  It
expands a single integer into month, day, and year values.

The storage format is identical to that used by DOS for file
dates, by the way, so this routine makes an apt companion for
LoadDirFull.


See also Int2DateSt$, a version of this routine which returns a
string instead of numbers.


   Int2Date MonthNr%, Day%, Year%, IntDate%

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

Name  : Int2DateSt$          (Integer to Date String)
Class : Time
Level : Any

This routine undoes the results of the Date2Int routine.  It
expands a single integer into a date string with the format
MM-DD-YYYY.

The storage format is identical to that used by DOS for file
dates, by the way, so this routine makes an apt companion for
LoadDirFull.

See also Int2Date, a version of this routine which returns
month, day, and year numbers instead of a string.


   DateSt$ = Int2DateSt$(IntDate%)

IntDate%     date compressed into an integer
-------
DateSt$      uncompressed date in MM-DD-YYYY format.

Name  : Int2Time             (Integer to Time)
Class : Time
Level : Any

This routine undoes the results of the Time2Int routine.  It
expands a single integer into hour, minute, and second values.

Note that the seconds will always be even, due to the storage
format.  The storage format is identical to that used by DOS
for file times, by the way, so this routine makes an apt
companion for LoadDirFull.

See also Int2TimeSt$, a version of this routine which returns a
string instead of numbers.

   Int2Time Hour%, Minute%, Second%, IntTime%

IntTime%     time compressed into an integer
-------
Hour%        hour (0-23)
Minute%      minute
Second%      second

Name  : Int2TimeSt$          (Integer to Time String)
Class : Time
Level : Any

This routine undoes the results of the Time2Int routine.  It
expands a single integer into hour, minute, and second values.

Note that the seconds will always be even, due to the storage
format.  The storage format is identical to that used by DOS
for file times, by the way, so this routine makes an apt
companion for LoadDirFull.

See also Int2Time, a version of this routine which returns
hour, minute, and second numbers instead of a string.

   TimeSt$ = Int2TimeSt$(IntTime%)

IntTime%     time compressed into an integer
-------
TimeSt$      uncompressed time in HH:MM:SS format

Name  : IntVector            (Interrupt Vector)
Class : Miscellaneous
Level : DOS

The IntVector routine retrieves the address of a specified
interrupt handler. If there is no interrupt handler, the
results will normally be zero, although early DOS versions did
not always have the sense to initialize unused vectors that way.

   IntVector DSeg%, DOfs%, Interrupt%

Interrupt%   interrupt number to examine
-------
DSeg%        segment of the interrupt handler
DOfs%        offset of the interrupt handler

Name  : IsAlNum%             (Is Alphanumeric?)
Class : String
Level : Any

This function returns whether a character is alphabetic or
numeric.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsAlNum%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is alphabetic or numeric

Name  : IsAlpha%             (Is Alphabetic?)
Class : String
Level : Any

This function returns whether a character is alphabetic.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsAlpha%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is alphabetic

Name  : IsASCII%             (Is ASCII?)
Class : String
Level : Any

This function returns whether a character is ASCII.  This is
true if the character ranges from CHR$(0)-CHR$(127).

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsASCII%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is ASCII

Name  : IsCntrl%             (Is Control?)
Class : String
Level : Any

This function returns whether a character is a control code.
This is true for CHR$(0)-CHR$(32) and CHR$(127).

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsCntrl%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is a control code

Name  : IsDigit%             (Is Digit?)
Class : String
Level : Any

This function returns whether a character is numeric.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsDigit%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is a digit

Name  : IsLower%             (Is Lowercase?)
Class : String
Level : Any

This function returns whether a character is a lowercase
letter.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsLower%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is a lowercase letter

Name  : IsPrint%             (Is Printable?)
Class : String
Level : Any

This function returns whether a character is printable.  This
is true for CHR$(32)-CHR$(126).

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsPrint%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is printable

Name  : IsPunct%             (Is Punctuation?)
Class : String
Level : Any

This function returns whether a character is punctuation.  This
is true for any ASCII character that is not alphabetic,
numeric, or a control code.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsPunct%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is punctuation

Name  : IsSpace%             (Is Space?)
Class : String
Level : Any

This function returns whether a character is white space.  This
includes Space, Carriage Return, Horizontal Tab, Vertical Tab,
LineFeed, and FormFeed characters.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsSpace%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is white space

Name  : IStr$                (Integer STR$)
Class : String
Level : Any

This routine is identical to the BASIC function STR$, but is
somewhat smaller.  It is only for integer values.

   St$ = IStr$(Number%)

Number%   integer to convert
-------
St$       string form of the number

Name  : IsUpper%             (Is Uppercase?)
Class : String
Level : Any

This function returns whether a character is an uppercase
letter.

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

   IsIt% = IsUpper%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is uppercase

Name  : IsXDigit%            (Is Hex Digit?)
Class : String
Level : Any

Functions in this family include:
   IsAlNum, IsAlpha, IsASCII, IsCntrl, IsDigit, IsLower,
   IsPrint, IsPunct, IsSpace, IsUpper, IsXDigit

This function returns whether a character is a hexadecimal
digit.

   IsIt% = IsXDigit%(Ch$)

Ch$       character to check
-------
IsIt%     -1 if the character is a hex digit

Name  : IVal%                (Integer VAL)
Class : Numeric
Level : Any

This routine is similar to the BASIC function VAL, but is much
faster.  If you are not using floating point numbers, this
routine may also decrease the size of your program
significantly, since it won't cause BASIC to pull in its
floating point routines as VAL does.

Unlike VAL, this routine only converts strings to integer
values.  It will not handle hex or octal strings.  It will not
notify you if there is an overflow error.  Finally, although
IVal% will ignore leading blanks, it assumes that a number may
not contain blanks, whereas VAL will ignore blanks in the
middle of a number:

     VAL("  12 34") returns 1234
   IVal%("  12 34") returns 12

Note that, like VAL (but unlike the IVal% function in ProBas),
multiple negation is considered illegal.  For example,
IVal%("--1") returns zero.

   Number% = IVal%(St$)

St$       string to convert
-------
Number%   integer form of string (0 if there isn't one)

Name  : KbdType              (Keyboard Type)
Class : Input / Equipment
Level : Clone

This routine tells you if an enhanced (101-key) keyboard is
available.

If KbdType is not entirely sure that an enhanced keyboard is
available, it plays safe and assumes there isn't one.  This
avoids possible disaster on older PCs.

   KbdType Enhanced%

-------
Enhanced%    whether keyboard is of the enhanced type (0 no)

Name  : KbdType2%            (Keyboard Type)
Class : Input / Equipment
Level : Clone

This routine tells you if an enhanced (101-key) keyboard is
available.

If KbdType2% is not entirely sure that an enhanced keyboard is
available, it plays safe and assumes there isn't one.  This
avoids possible disaster on older PCs.

   Enhanced% = KbdType2%

-------
Enhanced%    whether keyboard is of the enhanced type (0 no)

Name  : KeyPress             (detect Key Press)
Class : Input
Level : DOS

This routine works like the Turbo/Power BASIC function INSTAT.
It tells you whether there is a key waiting to be processed.

   KeyPress KeyHit%

-------
KeyHit%   whether a key is waiting (0 if no)

Name  : KVal&                (Kilobyte VAL)
Class : Numeric
Level : Any

This routine is similar to the BASIC function VAL, but is much
faster.  The number returned is divided by 1024, which is
useful if you're dealing in terms of kilobytes.  If you are not
using floating point numbers, this routine may decrease the
size of your program significantly, since it won't cause BASIC
to pull in its floating point routines as VAL does.

Unlike VAL, this routine only converts strings to long integer
values.  It will not handle hex or octal strings.  It will not
notify you if there is an overflow error.  Finally, although
KVal& will ignore leading blanks, it assumes that a number may
not contain blanks, whereas VAL will ignore blanks in the
middle of a number.

Note that, like VAL (but unlike the KVal& function in ProBas),
multiple negation is considered illegal.  For example,
KVal&("--10000") returns zero.

   Number& = KVal&(St$)

St$       string to convert
-------
Number&   long integer form of string, divided by 1024

Name  : LoadDir              (Load Directory)
Class : Disk
Level : DOS

Given a filespec with wildcards and a file attribute, this
routine loads a list of all matching files into an array.  The
array must be of fixed-length string type, with 12 characters
for each filename.  You can find out how large to DIM the array
by using the FileCount routine.

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, LoadDir 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.

NOTE:  we use FilAttr%, not FileAttr%, because BASIC has an
internal function named FILEATTR.

   LoadDir FileSpec$, FilAttr%, DSeg%, DOfs%, ErrCode%

FileSpec$    search file specification (may contain wildcards)
FilAttr%     search file attribute
DSeg%        segment of array (use VARSEG)
DOfs%        offset of array (use VARPTR)
-------
ErrCode%     error code (0 if no error)

Name  : LoadDirAll           (Load Directory, All info)
Class : Disk
Level : DOS

Given a filespec with wildcards and a file attribute, this
routine loads a list of all matching files into an array.  All
available information about the file is included: name, size,
time, date, and attribute.  The array must be of the TYPE shown
below.  You can find out how large to DIM the array by using
the FileCount routine.

   TYPE DirType
      FilAttr AS STRING * 1
      FilTime AS INTEGER
      FilDate AS INTEGER
      FilSize AS LONG
      FilName AS STRING * 12
   END TYPE

You can change the names if you like, but don't alter the order
of the information.  You can decode the file attribute with the
ASC function, then process it with ExplainFAttr$.  The file
time and date can be decoded with the Int2Time and Int2Date or
Int2TimeSt$ and Int2DateSt$ routines.

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, LoadDir 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.

NOTE:  we use FilAttr%, not FileAttr%, because BASIC has an
internal function named FILEATTR.

   LoadDir FileSpec$, FilAttr%, DSeg%, DOfs%, ErrCode%

FileSpec$    search file specification (may contain wildcards)
FilAttr%     search file attribute
DSeg%        segment of array (use VARSEG)
DOfs%        offset of array (use VARPTR)
-------
ErrCode%     error code (0 if no error)

Name  : Locase               (Lowercase)
Class : String
Level : Any

This routine, like BASIC's LCASE$ function, converts a string
to lowercase. Since it doesn't have to create a new return
string (a fairly slow process), it's faster than the BASIC
equivalent.

See also Locase1.

   Locase St$

St$     string to be put into lowercase
-------
St$     lowercase string

Name  : Locase1              (Lowercase)
Class : String
Level : Any

This routine, like BASIC's LCASE$ function, converts a string
to lowercase. It converts letters in the extended character set
as well as the usual letters, making it well suited for text
which may not be in English.

See also Locase.

   Locase1 St$

St$     string to be put into lowercase
-------
St$     lowercase string

Name  : LogicalDrives%       (Logical Drives)
Class : Disk / Equipment
Level : DOS

This function returns the number of logical drives available.

A logical drive corresponds roughly to a drive letter-- it may
point to zero or more actual devices.  For instance, on a
one-floppy system, both A: and B: point to the same drive.  On
a partitioned hard drive, both C: and D: may point to different
areas of the same drive.  Drive E: may point to a RAMdisk, or
maybe it doesn't point to anything at all.

As you can see, knowing the number of logical drives doesn't
tell you much about what's actually there.  However, it does
give you an upper limit on the number of drive letters
available, which is a good place to start.

   Drives% = LogicalDrives%

-------
Drives%    number of logical drives

Name  : LClose               (L/I/M Close)
Class : Memory
Level : BIOS

This routine closes a block of expanded memory that was opened
for access by LOpen.  It is important to close the block when
you are finished with it, to return it to the free memory pool.

Routines in this suite include: LOpen, LGet, LPut, LClose.

   LClose EMSHandle%

EMSHandle%    handle of the expanded memory block

Name  : LGet                 (L/I/M Get)
Class : Memory
Level : BIOS

This routine gets a block of data from expanded memory that was
opened for access by LOpen.  The amount of data is specified in
words; one word is the same as two bytes.  An integer takes up
a word, long integers and single precision numbers require two
words, and double precision numbers take four.

Routines in this suite include: LOpen, LGet, LPut, LClose.

   LGet EMSHandle%, DSeg%, DOfs%, Words%

EMSHandle%    handle of the expanded memory block
DSeg%         segment of place to store data
DOfs%         offset of place to store data
Words%        words to get from expanded memory

Name  : LOpen                (L/I/M Open)
Class : Memory
Level : BIOS

This routine opens a block of expanded memory for access.  The
size of the block is specified in words; one word is the same
as two bytes.  An integer takes up a word, long integers and
single precision numbers require two words, and double
precision numbers take four.  This allows you to store up to
64K in each EMS block that you open.

Note that LOpen expects an EMS driver to be available.  If you
are not certain on this point, use GetLIMM beforehand to make
sure.

Routines in this suite include: LOpen, LGet, LPut, LClose.

   LOpen Words%, EMSHandle%, ErrCode%

Words%        size of expanded memory block to allocate
-------
EMSHandle%    handle of the expanded memory block
ErrCode%      error code (0 if no error)

Name  : LPut                 (L/I/M Put)
Class : Memory
Level : BIOS

This routine puts a block of data into expanded memory that was
opened for access by LOpen.  The amount of data is specified in
words; one word is the same as two bytes.  An integer takes up
a word, long integers and single precision numbers require two
words, and double precision numbers take four.

Routines in this suite include: LOpen, LGet, LPut, LClose.

   LPut EMSHandle%, DSeg%, DOfs%, Words%

EMSHandle%    handle of the expanded memory block
DSeg%         segment of place from which to get data
DOfs%         offset of place from which to get data
Words%        words to put into expanded memory

Name  : LRotate              (Left Rotate)
Class : String
Level : Any

Many years ago, I wrote one of the first terminal programs for
the PC.  It died a horrible death when Qmodem came out...
sigh.  This routine comes from that experience.  It rotates the
characters in a string left once (e.g., "ABCDE" becomes
"BCDEA").  I used this in my routine to dial a list of BBSes,
skipping to the next one if the current one was busy.

LRotate can also be handy for things like scrolling a long
message across the screen (you just PRINT LEFT$(Message$, 80);
then delay a bit, LRotate and do it again).

See also RRotate.

   LRotate St$

St$     string to be rotated left once
-------
St$     string after being rotated left once

Name  : LScroll              (Left Scroll)
Class : Display
Level : Clone

This routine scrolls any selected part of the display left.
You may scroll as many times as you like, or scroll "zero"
times to totally clear the selected part of the display.

   LScroll 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  : LVal&                (Long integer VAL)
Class : Numeric
Level : Any

This routine is similar to the BASIC function VAL, but is much
faster.  If you are not using floating point numbers, this
routine may also decrease the size of your program
significantly, since it won't cause BASIC to pull in its
floating point routines as VAL does.

Unlike VAL, this routine only converts strings to long integer
values.  It will not handle hex or octal strings.  It will not
notify you if there is an overflow error.  Finally, although
LVal& will ignore leading blanks, it assumes that a number may
not contain blanks, whereas VAL will ignore blanks in the
middle of a number:

     VAL("  12 34") returns 1234
   LVal&("  12 34") returns 12

Note that, like VAL (but unlike the LVal& function in ProBas),
multiple negation is considered illegal.  For example,
LVal&("--1") returns zero.

   Number& = LVal&(St$)

St$       string to convert
-------
Number&   long integer form of string (0 if there isn't one)

Name  : MakeSub              (Make Subdirectory)
Class : Disk
Level : DOS

Like the DOS MD (or MKDIR) command, this routine creates a new
subdirectory.

   MakeSub SubDir$, ErrCode%

SubDir$    name of new subdirectory
-------
ErrCode%   error code: 0 if none, else DOS Error

Name  : MatchFile            (Match File)
Class : Disk / String
Level : Any

The MatchFile routine tells you whether a given filename
matches a file specification which may contain wildcards.  The
filename itself should not contain wildcards.  Neither the
filename nor filespec should include drive or subdirectory
specifications.

One way of using this is in processing file exclusion lists.
The FindFirstF routine allows you to find files that match a
given filespec; to this, you could add a MatchFile-based
routine which would screen out files that match a different
filespec.  Such a routine would allow you to create utilities
to do things like "DIR *.* /EXCEPT=*.BAS".

   MatchFile FileSpec$, FileName$, IsMatch%

FileSpec$   master file pattern (may contain wildcards)
FileName$   name of file to test against the master pattern
-------
IsMatch%    0 if the filename doesn't match the filespec

Name  : Max%                 (Maximum)
Class : Numeric
Level : Any

This function returns the larger of two integers.  It can be
handy in sorting routines or for keeping a value within a
desired range.

   Larger% = Max%(First%, Second%)

First%     one integer
Second%    another integer
-------
Larger%    larger of the two integers

Name  : MaxD#                (Maximum Double precision)
Class : Numeric
Level : Any

This function returns the larger of two double-precision
numbers.  It can be handy in sorting routines or for keeping a
value within a desired range.

   Larger# = MaxD#(First#, Second#)

First#     one number
Second#    another number
-------
Larger#    larger of the two numbers

Name  : MaxL&                (Maximum Long integer)
Class : Numeric
Level : Any

This function returns the larger of two long integers.  It can
be handy in sorting routines or for keeping a value within a
desired range.

   Larger& = MaxL&(First&, Second&)

First&     one long integer
Second&    another long integer
-------
Larger&    larger of the two long integers

Name  : MaxS!                (Maximum Single precision)
Class : Numeric
Level : Any

This function returns the larger of two single-precision
numbers.  It can be handy in sorting routines or for keeping a
value within a desired range.

   Larger! = MaxS!(First!, Second!)

First!     one number
Second!    another number
-------
Larger!    larger of the two numbers

Name  : MeanAverageD         (Mean Average Double precision)
Class : Array management
Level : Any

This routine averages the specified range of elements in an
array of double precision numbers.  The form of averaging used
is called the "mean", which is the sum of all of the elements
divided by the number of elements involved. This is the most
common method of averaging a list of numbers.

   MeanAverageD Array#(), First%, Last%, Average#, ErrCode%

Array#()    array to be averaged
First%      array element to start with
Last%       array element to end with
-------
Average#    average value of the specified elements
ErrCode%    0 if there was no error

Name  : MeanAverageI         (Mean Average Integer)
Class : Array management
Level : Any

This routine averages the specified range of elements in an
array of integer numbers.  The form of averaging used is called
the "mean", which is the sum of all of the elements divided by
the number of elements involved. This is the most common method
of averaging a list of numbers.

   MeanAverageI Array%(), First%, Last%, Average%, ErrCode%

Array()     array to be averaged
First%      array element to start with
Last%       array element to end with
-------
Average%    average value of the specified elements
ErrCode%    0 if there was no error

Name  : MeanAverageL         (Mean Average Long integer)
Class : Array management
Level : Any

This routine averages the specified range of elements in an
array of long integer numbers.  The form of averaging used is
called the "mean", which is the sum of all of the elements
divided by the number of elements involved. This is the most
common method of averaging a list of numbers.

   MeanAverageL Array&(), First%, Last%, Average&, ErrCode%

Array&()    array to be averaged
First%      array element to start with
Last%       array element to end with
-------
Average&    average value of the specified elements
ErrCode%    0 if there was no error

Name  : MeanAverageS         (Mean Average Single precision)
Class : Array management
Level : Any

This routine averages the specified range of elements in an
array of single precision numbers.  The form of averaging used
is called the "mean", which is the sum of all of the elements
divided by the number of elements involved. This is the most
common method of averaging a list of numbers.

   MeanAverageS Array!(), First%, Last%, Average!, ErrCode%

Array!()    array to be averaged
First%      array element to start with
Last%       array element to end with
-------
Average!    average value of the specified elements
ErrCode%    0 if no error

Name  : MemSwap              (Memory Swap)
Class : Memory
Level : Any

MemSwap swaps the contents of one area of memory with another.
This can be used for a variety of things, from swapping a saved
screen with the actual screen to exchanging the contents of two
arrays.

   MemSwap DSeg1%, DOfs1%, DSeg2%, DOfs2%, Bytes%

DSeg1%     segment of first memory area
DOfs1%     offset of first memory area
DSeg2%     segment of second memory area
DOfs2%     offset of second memory area
Bytes%     bytes to swap

Name  : Min%                 (Minimum)
Class : Numeric
Level : Any

This function returns the smaller of two integers.  It can be
handy in sorting routines or for keeping a value within a
desired range.

   Smaller% = Min%(First%, Second%)

First%     one integer
Second%    another integer
-------
Smaller%   smaller of the two integers

Name  : MinD#                (Minimum Double precision)
Class : Numeric
Level : Any

This function returns the smaller of two double-precision
numbers.  It can be handy in sorting routines or for keeping a
value within a desired range.

   Smaller# = MinD#(First#, Second#)

First#     one number
Second#    another number
-------
Smaller#   smaller of the two numbers

Name  : MinL&                (Minimum Long integer)
Class : Numeric
Level : Any

This function returns the smaller of two long integers.  It can
be handy in sorting routines or for keeping a value within a
desired range.

   Smaller& = MinL&(First&, Second&)

First&     one long integer
Second&    another long integer
-------
Smaller&   smaller of the two long integers

Name  : MinS!                (Minimum Single precision)
Class : Numeric
Level : Any

This function returns the smaller of two single-precision
numbers.  It can be handy in sorting routines or for keeping a
value within a desired range.

   Smaller! = MinS!(First!, Second!)

First!     one number
Second!    another number
-------
Smaller!   smaller of the two numbers

Name  : MMButton             (Mouse Button)
Class : Mouse
Level : BIOS

The MMButton routine allows you to find out which mouse buttons
are pressed. Although it will work with any mouse, it is
designed specifically for a mouse with two buttons (see also
MMButton3).  If you want to find out which buttons were pressed
in the past, rather than being pressed now, try MMClick instead.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MMButton LeftB%, RightB%

-------
LeftB%     whether the left button is pressed
RightB%    whether the right button is pressed

Name  : MMButton3            (Mouse Button for 3-button mouse)
Class : Mouse
Level : BIOS

The MMButton3 routine allows you to find out which mouse
buttons are pressed. Although it will work with any mouse, it
is designed specifically for a mouse with three buttons (see
also MMButton).  If you want to find out which buttons were
pressed in the past, rather than being pressed now, try
MMClick3 instead.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MMButton3 LeftB%, MiddleB%, RightB%

-------
LeftB%     whether the left button is pressed
MiddleB%   whether the middle button is pressed
RightB%    whether the right button is pressed

Name  : MMCheck              (Mouse Check and initialize)
Class : Mouse
Level : BIOS

This routine does a number of things.  Primarily, it is
intended to let you check to see if a mouse is available.  It
returns a zero if there is no mouse; if there is a mouse, the
number of mouse buttons is returned.  The mouse status is also
initialized, so this is best used once at the beginning of your
program.

All of the other mouse routines assume that a mouse is
available, so you should definitely use MMCheck if you're not
sure.  Otherwise, results will be unusual at best, and the
computer may even lock up under some DOS versions.

   MMCheck Buttons%

-------
Buttons%   number of mouse buttons (0 if no mouse is installed)

Name  : MMClick              (Mouse Click)
Class : Mouse
Level : BIOS

The MMClick routine allows you to find out which mouse buttons
have been pressed since you last checked, and how many times
they were pressed. Although it will work with any mouse, it is
designed specifically for a mouse with two buttons (see also
MMClick3).  If you want to find out which buttons are currently
being pressed, try MMButton instead.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MMClick LeftB%, RightB%

-------
LeftB%     # of times left button was pressed since last check
RightB%    # of times right button was pressed since last check

Name  : MMClick3             (Mouse Click for 3-button mouse)
Class : Mouse
Level : BIOS

The MMClick3 routine allows you to find out which mouse buttons
have been pressed since you last checked, and how many times
they were pressed. Although it will work with any mouse, it is
designed specifically for a mouse with three buttons (see also
MMClick).  If you want to find out which buttons are currently
being pressed, try MMButton3 instead.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MMClick3 LeftB%, MiddleB%, RightB%

-------
LeftB%     # of times left button was pressed since last check
MiddleB%   # of times middle button was pressed since last look
RightB%    # of times right button was pressed since last check

Name  : MMCursorOff          (Mouse Cursor Off)
Class : Mouse
Level : BIOS

This routine makes the mouse cursor invisible.  The mouse
cursor will still function as a location indicator, in the same
way that the normal cursor still functions when you make it
invisible.

Note that the mouse cursor is somewhat bizarre in that an
"invisibility level" is kept.  Every time you use MMCursorOff,
the invisibility depth is increased; subsequent attempts to
make the cursor visible will not actually do so until the
invisibility depth reaches zero.  In other words, if you call
MMCursorOff when the cursor is already invisible, the cursor
will not reappear until you've told it to reappear as many
times as you told it to disappear.  This is fairly demented,
but that's the way Microsoft made it.

This routine will not work properly if no mouse is installed.
See MMCheck.

   MMCursorOff

Name  : MMCursorOn           (Mouse Cursor On)
Class : Mouse
Level : BIOS

This routine makes the mouse cursor visible, or tries to do
so...

The mouse cursor is somewhat bizarre in that an "invisibility
level" is kept.  Every time you use MMCursorOff, the
invisibility depth is increased; subsequent attempts to make
the cursor visible will not actually do so until the
invisibility depth reaches zero.  In other words, if you call
MMCursorOff when the cursor is already invisible, the cursor
will not reappear until you've told it to reappear (with
MMCursorOn) as many times as you told it to disappear.  This is
fairly demented, but that's the way Microsoft made it.

This routine will not work properly if no mouse is installed.
See MMCheck.

   MMCursorOn

Name  : MMGetLoc             (Mouse Get Location)
Class : Mouse
Level : BIOS

This routine allows you to get the current location of the
mouse cursor.  It doesn't matter if the cursor is visible or
invisible.

The mouse cursor location is somewhat perverse in CGA and text
modes, due to the sloppy design of Microsoft's original mouse
driver.  In text modes and both CGA graphics modes, the cursor
is returned as if the screen is 640x200. To correct this for
SCREEN 1, divide the X coordinate by two.  To correct this for
text modes, divide each coordinate by eight.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

See also GetMouseLoc, which returns the appropriate coordinates
for text mode.

   MMGetLoc X%, Y%

-------
X%         X coordinate ("column")
Y%         Y coordinate ("row")

Name  : MMSetLoc             (Mouse Set Location)
Class : Mouse
Level : BIOS

This routine allows you to set the current location of the
mouse cursor.  It doesn't matter if the cursor is visible or
invisible.

The mouse cursor location is somewhat perverse in CGA and text
modes, due to the sloppy design of Microsoft's original mouse
driver.  In text modes and both CGA graphics modes, the cursor
is returned as if the screen is 640x200. To correct this for
SCREEN 1, double the X coordinate.  To correct this for text
modes, multiply each coordinate by eight and add four.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

See also SetMouseLoc, which does the coordinate conversions for
you in text mode.

   MMSetLoc X%, Y%

X%         X coordinate ("column")
Y%         Y coordinate ("row")

Name  : MMSetRange           (Mouse Set Range)
Class : Mouse
Level : BIOS

This routine allows you to set the allowable range of mouse
cursor locations. The mouse cursor will not be permitted to go
outside this range.  It doesn't matter if the cursor is visible
or invisible.

The mouse cursor location is somewhat perverse in CGA and text
modes, due to the sloppy design of Microsoft's original mouse
driver.  In text modes and both CGA graphics modes, the cursor
is returned as if the screen is 640x200. To correct this for
SCREEN 1, double the X coordinate.  To correct this for text
modes, multiply each coordinate by eight and add four.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MMSetRange X1%, Y1%, X2%, Y2%

X1%       left   X coordinate (upper left "column")
Y1%       top    Y coordinate (upper left "row")
X2%       right  X coordinate (lower right "column")
Y2%       bottom Y coordinate (lower right "row")

Name  : Month                (Month)
Class : String / Time
Level : Any

Given a month number, this routine tells you the name of the
month.

Note that QuickBASIC is apt to get confused if you use the same
name for a variable as for a routine.  Since this routine is
named "Month", you should avoid using a variable called "Month".

   MonthName$ = SPACE$(9)
   Month MonthName$, NameLen%, MonthNr%
   MonthName$ = LEFT$(MonthName$, NameLen)

MonthNr%    month number (1-12)
-------
MonthName$  name of the month.  Init to at least 9 characters.
NameLen%    length of the month name

Name  : MouseBuffer          (Mouse Buffer size)
Class : Mouse
Level : BIOS

This routine is used before MouseSave in order to find out how
many bytes are needed to save the mouse state.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MouseBuffer Bytes%
   St$ = SPACE$(Bytes%)
   MouseSave St$

-------
Bytes%     number of bytes needed to save the state of the mouse

Name  : MouseCursor          (Mouse Cursor type)
Class : Mouse
Level : BIOS

The MouseCursor routine allows you to select one of a number of
graphics mouse cursors.  The following types are supported:

    0   hourglass ("please wait" symbol)
    1   standard arrow pointer
    2   pointing hand
    3   crosshair
    4   target (box-in-a-box pointer)
    5   grabbing hand

If you'd like other shapes, please suggest a few!  I'll be glad
to add them.

   MouseCursor CursorNr%

CursorNr%    type of mouse graphics cursor to use (see above)

Name  : MousePen             (Mouse light Pen emulation)
Class : Mouse
Level : BIOS

The mouse can be made to emulate a light pen, allowing you to
use BASIC's light pen routines to provide a certain minimal
level of support for both light pens and mice.  This emulation
is on by default, but you can turn it off in case there is an
actual light pen attached.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MousePen EmulatePen%

EmulatePen%   whether mouse should emulate light pen (0 no)

Name  : MouseRest            (Mouse status Restore)
Class : Mouse
Level : BIOS

This routine is for use in conjunction with MouseSave.  It
allows you to restore the mouse settings to a state that was
saved in the past.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MouseRest St$

St$        mouse state to restore

Name  : MouseSave            (Mouse status Save)
Class : Mouse
Level : BIOS

This one is handy for use in subprograms or when SHELLing to
other programs that may use the mouse.  It allows you to save
the current mouse settings as a string.  To find out how long
the string should be, use MouseBuffer.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

   MouseBuffer Bytes%
   St$ = SPACE$(Bytes%)
   MouseSave St$

-------
St$        saved mouse state.  Init as shown above.

Name  : MPrint               (MS-DOS Print)
Class : Display
Level : BIOS

The MPrint routine displays text using mostly DOS services.
This allows it to handle ANSI codes if an ANSI driver is
installed.  In addition, the output of MPrint is confined to a
region of the screen that you may select with MWindow.  By
default, the region is 1,1 to 25,80: a full 80x25 text screen.

Using MPrint is similar to using PRINT followed by a semicolon.
It does not automatically move to the next line.  To do so, you
must MPrint a carriage return and linefeed: CHR$(13) + CHR$(10).

To clear the MWindow region, MPrint a formfeed: CHR$(12).

   MPrint St$

St$         string to display

Name  : MWindow              (MS-DOS Window)
Class : Display
Level : Any

The MWindow routine works in conjunction with MPrint.  It
defines an area of the screen in which text displayed by MPrint
must stay.  The default window is 1,1 to 25,80.

   MWindow TopRow%, LeftCol%, BottomRow%, RightCol%

TopRow%     top row
LeftCol%    left column
BottomRow%  bottom row
RightCol%   right column

Name  : MulMatI              (Multiply Matrix by Integer)
Class : Array management
Level : Any

This routine multiplies as many elements of an integer array as
you like by a given number, starting at a specified place in
the array.  If there was a numeric overflow at any point in the
operation, an error code will be returned.

   MulMatI DSeg%, DOfs%, Elements%, Value%, ErrCode%

DSeg%      segment of the array element to start at
DOfs%      offset of the array element to start at
Elements%  number of array elements to process
Value%     value to multiply each array element by
-------
ErrCode%   error code: 0 if no error

Name  : MultiAND             (Multiple AND)
Class : String
Level : Any

The MultiAND routine performs an arithmetic "AND" operation on
each character in a string.

Among the varied uses for MultiAND is stripping the high bit
from characters, as you might want to do in telecommunications
or in converting WordStar files.  In that case, you would use a
BitMask% of 127.

   MultiAND St$, BitMask%

St$        string to process
BitMask%   bit mask (0-255) with which to AND each character
-------
St$        processed string

Name  : MultiOR              (Multiple OR)
Class : String
Level : Any

The MultiOR routine performs an arithmetic "OR" operation on
each character in a string.

   MultiOR St$, BitMask%

St$        string to process
BitMask%   bit mask (0-255) with which to OR each character
-------
St$        processed string

Name  : MultiXOR             (Multiple XOR)
Class : String
Level : Any

The MultiXOR routine performs an arithmetic "XOR" operation on
each character in a string.

   MultiXOR St$, BitMask%

St$        string to process
BitMask%   bit mask (0-255) with which to XOR each character
-------
St$        processed string

Name  : NameCase             (Name Case)
Class : String
Level : Any

This routine provides a specialized uppercase/lowercase
converter designed especially for names.  It converts the first
letter in each word in a string to uppercase, with the rest of
the word being converted to lowercase.

See also NameCase2, the FUNCTION version of this routine.

   NameCase St$

St$         string to process
-------
St$         processed string

Name  : NameCase2$           (Name Case)
Class : String
Level : Any

This routine provides a specialized uppercase/lowercase
converter designed especially for names.  It converts the first
letter in each word in a string to uppercase, with the rest of
the word being converted to lowercase.

See also NameCase, the SUB version of this routine.

   Result$ = NameCase2$(St$)

St$         string to process
-------
Result$     processed string

Name  : Num2Phone$           (compressed phone# to string)
Class : Numeric String
Level : Any

This function takes a phone number (as encoded by Phone2Num&)
and converts it to unformatted string form.  Depending on the
original number, the result may be 4, 7, or 10 characters in
length.  An invalid code will result in a null string.

   Result$ = Num2Phone$(PhoneNumber&)

PhoneNumber&    encoded phone number
-------
Result$         phone number ("" if invalid number)

Name  : NumFormat            (Number Format)
Class : Numeric
Level : DOS

This works just like PRINT USING, but returns the results in a
string rather than sending them to the display or a file.

Note that an interaction between QuickBASIC, DOS and some
networks means that this routine will briefly access the
default drive.  Strange but true.

   NumFormat Format$, Number#, Result$

Format$     numeric format
Number#     number to format
-------
Result$     formatted number

Name  : NumProc              (Numeric Processor)
Class : Equipment
Level : Any

NumProc returns the type of numeric coprocessor installed.  I
haven't tried it with a 80486, but I would guess an 80486
always appears to have an 80387 (unless it's one of those
brain-damaged 80486SX chips).

Results are returned as follows:

   0    no math chip
   1    8087
   2    80287
   3    80387

If anyone can tell me how to better handle a 486 here, I'd
appreciate it.

   NumProc ProcType%

-------
ProcType%    type of numeric coprocessor (see above)

Name  : NumProc2%            (Numeric Processor)
Class : Equipment
Level : Any

NumProc2% returns the type of numeric coprocessor installed.  I
haven't tried it with a 80486, but I would guess an 80486
always appears to have an 80387 (unless it's one of those
brain-damaged 80486SX chips).


Results are returned as follows:

   0    no math chip
   1    8087
   2    80287
   3    80387

If anyone can tell me how to better handle a 486 here, I'd
appreciate it.

   ProcType% = NumProc2%

-------
ProcType%    type of numeric coprocessor (see above)

Name  : ObjScan              (Object file Scan)
Class : Disk
Level : DOS

This routine returns information about a specified .OBJ file.
It returns the module name, public names, and external names.
The module name is generally the name of the original file
which was compiled to produce the .OBJ file. Public names are
the names of routines (and sometimes variables) that can be
accessed by outside programs.  External names are the names of
routines (and variables) that the .OBJ file expects to be
provided by outside programs.

External names containing "$", starting with "_" or with
lowercase characters are screened out to avoid returning a huge
list of BASIC internal routines. For the same reason, routines
ending with "QQ" will also be screened out, as will
STRINGADDRESS, STRINGASSIGN, STRINGLENGTH, and STRINGRELEASE.
Y'know, it would be nice if Microsoft followed some sort of
standard for its names.

The public and external names are returned in string arrays.
ObjScan will fail with an error code if there is insufficient
space, so be sure to allow plenty of room.  If scanning
subprograms, a DIM to 30 or 40 elements is probably ample.  If
scanning large programs, you may need to increase the
dimensions substantially.

The ObjScan routine can be used as the basis for a simple ".OBJ
info" utility or for more complex applications, such as library
management.

   ObjScan ObjFile$, ModName$, Routine$(), External$(), ErrCode%

ObjFile$      name of .OBJ file
-------
ModName$      module name
Routine$()    public names
External$()   external names
ErrCode%      whether there was an error (0 no)

Name  : Odd%                 (Odd integer?)
Class : Numeric
Level : Any

This function returns whether an integer is odd.  If so, it
returns -1, otherwise 0.

   Result% = Odd%(Number%)

Number%    number to test
-------
Result%    whether the number is odd

Name  : OddL%                 (Odd Long integer?)
Class : Numeric
Level : Any

This function returns whether a long integer is odd.  If so, it
returns -1, otherwise 0.

   Result% = Odd%(Number&)

Number&    number to test
-------
Result%    whether the number is odd

Name  : OrSt                 (OR String)
Class : String
Level : Any

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

   OrSt St1$, St2$

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

Name  : ParseFSpec           (Parse File Specification)
Class : Disk
Level : Any

This routine splits a file specification into a drive,
subdirectory, and filename.  You are expected to initialize the
return strings to reasonable values beforehand (1 for drive, 64
for subdirectory, 12 for filename).  If the filespec may be
invalid, you may wish to leave additional space to avoid
potentially disastrous overflows.  An alternative would be to
use ExtendFSpec beforehand to check and complete the file
specification.  This is likely to be a good approach anyway--
these two routines complement each other nicely.

   Drive$ = SPACE$(1)
   Subdir$ = SPACE$(64)
   File$ = SPACE$(12)
   ParseFSpec FileSpec$, Drive$, DLen%, Subdir$, SLen%,
      File$, FLen%
   Drive$ = LEFT$(Drive$, DLen%)
   Subdir$ = LEFT$(Subdir$, SLen%)
   File$ = LEFT$(File$, FLen%)

FileSpec$   file specification
-------
Drive$      drive letter (init to 1+)
DLen%       length of Drive$
SubDir$     subdirectory (init to 64+)
SLen%       length of Subdir$
File$       file name (init to 12+)
FLen%       length of File$

Name  : PatchDone            (Patch Done)
Class : Disk
Level : DOS

This routine closes the file opened by FindPatch.  You must use
PatchDone when you are finished patching the file.

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

   PatchDone

Name  : PCDat$               (PC Date)
Class : Equipment
Level : Clone

The PCDat$ routine tells you the date of the BIOS ROM chip.
This date is not always available on some (mostly older)
clones, in which case "No Date" is returned.

   ROMDate$ = PCDat$

-------
ROMDate$   date of the BIOS ROM (xx/xx/xx).

Name  : PCDate               (PC Date)
Class : Equipment
Level : Clone

The PCDate routine tells you the date of the BIOS ROM chip.
This date is not always available on some (mostly older)
clones, in which case "No Date " is returned.  See also PCDat,
a function version of this routine.

   ROMDate$ = SPACE$(8)
   PCDate ROMDate$

-------
ROMDate$   date of the BIOS ROM (xx/xx/xx).  Init to 8+ chars.

Name  : PCType               (PC Type)
Class : Equipment
Level : Clone

This routine returns the machine I.D. code.  This code may not
be one of the listed values for some (mostly older) clones, but
the following is usually correct:

   I.D.  ....Machine....
   255   PC or XT
   254   XT
   253   PCjr
   252   PC AT
   251   XT
   250   PS/2 Model 30
   249   PC Convertible
   248   PS/2 Model 70 or 80
   154   Compaq Portable
    45   Compaq Portable

Note that, for identification purposes, a PC and XT are
essentially the same. The XT is simply a PC with an auto-boot
hard drive.  New I.D. numbers come out more or less at random
from IBM, although they aren't as capricious about it as they
used to be.  It is useful to identify Compaq Portables as
separate from PCs because those machines had an unusual
display, which acts like a CGA but has the resolution (in text
modes) of an MDA.  Hence, the cursor size of a Compaq Portable
is MDA-sized in text mode, but CGA-sized in graphics modes,
even though ordinary tests will tell your program that a CGA is
attached.  If you intend to alter the cursor size, this is an
important distinction, since the Compaq Portable was a great
success and is still in wide use.  Current Compaq machines,
like most other clones, follow the standard IBM I.D. codes.

See also PCType2, a function version of this routine.

   PCType MachineID%

-------
MachineID%   type of computer

Name  : PCType2%             (PC Type)
Class : Equipment
Level : Clone

This routine returns the machine I.D. code.  This code may not
be one of the listed values for some (mostly older) clones, but
the following is usually correct:
   I.D.  ....Machine....
   255   PC or XT
   254   XT
   253   PCjr
   252   PC AT
   251   XT
   250   PS/2 Model 30
   249   PC Convertible
   248   PS/2 Model 70 or 80
   154   Compaq Portable
    45   Compaq Portable

Note that, for identification purposes, a PC and XT are
essentially the same. The XT is simply a PC with an auto-boot
hard drive.  New I.D. numbers come out more or less at random
from IBM, although they aren't as capricious about it as they
used to be.  It is useful to identify Compaq Portables as
separate from PCs because those machines had an unusual
display, which acts like a CGA but has the resolution (in text
modes) of an MDA.  Hence, the cursor size of a Compaq Portable
is MDA-sized in text mode, but CGA-sized in graphics modes,
even though ordinary tests will tell your program that a CGA is
attached.  If you intend to alter the cursor size, this is an
important distinction, since the Compaq Portable was a great
success and is still in wide use.  Current Compaq machines,
like most other clones, follow the standard IBM I.D. codes.

   MachineID% = PCType2%

-------
MachineID%   type of computer

Name  : Phone2Num&           (Phone# to Number)
Class : Numeric String
Level : Any

This function converts a U.S. or Canadian phone number from
string form to a long integer.  It accepts phone numbers of 4,
7, 10, or 11 digits.  If there are 11 digits, the first digit
must be a 1.  Non-numeric characters are ignored so that
formatted phone numbers can be used.  If the phone number is of
the wrong length or otherwise does not appear to be valid, -1
is returned; otherwise, the result is a long integer which
represents the phone number in a format that can be decoded by
Num2Phone$.

This function will accept alphabetic phone numbers and convert
them to their numeric equivalents.

Since it only takes 4 bytes to store a long integer, as opposed
to 7 to 10 or more for the usual alphanumeric form, this can be
considered a compression routine as well as a validation
routine.  At worst, for 4-digit phone numbers, it is exactly as
efficient as a character representation.  For 7 or 10-digit
phone numbers, it roughly doubles your storage space.

A few words on how checking is done: obviously, there is no way
to tell whether a number is in use or is in fact whoever you
wished to call.  However, there are certain regularities to
numeric phone numbers which can be used to detect blatantly
false numbers.  Alphabetic phone numbers do not include all the
letters of the alphabet, either.  This routine will check for
any obvious peculiarities and warn you accordingly.

   Result& = Phone2Num&(PhoneNumber$)

PhoneNumber$    phone number (may be formatted)
-------
Result&         encoded phone number (-1 if invalid number)

Name  : PrinterReady%        (Printer Ready)
Class : Printer
Level : BIOS

This function lets you know if a printer is ready.  It checks
to make sure that the specified port exists, then makes sure a
printer is connected, turned on, and has paper in it.

Note that this will not work on serial printers, even if the
MODE command was used to redirect the port.  It works at the
BIOS level, so it doesn't know about any fooling around DOS
does.

   Ready% = PrinterReady%(Port%)

Port%         parallel port number (1-3)
-------
Ready%        whether there's a printer ready at that port

Name  : PrinterInit          (Printer Initialize)
Class : Printer
Level : BIOS

This routine initializes a printer in the same way as if the
computer had been rebooted.

Note that this will not work on serial printers, even if the
MODE command was used to redirect the port.  It works at the
BIOS level, so it doesn't know about any fooling around DOS
does.

   PrinterInit Port%

Port%         parallel port number (1-3)

Name  : PrintFile            (Print File)
Class : Printer
Level : DOS

This routine sends a file to the printer.  It does not
paginate, spool, or anything else fancy.  The LPT1 or PRN
device is used by default, although you can change this using
the PrtSwap routine.

The predefined device handle for stdprn is used, so don't use
FClose to free that handle if you expect to use this routine.
The results would be nasty.

   PrintFile FileName$, ErrCode%

FileName$     name of the file to print
-------
ErrCode%      whether there was an error (0 no, else DOS Error)

Name  : PrintScreen          (Print Screen)
Class : Display / Printer
Level : BIOS

Just like pressing the PrtSc/PrintScrn key on the keyboard,
this routine sends the contents of the display to the printer.
It is mostly designed for text modes, but use of the GRAPHICS
TSR provided with DOS will allow it to print out CGA graphics
displays as well.  For some reason, the GRAPHICS utility does
not handle Hercules, EGA or VGA displays; however, alternative
utilities which provide such features may be obtained from your
local BBS.

   PrintScreen

Name  : Processor            (Processor)
Class : Equipment
Level : Any

Processor returns the type of processor (CPU) installed.

Results are returned as follows:

   0    NEC V20
   1    8088 or 8086
   2    80186
   3    80286
   4    80386 or 80486

If anyone can tell me how to better handle a 486 here, I'd
appreciate it.

Note that, for most practical purposes, a NEC V20 works just
like an 80186.

   Processor ProcType%

-------
ProcType%    type of CPU (see above)

Name  : Processor2%          (Processor)
Class : Equipment
Level : Any

Processor returns the type of processor (CPU) installed.

Results are returned as follows:

   0    NEC V20
   1    8088 or 8086
   2    80186
   3    80286
   4    80386 or 80486

If anyone can tell me how to better handle a 486 here, I'd
appreciate it.

   ProcType% = Processor2%

-------
ProcType%    type of CPU (see above)

Name  : PrtSc                (Print Screen key)
Class : Input / Printer
Level : BIOS

This routine allows you to disable the "print screen" key.
This only affects the keyboard, not the PrintScreen routine in
PBClone.

If you disable the "print screen" key, be sure to enable it
again before your program ends.  Otherwise, the "print screen"
key will be left in an undefined state, probably causing the
computer to crash when it is next pressed.

   PrtSc Enable%

Enable%   whether "print screen" should be enabled (0 no)

Name  : PrtSwap              (Printer Swap)
Class : Printer
Level : Clone

It's handy to use LPRINT, but it isn't always practical.
LPRINT only works on the first printer available (PRN or
LPT1).  With this routine, it doesn't matter.  PrtSwap allows
you to swap any two printer ports.

Note that it's a good idea to swap the ports back to their
original locations before exiting your program.  You could
cause major confusion otherwise!

   PrtSwap Port1%, Port2%

Port1%    number of the first port (1-3)
Port2%    number of the second port (1-3)

Name  : PSortD               (Pointer Sort Double precision)
Class : Array management
Level : Any

This routine sorts the elements in a double precision array...
well, actually, it doesn't change the position of anything in
the double precision array.  It sorts the array using a set of
pointers to the array.  You can then use the pointers to refer
to the array or to re-order the array yourself.

Why bother with pointers?  Well, it's a lot faster than sorting
the numbers directly, since less information has to be
swapped.  It has another major advantage, though-- it allows
you to sort an array without losing track of how it corresponds
to any related arrays.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

The pointer array must be initialized so that each element is
equal to its index.  Either use InitPtr or do:
   FOR tmp% = 1 TO Elements%
      Ptr%(tmp%) = tmp%
   NEXT

After this routine, you can access the sorted array via the
pointer array. For instance, to print out a sorted double
precision array, you'd use:
   FOR tmp% = 1 TO Elements%
      PRINT Array#(Ptr%(tmp%))
   NEXT

If you would like the results to be last-to-first, rather than
first-to-last, just call ReverseI to reverse the pointer array
(after this routine).

   PSortD Ptr%(), Array#(), Elements%

Ptr%()      pointers to array to be sorted
Array#()    array to be sorted
Elements%   number of elements in array
-------
Ptr%()      pointers which allow accessing array in sorted order

Name  : PSortI               (Pointer Sort Integer)
Class : Array management
Level : Any

This routine sorts the elements in an integer array... well,
actually, it doesn't change the position of anything in the
integer array.  It sorts the array using a set of pointers to
the array.  You can then use the pointers to refer to the array
or to re-order the array yourself.

Why bother with pointers?  It has a major advantage-- it allows
you to sort an array without losing track of how it corresponds
to any related arrays.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

The pointer array must be initialized so that each element is
equal to its index.  Either use InitPtr or do:
   FOR tmp% = 1 TO Elements%
      Ptr%(tmp%) = tmp%
   NEXT

After this routine, you can access the sorted array via the
pointer array. For instance, to print out a sorted integer
array, you'd use:
   FOR tmp% = 1 TO Elements%
      PRINT Array%(Ptr%(tmp%))
   NEXT

If you would like the results to be last-to-first, rather than
first-to-last, just call ReverseI to reverse the pointer array
(after this routine).

   PSortI Ptr%(), Array%(), Elements%

Ptr%()      pointers to array to be sorted
Array%()    array to be sorted
Elements%   number of elements in array
-------
Ptr%()      pointers which allow accessing array in sorted order

Name  : PSortL               (Pointer Sort Long integer)
Class : Array management
Level : Any

This routine sorts the elements in a long integer array...
well, actually, it doesn't change the position of anything in
the long integer array.  It sorts the array using a set of
pointers to the array.  You can then use the pointers to refer
to the array or to re-order the array yourself.

Why bother with pointers?  Well, it's a lot faster than sorting
the numbers directly, since less information has to be
swapped.  It has another major advantage, though-- it allows
you to sort an array without losing track of how it corresponds
to any related arrays.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

The pointer array must be initialized so that each element is
equal to its index.  Either use InitPtr or do:
   FOR tmp% = 1 TO Elements%
      Ptr%(tmp%) = tmp%
   NEXT

After this routine, you can access the sorted array via the
pointer array. For instance, to print out a sorted long integer
array, you'd use:
   FOR tmp% = 1 TO Elements%
      PRINT Array&(Ptr%(tmp%))
   NEXT

If you would like the results to be last-to-first, rather than
first-to-last, just call ReverseI to reverse the pointer array
(after this routine).

   PSortL Ptr%(), Array&(), Elements%

Ptr%()      pointers to array to be sorted
Array&()    array to be sorted
Elements%   number of elements in array
-------
Ptr%()      pointers which allow accessing array in sorted order

Name  : PSortS               (Pointer Sort Single precision)
Class : Array management
Level : Any

This routine sorts the elements in a single precision array...
well, actually, it doesn't change the position of anything in
the single precision array.  It sorts the array using a set of
pointers to the array.  You can then use the pointers to refer
to the array or to re-order the array yourself.

Why bother with pointers?  Well, it's a lot faster than sorting
the numbers directly, since less information has to be
swapped.  It has another major advantage, though-- it allows
you to sort an array without losing track of how it corresponds
to any related arrays.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

The pointer array must be initialized so that each element is
equal to its index.  Either use InitPtr or do:
   FOR tmp% = 1 TO Elements%
      Ptr%(tmp%) = tmp%
   NEXT

After this routine, you can access the sorted array via the
pointer array. For instance, to print out a sorted single
precision array, you'd use:
   FOR tmp% = 1 TO Elements%
      PRINT Array!(Ptr%(tmp%))
   NEXT

If you would like the results to be last-to-first, rather than
first-to-last, just call ReverseI to reverse the pointer array
(after this routine).

   PSortS Ptr%(), Array!(), Elements%

Ptr%()      pointers to array to be sorted
Array!()    array to be sorted
Elements%   number of elements in array
-------
Ptr%()      pointers which allow accessing array in sorted order

Name  : PSortSt              (Pointer Sort String)
Class : Array management
Level : Any

This routine sorts the elements in a string array... well,
actually, it doesn't change the position of anything in the
string array.  It sorts the array using a set of pointers to
the array.  You can then use the pointers to refer to the array
or to re-order the array yourself.

Why bother with pointers?  Well, it's a lot faster than sorting
the strings directly, since less information has to be
swapped.  It has another major advantage, though-- it allows
you to sort an array without losing track of how it corresponds
to any related arrays.  For instance, if you have one array
holding names and another holding phone numbers, this allows
you to sort on names without losing track of which phone
numbers are which.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.  You can also specify whether the
capitalization of letters in a string should matter for sorting
purposes.

The pointer array must be initialized so that each element is
equal to its index.  Either use InitPtr or do:
   FOR tmp% = 1 TO Elements%
      Ptr%(tmp%) = tmp%
   NEXT

After this routine, you can access the sorted array via the
pointer array. For instance, to print out a sorted string
array, you'd use:
   FOR tmp% = 1 TO Elements%
      PRINT Array$(Ptr%(tmp%))
   NEXT

If you would like the results to be last-to-first, rather than
first-to-last, just call ReverseI to reverse the pointer array
(after this routine).

   PSortSt Ptr%(), Array$(), Elements%, CapsCount%

Ptr%()      pointers to array to be sorted
Array$()    array to be sorted
CapsCount%  use 0 if uppercase/lowercase distinctions don't matter
Elements%   number of elements in array
-------
Ptr%()      pointers which allow accessing array in sorted order

Name  : PutScreen            (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).

If you wish to restore the entire screen, you may find ScrRest
easier (see).

   PutScreen Array%(), TRow%, LCol%, BRow%, RCol%, Page%, Fast%

Array%()   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  : QPrint               (Quick Print)
Class : Display
Level : Clone

This is a replacement for the PRINT statement.  It is less
flexible in that it does not move the cursor or interpret
control codes, and because it uses the color that is already on
the screen instead of a specified color value. It also works
only in text modes.

In exchange, QPrint gives you much faster display speeds.

See also XQPrint, which is a bit more flexible (and somewhat
slower).

   QPrint St$, Row%, Column%, Page%, Fast%

St$        text to display
Row%       starting row
Column%    starting column
Page%      page on which to display
Fast%      whether to use fast mode (0 no)

Name  : Rand%                (Random number)
Class : Numeric
Level : Clone

This is a pseudo-random number function.  It returns a "random"
number in a range you specify (e.g., if you pass it 10, it will
return 0-9).  The number is less random than you'd get from the
BASIC function RND, and you can't set a random number seed a la
RANDOMIZE.  There is one major advantage to Rand%, however: it
doesn't bring in BASIC's floating point support, which makes it
much faster than RND and may make your program much smaller.

   Number% = Rand%(Range%)

Range%      range of desired pseudo-random number
-------
Number%     pseudo-random number from 0 to Range% - 1

Name  : ReadBitF             (Read Bit Field)
Class : Numeric
Level : Any

This routine allows you to get an element of a virtual array.
The actual array can be any numeric type, as it is just being
used as a storage area. The virtual array is composed of
numbers of a bit length that you specify (1-8).  This provides
efficient storage for numbers which have a limited range.

See also WriteBitF.

   ReadBitF DSeg%, DOfs%, ElementNr&, BitLen%, Value%

DSeg%        segment of actual array
DOfs%        offset of actual array
ElementNr&   virtual element number (starts at 0)
BitLen%      bits per virtual element (1-8)
-------
Value%       result (0-255 or less, depending on BitLen%)

Name  : Reboot               (Reboot)
Class : Miscellaneous
Level : Clone

This routine restarts the computer, just like typing
Control-Alt-Del at the keyboard.

   Reboot

Name  : Recolor              (Recolor)
Class : Display
Level : Clone

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

   Recolor OldAttr%, NewAttr%

OldAttr%   color to be changed
NewAttr%   color to which to change

Name  : RecolorArea          (Recolor Area)
Class : Display
Level : Clone

The RecolorArea 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.

   RecolorArea TRow%, LCol%, BRow%, RCol%, Attr%, Page%, Fast%

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
Page%       display page (normally zero)
Fast%       whether to use fast mode (0 no)

Name  : RedirectIn%          (Redirect Input)
Class : Miscellaneous
Level : DOS

The RedirectIn% function allows you to determine whether input
has been redirected.  This lets you know whether input is
coming from the keyboard or from a file or device.

Input that is done by BIOS key routines (e.g., BIOSInkey) is
not affected by redirection, so if you want to support
redirection it is best to avoid such routines unless there is
something that must come from the keyboard.

   Redir% = RedirectIn%

-------
Redir%     whether input has been redirected (0 no)

Name  : RedirectOut%         (Redirect Output)
Class : Miscellaneous
Level : DOS

The RedirectOut% function allows you to determine whether
output has been redirected.  This lets you know whether output
is going to the display or to a file or device.

Output that is done by direct screen writes (e.g., XQPrint) is
not affected by redirection, so if you want to allow
redirection it is best to avoid such routines unless there is
something that must to go to the screen itself.

   Redir% = RedirectOut%

-------
Redir%     whether output has been redirected (0 no)

Name  : Rename               (Rename file)
Class : Disk
Level : DOS

This routine allows you to rename an ordinary file.  See also
RenSub.

   Rename CurrentName$, NewName$, ErrCode%

CurrentName$   current name of the file
NewName$       desired name of the file
-------
ErrCode%       error code: 0 if no error, else DOS Error

Name  : RenSub               (Rename Subdirectory)
Class : Disk
Level : DOS

This routine provides a service that was inexplicably left out
of the DOS command shell.  It allows you to rename a
subdirectory.

Note that renaming a subdirectory is only possible using
old-style FCB file handling.  This means that the subdirectory
which you specify must be in the current directory (the routine
doesn't really understand subdirectories per se, but treats
them like any other file).  In this implementation, no drive
specification is allowed either.  Finally, if there is an
error, the error code may be a simple "255" instead of a useful
disk error number.

   RenSub CurrentSub$, NewSub$, ErrCode%

CurrentSub$   current name of the subdirectory
NewSub$       desired name of the subdirectory
-------
ErrCode%      error code: 0 if no error, else DOS Error

Name  : Replace              (Replace character)
Class : String
Level : Any

This routine replaces all occurrences of a given character in a
string with another character.

   Replace St$, CurCh$, NewCh$

St$         string to process
CurCh$      character to be replaced
NewCh$      character to replace with
-------
St$         processed string

Name  : ReplaceString        (Replace String)
Class : String
Level : Any

This routine replaces all occurrences of a given substring
within a string with another substring.  The substrings may be
of any length.

An error code will be returned if the string to search for is
null.

   ReplaceString St$, Old$, New$, Found%, ErrCode%

St$         string to process
Old$        substring to be replaced
New$        substring to replace with
-------
Found%      whether a replacement was done (0 if no)
ErrCode%    whether there was an error (0 if no)

Name  : Retries              (Retries)
Class : Disk
Level : DOS 3.1+

This routine allows you to adjust the handling of file-sharing
errors.  When such an error occurs, DOS normally retries 3
times, with a wait of 1 between tries.  This allows temporary
conditions, such as someone else using the file you want to
access, to clear up.  In many cases, though, you may want to
change this delay.  A shorter delay will improve response time,
allowing your program to handle the error more quickly.  A
longer delay may be more suited for a busy network, allowing
the request to proceed after a reasonable waiting period.

The delay period between each retry is unfortunately
machine-dependent, i.e., you will need larger delays on faster
machines to achieve the same effect. This can only be
considered a flaw in DOS.

Note that shorter waiting periods will improve response time
for your program, but may adversely affect the network.
Normally, you should use the longest waiting period with which
you feel comfortable.

   Retries Times%, WaitTime%

Times%     # of times to retry if file-sharing violation occurs
WaitTime%  amount of time to delay between retries

Name  : Reverse              (Reverse)
Class : String
Level : Any

This little fellow reverses the order of the characters in a
string.  It is one of the vital components of RInstr, but other
than that I see no real use for it.  On the other hand, George
Boole thought that Boolean logic was of solely theoretical
interest, and yet without it there would be no computers. I
leave it to you to find the earth-shattering possibilities of
Reverse!

   Reverse St$

St$      string to be reversed
-------
St$      reversed string

Name  : ReverseD             (Reverse Double precision array)
Class : Array management
Level : Any

This routine reverses the elements in an array of
double-precision numbers. This will probably be most useful for
an array sorted by SortD, in case you want the numbers to go
from largest to smallest.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to reverse only
part of an array if you like.

   ReverseD Array#(), Elements%

Array#()    array to be reversed
Elements%   number of elements in array
-------
Array#()    reversed array

Name  : ReverseI             (Reverse Integer array)
Class : Array management
Level : Any

This routine reverses the elements in an array of integers.
This will probably be most useful for an array sorted by SortI,
or a pointer array used in PSortD, PSortI, PSortL, PSortS, or
PSortSt, in case you want the values to go from largest to
smallest.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to reverse only
part of an array if you like.

   ReverseI Array%(), Elements%

Array%()    array to be reversed
Elements%   number of elements in array
-------
Array%()    reversed array

Name  : ReverseL             (Reverse Long integer array)
Class : Array management
Level : Any

This routine reverses the elements in an array of long
integers.  This will probably be most useful for an array
sorted by SortL, in case you want the values to go from largest
to smallest.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to reverse only
part of an array if you like.

   ReverseL Array&(), Elements%

Array&()    array to be reversed
Elements%   number of elements in array
-------
Array&()    reversed array

Name  : ReverseS             (Reverse Single precision array)
Class : Array management
Level : Any

This routine reverses the elements in an array of
single-precision numbers. This will probably be most useful for
an array sorted by SortS, in case you want the numbers to go
from largest to smallest.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to reverse only
part of an array if you like.

   ReverseS Array!(), Elements%

Array!()    array to be reversed
Elements%   number of elements in array
-------
Array!()    reversed array

Name  : ReverseSt            (Reverse String array)
Class : Array management
Level : Any

This routine reverses the elements in a string array.  This
will probably be most useful for an array sorted by SortSt, in
case you want the strings to be in reverse-alphabetical order.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to reverse only
part of an array if you like.

   ReverseSt Array$(), Elements%

Array$()    array to be reversed
Elements%   number of elements in array
-------
Array$()    reversed array

Name  : RInstr               (Reverse INSTR)
Class : String
Level : Any

Like INSTR, this routine tells you the position of a substring
within a string.  A "reverse" search is used, however-- whereas
INSTR tells you the first match, RInstr tells you the last
match.  Similarly, whereas INSTR will tell you that a null
search string matches the main string at the first position,
RInstr will match on the last position.  Of course, most of the
time you won't be searching for a null string!

   RInstr MainSt$, SeekSt$, Posn%

MainSt$    string to search
SeekSt$    string for which to search
-------
Posn%      position of substring within main string (0 no match)

Name  : RolSt                (Rotate Left String of bits)
Class : String
Level : Any

This routine rotates the bits in a string left by a desired
amount.  This may be helpful for manupulating strings
containing bit flags, images, et al.

   RolSt St$, Count%

St$       string to rotate left
Count%    bits by which to rotate
-------
St$       rotated string

Name  : RorSt                (Rotate Right String of bits)
Class : String
Level : Any

This routine rotates the bits in a string right by a desired
amount.  This may be helpful for manupulating strings
containing bit flags, images, et al.

   RorSt St$, Count%

St$       string to rotate right
Count%    bits by which to rotate
-------
St$       rotated string

Name  : RRotate              (Right Rotate String)
Class : String
Level : Any

This routine rotates the characters in a string right once.
I'll admit that I haven't found a use for this myself, but
people are always coming up with new uses for things... and it
complements the more useful LRotate routine.

See also LRotate.

   RRotate St$

St$      string to be rotated right once
-------
St$      string after being rotated right once

Name  : RScroll              (Right Scroll)
Class : Display
Level : Clone

This routine scrolls any selected part of the display right.
You may scroll as many times as you like, or scroll "zero"
times to totally clear the selected part of the display.

   RScroll 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  : ScanKey              (Scan Keyboard)
Class : Input
Level : BIOS

This one's like INKEY$, but a little bit more subtle.  It will
tell you if there's a key waiting (and if so, what key it is)
without actually getting the key.  The key will remain
available for later retrieval.

Among the more common uses for this routine is to handle keys
like Control-S (pause the display) and Control-C (abort).  You
can see if these keys have been pressed without disturbing
anything else the user might have typed.  DOS uses exactly this
technique for handling these keys.  Since BASIC doesn't go
through DOS I/O, though, the only way for you to support such
nice features is to write them into your program with ScanKey.

   ScanKey CharCode%, CharType%

-------
CharType%   key type: 0 none, 1 normal, 2 extended (scan code)
CharCode%   key ASCII or scan code

Name  : Scroll               (Scroll)
Class : Display
Level : BIOS

This routine scrolls any selected part of the display up.  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.

   Scroll 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  : ScrRest              (Screen Restore)
Class : Display
Level : Clone

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

   ScrRest Array%(), Page%, Fast%

Array%()   array holding the display information
Page%      page on which to restore the display
Fast%      whether to use fast mode (0 no)

Name  : ScrSave              (Screen Save)
Class : Display
Level : Clone

The ScrSave routine saves the display to an integer array.
Only text modes are supported.  For an 80x25 display, the array
must hold 4,000 bytes, so you would use DIM Array%(1 TO 2000).

   ScrSave Array%(), Page%, Fast%

Page%      display page to get
Fast%      whether to use fast mode (0 no)
-------
Array%()   saved display information

Name  : Scrunch              (Screen Crunch)
Class : Display
Level : Any

This routine is designed to be used in conjunction with ScrSave
and the other routines which store an entire 80x25 text screen
in an array.  It performs a "screen crunch", compressing the
original data into a new array.  The average result is about 8x
smaller than the original screen, resulting in a vast savings
in memory (4,000 bytes vs 500 or so).  The compression
algorithm is very fast and will not take any noticeable amount
of time for most purposes.

Besides saving main memory, this is great for storing screens
as disk files! The compression will not only make the file(s)
smaller, but will make disk access much faster since there is
less information to transfer.

   Scrunch DSeg%, DOfs%, CSeg%, COfs%, Bytes%

DSeg%     segment of the original screen image
DOfs%     offset of the original screen image
CSeg%     segment of array in which to store compressed image
COfs%     offset of array in which to store compressed image
-------
Bytes%    number of bytes in the compressed image

Name  : Sec2Time$            (Seconds to Time)
Class : Time
Level : Any

This routine converts the number of seconds past midnight into
a time string.

   TimeSt$ = Sec2Time$(Seconds&)

Seconds&   number of seconds past midnight
-------
TimeSt$    time string (TIME$ format)

Name  : SetBit               (Set Bit)
Class : Numeric
Level : Any

This routine sets a single bit "on" in an integer.  Bits are
numbered 0-15, with 0 being the least significant bit.

   SetBit Number%, BitNr%

Number%    number for which to set bit
BitNr%     bit number (0-15) to set
-------
Number%    number with the specified bit set

Name  : SetCGAColor          (Set CGA Color)
Class : Display
Level : Clone

This routine allows you to set certain aspects of CGA colors
which aren't available otherwise.  It is very CGA-specific,
however, and may not work on EGA or VGA systems.

The color specified has different meanings in different CGA
modes.  In the SCREEN 1 graphics mode, it changes the
background and border color.  In SCREEN 2, however, it allows
you to change the foreground color.  While you are still stuck
with a single foreground color, you can choose what that color
will be.

   SetCGAColor Colour%

Colour%    color to set (see above)

Name  : SetComm              (Set Comm port)
Class : Serial
Level : DOS

Although QuickBASIC has a fair range of communications support,
it doesn't do the capabilities of the PC full justice.  It's
also impossible to change the serial parameters "on the fly"
without risking disconnection, if BASIC alone is used.  SetComm
gets around those limitations.  It should be used -after- the
appropriate comm port is OPENed by BASIC.

Note that the true upper limits of the comm speed are
determined by your program and by the hardware being used.
Some PC/XTs may have trouble with 9,600 bps, for instance.  The
ability to set the serial port to a high speed doesn't
guarantee that the hardware can handle it!

   SetComm CommPort%, Bps%, Parity%, WordLength%, StopBits%

CommPort%    serial port (1-4, though BASIC only uses 1-2)
Bps%         bits per second ("baud rate"):
                0 for   300       5 for   9,600
                1 for   600       6 for  19,200
                2 for 1,200       7 for  38,400
                3 for 2,400       8 for  57,600
                4 for 4,800       9 for 115,200
Parity%      parity:
                0  none
                1  odd            3  mark  (always on)
                2  even           4  space (always off)
WordLength%  word length (5-8)
StopBits%    stop bits (1-2; if WordLength=5, "2" means 1 1/2)

Name  : SetCommAddr          (Set Comm Address)
Class : Serial
Level : Clone

This routine allows you to set the base port address of a
serial port.

One use for SetCommAddr is to give QuickBASIC access to the
comm port on those unusual machines which have a COM2 but no
COM1.  Use GetCommAddr to get the address of COM2, set the COM1
address accordingly, and tell QuickBASIC to use COM1.

BASIC will normally handle COM1 and COM2, but not COM3 or
COM4.  Although there is no way to use more two ports at once,
you can fool BASIC into using COM3 by swapping it with COM1, or
COM4 by swapping it with COM2.

Don't forget to set the ports back to their original values
before your program ends!

   SetCommAddr PortNr%, PortAddr%

PortNr%     COM port number (1-4)
PortAddr%   port address

Name  : SetDateAT            (Set Date of AT clock)
Class : Time
Level : BIOS (AT)

This routine sets the date of the hardware real-time clock in
AT-class computers.  Depending on the DOS version, this date
may be partially or completely independent of the date kept by
DOS in software.  DOS always reads the date from the hardware
clock when it starts up.  However, use of the DATE command in
DOS (and the DATE$ function in QuickBASIC) may relate only to
the software copy of the date, which is not always guaranteed
to be the same as the date in the hardware clock due to certain
discrepancies in DOS.

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.

   SetDateAT MonthNr%, Day%, Year%

MonthNr%    month number (1-12)
Day%        day (1-31)
Year%       year (1980-2079; see above for two-digit years)

Name  : SetDrv               (Set default Drive)
Class : Disk
Level : DOS

This routine sets the default disk drive.

If the specified drive does not exist, the current default
drive will remain the default.

   SetDrv Drive$

Drive$    drive letter

Name  : SetError             (Set Error code)
Class : Miscellaneous
Level : DOS

The SetError routine allows you to set the "error level" to be
returned by DOS when your program ends.  This is particularly
handy for returning information to batch files.

Note that SetError is best used just before your program ENDs,
to avoid complications.

   SetError ErrorLevel%

ErrorLevel%   exit code to be returned by your program

Name  : SetFAttr             (Set File Attribute)
Class : Disk
Level : DOS

This routine allows you to set the attribute of a file or
subdirectory.  Any combination of the following may be set:

   Normal          0      (nothing special)
   Read Only       1      file can be read, but not written to
   Hidden          2      file will be "invisible"
   System          4      (for special DOS files-- leave alone)
   Archive        32      (used by some backup utils- leave be)

To set more than one attribute, just add the numbers for the
desired attributes together.  The attributes marked "leave
alone" shouldn't be used casually, but if you're sure you know
what you're doing...

   SetFAttr FileName$, Attr%

FileName$   name of the file (or subdirectory) to manipulate
Attr%       attribute(s) to set

Name  : SetFTD               (Set File Time and Date)
Class : Disk
Level : DOS

This routine lets you set the time and date of a specified
file.  You may give the year either as two digits or four
digits.

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 DOS date format does not allow dates before 1980
anyway, so nothing is being lost by this change.

Note that the Second% value, if odd, will be rounded down to an
even number. This is due to the way DOS compresses the time
format, rather than any limitation in this routine.

   SetFTD File$, MonthNr%, Day%, Year%, Hour%, Minute%, Second%

File$        name of file for which to set the time and date
MonthNr%     month number (1-12)
Day%         day (1-31)
Year%        year (1980-2079; see above for two-digit years)
Hour%        hour (0-23)
Minute%      minute (0-59)
Second%      second (0-59; if odd, rounded down to even number)
-------
MonthNr%     -1 if there was an error, else unchanged

Name  : SetKbd               (Set Keyboard toggles)
Class : Input
Level : Clone

The SetKbd routine allows you to set the state of any of the
four keyboard toggles: Insert, Caps lock, Num lock, and Scroll
Lock.  You can give your input routines a professional touch by
setting this toggles instead of making the user remember to do
so.

It's considered proper to restore the original keyboard toggles
before your program exits, unless of course the purpose of the
program is to leave the toggles in a particular state!  The
GetKbd routine can be used in conjunction with SetKbd to do
this.

   SetKbd Insert%, Caps%, Num%, Scrl%

Insert%    whether to turn on "insert" mode (0 if no)
Caps%      whether to turn on "caps lock" (0 if no)
Num%       whether to put the keypad into numeric mode (0 no)
Scrl%      whether to turn on "scroll lock" (0 if no)

Name  : SetLabel             (Set disk volume Label)
Class : Disk
Level : DOS

This routine creates, renames or deletes a disk volume label.

Note that a disk volume label is essentially a file name
without an extension.  It can contain any character that can
normally be in a file name, plus spaces and periods.

   SetLabel Drive$, Label$, ErrCode%

Drive$     drive to set label on (use "" for current drive)
Label$     label to install (use "" to delete current label)
-------
ErrCode%   whether there was an error (0 no)

Name  : SetMatI              (Set Matrix to Integer)
Class : Numeric
Level : Any

This routine sets as many elements of an integer array as you
like, starting at a specified place in the array.  A good use
for it is to initialize an array (or a portion of it) to a
given value.

   SetMatI DSeg%, DOfs%, Elements%, Value%

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 which to set each array element

Name  : SetMatL              (Set Matrix to Long)
Class : Numeric
Level : Any

This routine sets as many elements of an long integer array as
you like, starting at a specified place in the array.  A good
use for it is to initialize an array (or a portion of it) to a
given value.

   SetMatL DSeg%, DOfs%, Elements%, Value&

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 which to set each array element

Name  : SetMouseLoc          (Set Mouse Location)
Class : Mouse
Level : BIOS

This routine allows you to set the current location of the
mouse cursor.  It doesn't matter if the cursor is visible or
invisible.  SetMouseLoc is only for use in text mode.

This routine will not work properly if there is no mouse
available.  Use the MMCheck routine if you are not sure.

See also MMSetLoc, which is for use in graphics modes.

   SetMouseLoc Row%, Column%

Row%       mouse cursor row
Column%    mouse cursor column

Name  : SetPatch             (Set Patch information)
Class : Disk
Level : DOS

This routine is used after FindPatch.  The FindPatch routine
finds the first DATA statement to be patched.  SetPatch places
new information in that DATA statement and moves the file
pointer to the position of the next DATA statement.  Note that
there must be only one item per DATA statement; this item must
be a quoted string.  The string in the DATA statement and the
patch string must be the same length.

If you need this routine to be able to handle variable-length
strings, don't fret!  Make the DATA string one character longer
than the maximum you need, and use the extra character to
indicate the actual string length:
   SetPatch CHR$(LEN(St$)) + St$
Then when you READ St$, decode it like so:
   St$ = MID$(St$, 2, ASC(St$))

Routines in this set include FindPatch, SetPatch, PatchDone.

   SetPatch St$

St$       string to patch into the current DATA statement

Name  : SetPrtAddr           (Set Printer Address)
Class : Printer
Level : Clone

This routine allows you to set the base port address of a
parallel port.

One use for this routine is to fool BASIC into using a
different port than LPT1 for LPRINT.  See also PRTSWAP.

Note that PS/2 systems only have ports 1-3 available.  They use
the fourth port data area for holding other information.  It
may be a good idea to restrict yourself to ports 1-3 for
compatibility purposes, although other computers allow ports
1-4.

Don't forget to set the ports back to their original values
before your program ends!

   SetPrtAddr PortNr%, PortAddr%

PortNr%     LPT port number (1-4 or 1-3 [see above])
PortAddr%   port address

Name  : SetSub               (Set default Subdirectory)
Class : Disk
Level : DOS

Just like the DOS CD (or CHDIR) command, this routine allows
you to change the current subdirectory.  Unlike the
corresponding DOS command, you may not use a period or double
period as shorthand for a directory.  However, you may specify
either an absolute or relative path, as usual, and can also use
either slashes or backslashes as delimiters.

   SetSub SubDir$, ErrCode%

SubDir$    subdirectory name
-------
ErrCode%   error code: 0 if no error, else a DOS Error number

Name  : SetTimeAT            (Set Time of AT clock)
Class : Time
Level : BIOS (AT)

This routine sets the time to the hardware real-time clock in
AT-class computers.  Depending on the DOS version, this time
may be partially or completely independent of the time kept by
DOS in software.  DOS always reads the time from the hardware
clock when it starts up.  However, use of the TIME command in
DOS (and the TIME$ function in QuickBASIC) may relate only to
the software copy of the time, which is not always guaranteed
to be the same as the time in the hardware clock due to certain
discrepancies in DOS.

   SetTimeAT Hour%, Minute%, Second%

Hour%      hour (0-23)
Minute%    minute
Second%    second

Name  : SetVerify            (Set Verify state)
Class : Disk
Level : DOS

The SetVerify routine allows you to set the state of the DOS
VERIFY flag. When VERIFY is on, some checking is done to make
sure that writing to the disk works as requested.  The checks
are not very good, however, and VERIFY slows down disk
handling, so it is usually better to have VERIFY off.

   SetVerify VerifyOn%

VerifyOn%   whether to turn VERIFY on (0 if no)

Name  : SetVGAPalette        (Set VGA Palette)
Class : Display
Level : BIOS

This routine allows you to set any number of the VGA palette
values from a TYPEd array.  The TYPE for the array should be
defined like this:

   TYPE Palet
      IRed AS STRING * 1
      IBlue AS STRING * 1
      IGreen AS STRING * 1
   END TYPE

This type holds a CHR$-encoded representation of the intensity
of each component of the color.  The values range from 0-63.

You can change many palette settings at a time, very quickly,
with this routine.  This routine is sufficiently faster than
the BASIC PALETTE statement as to make palette animation (and
some stupendous special effects) possible.  It may cause
flickering on displays with less well-designed video BIOS
chips, however.

   SetVGAPalette DSeg%, DOfs%, Start%, Colors%

DSeg%      segment of the palette array
DOfs%      offset of the palette array
Start%     color number to start with
Colors%    number of colors to set

Name  : SFRead               (String File Read)
Class : Disk / String
Level : DOS

This routine reads a string from a file that was opened by
FOpen or FCreate. The length of the string you provide
determines how many characters should be read.  If it wasn't
possible to read all the characters desired, an error code will
be returned and the BytesRead% value will tell you how many
characters were actually retrieved.

   St$ = SPACE$(BytesToRead%)
   SFRead Handle%, St$, BytesRead%, ErrCode%

Handle%     handle of the file from which to read
-------
St$         data read from the file.  Init to # of chars wanted
BytesRead%  number of bytes read from the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : SFWrite              (String File Write)
Class : Disk / String
Level : DOS

This routine writes a string to a file that was opened by FOpen
or FCreate. The length of the string you provide determines how
many characters will be written.  If it wasn't possible to
write the entire string to the file, an error code will be
returned and the BytesWrit% value will tell you how many
characters were actually written.

   SFWrite Handle%, St$, BytesWrit%, ErrCode%

Handle%     handle of the file to which to write
St$         data to write to the file.
-------
BytesWrit%  number of bytes written to the file (if error)
ErrCode%    error code: 0 if no error, else DOS Error

Name  : ShiftL               (Shift Left)
Class : Numeric
Level : Any

This routine shifts the bits in an integer left by a desired
amount.  The effect of this is similar to multiplying the
number by a power of two, if the number is positive, but is
much faster.

   ShiftL Value%, Count%

Value%    number to shift left
Count%    bits by which to shift
-------
Value%    shifted number

Name  : ShiftLL              (Shift Left Long)
Class : Numeric
Level : Any

This routine shifts the bits in a long integer left by a
desired amount.  The effect of this is similar to multiplying
the number by a power of two, if the number is positive, but is
much faster.

   ShiftLL Value&, Count%

Value&    number to shift left
Count%    bits by which to shift
-------
Value&    shifted number

Name  : ShiftR               (Shift Right)
Class : Numeric
Level : Any

This routine shifts the bits in an integer right by a desired
amount.  The effect of this is similar to dividing the number
by a power of two, if the number is positive, but is much
faster.

   ShiftR Value%, Count%

Value%    number to shift right
Count%    bits by which to shift
-------
Value%    shifted number

Name  : ShiftRL              (Shift Right Long)
Class : Numeric
Level : Any

This routine shifts the bits in a long integer right by a
desired amount. The effect of this is similar to dividing the
number by a power of two, if the number is positive, but is
much faster.

   ShiftRL Value&, Count%

Value&    number to shift right
Count%    bits by which to shift
-------
Value&    shifted number

Name  : ShlSt                (Shift Left String of bits)
Class : String
Level : Any

This routine shifts the bits in a string left by a desired
amount.  This may be helpful for manupulating strings
containing bit flags, images, et al.

   ShlSt St$, Count%

St$       string to shift left
Count%    bits by which to shift
-------
St$       shifted string

Name  : ShrSt                (Shift Right String of bits)
Class : String
Level : Any

This routine shifts the bits in a string right by a desired
amount.  This may be helpful for manupulating strings
containing bit flags, images, et al.

   ShrSt St$, Count%

St$       string to shift right
Count%    bits by which to shift
-------
St$       shifted string

Name  : SInput               (String Input)
Class : Input
Level : Clone

This is a flexible line input routine which supports WordStar
and DOS-style editing, default entries, key screening, and any
number of other options.  To keep SInput manageable, the less
volatile parameters are set with separate routines instead of
being passed directly.

The St$ parameter must be set to the maximum desired input
length.  It may also contain a default entry, in which case
SLen% should be set to the length of the default entry (set
SLen% to zero if there is no default entry).

Character screening is done through selection of valid
character types.  This may be any combination of the following
(add the desired types together):

    1    letters
    2    digits
    4    symbols
   16    graphics (ASCII 128-255)
   32    spaces

You can use -1 to allow any character.  You can also make use
of the NOT operator, e.g. NOT 2 allows everything but digits.

The ExitCode% returns the key used to terminate input.  This
will normally be 13 (return) or 27 (esc), but other results may
be returned depending on how you use the various SInputSet
routines.  Note that the cursor position is not altered when
SInput exits, to avoid accidentally scrolling your screen.  You
are left with full control over the cursor.

The SInput routine is designed with the idea of input forms and
windows in mind.  It is not capable of handling more than one
line of text at a time. It also doesn't know how to wrap at the
edge of the screen.

Routines in this series include:
   SInput, SInputSet, SInputSet1, SInputSet2

Since everyone has their own ideas about the perfect input
routine, I have recoded SInput largely in BASIC to allow
registered PBClone owners to modify it easily.  I've gotten a
huge number of requests for SInput modifications in the past;
hopefully this will be the best solution!

   SInput St$, SLen%, Valid%, MustFill%, Attr%, ExitCode%

St$         init to max length of input (may hold default)
SLen%       length of default entry (0 if none)
Valid%      valid character types (see above)
MustFill%   whether input field must be totally filled (0 no)
Attr%       color/attribute for input (see CalcAttr)
-------
St$         entered string
SLen%       length of entered string
ExitCode%   key used to exit (13 for <CR> or 27 for <ESC>)

Name  : SInputSet            (String Input Settings)
Class : Input
Level : Clone

This is one of a number of routines which allow you to modify
the default operation of SInput.

If you allow extended keys (like Alt keys and function keys) to
exit SInput, the ExitCode% parameter will return the negative
scan code of the key.

Routines in this series include:
   SInput, SInputSet, SInputSet1, SInputSet2

   SInputSet FillCh$, ExtExit%, BadBeep%, FullBeep%, Fast%

FillCh$     character used to show field length (default "_")
ExtExit%    extended keys can be used to exit (default 0, no)
BadBeep%    beep on invalid keys (default 0, no)
FullBeep%   beep when input field is full (default 0, no)
Fast%       use fast display, may make CGA flicker (def 0, no)

Name  : SInputSet1           (String Input Settings)
Class : Input
Level : Clone

This is one of a number of routines which allow you to modify
the default operation of SInput.

If you give SInput a default entry, it will normally place the
cursor at the end of that entry when input begins.  The
CurPosn% option here allows you to place the cursor where you
want it (1 - LEN(St$), or 0 for end of entry).

Routines in this series include:
   SInput, SInputSet, SInputSet1, SInputSet2

   SInputSet1 CurPosn%, FullExit%

CurPosn%    starting cursor posn within input field (default 0)
FullExit%   auto-exit when input field is full (default 0, no)

Name  : SInputSet2           (String Input Settings)
Class : Input
Level : Clone

This is one of a number of routines which allow you to modify
the default operation of SInput.

If you allow tabs to exit SInput, the ExitCode% may return an
additional value: 9 (tab).  A "back tab", by the way, can be
retrieved if you use SInputSet to allow extended keys to exit
(back tab would return -15).

Routines in this series include:
   SInput, SInputSet, SInputSet1, SInputSet2

   SInputSet2 Capitalize%, TabExit%

Capitalize%   whether to capitalize letters (default 0, no)
TabExit%      whether tab key can to exit (default 0, no)

Name  : SortD                (Sort Double precision)
Class : Array management
Level : Any

This routine sorts the elements in an array of double-precision
numbers.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

If you would like the results to be largest-to-smallest, rather
than smallest-to-largest, just call ReverseD after this routine.

   SortD Array#(), Elements%

Array#()    array to be sorted
Elements%   number of elements in array
-------
Array#()    sorted array

Name  : SortI                (Sort Integer)
Class : Array management
Level : Any

This routine sorts the elements in an array of integers.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

If you would like the results to be largest-to-smallest, rather
than smallest-to-largest, just call ReverseI after this routine.

   SortI Array%(), Elements%

Array%()    array to be sorted
Elements%   number of elements in array
-------
Array%()    sorted array

Name  : SortL                (Sort Long integer)
Class : Array management
Level : Any

This routine sorts the elements in an array of long integers.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

If you would like the results to be largest-to-smallest, rather
than smallest-to-largest, just call ReverseL after this routine.

   SortL Array&(), Elements%

Array&()    array to be sorted
Elements%   number of elements in array
-------
Array&()    sorted array

Name  : SortS                (Sort Single precision)
Class : Array management
Level : Any

This routine sorts the elements in an array of single-precision
numbers.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.

If you would like the results to be largest-to-smallest, rather
than smallest-to-largest, just call ReverseS after this routine.

   SortS Array!(), Elements%

Array!()    array to be sorted
Elements%   number of elements in array
-------
Array!()    sorted array

Name  : SortSt               (Sort String)
Class : Array management
Level : Any

This routine sorts the elements in a string array.

The array is assumed to start at element 1.  You may specify
the last element in the array, allowing you to sort only part
of an array if you like.  You can also specify whether the
capitalization of letters in a string should matter for sorting
purposes.

If you would like the results to be last-to-first, rather than
first-to-last, just call ReverseSt after this routine.

   SortSt Array$(), Elements%, CapsCount%

Array$()    array to be sorted
CapsCount%  use 0 if uppercase/lowercase doesn't matter
Elements%   number of elements in array
-------
Array$()    sorted array

Name  : Soundex              (Soundex code)
Class : String
Level : Any

This is a string comparison routine which returns a code that
is loosely based on the "sound" of a word.  It removes the
vowels and repeated characters from a word, then converts it
into a numeric code.  Any words with the same code are
considered to sound alike.

While not perfect, this algorithm does a fast and reasonably
good job.  It can be helpful in applications like spelling
checkers and phone books, where a search based on exact text
may not be appropriate.

   Code$ = St$
   Soundex St$, Code$, CodeLen%
   Code$ = LEFT$(St$, CodeLen%)

St$       string to be encoded
-------
Code$     result code.  Init to >= length of original string.
CodeLen%  length of the result code

Name  : SpeedKey             (Speed up Keyboard)
Class : Input
Level : BIOS (AT)

This routine provides control over the keyboard repeat rate for
AT-class machines.  Increasing the repeat rate can make the
computer seem a lot more responsive and pleasant to deal with.

  RepDelay%   Delay Time
     0        250 milliseconds
     1        500 ms
     2        750 ms
     3        1 second

  RepRate% is the key repeat rate, 0-31 (from around 30 cps to
  around 2 cps)

   SpeedKey RepDelay%, RepRate%

RepDelay%   delay before starting to repeat (0-3, default 1)
RepRate%    rate at which to repeat key (0-31, default 11)

Name  : Split                (Split screen image)
Class : Display
Level : Clone

This provides an elegant way to clear a text-mode screen.  It
splits the display into four parts, scrolling each part up or
down until it slides off the screen.

   Split

Name  : Spooler              (check for print Spooler)
Class : Printer
Level : DOS

The Spooler routine allows you to see whether the print spooler
(installed by the DOS PRINT utility) is available.

   Spooler Status%

-------
Status%   spooler status:
             -1   it's installed
              0   it isn't installed, but can be
              1   it isn't installed, and can't be

Name  : SSrch                (String Search)
Class : String
Level : Any

This is a string search routine which tells you whether one
string can be found inside another.  Uppercase/lowercase
distinctions are ignored.  Leading and trailing spaces in the
string for which to search are also ignored.

Note that the positions of the main string and search string
parameters are in the reverse of the order you might expect.

   SSrch Search$, MainSt$, Found%

Search$   string for which to search
MainSt$   string to be searched
-------
Found%    whether a match was found (0 if no)

Name  : StrDel               (String Delete)
Class : String
Level : Any

StrDel deletes a character from a string.  Actually, it doesn't
make the string any shorter, but it acts like a delete.  The
end of the string is filled with a space.

   StrDel St$, Posn%

St$       string from which to delete a character
Posn%     position of the character to delete (1-LEN(St$))
-------
St$       processed string

Name  : StrIns               (String Insert)
Class : String
Level : Any

StrIns inserts a space into a string.  Actually, it doesn't
make the string any longer, but it acts like an insert.  The
former end of the string is discarded.

   StrIns St$, Posn%

St$       string in which to insert a space
Posn%     where to insert the space (1-LEN(St$))
-------
St$       processed string

Name  : Strip                (Strip spaces)
Class : String
Level : Any

This routine strips both leading and trailing white space from
a string. This includes control characters as well as blanks
(anything below CHR$(33)).

   Strip St$

St$      string to process
-------
St$      processed string

Name  : StripBlanks          (Strip Blanks)
Class : String
Level : Any

This routine strips leading and/or trailing white space from a
string.  This includes control characters as well as blanks
(anything below CHR$(33)).

See also StripSpaces.

   StripBlanks St$, Which%, StLen%
   St$ = LEFT$(St$, StLen%)

St$      string to process
Which%   1: strip left, 2: strip right, 3: strip left and right
-------
St$      processed string
StLen    length of processed string

Name  : StripChar            (Strip Characters)
Class : String
Level : Any

This routine strips all occurrences of a given list of
characters out of a string.  Among the uses for this are
cleaning up user-entered values.  For instance, a strip list of
"$," would remove commas and dollar signs from a number, and
"()- " will remove telephone delimiters.

   StripChar St$, StripList$, StLen%
   St$ = LEFT$(St$, StLen%)

St$         string to process
StripList$  characters to remove from the string
-------
St$         processed string
StLen%      length of processed string

Name  : StripRange           (Strip Range of characters)
Class : String
Level : Any

This routine strips an inclusive range of characters out of a
string.  The range is specified as the first and last ASCII
codes to strip.  For instance, using a low character of "0" and
a high of "9" would remove all digits from a string.

   StripRange St$, ASC(LowChar$), ASC(HighChar$), StLen%
   St$ = LEFT$(St$, StLen%)

St$         string to process
LowChar$    lowest character to strip
HighChar$   highest character to strip
-------
St$         processed string
StLen%      length of processed string

Name  : StripSpaces          (Strip Spaces)
Class : String
Level : Any

This routine strips leading and/or trailing spaces from a
string.

See also StripBlanks.

   StripSpaces St$, Which%, StLen%
   St$ = LEFT$(St$, StLen%)

St$      string to process
Which%   1: strip left, 2: strip right, 3: strip left and right
-------
St$      processed string
StLen%   length of processed string

Name  : Strip2$              (Strip Spaces)
Class : String
Level : Any

This routine strips both leading and trailing white space from
a string.  It works just like Strip, but is a function rather
than a subprogram.  White space includes control characters as
well as blanks (anything below CHR$(33)).

   Result$ = Strip2$(St$)

St$       string to process
-------
Result$   processed string

Name  : StrSqu2              (String Squish, 2-gram)
Class : String
Level : Any

This is a text compression routine which uses a 2-gram
algorithm to compress common pairs of characters out of a
string.  You can reasonably expect to reduce the text size by
about a third with this routine.  Compression is quite fast.
The one limitation is that only plain text may be compressed;
the text may not contain CHR$(128) through CHR$(255), as these
codes are used by the compression algorithm.

You must use StrSquLen2 before this routine to determine the
proper length to which to initialize the result string.

The compressed text can be restored to original form with
StrUnsqu2.

   StrSquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrSqu2 St$, Result$

St$       string to compress
-------
Result$   compressed string

Name  : StrSquLen2           (String Squished Length, 2-gram)
Class : String
Level : Any

This routine is used in conjunction with the StrSqu2 text
compressor. It tells you what size the resulting text will be.
See StrSqu2 for further information.

   StrSquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrSqu2 St$, Result$

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

Name  : StrUnsqu2            (String Unsquish, 2-gram)
Class : String
Level : Any

This routine decompresses text which was compressed by
StrSqu2.  Text is decompressed at lightning speed, as this
routine has no overhead to speak of.

You must use StrUnsquLen2 before this routine to determine the
proper length to which to initialize the result string.

   StrUnsquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrUnsqu2 St$, Result$

St$       string to decompress
-------
Result$   decompressed string

Name  : StrUnsquLen2         (String Unsquished Length, 2-gram)
Class : String
Level : Any

This routine is used in conjunction with the StrUnsqu2 text
decompressor. It tells you what size the resulting text will
be.  See StrUnsqu2 for further information.

   StrUnsquLen2 St$, ResultLen%
   Result$ = SPACE$(ResultLen%)
   StrUnsqu2 St$, Result$

St$          string to decompress
-------
ResultLen%   length of the decompressed string

Name  : SubExist             (Subdirectory Existence)
Class : Disk
Level : DOS

This routine lets you see if a given subdirectory actually
exists.  This isn't really necessary for the PBClone file
routines, which will return an appropriate error code, but it's
a valuable safeguard when using the BASIC OPEN statement.

See also SubExist2, the FUNCTION version of this routine.

   SubExist SubDir$, Found%

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

Name  : SubExist2%           (Subdirectory Existence)
Class : Disk
Level : DOS

This routine lets you see if a given subdirectory actually
exists.  This isn't really necessary for the PBClone file
routines, which will return an appropriate error code, but it's
a valuable safeguard when using the BASIC OPEN statement.

See also SubExist, the SUB version of this routine.

   Found% = SubExist2%(SubDir$)

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

Name  : Time2Int             (Time to Integer)
Class : Time
Level : Any

This routine compresses a time 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.  If that's what you
want, try the Elapsed routine.

Note that odd numbers of seconds will be rounded down to the
previous even number.  This is a result of the storage format
used.

   Time2Int Hour%, Minute%, Second%, IntTime%

Hour%      hour (0-23)
Minute%    minute
Second%    second
-------
IntTime%   time compressed into an integer

Name  : Time2Sec&            (Time to Seconds)
Class : Time
Level : Any

This routine converts a time string into the number of seconds
past midnight. This is convenient if you want to find the
difference between two times or to calculate what time it will
be after a given interval.

   Seconds& = Time2Sec&(TimeSt$)

TimeSt$    time string (TIME$ format)
-------
Seconds&   number of seconds past midnight

Name  : TimeN2S              (Time Numbers to String)
Class : Time
Level : Any / DOS

Many of the PBClone routines return the time as a set of
numbers.  This routine provides an easy way to convert those
numbers into string form.  The time format used (whether
seconds are included) will be based on the length of the string
which you pass to the routine.  For instance, a string like
"xx:xx" would return a time like "21:35", whereas "xx:xx:xx"
would return "21:35:08".

   TimeSt$ = "xx:xx:xx"
   TimeN2S Hour%, Minute%, Second%, TimeSt$

Hour%     hour (0-23)
Minute%   minute
Second%   second
-------
TimeSt$   time string.  Init to 5 or 8 characters (see above).

Name  : TimeS2N              (Time String to Numbers)
Class : Time
Level : Any

Many of the PBClone routines need to be passed the time as a
set of numbers. This routine provides an easy way to convert a
time from string form into numbers.  You may use either
"xx:xx:xx" or "xx:xx" form to specify the time (the string
length is important, but the delimiter and contents of the
string are ignored).  If the 5-character short form is used,
the Second% value will be zero.

   TimeS2N Hour%, Minute%, Second%, TimeSt$

TimeSt$   time string.  Init to 5 or 8 characters (see above).
-------
Hour%     hour (0-23)
Minute%   minute
Second%   second (0 if 5-char format)

Name  : TInstr               (Typed INSTR)
Class : String
Level : Any

As you might guess from the "Instr" part of the name, this
routine searches a string.  Instead of searching for a specific
character or substring, though, it looks for a specific type of
character-- letters, numbers, control codes, or whatever.  You
can search for the first of a combination of types, too, which
also allows searching for "anything but" a specific type.

The character type code is specified by adding any of the
following:

    1    alphabetic
    2    numeric
    4    symbolic
    8    control
   16    graphics
   32    space

The TInstr routine is handy for parsing and cleaning up user
input, among other uses.

   TInstr St$, ChrType%, Place%

St$          string to search
ChrType%     type of character(s) to search for
-------
Place%       position of first char of desired type, or 0

Name  : TypeIn               (Type In)
Class : Input
Level : Clone

This is an unusual routine which combines both output and
input.  It sends a string to the keyboard buffer, where it acts
as if it had been typed in by someone.  The string may be up to
15 key codes in length (anything past 15 keys will be ignored,
due to the limited length of the keyboard buffer).

Normal keys can be put into the string simply as characters.
Extended keys, like Alt-key combinations, arrow keys, and
function keys, must be encoded as CHR$(0) + CHR$(ScanCode),
where the ScanCode is the key's scan code.  You can look up
such scan codes in your BASIC manual or use GetKey to find out
what they are.  Extended keys, although apparently taking up
two characters, only take up one space in the keyboard buffer.
The TypeIn routine allows for this fact.

Among other things, this routine can be used to provide default
answers to input routines, or to execute another program once
your program exits.

   TypeIn St$

St$     keys to be "typed" into the keyboard buffer

Name  : TypePrint            (Type Print)
Class : Display
Level : Clone

TypePrint displays a string as if it was being typed.  The
string is displayed a character at a time, with a delay between
each character.  You may choose one color to highlight the
just-displayed character and another color for the character to
turn after the delay is done.

   TypePrint St$, Row%, Column%, WaitTime%, TmpAttr%,
      Attr%, Fast%

St$        string to display
Row%       row at which to display string
Column%    column at which to display string
WaitTime%  delay between chars (milliseconds; 20-60 is decent)
TmpAttr%   color/attribute for just-displayed character
Attr%      color/attribute for character after the delay is up
Fast%      whether to use fast displays (0 no)

Name  : UnCalcAttr           (Undo Calculated 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.  The UnCalcAttr routine allows you to decode the
original colors given the attribute.

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).  The below
routine shows how to get around this, if needed.

   UnCalcAttr Foreground%, Background%, Attr%
   ' the following is optional and may not be desired...
   ' it converts colors to "no blink" equivalents (see above)
   IF Foreground% AND 16 THEN
      Foreground% = Foreground% - 16
      Background% = Background% + 8
   END IF

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

Name  : UnScrunch            (Undo Screen Crunch)
Class : Display
Level : Any

This routine is designed to be used in conjunction with ScrRest
and the other routines which restore an entire 80x25 text
screen from an array.  It expands screens that were compressed
by Scrunch to their full original size. The uncompression
algorithm is very fast and will not take any noticeable amount
of time for most purposes.

   REDIM FullScreen%(1 TO 2000)
   DSeg% = VARSEG(FullScreen%(1))
   DOfs% = VARPTR(FullScreen%(1))
   UnScrunch DSeg%, DOfs%, CSeg%, COfs%

DSeg%     segment of array in which to store expanded image
DOfs%     offset of array in which to store expanded image
CSeg%     segment of the compressed image
COfs%     offset of the compressed image

Name  : UnSplit              (Undo Split)
Class : Display
Level : Clone

This routine does the opposite of Split-- instead of clearing
the screen by scrolling it in different directions, it puts
text on the screen by scrolling it on from different
locations.  The effect is quite stunning.

The information to place on the screen comes from an array that
you specify which contains a saved screen.  Only 80x25 text
modes are supported.  Any of the screen save routines (e.g.,
ScrSave) may be used to load the array.  In a typical case, you
will use this routine with screens that were created in advance
and stored to disk for use by your program.

   UnSplit Scrn%(), Fast%

Scrn%()   array containing the text to display
Fast%     whether to use fast mode (0 no)

Name  : Upcase               (Uppercase)
Class : String
Level : Any

This routine, like BASIC's UCASE$ function, converts a string
to uppercase. Since it doesn't have to create a new return
string (a fairly slow process), it's faster than the BASIC
equivalent.

See also Upcase1.

   Upcase St$

St$     string to be capitalized
-------
St$     capitalized string

Name  : Upcase1              (Uppercase)
Class : String
Level : Any

This routine, like BASIC's UCASE$ function, converts a string
to uppercase. It converts letters in the extended character set
as well as the usual letters, making it well suited for text
which may not be in English.

See also Upcase.

   Upcase1 St$

St$     string to be capitalized
-------
St$     capitalized string

Name  : UpdTVScreen          (Update TopView Screen)
Class : Display
Level : BIOS

UpdTVScreen tells a TopView-compatible multitasker to update
the screen using a specified screen buffer (use GetTVScreen to
get the buffer location).  Some multitaskers will do this
automatically, but some won't.  It's safe to use this routine
either way.

See also GetDView, GetTView, GetTVScreen.

   UpdTVScreen DSeg%, DOfs%

DSeg%       segment of screen buffer
DOfs%       offset of screen buffer

Name  : VGARest13            (VGA Restore for SCREEN 13)
Class : Display
Level : Clone

This routine allows you to restore a SCREEN 13 (VGA, 320x200,
256 color) display that was saved using VGASave13 (see).

   VGARest13 DSeg%, DOfs%

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

Name  : VGASave13            (VGA Save of SCREEN 13)
Class : Display
Level : Clone

This routine allows you to save a SCREEN 13 (VGA, 320x200, 256
color) display that can be restored using VGARest13 (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).

   VGASave13 DSeg%, DOfs%

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

Name  : WeekDay              (Week Day)
Class : Time
Level : DOS

This routine tells you what the day of the week is, just the
thing for calendar programs and whatnot.  The day is returned
as a number from 1-7, which identifies a day from Sunday
through Saturday.

   WeekDay Day%

-------
Day%     current day

Name  : WeekDay1             (Week Day)
Class : Time
Level : Any

This routine tells you the day of the week for any given date.

   WeekDay1 MonthNr%, DayNr%, YearNr%, DayName$

MonthNr%     month number (1-12)
DayNr%       day number (1-31)
YearNr%      year number (1900 on)
-------
DayName$     day of the week

Name  : WinCheck             (Windows Check)
Class : Equipment
Level : BIOS

The WinCheck routine tells you what version of Microsoft
Windows is in use, if any.  It returns the results as two
integers containing the major and minor version numbers.  For
instance, Windows 3.0 would return a major number of 3, minor
0.  Windows/386 v2.x will be identified as 2.0.  If Windows is
not running, 0.0 will be returned.  NOTE that this routine is
not able to detect Windows 1.x versions!

   WinCheck MajorV%, MinorV%

-------
MajorV%   major part of the Windows version
MinorV%   minor part of the Windows version

Name  : WindowManager        (Window Manager)
Class : Display
Level : Clone

WindowManager 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.  Only text mode is 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:
   -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.

   WindowManager TRow%, LCol%, BRow%, RCol%, Frame%,
      Fore%, Back%, Grow%, Shade%, TFore%, Title$, Page%, 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 (see above)
TFore%      title foreground color
Title$      window title ("" if none)
Page%       display page (normally zero)
Fast%       whether to use fast mode (0 no)

Name  : WindowMan2           (Window Manager)
Class : Display
Level : Clone

This routine is identical to WindowManager but for the fact
that it allows you to design your own custom window frames.
Please see the description of WindowManager 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.

   WindowMan2 TRow%, LCol%, BRow%, RCol%, Frame%, FSt$,
      Fore%, Back%, Grow%, Shade%, TFore%, Title$, Page%, 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)
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)
Page%       display page (normally zero)
Fast%       whether to use fast mode (0 no)

Name  : WindowMan3           (Window Manager)
Class : Display
Level : Clone

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

   WindowMan3 Parm%(), Title$

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
Parm%(11)   display page (normally zero)
Parm%(12)   whether to use fast mode (0 no)
Title$      window title ("" if none)

Name  : WindowMan4           (Window Manager)
Class : Display
Level : Clone

This is an extremely cut-down version of WindowManager,
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.

   WindowMan4 TRow%, LCol%, BRow%, RCol%, Frame%, Attr%,
      Page%, 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)
Attr%       frame color/attribute (use CalcAttr)
Page%       display page (normally zero)
Fast%       whether to use fast mode (0 if no, to avoid snow on CGAs)

Name  : WriteBitF            (Write Bit Field)
Class : Numeric
Level : Any

This routine allows you to set an element of a virtual array.
The actual array can be any numeric type, as it is just being
used as a storage area. The virtual array is composed of
numbers of a bit length that you specify (1-8).  This provides
efficient storage for numbers which have a limited range.

Here's how you DIM the actual array, assuming an integer array
is used:
   DIM Array%(1 TO (VirtElements * VirtBits + 15) \ 16)

"VirtElements" is the number of elements in the virtual array
and "VirtBits" is the number of bits per element.

See also ReadBitF.

   WriteBitF DSeg%, DOfs%, ElementNr&, BitLen%, Value%

DSeg%        segment of actual array
DOfs%        offset of actual array
ElementNr&   virtual element number (starts at 0)
BitLen%      bits per virtual element (1-8)
Value%       value to set element to (range depends on BitLen%)

Name  : Xlate                (Translate)
Class : String
Level : Any

The Xlate routine allows for translating a string, character by
character, very quickly.  It uses a translation table that you
provide.  This table is 256 bytes long, one byte for each
character in the ASCII table.  The translation is done by
position-- for instance, if the original character was "A"
(ASCII 65), the translated character will be whatever is in the
translation table at position 66.  Why 66, when "A" is 65?
Because ASCII runs from 0-255, but the translation string is
1-256: everything is one higher in the string than the ASCII
character it represents.

Translation capabilities are handy in communications software.
They can also be used in other things.  One simple use would be
to set up a translation table where all lowercase characters
would be converted to uppercase.  You might ask why, since
BASIC has a UCASE$ function and PBClone has an Upcase routine.
Well, Upcase is faster than UCASE$, since it doesn't have to
create a return string; but Xlate would be even faster, since
it translates every character directly instead of deciding
whether it's a lowercase letter!

Simple encoding, WordStar file decryption, string reversal,
uppercase / lowercase conversion, and many other things can be
done with Xlate.

Remember to initialize all 256 characters in the translation
table!

   Xlate St$, XlateTable$

St$          string to translate
XlateTable$  translation table
-------
St$          translated string

Name  : XMPrint              (Translate and MS-DOS Print)
Class : Display
Level : DOS

A combination of the Xlate and DMPrint routines, this 'un
allows you to display using DOS services while being able to
translate or screen out characters.  Each character of the
string to display is passed through a translation table you
provide (256 bytes, where each position corresponds directly to
the ASCII code of the same number [0-255]).  If the result is
0, the character is not displayed.  Otherwise, the translated
character is displayed using DOS display services.  The new
cursor position is returned so you can inform BASIC about it.

Note that the new cursor position may not be accurate!  Some
ANSI drivers do not update the BIOS cursor position info, in
which case the results won't be useful.  That's a hazard of
using DOS output.

   XMPrint St$, XlateTable$, Row%, Column%
   LOCATE Row%, Column%

St$          string to display
XlateTable$  translation table
-------
Row%         current row
Column%      current column

Name  : XorSt                (XOR String)
Class : String
Level : Any

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

   XorSt St1$, St2$

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

Name  : XQPrint              (Extended Quick Print)
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 only in text modes.

See also QPrint, a slightly less flexible (but even faster)
routine.

   XQPrint St$, Row%, Column%, Attr%, Page%, Fast%

St$       string to display
Row%      starting row
Column%   starting column
Attr%     color/attribute (see CalcAttr)
Page%     display page (unused on MDA/Herc; normally 0)
Fast%     whether to use fast mode (0 no)

Name  : XQPrintOver          (Extended Quick Print Overwrite)
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 only in text modes.

This is a slightly unusual variant on a print routine.  It
displays all characters except spaces.  If your string contains
a space, that position on the screen will be skipped.  In other
words, it acts kind of like an overlay. This can be handy when
you have text in alternating colors.

I came up with this routine when I designed a program with a
function key display at the bottom of the screen-- the names of
the function keys were one color and the associated definitions
were another color.  It was obvious that the easiest way of
handling that would be to use an "overlay" approach.  The
function key definitions were laid down with XQPrint.  I then
overlaid the line with the function key names in a different
color, using XQPrintOver.

   XQPrintOver St$, Row%, Column%, Attr%, Page%, Fast%

St$       string to display
Row%      starting row
Column%   starting column
Attr%     color/attribute (see CalcAttr)
Page%     display page (unused on MDA/Herc; normally 0)
Fast%     whether to use fast mode (0 no)